Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 538d0e11c0.
Library Documentation Index

Safe Numerics


Using Automatic Type Promotion

The C++ standard describes how binary operations on different integer types are handled. Here is a simplified version of the rules:

So the type of the result of some binary operation may be different than the types of either or both of the original operands.

If the values are large, the result can exceed the size that the resulting integer type can hold. This is what we call "overflow". The C/C++ standard characterizes this as undefined behavior and leaves to compiler implementors the decision as to how such a situation will be handled. Usually, this means just truncating the result to fit into the result type - which sometimes will make the result arithmetically incorrect. However, depending on the compiler and compile time switch settings, such cases may result in some sort of run time exception or silently producing some arbitrary result.

The complete signature for a safe integer type is:

template <
    class T,                  // underlying integer type
    class P = native,         // type promotion policy class
    class E = default_exception_policy // error handling policy class

The promotion rules for arithmetic operations are implemented in the default native type promotion policy are consistent with those of standard C++

Up until now, we've focused on detecting when an arithmetic error occurs and invoking an exception or other kind of error handler.

But now we look at another option. Using the automatic type promotion policy, we can change the rules of C++ arithmetic for safe types to something like the following:

When using the automatic type promotion policy, with a given a binary operation, we silently promote the types of the operands to a wider result type so the result cannot overflow. This is a fundamental departure from the C++ Standard behavior.

If the interval of the result cannot be guaranteed to fit in the largest type that the machine can handle (usually 64 bits these days), the largest available integer type with the correct result sign is used. So even with our "automatic" type promotion scheme, it's still possible to overflow. So while our automatic type promotion policy might eliminate exceptions in our example above, it wouldn't be guaranteed to eliminate them for all programs.

Using the loose_trap_policy exception policy will produce a compile time error anytime it's possible for an error to occur.

This small example illustrates how to use automatic type promotion to eliminate all runtime penalty.

//  Copyright (c) 2018 Robert Ramey
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at

#include <iostream>

#include <boost/safe_numerics/safe_integer.hpp>
#include <boost/safe_numerics/exception_policies.hpp>
#include <boost/safe_numerics/automatic.hpp>
#include "safe_format.hpp" // prints out range and value of any type

using safe_t = boost::safe_numerics::safe<
    boost::safe_numerics::automatic, // note use of "automatic" policy!!!

int main(int, const char *[]){
    std::cout << "example 82:\n";
    safe_t x(INT_MAX);
    safe_t y = 2;
    std::cout << "x = " << safe_format(x) << std::endl;
    std::cout << "y = " << safe_format(y) << std::endl;
    std::cout << "x + y = " << safe_format(x + y) << std::endl;
    return 0;

The above program produces the following output:

example 82:
x = <int>[-2147483648,2147483647] = 2147483647
y = <int>[-2147483648,2147483647] = 2
x + y = <long>[-4294967296,4294967294] = 2147483649

Note that if any time in the future we were to change safe<int> to safe<long long> the program could now overflow. But since we're using loose_trap_policy the modified program would fail to compile. At this point we'd have to alter our yet program again to eliminate run time penalty or set aside our goal of zero run time overhead and change the exception policy to default_exception_policy .

Note that once we use automatic type promotion, our programming language isn't C/C++ anymore. So don't be tempted to so something like the following:

#if defined(NDEBUG)
using safe_t = boost::numeric::safe<
    boost::numeric::automatic, // note use of "automatic" policy!!!
using safe_t = boost::numeric::safe<int>;