232 lines
9.1 KiB
XML
232 lines
9.1 KiB
XML
<?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="logic" id="tribool"
|
|
last-revision="$Date: 2007/05/03 03:28:53 $" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<libraryinfo>
|
|
<author>
|
|
<firstname>Douglas</firstname>
|
|
<surname>Gregor</surname>
|
|
<email>dgregor -at- cs.indiana.edu</email>
|
|
</author>
|
|
|
|
<copyright>
|
|
<year>2002</year>
|
|
<year>2003</year>
|
|
<year>2004</year>
|
|
<holder>Douglas Gregor</holder>
|
|
</copyright>
|
|
|
|
<legalnotice>
|
|
<para>Use, modification and distribution is subject to the Boost
|
|
Software License, Version 1.0. (See accompanying file
|
|
<filename>LICENSE_1_0.txt</filename> or copy at <ulink
|
|
url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)</para>
|
|
</legalnotice>
|
|
|
|
<librarypurpose>Three-state boolean type</librarypurpose>
|
|
<librarycategory name="category:misc"/>
|
|
</libraryinfo>
|
|
|
|
<title>Boost.Tribool</title>
|
|
|
|
<section id="tribool.introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>The 3-state boolean library contains a single class,
|
|
<code><classname>boost::logic::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::logic"/>
|
|
|
|
<section>
|
|
<title>Basic usage</title>
|
|
<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. Consequently, the following idiom
|
|
may be used to determine which of the three states a
|
|
<code><classname>tribool</classname></code> currently
|
|
holds:</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>&&</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 && 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
|
|
}
|
|
}</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
|
|
instance:</para>
|
|
|
|
<programlisting><classname>tribool</classname> x(true);
|
|
<classname>tribool</classname> y(<functionname>indeterminate</functionname>);
|
|
|
|
assert(x == x); // okay, x == x returns true
|
|
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> <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> All the logical operators and methods of <code><classname>tribool</classname></code> are marked
|
|
as <code>constexpr</code> in C++11. It means that <code><classname>tribool</classname></code> can
|
|
be used in compile time expressions:</para>
|
|
|
|
<programlisting>constexpr <classname>tribool</classname> x = (tribool(true) || tribool(indeterminate));
|
|
<functionname>static_assert</functionname>(x, "Must be true!");
|
|
</programlisting>
|
|
|
|
<note>Some compilers may have troubles with evaluating <code>tribool::operator safe_bool()</code> at compile time.</note>
|
|
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Renaming the indeterminate state</title>
|
|
<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)
|
|
<classname>tribool</classname> x = maybe;
|
|
if (maybe(x)) { /* ... */ }</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title><code>tribool</code> input/output</title>
|
|
<para><code><classname>tribool</classname></code> objects may be
|
|
read from and written to streams by including the
|
|
<headername>boost/logic/tribool_io.hpp</headername> header in a
|
|
manner very similar to <code>bool</code> values. When the
|
|
<code>boolalpha</code> flag is not set on the input/output stream,
|
|
the integral values 0, 1, and 2 correspond to <code>tribool</code>
|
|
values <code>false</code>, <code>true</code>, and
|
|
<code>indeterminate</code>, respectively. When
|
|
<code>boolalpha</code> is set on the stream, arbitrary strings can
|
|
be used to represent the three values, the default being "false",
|
|
"true", and "indeterminate". For instance:</para>
|
|
<programlisting><classname>tribool</classname> x;
|
|
cin >> x; // Type "0", "1", or "2" to get false, true, or indeterminate
|
|
cout << boolalpha << x; // Produces "false", "true", or "indeterminate"</programlisting>
|
|
|
|
<para><code><classname>tribool</classname></code> input and output
|
|
is sensitive to the stream's current locale. The strings associated
|
|
with false and true values are contained in the standard
|
|
<code><classname>std::numpunct</classname></code> facet, and the
|
|
string naming the indeterminate type is contained in the
|
|
<code><classname>indeterminate_name</classname></code> facet. To
|
|
replace the name of the indeterminate state, you need to imbue your
|
|
stream with a local containing a
|
|
<code><classname>indeterminate_name</classname></code> facet, e.g.:</para>
|
|
|
|
<programlisting><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname>(maybe)
|
|
locale global;
|
|
locale test_locale(global, new <classname>indeterminate_name</classname><char>("maybe"));
|
|
cout.imbue(test_locale);
|
|
<classname>tribool</classname> x(maybe);
|
|
cout << boolalpha << x << endl; // Prints "maybe"</programlisting>
|
|
|
|
<para>If you C++ standard library implementation does not support
|
|
locales, <code>tribool</code> input/output will still work, but you
|
|
will be unable to customize the strings printed/parsed when
|
|
<code>boolalpha</code> is set.</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<xi:include href="reference.xml"/>
|
|
|
|
<testsuite id="tribool.tests">
|
|
<run-test filename="tribool_test.cpp">
|
|
<purpose><para>Test all features of the
|
|
<code><classname>boost::logic::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>
|
|
|
|
<run-test filename="tribool_io_test.cpp">
|
|
<purpose><para>Test tribool input/output.</para></purpose>
|
|
</run-test>
|
|
</testsuite>
|
|
</library>
|