ceph/src/boost/libs/numeric/interval/doc/guide.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5 <head>
   6   <meta http-equiv="Content-Language" content="en-us">
   7   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   8   <link rel="stylesheet" type="text/css" href="../../../../boost.css">
   9
  10   <title>Choosing Your Own Interval Type</title>
  11 </head>
  12
  13 <body lang="en">
  14   <h1>Choosing Your Own Interval Type</h1>
  15
  16   <p>First of all, you need to select your base type. In order to obtain an
  17   useful interval type, the numbers should respect some requirements. Please
  18   refer to <a href="numbers.htm">this page</a> in order to see them. When
  19   your base type is robust enough, you can go to the next step: the choice of
  20   the policies.</p>
  21
  22   <p>As you should already know if you did not come to this page by accident,
  23   the <code>interval</code> class expect a policies argument describing the
  24   <a href="rounding.htm">rounding</a> and <a href="checking.htm">checking</a>
  25   policies. The first thing to do is to verify if the default policies are or
  26   are not adapted to your case. If your base type is not <code>float</code>,
  27   <code>double</code>, or <code>long double</code>, the default rounding
  28   policy is probably not adapted. However, by specializing
  29   <code>interval_lib::rounded_math</code> to your base type, the default
  30   rounding policy will be suitable.</p>
  31
  32   <p>The default policies define an interval type that performs precise
  33   computations (for <code>float</code>, <code>double</code>, <code>long
  34   double</code>), detects invalid numbers and throws exception each times an
  35   empty interval is created. This is a brief description and you should refer
  36   to the corresponding sections for a more precise description of the default
  37   policies. Unless you need some special behavior, this default type is
  38   usable in a lot of situations.</p>
  39
  40   <p>After having completely defined the interval type (and its policies),
  41   the only thing left to do is to verify that the constants are defined and
  42   <code>std::numeric_limits</code> is correct (if needed). Now you can use
  43   your brand new interval type.</p>
  44
  45   <h2>Some Examples</h2>
  46
  47   <h3>Solving systems</h3>
  48
  49   <p>If you use the interval library in order to solve equation and
  50   inequation systems by bisection, something like
  51   <code>boost::interval&lt;double&gt;</code> is probably what you need. The
  52   computations are precise, and they may be fast if enclosed in a protected
  53   rounding mode block (see the <a href="rounding.htm#perf">performance</a>
  54   section). The comparison are "certain"; it is probably the most used type
  55   of comparison, and the other comparisons are still accessible by the
  56   explicit comparison functions. The checking forbid empty interval; they are
  57   not needed since there would be an empty interval at end of the computation
  58   if an empty interval is created during the computation, and no root would
  59   be inside. The checking also forbid invalid numbers (NaN for floating-point
  60   numbers). It can be a minor performance hit if you only use exact
  61   floating-point constants (which are clearly not NaNs); however, if
  62   performance really does matter, you will probably use a good compiler which
  63   knows how to inline functions and all these annoying little tests will
  64   magically disappear (if not, it is time to upgrade your compiler).</p>
  65
  66   <h3>Manipulating wide intervals</h3>
  67
  68   <p>You may want to use the library on intervals with imprecise bounds or on
  69   inexact numbers. In particular, it may be an existing algorithm that you
  70   want to rewrite and simplify by using the library. In that case, you are
  71   not really interested by the inclusion property; you are only interested by
  72   the computation algorithms the library provides. So you do not need to use
  73   any rounding; the checking also may not be useful. Use an "exact
  74   computation" rounding (you are allowed to think the name strangely applies
  75   to the situation) and a checking that never tests for any invalid numbers
  76   or empty intervals. By doing that, you will obtain library functions
  77   reduced to their minimum (an addition of two intervals will only be two
  78   additions of numbers).</p>
  79
  80   <h3>Computing ranges</h3>
  81
  82   <p>The inputs of your program may be empty intervals or invalid values (for
  83   example, a database can allow undefined values in some field) and the core
  84   of your program could also do some non-arithmetic computations that do not
  85   always propagate empty intervals. For example, in the library, the
  86   <code>hull</code> function can happily receive an empty interval but not
  87   generate an empty interval if the other input is valid. The
  88   <code>intersect</code> function is also able to produce empty intervals if
  89   the intervals do not overlap. In that case, it is not really interesting if
  90   an exception is thrown each time an empty interval is produced or an
  91   invalid value is used; it would be better to generate and propagate empty
  92   intervals. So you need to change the checking policy to something like
  93   <code>interval_lib::checking_base&lt;T&gt;</code>.</p>
  94
  95   <h3>Switching interval types</h3>
  96
  97   <p>This example does not deal with a full case, but with a situation that
  98   can occur often. Sometimes, it can be useful to change the policies of an
  99   interval by converting it to another type. For example, this happens when
 100   you use an unprotected version of the interval type in order to speed up
 101   the computations; it is a change of the rounding policy. It also happens
 102   when you want to temporarily allow empty intervals to be created; it is a
 103   change of the checking policy. These changes should not be prohibited: they
 104   can greatly enhance a program (lisibility, interest, performance).</p>
 105   <hr>
 106
 107   <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
 108   "../../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
 109   height="31" width="88"></a></p>
 110
 111   <p>Revised
 112   <!--webbot bot="Timestamp" s-type="EDITED" s-format="%Y-%m-%d" startspan -->2006-12-24<!--webbot bot="Timestamp" endspan i-checksum="12172" --></p>
 113
 114   <p><i>Copyright &copy; 2002 Guillaume Melquiond, Sylvain Pion, Herv&eacute;
 115   Br&ouml;nnimann, Polytechnic University</i></p>
 116
 117   <p><i>Distributed under the Boost Software License, Version 1.0. (See
 118   accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
 119   or copy at <a href=
 120   "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
 121 </body>
 122 </html>