• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
4<section id="safe_numerics.promotion_policies.native">
5  <title>native</title>
6
7  <section>
8    <title>Description</title>
9
10    <para>This type contains the functions to return a safe type corresponding
11    to the C++ type resulting from a given arithmetic operation.</para>
12
13    <para>Usage of this policy with safe types will produce the exact same
14    arithmetic results that using normal unsafe integer types will. Hence this
15    policy is suitable as a drop-in replacement for these unsafe types. Its
16    main function is to trap incorrect arithmetic results when using C++ for
17    integer arithmetic.</para>
18  </section>
19
20  <section>
21    <title>Model of</title>
22
23    <para><link
24    linkend="safe_numerics.promotion_policy">PromotionPolicy</link></para>
25
26    <para>As an example of how this works consider C++ rules from section 5 of
27    the standard - "usual arithmetic conversions".</para>
28
29    <para><programlisting>void int f(int x, int y){
30    auto z = x + y; // z will be of type "int"
31    return z;
32}</programlisting></para>
33
34    <para>According to these rules, z will be of type int. Depending on the
35    values of x and y, z may or may not contain the correct arithmetic result
36    of the operation x + y.</para>
37
38    <programlisting>using safe_int = safe&lt;int, native&gt;;
39void int f(safe_int x, safe_int y){
40    auto z = x + y; // z will be of type "safe_int"
41    return z;
42}</programlisting>
43  </section>
44
45  <section>
46    <title>Example of use</title>
47
48    <para>The following example illustrates the <code>native</code> type being
49    passed as a template parameter for the type <code>safe&lt;int&gt;</code>.
50    This example is slightly contrived in that <code>safe&lt;int&gt;</code>
51    has <code>native</code> as its default promotion parameter so explicitly
52    using <code>native</code> is not necessary.</para>
53
54    <programlisting>#include &lt;cassert&gt;
55#include &lt;boost/numeric/safe_numerics/safe_integer.hpp&gt;
56#include &lt;boost/numeric/safe_numerics/native.hpp&gt;
57int main(){
58    using namespace boost::numeric;
59    // use native promotion policy where C++ standard arithmetic
60    // might lead to incorrect results
61    using safe_int8 = safe&lt;std::int8_t, native&gt;;
62    try{
63        safe_int8 x = 127;
64        safe_int8 y = 2;
65        safe_int8 z;
66        // rather than producing an invalid result an exception is thrown
67        z = x + y;
68        assert(false); // never arrive here
69    }
70    catch(std::exception &amp; e){
71        // which we can catch here
72        std::cout &lt;&lt; e.what() &lt;&lt; std::endl;
73    }
74
75    // When result is an int, C++ promotion rules guarentee
76    // that there will be no incorrect result.
77    // In such cases, there is no runtime overhead from using safe types.
78    safe_int8 x = 127;
79    safe_int8 y = 2;
80    safe&lt;int, native&gt; z; // z can now hold the result of the addition of any two 8 bit numbers
81    z = x + y; // is guaranteed correct without any runtime overhead or exception.
82
83    return 0;
84}</programlisting>
85  </section>
86
87  <section>
88    <title>Notes</title>
89
90    <para>See Chapter 5, Expressions, C++ Standard</para>
91  </section>
92
93  <section>
94    <title>Header</title>
95
96    <para><code><ulink
97    url="../../include/boost/safe_numerics/native.hpp"><code>#include
98    &lt;boost/numeric/safe_numerics/native.hpp&gt;
99    </code></ulink></code></para>
100  </section>
101</section>
102