tribool documentation, first draft

[SVN r352]
This commit is contained in:
Douglas Gregor
2002-08-02 17:13:06 +00:00
parent b6eddd2138
commit 30c106e62e

536
doc/tribool.html Normal file
View File

@@ -0,0 +1,536 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>3-State Boolean Library</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080">
<h1><IMG SRC="../../../c++boost.gif" WIDTH="276" HEIGHT="86">3-State Boolean Library</h1>
<p> The 3-state boolean library contains a single class, <code>tribool</code>, along with support functions and operator overloads that implement 3-state boolean logic.
<h2>Table of Contents</h2>
<ul>
<li><a href="#usage">Usage</a></li>
<li><a href="#tables">Truth tables</a></li>
<li><a href="#reference">Reference</a>
<ul>
<li><a href="#synopsis">Header <code>&lt;boost/tribool.hpp&gt;</code> synopsis</a></li>
<li><a href="#tribool">Class <code>tribool</code></a></li>
<li><a href="#indeterminate">Indeterminate value</a></li>
<li><a href="#equality">Equality comparisons</a></li>
<li><a href="#logical">Logical operators</a></li>
</ul></li>
</ul>
<a name="usage"><h2>Usage</h2></a>
<p> The <code>tribool</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>indeterminate</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).
<p> The <code>tribool</code> class supports conversion from <code>bool</code> values and literals along with its own <code>indeterminate</code> keyword:
<pre>
tribool b(true);
b = false;
b = indeterminate;
tribool b2(b);
</pre>
<p> <code>tribool</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>tribool</code> is always true, and <code>false</code> otherwise.
<pre>
tribool b = some_operation();
if (b) {
// b is true
}
else if (!b) {
// b is false
}
else {
// b is indeterminate
}
</pre>
<p> <code>tribool</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>tribool</code> values. For instance:
<pre>
tribool x = some_op();
tribool 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, or both
}
}
</pre>
<p> Similarly, <code>tribool</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>tribool</code>, because potentially we might not know the result of a comparison (try to compare <code>true</code> and <code>indeterminate</code>). For example:
<pre>
tribool x(true);
tribool y(indeterminate);
assert(x == x); // okay, x == x returns true
assert(!(y == y)); // okay, because y == y is indeterminate
assert(x == true); // okay, can compare tribools and bools
</pre>
<p>See the set of <a href="#tables">truth tables</a> or the <a href="#reference">reference</a> documentation for the exact semantics of these operators.
<p> The <code>indeterminate</code> keyword (representing the indeterminate <code>tribool</code> value) doubles as a function to check if the value of a <code>tribool</code> is indeterminate, e.g.,
<pre>
tribool x = try_to_do_something_tricky();
if (indeterminate(x)) {
// value of x is indeterminate
}
else {
// report success or failure of x
}
</pre>
<a name="tables"><h2>Truth Tables</h2></a>
<p>
<table>
<tr>
<td colspan=2><center>
<table border=1>
<tr>
<th>p</th>
<th>!p</th>
</tr>
<tr><td><center>false</center></td><td><center>true</center></td></tr>
<tr><td><center>true</center></td><td><center>false</center></td></tr>
<tr><td><center>indeterminate</center></td><td><center>indeterminate</center></td></tr>
</table>
</center></td>
</tr>
<tr>
<td><center>
<table border=1>
<tr>
<th><center><code>==</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>true</center></td>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
</center></td>
<td><center>
<table border=1>
<tr>
<th><center><code>!=</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>true</center></td>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
</center></td>
</tr>
<tr>
<td><center>
<table border=1>
<tr>
<th><center><code>&amp;&amp;</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>false</center></td>
<td><center>false</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
</center></td>
<td><center>
<table border=1>
<tr>
<th><center><code>||</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>true</center></td>
<td><center>true</center></td>
<td><center>true</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
</center></td>
</tr>
</table>
<a name="reference"><h2>Reference</h2></a>
<a name="synopsis"><h3>Header <code>&lt;boost/tribool.hpp&gt;</code> synopsis</h3></a>
<pre>
<b>namespace</b> boost {
<b>class</b> <a href="#tribool">tribool</a>;
<a href="#indeterminate"><em>// Indeterminate value</em></a>
<b>struct</b> indeterminate_t;
<b>typedef</b> <b>bool</b> (*indeterminate_keyword_t)(tribool, indeterminate_t);
<b>bool</b> indeterminate(tribool, indeterminate_t = indeterminate_t());
<a href="#equality"><em>// Equality comparisons</em></a>
tribool <b>operator</b>==(tribool, <b>bool</b>);
tribool <b>operator</b>==(<b>bool</b>, tribool);
tribool <b>operator</b>==(indeterminate_keyword_t, tribool);
tribool <b>operator</b>==(tribool, indeterminate_keyword_t);
tribool <b>operator</b>==(tribool, tribool);
tribool <b>operator</b>!=(tribool, <b>bool</b>);
tribool <b>operator</b>!=(<b>bool</b>, tribool);
tribool <b>operator</b>!=(indeterminate_keyword_t, tribool);
tribool <b>operator</b>!=(tribool, indeterminate_keyword_t);
tribool <b>operator</b>!=(tribool, tribool);
<a href="#logical"><em>// Logical operators</em></a>
tribool <b>operator</b>&amp;&amp;(tribool, <b>bool</b>);
tribool <b>operator</b>&amp;&amp;(<b>bool</b>, tribool);
tribool <b>operator</b>&amp;&amp;(indeterminate_keyword_t, tribool);
tribool <b>operator</b>&amp;&amp;(tribool, indeterminate_keyword_t);
tribool <b>operator</b>&amp;&amp;(tribool, tribool);
tribool <b>operator</b>||(tribool, <b>bool</b>);
tribool <b>operator</b>||(<b>bool</b>, tribool);
tribool <b>operator</b>||(indeterminate_keyword_t, tribool);
tribool <b>operator</b>||(tribool, indeterminate_keyword_t);
tribool <b>operator</b>||(tribool, tribool);
} <em>// end namespace boost</em>
</pre>
<a name="tribool"><h3>Class <code>tribool</code></h3></a>
<p> The <code>tribool</code> class is a 3-state boolean value type that emulates the syntax and, to some extent, the semantics of the built-in <code><b>bool</b></code> type.
<pre>
<b>namespace</b> boost {
<b>class</b> tribool {
<b>typedef</b> <em>implementation-defined</em> safe_bool; <em>// See <a href="#conversions"><code>tribool</code> conversions</a></em>
<b>public</b>:
<a href="#constructors"><em>// Constructors</em></a>
<a href="#default_constructor">tribool()</a>;
<a href="#bool_constructor">tribool(<b>bool</b>)</a>;
<a href="#indeterminate_constructor">tribool(indeterminate_keyword_t)</a>;
<a href="#conversions"><em>// Boolean conversion</em></a>
<a href="#bool_convert"><b>operator</b> safe_bool() <b>const</b></a>;
<a href="#negation"><em>// Logical negation</em></a>
<a href="#not">tribool <b>operator</b>!()</a>;
<em>// Value</em>
<b>enum</b> { false_value, true_value, indeterminate_value } value;
};
} <em>// end namespace boost</em>
</pre>
<a name="constructors"><h4><code>tribool</code> constructors</h4></a>
<ol>
<li><a name="default_constructor"><code>tribool()</code>;</a>
<ul>
<li><b>Postconditions</b>: <code>value == false_value</code></li>
<li><b>Throws</b>: will not throw</li>
</ul>
<li><a name="bool_constructor"><code>tribool(<b>bool</b> x);</code></a>
<ul>
<li><b>Postconditions</b>: <code>value == x? true_value : false_value</code></li>
<li><b>Throws</b>: will not throw</li>
</ul>
<li><a name="indeterminate_constructor"><code>tribool(indeterminate_keyword_t);</code></a>
<ul>
<li><b>Postconditions</b>: <code>value == indeterminate_value</code></li>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<a name="conversions"><h4><code>tribool</code> conversions</h4></a>
<ol>
<li><a name="bool_convert"><code><b>operator</b> safe_bool();</code></a>
<ul>
<li><b>Returns</b>: a value that will evaluate true in a boolean context if <code>value == true_value</code> or that will evaluate false in a boolean context if <code>value != true_value</code>.</li>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<a name="negation"><h4><code>tribool</code> logical negation</h4></a>
<ol>
<li><a name="not"><code>tribool <b>operator</b>!() <b>const</b>;</code></a>
<ul>
<li><b>Returns</b>: the logical negation of the 3-state boolean value, according to the following negation table:
<table border=1>
<tr>
<th>p</th>
<th>!p</th>
</tr>
<tr><td><center>false</center></td><td><center>true</center></td></tr>
<tr><td><center>true</center></td><td><center>false</center></td></tr>
<tr><td><center>indeterminate</center></td><td><center>indeterminate</center></td></tr>
</table>
</li>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<a name="indeterminate"><h3>Indeterminate value</h3></a>
<ol>
<li>The <code>indeterminate</code> function has a dual purpose: it determines whether or not a <a href="#tribool"><code>tribool</code></a> has an indeterminate value but also acts as a keyword for the indeterminate value.<br>
[Example -
<pre>
tribool x;
x = <b>true</b>; <em>// okay, x is true</em>
x = indeterminate; <em>// okay, x has an indeterminate value</em>
</pre> - end example]
<li>The <code>indeterminate_t</code> type is a tag that makes the signature of the <code>indeterminate</code> function unique.<br>
<code><b>struct</b> indeterminate_t {};</code>
<li>The type of the <code>indeterminate</code> function is used to recognize <code>indeterminate</code> as a value.<br>
<b>typedef</b> <b>bool</b> (*indeterminate_keyword_t)(tribool, indeterminate_t);
<li><code><b>bool</b> indeterminate(tribool x, indeterminate_t = indeterminate_t());</code>
<ul>
<li><b>Returns</b>: <code>x.value == tribool::indeterminate_value</code></li>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<a name="equality"><h3>Equality Comparisons</h3></a>
<ol>
<li>
<pre>
tribool <b>operator</b>==(tribool x, <b>bool</b> y);
tribool <b>operator</b>==(<b>bool</b> x, tribool y);
tribool <b>operator</b>==(indeterminate_keyword_t x, tribool y);
tribool <b>operator</b>==(tribool x, indeterminate_keyword_t y);
tribool <b>operator</b>==(tribool x, tribool y);
</pre>
<ul>
<li><b>Returns</b>: the result of comparing two 3-state boolean values, according to the following table:
<table border=1>
<tr>
<th><center><code>==</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>true</center></td>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
<li><b>Throws</b>: will not throw</li>
</ul>
<li>
<pre>
tribool <b>operator</b>!=(tribool x, <b>bool</b> y);
tribool <b>operator</b>!=(<b>bool</b> x, tribool y);
tribool <b>operator</b>!=(indeterminate_keyword_t x, tribool y);
tribool <b>operator</b>!=(tribool x, indeterminate_keyword_t y);
tribool <b>operator</b>!=(tribool x, tribool y);
</pre>
<ul>
<li><b>Returns</b>: the negated result of comparing two 3-state boolean values, according to the following table:
<table border=1>
<tr>
<th><center><code>!=</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>true</center></td>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<a name="logical"><h3>Logical Operators</h3></a>
<ol>
<li>
<pre>
tribool <b>operator</b>&amp;&amp;(tribool x, <b>bool</b> y);
tribool <b>operator</b>&amp;&amp;(<b>bool</b> x, tribool y);
tribool <b>operator</b>&amp;&amp;(indeterminate_keyword_t x, tribool y);
tribool <b>operator</b>&amp;&amp;(tribool x, indeterminate_keyword_t y);
tribool <b>operator</b>&amp;&amp;(tribool x, tribool y);
</pre>
<ul>
<li><b>Returns</b>: the result of a logical AND of two 3-state boolean values, according to the following table:
<table border=1>
<tr>
<th><center><code>&amp;&amp;</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>false</center></td>
<td><center>false</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>false</center></td>
<td><center>indeterminate</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
<li><b>Throws</b>: will not throw</li>
</ul>
<li>
<pre>
tribool <b>operator</b>||(tribool x, <b>bool</b> y);
tribool <b>operator</b>||(<b>bool</b> x, tribool y);
tribool <b>operator</b>||(indeterminate_keyword_t x, tribool y);
tribool <b>operator</b>||(tribool x, indeterminate_keyword_t y);
tribool <b>operator</b>||(tribool x, tribool y);
</pre>
<ul>
<li><b>Returns</b>: the result of the logical OR of two 3-state boolean values, according to the following table:
<table border=1>
<tr>
<th><center><code>||</code></center></th>
<th><center>false</center></th>
<th><center>true</center></th>
<th><center>indeterminate</center></th>
</tr>
<tr>
<th><center>false</center></th>
<td><center>false</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
<tr>
<th><center>true</center></th>
<td><center>true</center></td>
<td><center>true</center></td>
<td><center>true</center></td>
</tr>
<tr>
<th><center>indeterminate</center></th>
<td><center>indeterminate</center></td>
<td><center>true</center></td>
<td><center>indeterminate</center></td>
</tr>
</table>
<li><b>Throws</b>: will not throw</li>
</ul>
</ol>
<hr>
<p>&copy; Copyright Douglas Gregor 2002. Permission to copy,
use, modify, sell and distribute this document is granted provided this
copyright notice appears in all copies. This document is provided "as is"
without express or implied warranty, and with no claim as to its
suitability for any purpose.
<address><a href="mailto:gregod@cs.rpi.edu"></a></address>
<!-- Created: Thu Aug 1 16:09:25 EDT 2002 -->
<!-- hhmts start -->
Last modified: Fri Aug 2 13:08:52 EDT 2002
<!-- hhmts end -->
</body>
</html>