safe_numerics/doc/boostbook/checked_result.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&lt;typename R&gt;</title>

  <section>
    <title>Description</title>

    <para>checked_result is a wrapper class designed to hold 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. Note that this type
    is an internal feature of the library and shouldn't be exposed to library
    users because it has some unsafe behavior.</para>
  </section>

  <section>
    <title>Template Parameters</title>

    <para>The sole template parameter is the return type of some
    operation.</para>

    <informaltable>
      <tgroup cols="4">
        <colspec align="left"/>

        <colspec align="left"/>

        <colspec align="left" colwidth="4*"/>

        <colspec align="left" colwidth="4*"/>

        <thead>
          <row>
            <entry align="left">Parameter</entry>

            <entry>Default</entry>

            <entry align="left">Type Requirements</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><code>R</code></entry>

            <entry><code/></entry>

            <entry/>

            <entry><para>The value type. </para></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Notation</title>

    <informaltable>
      <tgroup cols="2">
        <colspec align="left"/>

        <colspec align="left" colwidth="4*"/>

        <thead>
          <row>
            <entry align="left">Symbol</entry>

            <entry align="left">Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><code>C</code></entry>

            <entry>checked_result&lt;R&gt;</entry>
          </row>

          <row>
            <entry><code>c</code></entry>

            <entry>an instance of checked_result&lt;R&gt;</entry>
          </row>

          <row>
            <entry><code>t</code></entry>

            <entry>an instance of checked_result&lt;T&gt; for some type T not
            necessarily the same as R</entry>
          </row>

          <row>
            <entry><code>r</code></entry>

            <entry>An object of type R</entry>
          </row>

          <row>
            <entry><code>EP</code></entry>

            <entry><link
            linkend="safe_numerics.exception_policy">ExceptionPolicy</link></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Valid Expressions</title>

    <para>All expressions are constexpr.</para>

    <para><informaltable>
        <tgroup cols="3">
          <colspec align="left" colwidth="2*"/>

          <colspec align="left" colwidth="1*"/>

          <colspec align="left" colwidth="4*"/>

          <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&lt;R&gt;</code></entry>

              <entry>constructor with valid instance of R</entry>
            </row>

            <row>
              <entry><code>checked_result(e, msg)</code></entry>

              <entry><code>checked_result&lt;R&gt;</code></entry>

              <entry>constructor with error information</entry>
            </row>

            <row>
              <entry><code>static_cast&lt;R&gt;(c)</code></entry>

              <entry>R</entry>

              <entry>extract wrapped value - asserts if not possible</entry>
            </row>

            <row>
              <entry><code>static_cast&lt;const char *&gt;(c)</code></entry>

              <entry>R</entry>

              <entry>extract wrapped value - asserts if not possible</entry>
            </row>

            <row>
              <entry><code><simplelist>
                  <member>c &lt; t</member>

                  <member>c &gt;= t</member>

                  <member>c &gt; t</member>

                  <member>c &lt;= t</member>

                  <member>c == t</member>

                  <member>c != t</member>
                </simplelist></code></entry>

              <entry>boost::logic::tribool</entry>

              <entry>compare the wrapped values of two checked_result
              instances. If either one contains an invalid value, return
              boost::logic::tribool::indeterminant.</entry>
            </row>

            <row>
              <entry><code>c.no_exception()</code></entry>

              <entry>bool</entry>

              <entry>true if checked_result contains a valid result</entry>
            </row>

            <row>
              <entry><code>c.exception()</code></entry>

              <entry>bool</entry>

              <entry>true if checked_result contains an error
              condition</entry>
            </row>

            <row>
              <entry><code>dispatch&lt;EP&gt;(c)</code></entry>

              <entry>void</entry>

              <entry>invoke exception in accordance exception_type
              value</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable></para>
  </section>

  <section>
    <title>Header</title>

    <para><code>#include "checked_result.hpp" </code></para>
  </section>

  <section>
    <title>Example of use</title>

    <programlisting>#include "checked_result.hpp"

template&lt;class R&gt;
checked_result&lt;R&gt;
constexpr modulus(
    const R &amp; t,
    const R &amp; u
) {
    if(0 == u)
        return checked_result&lt;R&gt;(
            exception_type::domain_error,
            "denominator is zero"
        );

    return t % u;
}</programlisting>
  </section>

  <section>
    <title>See Also</title>

    <para><link
    linkend="safe_numerics.exception_policy">ExceptionPolicy</link></para>
  </section>
</section>