123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101 |
- <?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<int, native>;
- 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<int></code>.
- This example is slightly contrived in that <code>safe<int></code>
- has <code>native</code> as its default promotion parameter so explicitly
- using <code>native</code> is not necessary.</para>
- <programlisting>#include <cassert>
- #include <boost/numeric/safe_numerics/safe_integer.hpp>
- #include <boost/numeric/safe_numerics/native.hpp>
- int main(){
- using namespace boost::numeric;
- // use native promotion policy where C++ standard arithmetic
- // might lead to incorrect results
- using safe_int8 = safe<std::int8_t, native>;
- 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 & e){
- // which we can catch here
- std::cout << e.what() << 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<int, native> 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
- <boost/numeric/safe_numerics/native.hpp>
- </code></ulink></code></para>
- </section>
- </section>
|