| ## Safe Numerics

#### native

##### Description

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

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.

##### Model of

PromotionPolicy

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

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

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.

    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;
    }

##### Example of use

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

    #include <cassert>
    #include <boost/safe_numerics/safe_integer.hpp>
    #include <boost/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;
    }

##### Notes

See Chapter 5, Expressions, C++ Standard

##### Header

``#include <boost/numeric/safe_numerics/native.hpp>``