safe_numerics/doc/boostbook/safe_range.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_range">
  <title>safe_signed_range&lt;MIN, MAX, PP, EP&gt; and
  safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</title>

  <?dbhtml stop-chunking?>

  <section>
    <title>Description</title>

    <para>This type holds a signed or unsigned integer in the closed range
    [MIN, MAX]. A <code>safe_signed_range&lt;MIN, MAX, PP, EP&gt;</code> or
    <code>safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</code> can be used
    anywhere an arithmetic type is permitted. Any expression which uses either
    of these types is guaranteed to return an arithmetically correct value or
    to trap in some way.</para>
  </section>

  <section>
    <title>Notation</title>

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

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

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

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

        <tbody>
          <row>
            <entry><code>MIN, MAX</code></entry>

            <entry>Minimum and maximum values that the range can
            represent.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            <entry><link
            linkend="safe_numerics.integer_concept">std::is_integer&lt;T&gt;</link></entry>

            <entry><para>The underlying type. Currently only built-in integer
            types are supported</para></entry>
          </row>

          <row>
            <entry><code>MIN</code></entry>

            <entry>must be a non-negative literal</entry>

            <entry>The minimum non-negative integer value that this type may
            hold</entry>
          </row>

          <row>
            <entry><code>MAX</code></entry>

            <entry>must be a non-negative literal</entry>

            <entry>The maximum non-negative integer value that this type may
            hold</entry>
          </row>

          <row>
            <entry/>

            <entry>MIN &lt;= MAX</entry>

            <entry>must be a valid closed range</entry>
          </row>

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

            <entry><link linkend="safe_numerics.numeric"><link
            linkend="safe_numerics.promotion_policy">PromotionPolicy&lt;PP&gt;</link></link></entry>

            <entry><para>Default value is <link
            linkend="safe_numerics.promotion_policies.native"><code>boost::numeric::native</code></link></para></entry>
          </row>

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

            <entry><link linkend="safe_numerics.numeric"><link
            linkend="safe_numerics.exception_policy">Exception
            Policy&lt;EP&gt;</link></link></entry>

            <entry><para>Default value is <link
            linkend="safe_numerics.exception_policies.default_exception_policy"><code>boost::numeric::default_exception_policy</code></link></para></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>Model of</title>

    <para><link linkend="safe_numerics.numeric_concept">Numeric</link></para>

    <para><link linkend="safe_numerics.integer_concept">Integer</link></para>
  </section>

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

    <para>Implements all expressions and only those expressions supported by
    the base type T. Note that all these expressions are
    <code>constexpr</code>. The result type of such an expression will be
    another safe type. The actual type of the result of such an expression
    will depend upon the specific promotion policy template parameter.</para>

    <para>When a binary operand is applied to two instances of A
    <code>safe_signed_range&lt;MIN, MAX, PP, EP&gt;</code> or
    <code>safe_unsigned_range&lt;MIN, MAX, PP, EP&gt;</code> one of the
    following must be true:<itemizedlist>
        <listitem>
          <para>The promotion policies of the two operands must be the same or
          one of them must be void</para>
        </listitem>

        <listitem>
          <para>The exception policies of the two operands must be the same or
          one of them must be void</para>
        </listitem>
      </itemizedlist>If either of the above is not true, a compile error will
    result.</para>
  </section>

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

    <programlisting><xi:include href="../../example/example19.cpp"
        parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting>
  </section>

  <section>
    <title>Header</title>

    <para><filename><ulink
    url="../../include/boost/safe_numerics/safe_integer_range.hpp">#include
    &lt;boost/numeric/safe_numerics/safe_range.hpp&gt;</ulink></filename></para>
  </section>
</section>