ceph/src/boost/libs/logic/doc/tribool.boostbook

   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);
  65 b = false;
  66 b = <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();
  80 if (b) {
  81   // b is true
  82 }
  83 else if (!b) {
  84   // b is false
  85 }
  86 else {
  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>&amp;&amp;</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();
  98 if (x &amp;&amp; y) {
  99   // both x and y are true
 100 }
 101 else if (!(x &amp;&amp; y)) {
 102   // either x or y is false
 103 }
 104 else {
 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
 125 assert(x == x); // okay, x == x returns true
 126 assert(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>&nbsp;<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();
 135 if (<functionname>indeterminate</functionname>(x)) {
 136   // value of x is indeterminate
 137 }
 138 else {
 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;
 167 if (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;
 184 cin &gt;&gt; x; // Type "0", "1", or "2" to get false, true, or indeterminate
 185 cout &lt;&lt; boolalpha &lt;&lt; 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)
 198 locale global;
 199 locale test_locale(global, new <classname>indeterminate_name</classname>&lt;char&gt;("maybe"));
 200 cout.imbue(test_locale);
 201 <classname>tribool</classname> x(maybe);
 202 cout &lt;&lt; boolalpha &lt;&lt; x &lt;&lt; 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>