safe_numerics/doc/boostbook/safe_numeric_concept.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="safe_numerics.safe_numeric_concept">
  <title>SafeNumeric&lt;T&gt;</title>

  <section>
    <title>Description</title>

    <para>This holds an arithmetic value which can be used as a replacement
    for built-in C++ arithmetic values. These types differ from their built-in
    counter parts in that the ar guarenteed not to produce invalid arithemetic
    results.</para>
  </section>

  <section>
    <title>Refinement of</title>

    <para><link linkend="safe_numerics.numeric">Numeric</link></para>
  </section>

  <section>
    <title>Notation</title>

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

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

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

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

        <tbody>
          <row>
            <entry><code>T, U</code></entry>

            <entry>Underlying <link
            linkend="safe_numerics.numeric">Numeric</link> type from which a
            safe type is being derived</entry>
          </row>

          <row>
            <entry>t, u</entry>

            <entry>objects of types T</entry>
          </row>

          <row>
            <entry>S</entry>

            <entry>A type fullfilling a SafeNumeric type requirements</entry>
          </row>

          <row>
            <entry>s, s1, s2</entry>

            <entry>objects of types S</entry>
          </row>

          <row>
            <entry>op</entry>

            <entry>C++ infix operator</entry>
          </row>

          <row>
            <entry>prefix_op</entry>

            <entry>C++ prefix operator</entry>
          </row>

          <row>
            <entry>postfix_op</entry>

            <entry>C++ postix operator</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Associated Types</title>

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

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

        <tbody>
          <row>
            <entry><code>PP</code></entry>

            <entry>A type which specifes the result type of an expression
            using safe types.</entry>
          </row>

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

            <entry>A type containing members which are called when a correct
            result cannot be returned</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

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

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

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

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

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

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

          <tbody>
            <row>
              <entry><code>s op u</code></entry>

              <entry>unspecified S</entry>

              <entry><para>invoke C++ operator op and return another
              SafeNumeric type</para></entry>
            </row>

            <row>
              <entry><code>t op s</code></entry>

              <entry>unspecified S</entry>

              <entry><para>invoke C++ operator op and return another
              SafeNumeric type</para></entry>
            </row>

            <row>
              <entry><code>s1 op s2</code></entry>

              <entry>unspecified S</entry>

              <entry><para>invoke C++ operator op and return another
              SafeNumeric type</para></entry>
            </row>

            <row>
              <entry><code>s(t)</code></entry>

              <entry>unspecified S</entry>

              <entry><para>construct a instance of S from t</para></entry>
            </row>

            <row>
              <entry><code>s</code></entry>

              <entry>S</entry>

              <entry><para>construct a unitiaized instance of S</para></entry>
            </row>

            <row>
              <entry><code>prefix_op S</code></entry>

              <entry>unspecified S</entry>

              <entry><para>invoke C++ operator op and return another
              SafeNumeric type</para></entry>
            </row>

            <row>
              <entry><code>S postfix_op</code></entry>

              <entry>unspecified S</entry>

              <entry><para>invoke C++ operator op and return another
              SafeNumeric type</para></entry>
            </row>

            <row>
              <entry><code>is_safe&lt;S&gt;</code></entry>

              <entry>std::true_type or std::false_type</entry>

              <entry><para>type trait to query whether any type T fullfills
              the requirments for a SafeNumeric type.</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable></para>
  </section>

  <section>
    <title>Complexity Guarentees</title>

    <para>There are no explicit complexity guarentees here. However, it would
    be very surprising if any implementation were to be more complex that
    O(0);</para>
  </section>

  <section>
    <title>Invariants</title>

    <para>The fundamental requirement of a SafeNumeric type is that implements
    all C++ operations permitted on it's base type in a way the prevents the
    return of an incorrect arithmetic result. Various implementations of this
    concept may handle circumstances which produce such results differently (
    throw exception, compile time trap, etc..) no implementation should return
    an arithmetically incorrect result.</para>
  </section>

  <section>
    <title>Header</title>

    <para>[A link to the source code where the concept checking header is
    defined. This header should contain boost concept checking class for this
    concept]</para>

    <para><ulink
    url="../../include/concept/exception_policy.hpp"><code>#include
    &lt;safe_numerics/include/concepts/safe_numeric_policy.hpp&gt;
    </code></ulink></para>
  </section>

  <section>
    <title>Models</title>

    <para>boost::numeric::safe&lt;T&gt;</para>

    <para>boost::numeric::safe_signed_range&lt;T&gt;</para>

    <para>boost::numeric::safe_unsigned_range&lt;T&gt;</para>
  </section>
</section>