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

#include <exception>
#include <iostream>
#include <safe_integer.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;
}

The term "drop-in replacement" reveals the aspiration of this library. In most cases, this aspiration is realized. In the following example, the normal implicit conversions function the same for safe integers as they do for built-in integers.

#include <boost/safe_numerics/safe_integer.hpp>
using namespace boost::safe_numerics;

int f(int i){
    return i;
}

using safe_t = safe<long>;

int main(){
    const long x = 97;
    f(x);   // OK - implicit conversion to int
    const safe_t y = 97;
    f(y);   // Also OK - checked implicit conversion to int
    return 0;
}

When the safe<long> is implicitly converted to an int when calling f, the value is checked to be sure that it is within the legal range of an int and will invoke an exception if it cannot. We can easily verify this by altering the exception handling policy in the above example to loose_trap_policy. This will invoke a compile time error on any conversion might invoke a runtime exception.

#include <boost/safe_numerics/safe_integer.hpp>
using namespace boost::safe_numerics;

int f(int i){
    return i;
}

using safe_t = safe<long, native, loose_trap_policy>;

int main(){
    const long x = 97;
    f(x);   // OK - implicit conversion to int
    const safe_t y = 97;
    f(y);   // Would be OK, but will invoke compile time error
    return 0;
}

But this raises it's own questions. We can see that in this example, the program can never fail:

The conversion can never fail because the value of 97 can always fit into an int. But the library code can't detect this and emits the checking code even though it's not necessary.

This can be addressed by using a safe_literal. A safe literal can contain one and only one value. All the functions in this library are marked constexpr. So it can be determined at compile time that conversion to an int can never fail and no runtime checking code need be emitted. Making this small change will permit the above example to run with zero runtime overhead while guaranteeing that no error can ever occur.

#include <boost/safe_numerics/safe_integer.hpp>
#include <boost/safe_numerics/safe_integer_literal.hpp>

using namespace boost::safe_numerics;

int f(int i){
    return i;
}

template<intmax_t N>
using safe_literal = safe_signed_literal<N, native, loose_trap_policy>;

int main(){
    const long x = 97;
    f(x);   // OK - implicit conversion to int
    const safe_literal<97> y;
    f(y);   // OK - y is a type with min/max = 97;
    return 0;
}

With this trivial example, such efforts would hardly be deemed necessary. But in a more complex case, perhaps including compile time arithmetic expressions, it could be much more difficult to verify that the constant is valid and/or no checking code is needed. And there is also possibility that over the life time of the application, the compile time constants might change, thus rendering any ad hoc analyse obsolete. Using safe_literal will future-proof your code against well-meaning, but code-breaking updates.

Another way to avoid arithmetic errors like overflow is to promote types to larger sizes before doing the arithmetic.

Stepping back, we can see that many of the cases of invalid arithmetic wouldn't exist if the result 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 promotion policy automatic. The policy stores the result of an expression in the smallest size type that can accommodate the largest value that an expression can yield. No checking for exceptions is necessary. The following example illustrates this.

#include <boost/safe_numerics/safe_integer.hpp>
#include <iostream>

int main(int, char[]){
    using safe_int = safe<
        int, boost::numeric::automatic, 
        boost::numeric::default_exception_policy
    >; 
    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

    return 0;
}