...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Safe Numerics |
In C++ expressions, arguments must be of the same type. If they are not, all arguments are converted to a common type in accordance with rules of the C++ standard. For some applications of the safe numerics library, we might want conversions which are different than the standard ones. This class type implements the conversion functions that are to be used with the safe numeric type being instantiated.
int x; char y; auto z = x + y
the type of z
will be an
int
. This is a consequence for the standard rules for type
promotion for C/C++ arithmetic. A key feature of library permits one to
specify his own type promotion rules via a PromotionPolicy class.
PP |
A type that full fills the requirements of a PromotionPollicy |
T, U |
A type that is a model of the Numeric concept |
R |
An object of type modeling Numeric which can be used to construct a SafeNumeric type. |
Any operations which result in integers which cannot be represented as some Numeric type will throw an exception.These expressions return a type which can be used as the basis create a SafeNumeric type.
Expression | Return Value |
---|---|
PP::addition_result<T,
U>::type |
unspecified Numeric type |
PP::subtraction_result<T,
U>::type |
unspecified Numeric type |
PP::multiplication_result<T,
U>::type |
unspecified Numeric type |
PP::division_result<T,
U>::type |
unspecified Numeric type |
PP::modulus_result<T, U>::type |
unspecified Numeric type |
PP::comparison_result<T,
U>::type |
bool |
PP::left_shift_result<T,
U>::type |
unspecified Numeric type |
PP::right_shift_result<T,
u>::type |
unspecified Numeric type |
PP::bitwise_or_result<T,
U>::type |
unspecified Numeric type |
PP::bitwise_and_result<T,
U>::type |
unspecified Numeric type |
PP::bitwise_xor_result<T,
U>::type |
unspecified Numeric type |
The library contains a number of pre-made promotion policies:
Use the normal C/C++ expression type promotion rules.
int x; char y; auto z = x + y; // could result in overflow safe<int, native> sx; auto sz = sx + y; // standard C++ code which detects errors
Type sz will be a SafeNumeric type
based on int
. If the result exceeds the maximum value
that can be stored in an int
, an error is
detected.
The native
policy is documented in Promotion Policies -
native.
Use optimizing expression type promotion rules. These rules replace the normal C/C++ type promotion rules with other rules which are designed to result in more efficient computations. Expression types are promoted to the smallest type which can be guaranteed to hold the result without overflow. If there is no such type, the result will be checked for overflow. Consider the following example:
int x; char y; auto z = x + y; // could result in overflow safe<int, automatic> sx; auto sz = sx + y; // sz is a safe type based on long // hence sz is guaranteed not to overflow. safe_unsigned_range<1, 4> a; safe_unsigned_range<2, 4> b; auto c = a + b; // c will be a safe type with a range [3,8] and cannot overflow
Type sz will be a SafeNumeric type which is guaranteed to hold he result of x + y. In this case that will be a long int (or perhaps a long long) depending upon the compiler and machine architecture. In this case, there will be no need for any special checking on the result and there can be no overflow.
Type of c will be a signed character as that type can be guaranteed to hold the sum so no overflow checking is done.
This policy is documented in Promotion Policies - automatic
boost::numeric::cpp
Use expression type promotion rules to emulate another processor. When this policy is used, C++ type for safe integers follows the rules that a compiler on the target processor would use. This permits one to test code destined for a one processor on the another one. One situation there this can be very, very useful is when testing code destined for a micro controller which doesn't have the logging, debugging, input/output facilities of a desktop.
// specify a promotion policy to support proper emulation of // PIC 18f2520 types on the desktop using pic16_promotion = boost::numeric::cpp< 8, // char 8 bits 16, // short 16 bits 16, // int 16 bits 16, // long 16 bits 32 // long long 32 bits >; ... safe<std::uint16_t, pic16_promotion> x, y; ... x + y; // detect possible overflow on the pic.
For a complete example see Safety Critical Embedded Controller.