feedc0de/boost_utility
1
0
Fork 0
forked from boostorg/utility
Code Pull Requests Activity

Jamfile.v2: Generate tribool documentation

Browse Source 
tribool.boostbook:
	- tribool documentation, now (obviously) in BoostBook


[SVN r1584]
This commit is contained in:
Douglas Gregor
2003-09-22 01:25:52 +00:00
parent e8aa29bc3c
commit 22581f82b4
2 changed files with 159 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Jamfile.v2 Normal file
View File

@@ -0,0 +1,6 @@
project boost-sandbox/utility/doc ;
import boostbook ;
import doxygen ;
doxygen reference : ../../../boost/tribool.hpp ;
boostbook tribool : tribool.boostbook ;

153
doc/tribool.boostbook Normal file
View File

@@ -0,0 +1,153 @@
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<library name="Tribool" dirname="utility/tribool" id="tribool"
last-revision="$Date$" xmlns:xi="http://www.w3.org/2001/XInclude">
<libraryinfo>
<author>
<firstname>Douglas</firstname>
<surname>Gregor</surname>
<email>gregod@cs.rpi.edu</email>
</author>
<copyright>
<year>2002</year>
<year>2003</year>
<holder>Douglas Gregor</holder>
</copyright>
<legalnotice>
<para>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. </para>
<para> This software is provided "as is" without express or
implied warranty, and with no claim as to its suitability for any
purpose. </para>
</legalnotice>
<librarypurpose>Three-state boolean type</librarypurpose>
<librarycategory name="category:misc"/>
</libraryinfo>
<section id="tribool.introduction">
<title>Introduction</title>
<para>The 3-state boolean library contains a single class,
<code><classname>boost::tribool</classname></code>, along with
support functions and operator overloads that implement 3-state
boolean logic. </para>
</section>
<section id="tribool.tutorial">
<title>Tutorial</title>
<using-namespace name="boost"/>
<para> The <code><classname>tribool</classname></code> class acts
like the built-in <code>bool</code> type, but for 3-state boolean
logic. The three states are <code>true</code>, <code>false</code>,
and <code><functionname>indeterminate</functionname></code>, where
the first two states are equivalent to those of the C++
<code>bool</code> type and the last state represents an unknown
boolean value (that may be <code>true</code> or
<code>false</code>, we don't know).</para>
<para> The <code><classname>tribool</classname></code> class
supports conversion from <code>bool</code> values and literals
along with its own
<code><functionname>indeterminate</functionname></code>
keyword:</para>
<programlisting><classname>tribool</classname> b(true);
b = false;
b = <functionname>indeterminate</functionname>;
<classname>tribool</classname> b2(b);</programlisting>
<para> <code><classname>tribool</classname></code> supports
conversions to <code>bool</code> for use in conditional
statements. The conversion to <code>bool</code> will be
<code>true</code> when the value of the
<code><classname>tribool</classname></code> is always true, and
<code>false</code> otherwise.</para>
<programlisting><classname>tribool</classname> b = some_operation();
if (b) {
// b is true
}
else if (!b) {
// b is false
}
else {
// b is indeterminate
}</programlisting>
<para> <code><classname>tribool</classname></code> supports the
3-state logic operators <code>!</code> (negation),
<code>&amp;&amp;</code> (AND), and <code>||</code> (OR), with
<code>bool</code> and <code><classname>tribool</classname></code>
values. For instance:</para>
<programlisting><classname>tribool</classname> x = some_op();
<classname>tribool</classname> y = some_other_op();
if (x &amp;&amp; y) {
// both x and y are true
}
else if (!(x &amp;&amp; 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
}
}</programlisting>
<para> Similarly, <code><classname>tribool</classname></code>
supports 3-state equality comparisons via the operators
<code>==</code> and <code>!=</code>. These operators differ from
"normal" equality operators in C++ because they return a
<code><classname>tribool</classname></code>, because potentially we
might not know the result of a comparison (try to compare
<code>true</code> and
<code><functionname>indeterminate</functionname></code>). For
example:</para>
<programlisting><classname>tribool</classname> x(true);
<classname>tribool</classname> y(<functionname>indeterminate</functionname>);
assert(x == x); // okay, x == x returns true
assert(!(y == y)); // okay, because y == y is <functionname>indeterminate</functionname>
assert(x == true); // okay, can compare <classname>tribool</classname>s and bools</programlisting>
<para> The <code><functionname>indeterminate</functionname></code> keyword (representing the
<functionname>indeterminate</functionname>&nbsp;<code><classname>tribool</classname></code> value)
doubles as a function to check if the value of a
<code><classname>tribool</classname></code> is indeterminate,
e.g.,</para>
<programlisting><classname>tribool</classname> x = try_to_do_something_tricky();
if (<functionname>indeterminate</functionname>(x)) {
// value of x is indeterminate
}
else {
// report success or failure of x
}</programlisting>
<para> Users may introduce additional keywords for the indeterminate
value in addition to the implementation-supplied
<code><functionname>indeterminate</functionname></code> using the
<code><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname></code>
macro. For instance, the following macro instantiation (at the
global scope) will introduce the keyword <code>maybe</code> as a
synonym for <code><functionname>indeterminate</functionname></code>
(also residing in the <code>boost</code> namespace):</para>
<programlisting><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname>(maybe)</programlisting>
</section>
<xi:include href="reference.boostbook"/>
</library>