| ## Safe Numerics

### checked_result<R>

#### Description

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

#### Notation

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`

#### Template Parameters

R must model the type requirements of Numeric

Parameter | Description
--- | ---
`R` | Underlying type

#### Model of

Numeric

#### Valid Expressions

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``>(c)` | `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.
`
c1 < c2
c1 >= c2
c1 > c2
c1 <= c2
c1 == c2
c1 != c2
` | `boost::logic::tribool` | compare the wrapped values of two checked_result instances. If the values are such that the result of such a comparison cannot be reasonably defined, The result of the comparison is `boost::logic::tribool::indeterminant`.
`
c1 + c2
c1 - c2
c1 * c2
c1 / c2
c1 % c2
c1 | c2
c1 & c2
c1 ^ c2
c1 << c2
c1 >> c2
` | `checked_result<R>` | returns a new instance of `checked_result<R>.`
`
os << c
` | `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.

#### Example of use

    //  Copyright (c) 2018 Robert Ramey
    //
    // Distributed under the Boost Software License, Version 1.0. (See
    // accompanying file LICENSE_1_0.txt or copy at
    // http://www.boost.org/LICENSE_1_0.txt)

    #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;
    }

#### See Also

ExceptionPolicy

#### Header

`#include <boost/numeric/safe_numerics/checked_result.hpp>`

`#include <boost/numeric/safe_numerics/checked_result_operations.hpp>`