From 22581f82b4e7a29577fd6666f96b3a133fce4b4b Mon Sep 17 00:00:00 2001 From: Douglas Gregor Date: Mon, 22 Sep 2003 01:25:52 +0000 Subject: [PATCH] Jamfile.v2: Generate tribool documentation tribool.boostbook: - tribool documentation, now (obviously) in BoostBook [SVN r1584] --- doc/Jamfile.v2 | 6 ++ doc/tribool.boostbook | 153 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 doc/Jamfile.v2 create mode 100644 doc/tribool.boostbook diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 0000000..78bc258 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,6 @@ +project boost-sandbox/utility/doc ; +import boostbook ; +import doxygen ; + +doxygen reference : ../../../boost/tribool.hpp ; +boostbook tribool : tribool.boostbook ; diff --git a/doc/tribool.boostbook b/doc/tribool.boostbook new file mode 100644 index 0000000..aac7c7f --- /dev/null +++ b/doc/tribool.boostbook @@ -0,0 +1,153 @@ + + + + + + Douglas + Gregor + gregod@cs.rpi.edu + + + + 2002 + 2003 + Douglas Gregor + + + + Permission to copy, use, sell and distribute this software + is granted provided this copyright notice appears in all copies. + Permission to modify the code and to distribute modified code is + granted provided this copyright notice appears in all copies, and + a notice that the code was modified is included with the copyright + notice. + + This software is provided "as is" without express or + implied warranty, and with no claim as to its suitability for any + purpose. + + + Three-state boolean type + + + +
+ Introduction + + The 3-state boolean library contains a single class, + boost::tribool, along with + support functions and operator overloads that implement 3-state + boolean logic. +
+ +
+ Tutorial + + + + The tribool class acts + like the built-in bool type, but for 3-state boolean + logic. The three states are true, false, + and indeterminate, where + the first two states are equivalent to those of the C++ + bool type and the last state represents an unknown + boolean value (that may be true or + false, we don't know). + + The tribool class + supports conversion from bool values and literals + along with its own + indeterminate + keyword: + + tribool b(true); +b = false; +b = indeterminate; +tribool b2(b); + + tribool supports + conversions to bool for use in conditional + statements. The conversion to bool will be + true when the value of the + tribool is always true, and + false otherwise. + +tribool b = some_operation(); +if (b) { + // b is true +} +else if (!b) { + // b is false +} +else { + // b is indeterminate +} + + tribool supports the + 3-state logic operators ! (negation), + && (AND), and || (OR), with + bool and tribool + values. For instance: + + tribool x = some_op(); +tribool y = some_other_op(); +if (x && y) { + // both x and y are true +} +else if (!(x && y)) { + // either x or y is false +} +else { + // neither x nor y is false, but we don't know that both are true + + if (x || y) { + // either x or y is true, or both + } +} + + Similarly, tribool + supports 3-state equality comparisons via the operators + == and !=. These operators differ from + "normal" equality operators in C++ because they return a + tribool, because potentially we + might not know the result of a comparison (try to compare + true and + indeterminate). For + example: + +tribool x(true); +tribool y(indeterminate); + +assert(x == x); // okay, x == x returns true +assert(!(y == y)); // okay, because y == y is indeterminate +assert(x == true); // okay, can compare tribools and bools + + The indeterminate keyword (representing the + indeterminate tribool value) + doubles as a function to check if the value of a + tribool is indeterminate, + e.g., + + tribool x = try_to_do_something_tricky(); +if (indeterminate(x)) { + // value of x is indeterminate +} +else { + // report success or failure of x +} + + Users may introduce additional keywords for the indeterminate + value in addition to the implementation-supplied + indeterminate using the + BOOST_TRIBOOL_THIRD_STATE + macro. For instance, the following macro instantiation (at the + global scope) will introduce the keyword maybe as a + synonym for indeterminate + (also residing in the boost namespace): + BOOST_TRIBOOL_THIRD_STATE(maybe) +
+ + + \ No newline at end of file