safe<T, PP = boost::numeric::native, EP = boost::numeric::throw

safe<T, PP = boost::numeric::native, EP = boost::numeric::throw_exception>

Description
Notation
Associated Types
Template Parameters
Model of
Valid Expressions
Header
Examples of use

Description

A safe<T, PP , EP> can be used anywhere a type T can be used. Any expression which uses this type is guaranteed to return an arithmetically correct value or trap in some way.

Notation

Symbol	Description
`T`	Underlying type from which a safe type is being derived

Associated Types

`PP`	A type which specifies the result type of an expression using safe types.
`EP`	A type containing members which are called when a correct result cannot be returned

Template Parameters

Parameter	Type Requirements	Description
`T`	Integer<T>	The underlying type. Currently only integer types supported
`PP`	PromotionPolicy<PP>	Default value is boost::numeric::native
`EP`	Exception Policy<EP>	Default value is boost::numeric::throw_exception

See examples below.

Model of

Integer

SafeNumeric

Valid Expressions

Implements all expressions and only those expressions defined by the SafeNumeric type requirements. This, the result type of such an expression will be another safe type. The actual type of the result of such an expression will depend upon the specific promotion policy template parameter.

Header

#include <boost/safe_numerics/safe_integer.hpp>

Examples of use

The most common usage would be safe<T> which uses the default promotion and exception policies. This type is meant to be a "drop-in" replacement of the intrinsic integer types. That is, expressions involving these types will be evaluated into result types which reflect the standard rules for evaluation of C++ expressions. Should it occur that such evaluation cannot return a correct result, an exception will be thrown.

There are two aspects of the operation of this type which can be customized with a policy. The first is the result type of an arithmetic operation. C++ defines the rules which define this result type in terms of the constituent types of the operation. Here we refer to these rules a "type promotion" rules. These rules will sometimes result in a type which cannot hold the actual arithmetic result of the operation. This is the main motivation for making this library in the first place. One way to deal with this problem is to substitute our own type promotion rules for the C++ ones.

Drop-in replacement for standard integer type.

The following program will throw an exception and emit a error message at runtime if any of several events result in an incorrect arithmetic type. Behavior of this program could vary according to the machine architecture in question.

#include <exception>
#include <iostream>
#include <boost/numeric/safe.hpp>

void f(){
    using namespace boost::numeric;
    safe<int> j;
    try {
        safe<int> i;
        std::cin >> i;  // could overflow !
        j = i * i;      // could overflow
    }
    catch(std::exception & e){
       std::cout << e.what() << std::endl;
    }
    std::cout << j;
}

Guarantee correct behavior at compile time.

In some instance catching an error at run time is not sufficient. We want to be sure that the program can never fail. To achieve this, use the trap_exception exception policy rather than the default throw exception policy.

The following program will emit a compile error at any statement which might possibly result in incorrect behavior.

This is because there is no way to guarantee that the expression i * i will return an arithmetically correct result. Since we know that the program cannot compile if there is any possibility of arithmetic error, we can dispense with the exception handling used above.

#include <iostream>
#include <boost/numeric/safe.hpp>

void f(){
    using safe_int = safe<int, boost::numeric::native, boost::numeric::trap_exception>; 
    safe_int i;
    std::cin >> i;  // could throw exception here !!!
    safe_int j;
    j = i * i; // could throw exception here !!!
}

Adjust type promotion rules.

Another way to avoid arithmetic errors like overflow is to promote types to larger sizes before doing the arithmetic. This can be justified by the observe

Stepping back, we can see that many of the cases of invalid arithmetic are wouldn't exist if results types were larger. So we can avoid these problems by replacing the C++ type promotion rules for expressions with our own rules. This can be done by specifying a non-default type promotion policy automatic. The policy stores the result of an expression in the smallest size that can accommodate the largest value that an expression can yield. All the work is done at compile time - checking for exceptions necessary (input is of course an exception). The following example illustrates this.

#include <boost/numeric/safe.hpp>
#include <iostream>
void f(){
    using safe_int = safe<int, boost::numeric::automatic, boost::numeric::throw_exception>; 
    safe_int i;
    std::cin >> i; // might throw exception
    auto j = i * i; // won't ever trap - result type can hold the maximum value of i * i
    static_assert(boost::numeric::is_safe<decltype(j)>::value); // result is another safe type
    static_assert(
        std::numeric_limits<decltype(i * i)>::max() >=
        std::numeric_limits<safe_int>::max() * std::numeric_limits<safe_int>::max()
    ); // always true
}

Safe Numerics