415 lines
11 KiB
XML
415 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<section id="safe_numerics.interval">
|
|
<title>interval<R></title>
|
|
|
|
<?dbhtml stop-chunking?>
|
|
|
|
<section>
|
|
<title>Description</title>
|
|
|
|
<para>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 <code>constexpr</code>.
|
|
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 <code>interval<R></code>
|
|
type.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Template Parameters</title>
|
|
|
|
<para>R must model the type requirements of <link
|
|
linkend="safe_numerics.numeric">Numeric</link>. Note this in principle
|
|
includes any numeric type including floating point numbers and instances
|
|
of <link
|
|
linkend="safenumerics.checked_result"><code>checked_result<R></code></link>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Notation</title>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="4*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Symbol</entry>
|
|
|
|
<entry align="left">Description</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>I</code></entry>
|
|
|
|
<entry>An interval type</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i, j</code></entry>
|
|
|
|
<entry>An instance of interval type</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>R</code></entry>
|
|
|
|
<entry>Numeric types which can be used to make an interval</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>r</code></entry>
|
|
|
|
<entry>An instance of type R</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>p</code></entry>
|
|
|
|
<entry>An instance of std::pair<R, R></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>l, u</code></entry>
|
|
|
|
<entry>Lowermost and uppermost values in an interval</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>os</code></entry>
|
|
|
|
<entry>std::basic_ostream<class CharT, class Traits =
|
|
std::char_traits<CharT>></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Associated Types</title>
|
|
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="4*"/>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><link
|
|
linkend="safenumerics.checked_result"><code>checked_result</code></link></entry>
|
|
|
|
<entry>holds either the result of an operation or information as
|
|
to why it failed</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Valid Expressions</title>
|
|
|
|
<para>Note that all expressions are constexpr.</para>
|
|
|
|
<para><informaltable>
|
|
<tgroup cols="3">
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="1*"/>
|
|
|
|
<colspec align="left" colwidth="3*"/>
|
|
|
|
<thead>
|
|
<row>
|
|
<entry align="left">Expression</entry>
|
|
|
|
<entry>Return Type</entry>
|
|
|
|
<entry>Semantics</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><code>interval<R>(l, u)</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>construct a new interval from a pair of limits</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>interval<R>(p)</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>construct a new interval from a pair of limits</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>interval<R>(i)</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>copy constructor</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>make_interval<R>()</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>return new interval with
|
|
std::numric_limits<R>::min() and
|
|
std::numric_limits<R>::max()</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>make_interval<R>(const R
|
|
&r)</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>return new interval with
|
|
std::numric_limits<R>::min() and
|
|
std::numric_limits<R>::max()</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.l</code></entry>
|
|
|
|
<entry><code>R</code></entry>
|
|
|
|
<entry>lowermost value in the interval i</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.u</code></entry>
|
|
|
|
<entry><code>R</code></entry>
|
|
|
|
<entry>uppermost value in the interval i</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.includes(j)</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>return true if interval i includes interval j</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.excludes(j)</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>return true if interval i includes interval j</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.includes(t)</code></entry>
|
|
|
|
<entry><code>bool</code></entry>
|
|
|
|
<entry>return true if interval i includes value t</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i.excludes(t)</code></entry>
|
|
|
|
<entry><code>bool</code></entry>
|
|
|
|
<entry>return true if interval i includes value t</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i + j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>add two intervals and return the result</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i - j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>subtract two intervals and return the result</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i * j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>multiply two intervals and return the result</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i / j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>divide one interval by another and return the
|
|
result</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i % j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>calculate modulus of one interval by another and return
|
|
the result</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i << j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>calculate the range that would result from shifting one
|
|
interval by another</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i >> j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>calculate the range that would result from shifting one
|
|
interval by another</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i | j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>range of values which can result from applying | to any
|
|
pair of operands from I and j</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i & j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>range of values which can result from applying & to
|
|
any pair of operands from I and j</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>i ^ j</code></entry>
|
|
|
|
<entry><code>interval<R></code></entry>
|
|
|
|
<entry>range of values which can result from applying ^ to any
|
|
pair of operands from I and j</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t < u</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>true if every element in t is less than every element in
|
|
u</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t > u</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>true if every element in t is greater than every element
|
|
in u</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t <= u</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>true if every element in t is less than or equal to every
|
|
element in u</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t >= u</code></entry>
|
|
|
|
<entry><code>boost::logic::tribool</code></entry>
|
|
|
|
<entry>true if every element in t is greater than or equal to
|
|
every element in u</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t == u</code></entry>
|
|
|
|
<entry><code>bool</code></entry>
|
|
|
|
<entry>true if limits are equal</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>t != u</code></entry>
|
|
|
|
<entry><code>bool</code></entry>
|
|
|
|
<entry>true if limits are not equal</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><code>os << i</code></entry>
|
|
|
|
<entry><code>os &</code></entry>
|
|
|
|
<entry>print interval to output stream</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example of use</title>
|
|
|
|
<programlisting>#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;
|
|
}</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Header</title>
|
|
|
|
<para><ulink
|
|
url="../../include/boost/safe_numerics/interval.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/interval.hpp></code></ulink></para>
|
|
</section>
|
|
</section>
|