1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3 "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<library name="Tribool" dirname="logic" id="tribool" 5 last-revision="$Date: 2007/05/03 03:28:53 $" xmlns:xi="http://www.w3.org/2001/XInclude"> 6 <libraryinfo> 7 <author> 8 <firstname>Douglas</firstname> 9 <surname>Gregor</surname> 10 <email>dgregor -at- cs.indiana.edu</email> 11 </author> 12 13 <copyright> 14 <year>2002</year> 15 <year>2003</year> 16 <year>2004</year> 17 <holder>Douglas Gregor</holder> 18 </copyright> 19 20 <legalnotice> 21 <para>Use, modification and distribution is subject to the Boost 22 Software License, Version 1.0. (See accompanying file 23 <filename>LICENSE_1_0.txt</filename> or copy at <ulink 24 url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)</para> 25 </legalnotice> 26 27 <librarypurpose>Three-state boolean type</librarypurpose> 28 <librarycategory name="category:misc"/> 29 </libraryinfo> 30 31 <title>Boost.Tribool</title> 32 33 <section id="tribool.introduction"> 34 <title>Introduction</title> 35 36 <para>The 3-state boolean library contains a single class, 37 <code><classname>boost::logic::tribool</classname></code>, along with 38 support functions and operator overloads that implement 3-state 39 boolean logic. </para> 40 </section> 41 42 <section id="tribool.tutorial"> 43 <title>Tutorial</title> 44 45 <using-namespace name="boost::logic"/> 46 47 <section> 48 <title>Basic usage</title> 49 <para> The <code><classname>tribool</classname></code> class acts 50 like the built-in <code>bool</code> type, but for 3-state boolean 51 logic. The three states are <code>true</code>, <code>false</code>, 52 and <code><functionname>indeterminate</functionname></code>, where 53 the first two states are equivalent to those of the C++ 54 <code>bool</code> type and the last state represents an unknown 55 boolean value (that may be <code>true</code> or 56 <code>false</code>, we don't know).</para> 57 58 <para> The <code><classname>tribool</classname></code> class 59 supports conversion from <code>bool</code> values and literals 60 along with its own 61 <code><functionname>indeterminate</functionname></code> 62 keyword:</para> 63 64 <programlisting><classname>tribool</classname> b(true); 65b = false; 66b = <functionname>indeterminate</functionname>; 67<classname>tribool</classname> b2(b);</programlisting> 68 69 <para> <code><classname>tribool</classname></code> supports 70 conversions to <code>bool</code> for use in conditional 71 statements. The conversion to <code>bool</code> will be 72 <code>true</code> when the value of the 73 <code><classname>tribool</classname></code> is always true, and 74 <code>false</code> otherwise. Consequently, the following idiom 75 may be used to determine which of the three states a 76 <code><classname>tribool</classname></code> currently 77 holds:</para> 78 79<programlisting><classname>tribool</classname> b = some_operation(); 80if (b) { 81 // b is true 82} 83else if (!b) { 84 // b is false 85} 86else { 87 // b is indeterminate 88}</programlisting> 89 90 <para> <code><classname>tribool</classname></code> supports the 91 3-state logic operators <code>!</code> (negation), 92 <code>&&</code> (AND), and <code>||</code> (OR), with 93 <code>bool</code> and <code><classname>tribool</classname></code> 94 values. For instance:</para> 95 96 <programlisting><classname>tribool</classname> x = some_op(); 97<classname>tribool</classname> y = some_other_op(); 98if (x && y) { 99 // both x and y are true 100} 101else if (!(x && y)) { 102 // either x or y is false 103} 104else { 105 // neither x nor y is false, but we don't know that both are true 106 107 if (x || y) { 108 // either x or y is true 109 } 110}</programlisting> 111 112 <para> Similarly, <code><classname>tribool</classname></code> 113 supports 3-state equality comparisons via the operators 114 <code>==</code> and <code>!=</code>. These operators differ from 115 "normal" equality operators in C++ because they return a 116 <code><classname>tribool</classname></code>, because potentially we 117 might not know the result of a comparison (try to compare 118 <code>true</code> and 119 <code><functionname>indeterminate</functionname></code>). For 120 instance:</para> 121 122<programlisting><classname>tribool</classname> x(true); 123<classname>tribool</classname> y(<functionname>indeterminate</functionname>); 124 125assert(x == x); // okay, x == x returns true 126assert(x == true); // okay, can compare <classname>tribool</classname>s and bools</programlisting> 127 128 <para> The <code><functionname>indeterminate</functionname></code> keyword (representing the 129 <functionname>indeterminate</functionname> <code><classname>tribool</classname></code> value) 130 doubles as a function to check if the value of a 131 <code><classname>tribool</classname></code> is indeterminate, 132 e.g.,</para> 133 134 <programlisting><classname>tribool</classname> x = try_to_do_something_tricky(); 135if (<functionname>indeterminate</functionname>(x)) { 136 // value of x is indeterminate 137} 138else { 139 // report success or failure of x 140}</programlisting> 141 142 <para> All the logical operators and methods of <code><classname>tribool</classname></code> are marked 143 as <code>constexpr</code> in C++11. It means that <code><classname>tribool</classname></code> can 144 be used in compile time expressions:</para> 145 146 <programlisting>constexpr <classname>tribool</classname> x = (tribool(true) || tribool(indeterminate)); 147<functionname>static_assert</functionname>(x, "Must be true!"); 148</programlisting> 149 150 <note>Some compilers may have troubles with evaluating <code>tribool::operator safe_bool()</code> at compile time.</note> 151 152 153</section> 154 155 <section> 156 <title>Renaming the indeterminate state</title> 157 <para> Users may introduce additional keywords for the indeterminate 158 value in addition to the implementation-supplied 159 <code><functionname>indeterminate</functionname></code> using the 160 <code><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname></code> 161 macro. For instance, the following macro instantiation (at the 162 global scope) will introduce the keyword <code>maybe</code> as a 163 synonym for <code><functionname>indeterminate</functionname></code> 164 (also residing in the <code>boost</code> namespace):</para> 165 <programlisting><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname>(maybe) 166<classname>tribool</classname> x = maybe; 167if (maybe(x)) { /* ... */ }</programlisting> 168 </section> 169 170 <section> 171 <title><code>tribool</code> input/output</title> 172 <para><code><classname>tribool</classname></code> objects may be 173 read from and written to streams by including the 174 <headername>boost/logic/tribool_io.hpp</headername> header in a 175 manner very similar to <code>bool</code> values. When the 176 <code>boolalpha</code> flag is not set on the input/output stream, 177 the integral values 0, 1, and 2 correspond to <code>tribool</code> 178 values <code>false</code>, <code>true</code>, and 179 <code>indeterminate</code>, respectively. When 180 <code>boolalpha</code> is set on the stream, arbitrary strings can 181 be used to represent the three values, the default being "false", 182 "true", and "indeterminate". For instance:</para> 183<programlisting><classname>tribool</classname> x; 184cin >> x; // Type "0", "1", or "2" to get false, true, or indeterminate 185cout << boolalpha << x; // Produces "false", "true", or "indeterminate"</programlisting> 186 187 <para><code><classname>tribool</classname></code> input and output 188 is sensitive to the stream's current locale. The strings associated 189 with false and true values are contained in the standard 190 <code><classname>std::numpunct</classname></code> facet, and the 191 string naming the indeterminate type is contained in the 192 <code><classname>indeterminate_name</classname></code> facet. To 193 replace the name of the indeterminate state, you need to imbue your 194 stream with a local containing a 195 <code><classname>indeterminate_name</classname></code> facet, e.g.:</para> 196 197 <programlisting><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname>(maybe) 198locale global; 199locale test_locale(global, new <classname>indeterminate_name</classname><char>("maybe")); 200cout.imbue(test_locale); 201<classname>tribool</classname> x(maybe); 202cout << boolalpha << x << endl; // Prints "maybe"</programlisting> 203 204 <para>If you C++ standard library implementation does not support 205 locales, <code>tribool</code> input/output will still work, but you 206 will be unable to customize the strings printed/parsed when 207 <code>boolalpha</code> is set.</para> 208 </section> 209 210 </section> 211 212 <xi:include href="reference.xml"/> 213 214 <testsuite id="tribool.tests"> 215 <run-test filename="tribool_test.cpp"> 216 <purpose><para>Test all features of the 217 <code><classname>boost::logic::tribool</classname></code> 218 class.</para></purpose> 219 </run-test> 220 221 <run-test filename="tribool_rename_test.cpp"> 222 <purpose><para>Test the use of the 223 <code><macroname>BOOST_TRIBOOL_THIRD_STATE</macroname></code> 224 macro.</para></purpose> 225 </run-test> 226 227 <run-test filename="tribool_io_test.cpp"> 228 <purpose><para>Test tribool input/output.</para></purpose> 229 </run-test> 230 </testsuite> 231</library> 232