...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 |
checked_result is a special kind of variant class designed to hold
the result of some operation. It can hold either the result of the
operation or information on why the operation failed to produce a valid
result. It is similar to other types proposed for and/or included to the
C++ standard library or Boost such as expected
,
variant
, optional
and outcome
. In
some circumstances it may be referred to as a "monad".
All instances of checked_result<R>
are
immutable. That is, once constructed, they cannot be altered.
There is no default constructor.
checked_result<R>
is never empty.
Binary operations supported by type R are guaranteed to be supported by checked_result<R>.
Binary operations can be invoked on a pair of
checked_result<R>
instances if and only if the
underlying type (R) is identical for both instances. They will
return a value of type checked_result<R>
.
Unary operations can be invoked on
checked_result<R>
instances. They will return a
value of type checked_result<R>
.
Comparison operations will return a
boost::logic::tribool
. Other binary operations will a
value of the same type as the arguments.
Think of checked<R>
as an "extended" version of R
which can hold all the values that R can hold in addition other "special
values". For example, consider checked<int>.
Symbol | Description |
---|---|
R |
Underlying type |
r |
An instance of type R |
c, c1, c2 |
an instance of checked_result<R> |
t |
an instance of checked_result<T> for some type T not necessarily the same as R |
e |
An instance of type safe_numerics_error
|
msg |
An instance of type const char * |
OS |
A type convertible to std::basic_ostream
|
os |
An instance of type convertible to std::basic_ostream
|
R must model the type requirements of Numeric
Parameter | Description |
---|---|
R |
Underlying type |
All expressions are constexpr
.
Expression | Return Type | Semantics | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
checked_result(r) |
checked_result<R> |
constructor with valid instance of R | ||||||||||
checked_result<R>(t) |
checked_result<R> |
constructor with checked_result<T>
where T is not R. T must be convertible to R. |
||||||||||
checked_result(e, msg) |
checked_result<R> |
constructor with error information | ||||||||||
static_cast<R>(c) |
R | extract wrapped value - compile time error if not possible | ||||||||||
static_cast< |
safe_numerics_error |
extract wrapped value - may return safe_numerics_error ::success
if there is no error |
||||||||||
static_cast<const char *>(c) |
const char * |
returns pointer to the included error message | ||||||||||
c.exception() |
bool |
true if checked_result contains an error
condition. |
||||||||||
|
boost::logic::tribool |
compare the wrapped values of two checked_result
instances. If either one contains an error_type value, return
boost::logic::tribool::indeterminant . |
||||||||||
|
checked_result<R> |
returns a new instance of
checked_result<R>.
|
||||||||||
|
OS |
writes result to output stream. If the result is an error it writes the string corresponding to the error message. Otherwise, it writes the numeric value resulting from the operation. Returns reference to output stream. |
#include <exception> #include <iostream> #include <boost/safe_numerics/checked_result.hpp> #include <boost/safe_numerics/checked_result_operations.hpp> int main(){ using ext_uint = boost::safe_numerics::checked_result<unsigned int>; const ext_uint x{4}; const ext_uint y{3}; // operation is a success! std::cout << "success! x - y = " << x - y; // subtraction would result in -1, and invalid result for an unsigned value std::cout << "problem: y - x = " << y - x; const ext_uint z = y - x; std::cout << "z = " << z; // sum of two negative overflows is a negative overflow. std::cout << "z + z" << z + z; return 0; }