PromotionPolicy<PP>

Description
Notation
Valid Expressions
Models
Header

Description

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.

Notation

`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.

Valid Expressions

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

Models

The library contains a number of pre-made promotion policies:

boost::numeric::native

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.
boost::numeric::automatic

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.

Header

#include <boost/safe_numerics/concepts/promotion_policy.hpp>

Safe Numerics