| ## Safe Numerics

### interval<R>

#### Description

A closed arithmetic interval represented by a pair of elements of type R. In principle, one should be able to use Boost.Interval library for this. But the functions in this library are not `constexpr`. Also, this Boost.Interval is more complex and does not support certain operations such bit operations. Perhaps some time in the future, Boost.Interval will be used instead of this `interval<R>` type.

#### Template Parameters

R must model the type requirements of Numeric. Note this in principle includes any numeric type including floating point numbers and instances of `checked_result<R>`.

#### Notation

Symbol | Description
--- | ---
`I` | An interval type
`i, j` | An instance of interval type
`R` | Numeric types which can be used to make an interval
`r` | An instance of type R
`p` | An instance of std::pair<R, R>
`l, u` | Lowermost and uppermost values in an interval
`os` | std::basic_ostream<class CharT, class Traits = std::char_traits<CharT>>

#### Associated Types

`checked_result` | holds either the result of an operation or information as to why it failed

#### Valid Expressions

Note that all expressions are constexpr.

Expression | Return Type | Semantics
--- | --- | ---
`interval<R>(l, u)` | `interval<R>` | construct a new interval from a pair of limits
`interval<R>(p)` | `interval<R>` | construct a new interval from a pair of limits
`interval<R>(i)` | `interval<R>` | copy constructor
`make_interval<R>()` | `interval<R>` | return new interval with std::numric_limits<R>::min() and std::numric_limits<R>::max()
`make_interval<R>(const R &r)` | `interval<R>` | return new interval with std::numric_limits<R>::min() and std::numric_limits<R>::max()
`i.l` | `R` | lowermost value in the interval i
`i.u` | `R` | uppermost value in the interval i
`i.includes(j)` | `boost::logic::tribool` | return true if interval i includes interval j
`i.excludes(j)` | `boost::logic::tribool` | return true if interval i includes interval j
`i.includes(t)` | `bool` | return true if interval i includes value t
`i.excludes(t)` | `bool` | return true if interval i includes value t
`i + j` | `interval<R>` | add two intervals and return the result
`i - j` | `interval<R>` | subtract two intervals and return the result
`i * j` | `interval<R>` | multiply two intervals and return the result
`i / j` | `interval<R>` | divide one interval by another and return the result
`i % j` | `interval<R>` | calculate modulus of one interval by another and return the result
`i << j` | `interval<R>` | calculate the range that would result from shifting one interval by another
`i >> j` | `interval<R>` | calculate the range that would result from shifting one interval by another
`i | j` | `interval<R>` | range of values which can result from applying | to any pair of operands from I and j
`i & j` | `interval<R>` | range of values which can result from applying & to any pair of operands from I and j
`i ^ j` | `interval<R>` | range of values which can result from applying ^ to any pair of operands from I and j
`t < u` | `boost::logic::tribool` | true if every element in t is less than every element in u
`t > u` | `boost::logic::tribool` | true if every element in t is greater than every element in u
`t <= u` | `boost::logic::tribool` | true if every element in t is less than or equal to every element in u
`t >= u` | `boost::logic::tribool` | true if every element in t is greater than or equal to every element in u
`t == u` | `bool` | true if limits are equal
`t != u` | `bool` | true if limits are not equal
`os << i` | `os &` | print interval to output stream

#### Example of use

    #include <iostream>
    #include <cstdint>
    #include <cassert>
    #include <boost/numeric/safe_numerics/interval.hpp>

    int main(){
        std::cout << "test1" << std::endl;
        interval<std::int16_t> x = {-64, 63};
        std::cout << "x = " << x << std::endl;
        interval<std::int16_t> y(-128, 126);
        std::cout << "y = " << y << std::endl;
        assert(static_cast<interval<std::int16_t>>(add<std::int16_t>(x,x)) == y);
        std::cout << "x + x =" << add<std::int16_t>(x, x) << std::endl;
        std::cout << "x - x = " << subtract<std::int16_t>(x, x) << std::endl;
        return 0;
    }

#### Header

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