Introduction

Problem
Solution
Implementation
Additional Features
Requirements
Scope

All data types, type requirements, function and meta function names are found in the name space boost::numeric . In order to make this document more readable, we have omitted this name space qualifier.

	Note
	Library code in this document resides in the name space `boost::numeric`. This name space has generally been eliminated from text, code and examples in order to avoid clutter.

This library is intended as a drop-in replacement for all built-in integer types in any program which must:

be demonstrably and verifiably correct.
detect every user error such as input, assignment, etc.
be efficient as possible subject to the constraints above.

Problem

Arithmetic operations in C++ are NOT guaranteed to yield a correct mathematical result. This feature is inherited from the early days of C. The behavior of int, unsigned int and others were designed to map closely to the underlying hardware. Computer hardware implements these types as a fixed number of bits. When the result of arithmetic operations exceeds this number of bits, the result will not be arithmetically correct. The following example illustrates this problem.

int f(int x, int y){
    // this returns an invalid result for some legal values of x and y !
    return x + y;
}

It is incumbent up the C/C++ programmer to guarantee that this behavior does not result in incorrect or unexpected operation of the program. There are no language facilities which do this. They have to be explicitly addressed in the program code. There are a number of ways to do this. See[INT32-C] seems to recommend the following approach.

int f(int x, int y){
  if (((y > 0) && (x > (INT_MAX - y))) 
  || ((y < 0) && (x < (INT_MIN - y)))) {
    /* Handle error */
  }
  return x + y;
}

This will indeed trap the error. However, it would be tedious and laborious for a programmer to do alter his code to do. Altering code in this way for all arithmetic operations would likely render the code unreadable and add another source of potential programming errors. This approach is clearly not functional when the expression is even a little more complex as is shown in the following example.

int f(int x, int y, int z){
    // this returns an invalid result for some legal values of x and y !
    return x + y * z;
}

Solution

This library implements special versions of int, unsigned, etc. which behave exactly like the original ones EXCEPT that the results of these operations are guaranteed to be either arithmetically correct or invoke an error. Using this library, the above example would be rendered as:

#include <boost/safe_numeric/safe_integer.hpp>

safe<int> f(safe<int> x, safe<int> y){
  return x + y; // throw exception if correct result cannot be returned
}

The addition expression is checked at runtime or (if possible) at compile time to trap any possible errors resulting from incorrect arithmetic behavior. This will permit one to write arithmetic expressions that cannot produce an erroneous result. Instead, one and only one of the following is guaranteed to occur.

the expression will yield the correct mathematical result
the expression will emit a compilation error.
the expression will invoke a runtime exception.

In other words, the library absolutely guarantees that no arithmetic expression will yield incorrect results.

Implementation

All facilities modern C++ are employed to minimize runtime overhead required to make this guarantee. In many cases there is no runtime overhead at all. In other cases, small changes in the program are required to eliminate the runtime overhead. The library implements special versions of int, unsigned, etc. named safe<int>, safe<unsigned int> etc. These behave exactly like the original ones EXCEPT that expressions using these types fulfill the above guarantee. These types are meant to be "drop-in" replacements for the built-in types they are meant to replace. So things which are legal - such as assigning an signed to unsigned value are not trapped at compile time - as they are legal C/C++ code - but rather checked at runtime to trap the case where this (legal) operation would lead to an arithmetically incorrect result.

Note that the library addresses arithmetical errors generated by straightforward C/C++ expressions. Some of these arithmetic errors are defined as conforming to C/C++ standard while others are not. So characterizing this library as addressing undefined behavior of C/C++ numeric expressions is misleading.

Additional Features

Operation of safe types is determined by template parameters which specify a pair of policy classes which specify the behavior for type promotion and error handling. In addition to the usage serving as a drop-in replacement for standard integer types, Users of the library can:

Select or define an exception policy class to specify handling of exceptions.
- throw exception or runtime, trap at compile time.
- trap at compiler time all operations which might fail at runtime.
- specify custom functions which should be called at runtime
Select or define a promotion policy class to alter the C++ type promotion rules. This can be used to
- use C++ native type promotion rules so that, except throwing/trapping of exceptions, programs will operate identically when using/not using safe types.
- replace C++ native promotion rules with ones which are arithmetically equivalent but minimize the need for runtime checking of arithmetic results.
- replace C++ native promotion rules with ones which emulate other machine architectures. This is designed to permit the testing of C++ code destined to be run on another machine on one's development platform. Such a situation often occurs while developing code for embedded systems.
Enforce of other program requirements using ranged integer types. The library includes types safe_..._range<Min, Max> and safe_literal(...). These types can be used to improve program correctness and performance.

Requirements

This library is composed entirely of C++ Headers. It requires a compiler compatible with the C++14 standard.

The following Boost Libraries must be installed in order to use this library

mpl
integer
config
concept checking
tribool
enable_if

In order to run the test suite, the following the Boost preprocessor library is also required.

Scope

This library currently applies only to built-in integer types. Analogous issues arise for floating point types but they are not currently addressed by this version of the library. User or Library defined types such as arbitrary precision integers can also have this problem. Extension of this library to these other types is not currently under development but may be addressed in the future. This is one reason why the library name is "safe numeric" rather than "safe integer" library.

Safe Numerics