1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN" 3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<section id="safe_numerics.interval"> 5 <title>interval<R></title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>A closed arithmetic interval represented by a pair of elements of 13 type R. In principle, one should be able to use Boost.Interval library for 14 this. But the functions in this library are not <code>constexpr</code>. 15 Also, this Boost.Interval is more complex and does not support certain 16 operations such bit operations. Perhaps some time in the future, 17 Boost.Interval will be used instead of this <code>interval<R></code> 18 type.</para> 19 </section> 20 21 <section> 22 <title>Template Parameters</title> 23 24 <para>R must model the type requirements of <link 25 linkend="safe_numerics.numeric">Numeric</link>. Note this in principle 26 includes any numeric type including floating point numbers and instances 27 of <link 28 linkend="safenumerics.checked_result"><code>checked_result<R></code></link>.</para> 29 </section> 30 31 <section> 32 <title>Notation</title> 33 34 <informaltable> 35 <tgroup cols="2"> 36 <colspec align="left" colwidth="1*"/> 37 38 <colspec align="left" colwidth="4*"/> 39 40 <thead> 41 <row> 42 <entry align="left">Symbol</entry> 43 44 <entry align="left">Description</entry> 45 </row> 46 </thead> 47 48 <tbody> 49 <row> 50 <entry><code>I</code></entry> 51 52 <entry>An interval type</entry> 53 </row> 54 55 <row> 56 <entry><code>i, j</code></entry> 57 58 <entry>An instance of interval type</entry> 59 </row> 60 61 <row> 62 <entry><code>R</code></entry> 63 64 <entry>Numeric types which can be used to make an interval</entry> 65 </row> 66 67 <row> 68 <entry><code>r</code></entry> 69 70 <entry>An instance of type R</entry> 71 </row> 72 73 <row> 74 <entry><code>p</code></entry> 75 76 <entry>An instance of std::pair<R, R></entry> 77 </row> 78 79 <row> 80 <entry><code>l, u</code></entry> 81 82 <entry>Lowermost and uppermost values in an interval</entry> 83 </row> 84 85 <row> 86 <entry><code>os</code></entry> 87 88 <entry>std::basic_ostream<class CharT, class Traits = 89 std::char_traits<CharT>></entry> 90 </row> 91 </tbody> 92 </tgroup> 93 </informaltable> 94 </section> 95 96 <section> 97 <title>Associated Types</title> 98 99 <informaltable> 100 <tgroup cols="2"> 101 <colspec align="left" colwidth="1*"/> 102 103 <colspec align="left" colwidth="4*"/> 104 105 <tbody> 106 <row> 107 <entry><link 108 linkend="safenumerics.checked_result"><code>checked_result</code></link></entry> 109 110 <entry>holds either the result of an operation or information as 111 to why it failed</entry> 112 </row> 113 </tbody> 114 </tgroup> 115 </informaltable> 116 </section> 117 118 <section> 119 <title>Valid Expressions</title> 120 121 <para>Note that all expressions are constexpr.</para> 122 123 <para><informaltable> 124 <tgroup cols="3"> 125 <colspec align="left" colwidth="1*"/> 126 127 <colspec align="left" colwidth="1*"/> 128 129 <colspec align="left" colwidth="3*"/> 130 131 <thead> 132 <row> 133 <entry align="left">Expression</entry> 134 135 <entry>Return Type</entry> 136 137 <entry>Semantics</entry> 138 </row> 139 </thead> 140 141 <tbody> 142 <row> 143 <entry><code>interval<R>(l, u)</code></entry> 144 145 <entry><code>interval<R></code></entry> 146 147 <entry>construct a new interval from a pair of limits</entry> 148 </row> 149 150 <row> 151 <entry><code>interval<R>(p)</code></entry> 152 153 <entry><code>interval<R></code></entry> 154 155 <entry>construct a new interval from a pair of limits</entry> 156 </row> 157 158 <row> 159 <entry><code>interval<R>(i)</code></entry> 160 161 <entry><code>interval<R></code></entry> 162 163 <entry>copy constructor</entry> 164 </row> 165 166 <row> 167 <entry><code>make_interval<R>()</code></entry> 168 169 <entry><code>interval<R></code></entry> 170 171 <entry>return new interval with 172 std::numric_limits<R>::min() and 173 std::numric_limits<R>::max()</entry> 174 </row> 175 176 <row> 177 <entry><code>make_interval<R>(const R 178 &r)</code></entry> 179 180 <entry><code>interval<R></code></entry> 181 182 <entry>return new interval with 183 std::numric_limits<R>::min() and 184 std::numric_limits<R>::max()</entry> 185 </row> 186 187 <row> 188 <entry><code>i.l</code></entry> 189 190 <entry><code>R</code></entry> 191 192 <entry>lowermost value in the interval i</entry> 193 </row> 194 195 <row> 196 <entry><code>i.u</code></entry> 197 198 <entry><code>R</code></entry> 199 200 <entry>uppermost value in the interval i</entry> 201 </row> 202 203 <row> 204 <entry><code>i.includes(j)</code></entry> 205 206 <entry><code>boost::logic::tribool</code></entry> 207 208 <entry>return true if interval i includes interval j</entry> 209 </row> 210 211 <row> 212 <entry><code>i.excludes(j)</code></entry> 213 214 <entry><code>boost::logic::tribool</code></entry> 215 216 <entry>return true if interval i includes interval j</entry> 217 </row> 218 219 <row> 220 <entry><code>i.includes(t)</code></entry> 221 222 <entry><code>bool</code></entry> 223 224 <entry>return true if interval i includes value t</entry> 225 </row> 226 227 <row> 228 <entry><code>i.excludes(t)</code></entry> 229 230 <entry><code>bool</code></entry> 231 232 <entry>return true if interval i includes value t</entry> 233 </row> 234 235 <row> 236 <entry><code>i + j</code></entry> 237 238 <entry><code>interval<R></code></entry> 239 240 <entry>add two intervals and return the result</entry> 241 </row> 242 243 <row> 244 <entry><code>i - j</code></entry> 245 246 <entry><code>interval<R></code></entry> 247 248 <entry>subtract two intervals and return the result</entry> 249 </row> 250 251 <row> 252 <entry><code>i * j</code></entry> 253 254 <entry><code>interval<R></code></entry> 255 256 <entry>multiply two intervals and return the result</entry> 257 </row> 258 259 <row> 260 <entry><code>i / j</code></entry> 261 262 <entry><code>interval<R></code></entry> 263 264 <entry>divide one interval by another and return the 265 result</entry> 266 </row> 267 268 <row> 269 <entry><code>i % j</code></entry> 270 271 <entry><code>interval<R></code></entry> 272 273 <entry>calculate modulus of one interval by another and return 274 the result</entry> 275 </row> 276 277 <row> 278 <entry><code>i << j</code></entry> 279 280 <entry><code>interval<R></code></entry> 281 282 <entry>calculate the range that would result from shifting one 283 interval by another</entry> 284 </row> 285 286 <row> 287 <entry><code>i >> j</code></entry> 288 289 <entry><code>interval<R></code></entry> 290 291 <entry>calculate the range that would result from shifting one 292 interval by another</entry> 293 </row> 294 295 <row> 296 <entry><code>i | j</code></entry> 297 298 <entry><code>interval<R></code></entry> 299 300 <entry>range of values which can result from applying | to any 301 pair of operands from I and j</entry> 302 </row> 303 304 <row> 305 <entry><code>i & j</code></entry> 306 307 <entry><code>interval<R></code></entry> 308 309 <entry>range of values which can result from applying & to 310 any pair of operands from I and j</entry> 311 </row> 312 313 <row> 314 <entry><code>i ^ j</code></entry> 315 316 <entry><code>interval<R></code></entry> 317 318 <entry>range of values which can result from applying ^ to any 319 pair of operands from I and j</entry> 320 </row> 321 322 <row> 323 <entry><code>t < u</code></entry> 324 325 <entry><code>boost::logic::tribool</code></entry> 326 327 <entry>true if every element in t is less than every element in 328 u</entry> 329 </row> 330 331 <row> 332 <entry><code>t > u</code></entry> 333 334 <entry><code>boost::logic::tribool</code></entry> 335 336 <entry>true if every element in t is greater than every element 337 in u</entry> 338 </row> 339 340 <row> 341 <entry><code>t <= u</code></entry> 342 343 <entry><code>boost::logic::tribool</code></entry> 344 345 <entry>true if every element in t is less than or equal to every 346 element in u</entry> 347 </row> 348 349 <row> 350 <entry><code>t >= u</code></entry> 351 352 <entry><code>boost::logic::tribool</code></entry> 353 354 <entry>true if every element in t is greater than or equal to 355 every element in u</entry> 356 </row> 357 358 <row> 359 <entry><code>t == u</code></entry> 360 361 <entry><code>bool</code></entry> 362 363 <entry>true if limits are equal</entry> 364 </row> 365 366 <row> 367 <entry><code>t != u</code></entry> 368 369 <entry><code>bool</code></entry> 370 371 <entry>true if limits are not equal</entry> 372 </row> 373 374 <row> 375 <entry><code>os << i</code></entry> 376 377 <entry><code>os &</code></entry> 378 379 <entry>print interval to output stream</entry> 380 </row> 381 </tbody> 382 </tgroup> 383 </informaltable></para> 384 </section> 385 386 <section> 387 <title>Example of use</title> 388 389 <programlisting>#include <iostream> 390#include <cstdint> 391#include <cassert> 392#include <boost/numeric/safe_numerics/interval.hpp> 393 394int main(){ 395 std::cout << "test1" << std::endl; 396 interval<std::int16_t> x = {-64, 63}; 397 std::cout << "x = " << x << std::endl; 398 interval<std::int16_t> y(-128, 126); 399 std::cout << "y = " << y << std::endl; 400 assert(static_cast<interval<std::int16_t>>(add<std::int16_t>(x,x)) == y); 401 std::cout << "x + x =" << add<std::int16_t>(x, x) << std::endl; 402 std::cout << "x - x = " << subtract<std::int16_t>(x, x) << std::endl; 403 return 0; 404}</programlisting> 405 </section> 406 407 <section> 408 <title>Header</title> 409 410 <para><ulink 411 url="../../include/boost/safe_numerics/interval.hpp"><code>#include 412 <boost/numeric/safe_numerics/interval.hpp></code></ulink></para> 413 </section> 414</section> 415