123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358 |
- <?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>
|