]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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>&&</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 && y) { | |
99 | // both x and y are true | |
100 | } | |
101 | else if (!(x && 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> <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 >> x; // Type "0", "1", or "2" to get false, true, or indeterminate | |
185 | cout << 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) | |
198 | locale global; | |
199 | locale test_locale(global, new <classname>indeterminate_name</classname><char>("maybe")); | |
200 | cout.imbue(test_locale); | |
201 | <classname>tribool</classname> x(maybe); | |
202 | cout << 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> |