safe_numerics/doc/boostbook/safe_signed_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_signed_range">
  <title>safe_signed_range&lt;MIN, MAX, PP, EP&gt;</title>

  <section>
    <title>Description</title>

    <para>This type holds a signed integer in the range [MIN, MAX]. It will
    throw a <code>std::out_of_range</code> exception for operation which would
    result in assigning an integer value outside of this range.</para>
  </section>

  <section>
    <title>Notation</title>

    <para>In addition</para>

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

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

        <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 signed values that the
            safe_signed_range can represent.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

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

        <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>Template Parameters</title>

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

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

        <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>MIN</code></entry>

            <entry>must be an integer literal</entry>

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

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

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

            <entry>The maximum 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_policy.models.native">boost::numeric::native</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_policy.models.thow_exception">boost::throw_exception</link></para></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

    <para><link linkend="safe_numerics.numeric">Integer</link></para>

    <para><link
    linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link></para>
  </section>

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

    <para>Implements all expressions and only those expressions defined by the
    <link linkend="safe_numerics.safe_numeric_concept">SafeNumeric</link> type
    requirements. This, 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>
  </section>

  <section>
    <title>Header</title>

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

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

    <programlisting>#include &lt;safe/numeric/safe_range.hpp&gt;

void f(){
    boost::numeric::safe_signed_range&lt;-7, 24&gt; i;
    // since the range is included in [-128,127], the underlying type of i 
    // will be a char.
    i = -41; // throws out_of_range exception
    i = 9;   // ok
    i = -1;  // ok
    i *= 9;  // throws out_of_range exception
    std::int8_t j = 4;
    auto k = i + j;
        // These types use default promotion policy so standard C++ type promotion rules 
        // will be used in evaluating expressions.   C++ type promotion rules mandate
        // that the result of k = i + j when both are signed char types, will be another
        // signed char type.
}</programlisting>
  </section>
</section>