boostorg/utility
1
0
Fork 1
mirror of https://github.com/boostorg/utility.git synced 2025-08-03 23:04:34 +02:00
Code Issues Packages Projects Releases Wiki Activity

tribool has been in Boost proper for ages

Browse Source 
[SVN r2753]
This commit is contained in:
Douglas Gregor
2005-11-20 14:37:12 +00:00
parent 21bc200ca0
commit 0e3d2ccb2c
2 changed files with 0 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Jamfile.v2
View File

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

167
doc/tribool.boostbook
View File

@@ -1,167 +0,0 @@
<?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"/>
<testsuite>
<run-test filename="tribool_test.cpp">
<purpose><para>Test all features of the
<code><classname>boost::tribool</classname></code>
class.</para></purpose>
</run-test>
<run-test filename="tribool_rename_test.cpp">
<purpose><para>Test the use of the
<code><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname></code>
macro.</para></purpose>
</run-test>
</testsuite>
</library>