generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
main
boost/doc/html/tribool/tutorial.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

199 lines
15 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Tutorial</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../tribool.html" title="Chapter 23. Boost.Tribool">
<link rel="prev" href="../tribool.html" title="Chapter 23. Boost.Tribool">
<link rel="next" href="reference.html" title="Reference">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../tribool.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tribool.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="tribool.tutorial"></a>Tutorial</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="tutorial.html#id-1.3.24.4.2">Basic usage</a></span></dt>
<dt><span class="section"><a href="tutorial.html#id-1.3.24.4.3">Renaming the indeterminate state</a></span></dt>
<dt><span class="section"><a href="tutorial.html#id-1.3.24.4.4"><code class="computeroutput">tribool</code> input/output</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.24.4.2"></a>Basic usage</h3></div></div></div>
<p> The <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> class acts
like the built-in <code class="computeroutput">bool</code> type, but for 3-state boolean
logic. The three states are <code class="computeroutput">true</code>, <code class="computeroutput">false</code>,
and <code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>, where
the first two states are equivalent to those of the C++
<code class="computeroutput">bool</code> type and the last state represents an unknown
boolean value (that may be <code class="computeroutput">true</code> or
<code class="computeroutput">false</code>, we don't know).</p>
<p> The <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> class
supports conversion from <code class="computeroutput">bool</code> values and literals
along with its own
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>
keyword:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> b(true);
b = false;
b = <code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>;
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> b2(b);</pre>
<p> <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> supports
conversions to <code class="computeroutput">bool</code> for use in conditional
statements. The conversion to <code class="computeroutput">bool</code> will be
<code class="computeroutput">true</code> when the value of the
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> is always true, and
<code class="computeroutput">false</code> otherwise. Consequently, the following idiom
may be used to determine which of the three states a
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> currently
holds:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> b = some_operation();
if (b) {
// b is true
}
else if (!b) {
// b is false
}
else {
// b is indeterminate
}</pre>
<p> <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> supports the
3-state logic operators <code class="computeroutput">!</code> (negation),
<code class="computeroutput">&amp;&amp;</code> (AND), and <code class="computeroutput">||</code> (OR), with
<code class="computeroutput">bool</code> and <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code>
values. For instance:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x = some_op();
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> y = some_other_op();
if (x &amp;&amp; y) {
// both x and y are true
}
else if (!(x &amp;&amp; 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
}
}</pre>
<p> Similarly, <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code>
supports 3-state equality comparisons via the operators
<code class="computeroutput">==</code> and <code class="computeroutput">!=</code>. These operators differ from
"normal" equality operators in C++ because they return a
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code>, because potentially we
might not know the result of a comparison (try to compare
<code class="computeroutput">true</code> and
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>). For
instance:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x(true);
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> y(<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>);
assert(x == x); // okay, x == x returns true
assert(x == true); // okay, can compare <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code>s and bools</pre>
<p> The <code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code> keyword (representing the
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code> <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> value)
doubles as a function to check if the value of a
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> is indeterminate,
e.g.,</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x = try_to_do_something_tricky();
if (<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>(x)) {
// value of x is indeterminate
}
else {
// report success or failure of x
}</pre>
<p> All the logical operators and methods of <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> are marked
as <code class="computeroutput">constexpr</code> in C++11. It means that <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> can
be used in compile time expressions:</p>
<pre class="programlisting">constexpr <code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x = (tribool(true) || tribool(indeterminate));
<code class="computeroutput">static_assert</code>(x, "Must be true!");
</pre>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">Some compilers may have troubles with evaluating <code class="computeroutput">tribool::operator safe_bool()</code> at compile time.</td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.24.4.3"></a>Renaming the indeterminate state</h3></div></div></div>
<p> Users may introduce additional keywords for the indeterminate
value in addition to the implementation-supplied
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code> using the
<code class="computeroutput"><a class="link" href="../BOOST_TRIBOOL_THIRD_STATE.html" title="Macro BOOST_TRIBOOL_THIRD_STATE">BOOST_TRIBOOL_THIRD_STATE</a></code>
macro. For instance, the following macro instantiation (at the
global scope) will introduce the keyword <code class="computeroutput">maybe</code> as a
synonym for <code class="computeroutput"><a class="link" href="../boost/logic/indeterminate.html" title="Function indeterminate">indeterminate</a></code>
(also residing in the <code class="computeroutput">boost</code> namespace):</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../BOOST_TRIBOOL_THIRD_STATE.html" title="Macro BOOST_TRIBOOL_THIRD_STATE">BOOST_TRIBOOL_THIRD_STATE</a></code>(maybe)
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x = maybe;
if (maybe(x)) { /* ... */ }</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="id-1.3.24.4.4"></a><code class="computeroutput">tribool</code> input/output</h3></div></div></div>
<p><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> objects may be
read from and written to streams by including the
<code class="computeroutput"><a class="link" href="reference.html#header.boost.logic.tribool_io_hpp" title="Header &lt;boost/logic/tribool_io.hpp&gt;">boost/logic/tribool_io.hpp</a></code> header in a
manner very similar to <code class="computeroutput">bool</code> values. When the
<code class="computeroutput">boolalpha</code> flag is not set on the input/output stream,
the integral values 0, 1, and 2 correspond to <code class="computeroutput">tribool</code>
values <code class="computeroutput">false</code>, <code class="computeroutput">true</code>, and
<code class="computeroutput">indeterminate</code>, respectively. When
<code class="computeroutput">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:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x;
cin &gt;&gt; x; // Type "0", "1", or "2" to get false, true, or indeterminate
cout &lt;&lt; boolalpha &lt;&lt; x; // Produces "false", "true", or "indeterminate"</pre>
<p><code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></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 class="computeroutput">std::numpunct</code> facet, and the
string naming the indeterminate type is contained in the
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate_name.html" title="Class template indeterminate_name">indeterminate_name</a></code> facet. To
replace the name of the indeterminate state, you need to imbue your
stream with a local containing a
<code class="computeroutput"><a class="link" href="../boost/logic/indeterminate_name.html" title="Class template indeterminate_name">indeterminate_name</a></code> facet, e.g.:</p>
<pre class="programlisting"><code class="computeroutput"><a class="link" href="../BOOST_TRIBOOL_THIRD_STATE.html" title="Macro BOOST_TRIBOOL_THIRD_STATE">BOOST_TRIBOOL_THIRD_STATE</a></code>(maybe)
locale global;
locale test_locale(global, new <code class="computeroutput"><a class="link" href="../boost/logic/indeterminate_name.html" title="Class template indeterminate_name">indeterminate_name</a></code>&lt;char&gt;("maybe"));
cout.imbue(test_locale);
<code class="computeroutput"><a class="link" href="../boost/logic/tribool.html" title="Class tribool">tribool</a></code> x(maybe);
cout &lt;&lt; boolalpha &lt;&lt; x &lt;&lt; endl; // Prints "maybe"</pre>
<p>If you C++ standard library implementation does not support
locales, <code class="computeroutput">tribool</code> input/output will still work, but you
will be unable to customize the strings printed/parsed when
<code class="computeroutput">boolalpha</code> is set.</p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2002-2004 Douglas Gregor<p>Use, modification and distribution is subject to the Boost
Software License, Version 1.0. (See accompanying file
<code class="filename">LICENSE_1_0.txt</code> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../tribool.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tribool.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="reference.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink