safe_numerics/doc/boostbook/safe_unsigned_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_unsigned_range">
  <title>safe_unsigned_range&lt;boost::uintmax_t MIN, boost::uintmax_t
  MAX&gt;</title>

  <section>
    <title>Description</title>

    <para>This type holds a integer in the range [MIN, MAX]. It will throw a
    <code>std::out_of_range</code> exception for any operation which would
    result in assigning an integer value outside of this range.</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, V</code></entry>

            <entry>Types which model the <link
            linkend="safe_numerics.numeric">Numeric</link> concept</entry>
          </row>

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

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

          <row>
            <entry>sur</entry>

            <entry>object of type safe_unsigned_range</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

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

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

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

        <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 a non-negative 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 positive integer literal</entry>

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

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

            <entry>MIN &lt;= MAX</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

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

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

    <para>The usage of this type in an arithmetic expression with another
    unsigned type will result in another unsigned type fulfilling the <link
    linkend="safe_numerics.numeric">Numeric</link> concept. This will be the
    smallest unsigned integer type of sufficient size to hold the result of
    the operation.</para>
  </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>st op u</code></entry>

              <entry><link linkend="safe_numerics.numeric">typeof(t op
              u)</link></entry>

              <entry><para>op is any valid binary operator for type
              T</para></entry>
            </row>

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

              <entry><link linkend="safe_numerics.numeric">typeof(t op
              u)</link></entry>

              <entry><para>op is any valid binary operator for type
              T</para></entry>
            </row>

            <row>
              <entry><code>st op su</code></entry>

              <entry><link linkend="safe_numerics.numeric">typeof(t op
              u)</link></entry>

              <entry><para>op is any valid binary operator for type
              T</para></entry>
            </row>

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

              <entry><link
              linkend="safe_numerics.numeric">safe&lt;T&gt;</link></entry>

              <entry><para>construct a instance of safe&lt;T&gt; from
              t</para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable></para>
  </section>

  <section>
    <title>Header</title>

    <para><filename><ulink url="../../include/safe_range.hpp">#include
    &lt;safe/numeric/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_unsigned_range&lt;7, 24&gt; i;
    i = 0;  // throws out_of_range exception
    i = 9;  // ok
    i *= 9; // throws out_of_range exception
    i = -1; // throws out_of_range exception

    std::uint8_t j = 4;
    auto k = i + j;
        // since i can vary between 7 and 24 and j can vary between 0 and 255
        // the smallest unsigned integer which can hold the result std::uint16_t
        // j will be of type std::uint16_t 
    
}</programlisting>
  </section>

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

    <para><code>std::out_of_range</code></para>

    <para><code>safe_signed_range</code></para>
  </section>
</section>