359 lines
10 KiB
XML
359 lines
10 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<section id="safenumerics.checked_result">
|
|
<title>checked_result<R></title>
|
|
|
|
<?dbhtml stop-chunking?>
|
|
|
|
<section>
|
|
<title>Description</title>
|
|
|
|
<para>checked_result is a special kind of variant class designed to hold
|
|
the result of some operation. It can hold either the result of the
|
|
operation or information on why the operation failed to produce a valid
|
|
result. It is similar to other types proposed for and/or included to the
|
|
C++ standard library or Boost such as<code> expected</code>,
|
|
<code>variant</code>, <code>optional</code> and <code>outcome</code>. In
|
|
some circumstances it may be referred to as a "monad".</para>
|
|
|
|
<para><itemizedlist>
|
|
<listitem>
|
|
<para>All instances of <code>checked_result<R></code> are
|
|
immutable. That is, once constructed, they cannot be altered.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>There is no default constructor.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><code>checked_result<R></code> is never empty.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Binary operations supported by type R are guaranteed to be
|
|
supported by checked_result<R>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Binary operations can be invoked on a pair of
|
|
<code>checked_result<R></code> instances if and only if the
|
|
underlying type (R) is identical for both instances. They will
|
|
return a value of type <code>checked_result<R></code>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Unary operations can be invoked on
|
|
<code>checked_result<R></code> instances. They will return a
|
|
value of type <code>checked_result<R></code>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Comparison operations will return a
|
|
<code>boost::logic::tribool</code>. Other binary operations will a
|
|
value of the same type as the arguments.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Think of <code>checked<R></code> as an "extended" version of R
|
|
which can hold all the values that R can hold in addition other "special
|
|
values". For example, consider checked<int>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Notation</title>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="4*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Symbol</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>R</code></entry>
|
|
|
|
<entry>Underlying type</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>r</code></entry>
|
|
|
|
<entry>An instance of type R</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>c, c1, c2</code></entry>
|
|
|
|
<entry>an instance of checked_result<R></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t</code></entry>
|
|
|
|
<entry>an instance of checked_result<T> for some type T not
|
|
necessarily the same as R</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>e</code></entry>
|
|
|
|
<entry>An instance of type <link
|
|
linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>msg</code></entry>
|
|
|
|
<entry>An instance of type const char *</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>OS</code></entry>
|
|
|
|
<entry>A type convertible to <link
|
|
linkend="safe_numerics.safe_numerics_error"><code>std::basic_ostream</code></link></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>os</code></entry>
|
|
|
|
<entry>An instance of type convertible to <link
|
|
linkend="safe_numerics.safe_numerics_error"><code>std::basic_ostream</code></link></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Template Parameters</title>
|
|
|
|
<para>R must model the type requirements of <link
|
|
linkend="safe_numerics.numeric">Numeric</link></para>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="4*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Parameter</entry>
|
|
|
|
<entry>Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>R</code></entry>
|
|
|
|
<entry>Underlying type</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Model of</title>
|
|
|
|
<para><link linkend="safe_numerics.numeric">Numeric</link></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Valid Expressions</title>
|
|
|
|
<para>All expressions are <code>constexpr</code>.</para>
|
|
|
|
<para><informaltable>
|
|
<tgroup cols="3">
|
|
<colspec align="left" colwidth="2*"/>
|
|
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Expression</entry>
|
|
|
|
<entry>Return Type</entry>
|
|
|
|
<entry>Semantics</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>checked_result(r)</code></entry>
|
|
|
|
<entry><code>checked_result<R></code></entry>
|
|
|
|
<entry>constructor with valid instance of R</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>checked_result<R>(t)</code></entry>
|
|
|
|
<entry><code>checked_result<R></code></entry>
|
|
|
|
<entry>constructor with <code>checked_result<T></code>
|
|
where T is not R. T must be convertible to R.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>checked_result(e, msg)</code></entry>
|
|
|
|
<entry><code>checked_result<R></code></entry>
|
|
|
|
<entry>constructor with error information</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>static_cast<R>(c)</code></entry>
|
|
|
|
<entry>R</entry>
|
|
|
|
<entry>extract wrapped value - compile time error if not
|
|
possible</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>static_cast<<code><link
|
|
linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></code>>(c)</code></entry>
|
|
|
|
<entry><link
|
|
linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry>
|
|
|
|
<entry>extract wrapped value - may return <link
|
|
linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link><code>::success</code>
|
|
if there is no error</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>static_cast<const char *>(c)</code></entry>
|
|
|
|
<entry><code>const char *</code></entry>
|
|
|
|
<entry>returns pointer to the included error message</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>c.exception()</code></entry>
|
|
|
|
<entry><code>bool</code></entry>
|
|
|
|
<entry>true if <code>checked_result</code> contains an error
|
|
condition.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code><simplelist>
|
|
<member>c1 < c2</member>
|
|
|
|
<member>c1 >= c2</member>
|
|
|
|
<member>c1 > c2</member>
|
|
|
|
<member>c1 <= c2</member>
|
|
|
|
<member>c1 == c2</member>
|
|
|
|
<member>c1 != c2</member>
|
|
</simplelist></code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>compare the wrapped values of two checked_result
|
|
instances. If the values are such that the result of such a
|
|
comparison cannot be reasonably defined, The result of the
|
|
comparison is
|
|
<code>boost::logic::tribool::indeterminant</code>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code><simplelist>
|
|
<member>c1 + c2</member>
|
|
|
|
<member>c1 - c2</member>
|
|
|
|
<member>c1 * c2</member>
|
|
|
|
<member>c1 / c2</member>
|
|
|
|
<member>c1 % c2</member>
|
|
|
|
<member>c1 | c2</member>
|
|
|
|
<member>c1 & c2</member>
|
|
|
|
<member>c1 ^ c2</member>
|
|
|
|
<member>c1 << c2</member>
|
|
|
|
<member>c1 >> c2</member>
|
|
</simplelist></code></entry>
|
|
|
|
<entry><code>checked_result<R></code></entry>
|
|
|
|
<entry>returns a new instance of
|
|
<code>checked_result<R>.</code></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code><simplelist>
|
|
<member>os << c</member>
|
|
</simplelist></code></entry>
|
|
|
|
<entry><code>OS</code></entry>
|
|
|
|
<entry>writes result to output stream. If the result is an error
|
|
it writes the string corresponding to the error message.
|
|
Otherwise, it writes the numeric value resulting from the
|
|
operation. Returns reference to output stream.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example of use</title>
|
|
|
|
<programlisting><xi:include href="../../example/example20.cpp"
|
|
parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>See Also</title>
|
|
|
|
<para><link
|
|
linkend="safe_numerics.exception_policy">ExceptionPolicy</link></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Header</title>
|
|
|
|
<para><ulink
|
|
url="../../include/boost/safe_numerics/checked_result.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/checked_result.hpp></code></ulink></para>
|
|
|
|
<para><ulink
|
|
url="../../include/boost/safe_numerics/checked_result_operations.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/checked_result_operations.hpp>
|
|
</code></ulink></para>
|
|
</section>
|
|
</section>
|