SafeNumeric<T>

Description

This holds an arithmetic value which can be used as a replacement for built-in C++ arithmetic values. These types differ from their built-in counter parts in that the are guaranteed not to produce invalid arithmetic results. These operations return safe types rather than built-in types.

Refinement of

Numeric or Integer

Notation

Symbol	Description
`T, U`	Types fulfilling Numeric or Integer type requirements.
t, u	objects of types T, U
S	A type fulfilling SafeNumeric type requirements
s, s1, s2	objects of types S
op	C++ infix operator supported by underlying type T
prefix_op	C++ prefix operator: -, +, ~, ++, -- supported by underlying type T
postfix_op	C++ postfix operator:++, -- supported by underlying type T
assign_op	C++ assignment operator

Valid Expressions

Expression	Result Type	Description
`s op t`	unspecified S	invoke C++ operator op and return another SafeNumeric type.
`t op s`	unspecified S	invoke C++ operator op and return another SafeNumeric type.
`s1 op s2`	unspecified S	invoke C++ operator op and return another SafeNumeric type.
`prefix_op S`	unspecified S	invoke C++ operator `prefix_op` and return another SafeNumeric type.
`S postfix_op`	unspecified S	invoke C++ operator `postfix_op` and return another SafeNumeric type.
`s assign_op t`	S &	convert t to type S and assign it to s.
`t assign_op s`	T &	convert s to type T and assign it to s. If the value t cannot be represented as an instance of type S, it is an error.
`S(t)`	S	construct an instance of S from a value of type T. In this case, T is referred to as the base type of S. If the value t cannot be represented as an instance of type S, it is an exception condition is invoked.
`S`	S	construct an uninitialized instance of S.
`T(s)`	T	implicit conversion of the value of s to type T. If the value of s cannot be correctly represented as a type T, an exception condition is invoked.
`static_cast<T>(s)`	T	convert the value of s to type T. If the value of s cannot be correctly represented as a type T, an exception condition is invoked.
`is_safe<S>`	`std::true_type`	type trait to query whether any type S fulfills the requirements for a SafeNumeric type.
`base_type<S>::type`	T	Retrieve the base type of a given safe type.
`base_value(s)`	T	Retrieve the value of an instance of a safe type. This is equivalent to `static_cast<base_type<S>>(s)`.

The result of any binary operation where one or both of the operands is a SafeNumeric type is also a SafeNumeric type.
All the expressions in the above table are constexpr expressions.
Binary expressions which are not assignments and whose operands are both safe types require that promotion and exception policies of the operands be identical.
Operations on safe types are supported if and only if the same operation is supported on the underlying types. For example, the binary operations |, &, ^ and ~ operations defined for safe unsigned integer types. But they are not defined for floating point types. Currently the are also defined for signed integer types. It's not clear that this is the correct decision. On one hand, usage of these operators on signed types is almost certainly an error in program logic. But trapping this as an error conflicts with the goal of making safe types "drop-in" replacements for the corresponding built-in types. In light of this, these operators are currently supported as they are for normal built-in types.
Safe Numeric types will be implicitly converted to built-in types when appropriate. Here's an example:
```
void f(int);

int main(){
    long x;
    f(x);         // OK - builtin implicit version
    safe<long> y;
    f(y);
    return 0;
}
```
This behavior supports the concept of safe<T> as being a "drop-in" replacement for a T.

Invariants

The fundamental requirement of a SafeNumeric type is that it implements all C++ operations permitted on its base type in a way the prevents the return of an incorrect arithmetic result. Various implementations of this concept may handle circumstances which produce such results differently (throw exception, compile time trap, etc..). But no implementation should return an arithmetically incorrect result.

Models

safe<T>

safe_signed_range<-11, 11>

safe_unsigned_range<0, 11>

safe_signed_literal<4>

Header

#include <boost/numeric/safe_numerics/concepts/safe_numeric.hpp>

Boost C++ Libraries

Safe Numerics