EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/safe_numerics/doc/boostbook/native.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.promotion_policies.native">
  <title>native</title>

  <section>
    <title>Description</title>

    <para>This type contains the functions to return a safe type corresponding
    to the C++ type resulting from a given arithmetic operation.</para>

    <para>Usage of this policy with safe types will produce the exact same
    arithmetic results that using normal unsafe integer types will. Hence this
    policy is suitable as a drop-in replacement for these unsafe types. Its
    main function is to trap incorrect arithmetic results when using C++ for
    integer arithmetic.</para>
  </section>

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

    <para><link
    linkend="safe_numerics.promotion_policy">PromotionPolicy</link></para>

    <para>As an example of how this works consider C++ rules from section 5 of
    the standard - "usual arithmetic conversions".</para>

    <para><programlisting>void int f(int x, int y){
    auto z = x + y; // z will be of type "int"
    return z;
}</programlisting></para>

    <para>According to these rules, z will be of type int. Depending on the
    values of x and y, z may or may not contain the correct arithmetic result
    of the operation x + y.</para>

    <programlisting>using safe_int = safe&lt;int, native&gt;;
void int f(safe_int x, safe_int y){
    auto z = x + y; // z will be of type "safe_int"
    return z;
}</programlisting>
  </section>

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

    <para>The following example illustrates the <code>native</code> type being
    passed as a template parameter for the type <code>safe&lt;int&gt;</code>.
    This example is slightly contrived in that <code>safe&lt;int&gt;</code>
    has <code>native</code> as its default promotion parameter so explicitly
    using <code>native</code> is not necessary.</para>

    <programlisting>#include &lt;cassert&gt;
#include &lt;boost/numeric/safe_numerics/safe_integer.hpp&gt; 
#include &lt;boost/numeric/safe_numerics/native.hpp&gt; 
int main(){
    using namespace boost::numeric;
    // use native promotion policy where C++ standard arithmetic 
    // might lead to incorrect results
    using safe_int8 = safe&lt;std::int8_t, native&gt;;
    try{
        safe_int8 x = 127;
        safe_int8 y = 2;
        safe_int8 z;
        // rather than producing an invalid result an exception is thrown
        z = x + y;
        assert(false); // never arrive here
    }
    catch(std::exception &amp; e){
        // which we can catch here
        std::cout &lt;&lt; e.what() &lt;&lt; std::endl;
    }

    // When result is an int, C++ promotion rules guarentee 
    // that there will be no incorrect result.
    // In such cases, there is no runtime overhead from using safe types.
    safe_int8 x = 127;
    safe_int8 y = 2;
    safe&lt;int, native&gt; z; // z can now hold the result of the addition of any two 8 bit numbers
    z = x + y; // is guaranteed correct without any runtime overhead or exception.

    return 0;
}</programlisting>
  </section>

  <section>
    <title>Notes</title>

    <para>See Chapter 5, Expressions, C++ Standard</para>
  </section>

  <section>
    <title>Header</title>

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