ceph/src/boost/libs/numeric/interval/doc/numbers.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>Numbers Requirements</title>
  11 </head>
  12
  13 <body lang="en">
  14   <h1>Numbers Requirements</h1>
  15
  16   <p>What we call "number" is the base type of the <code>interval</code>
  17   class. The interval library expect a lot of properties from this base type
  18   in order to respect the inclusion property. All these properties are
  19   already detailed in the other sections of this documentation; but we will
  20   try to summarize them here.</p>
  21
  22   <h3>Ordering</h3>
  23
  24   <p>The numbers need to be supplied with an ordering. This ordering
  25   expresses itself by the operators <code>&lt; &lt;= =&gt; &gt; == !=</code>.
  26   It must be a total order (reflexivity, antisymmetry, transitivity, and each
  27   pair of numbers is ordered). So <code>complex&lt;T&gt;</code> will not be a
  28   good candidate for the base type; if you need the inclusion property of
  29   interval property, you should use <code>complex&lt; interval&lt;T&gt;
  30   &gt;</code> in place of <code>interval&lt; complex&lt;T&gt; &gt;</code>
  31   (but unfortunately, <code>complex</code> only provides specialization).</p>
  32
  33   <p>Please note that invalid numbers are not concerned by the order; it can
  34   even be conceptually better if a comparison with these invalid numbers is
  35   always <code>false</code> (except for <code>!=</code>). If your checking
  36   policy uses <code>interval_lib::checking_base</code> and your base type
  37   contains invalid numbers, then this property is needed:
  38   <code>nan!=nan</code> (here <code>nan</code> is an invalid number). If this
  39   property is not present, then you should not use <code>checking_base</code>
  40   directly.</p>
  41
  42   <p>Interval arithmetic involves a lot of comparison to zero. By default,
  43   they are done by comparing the numbers to
  44   <code>static_cast&lt;T&gt;(0)</code>. However, if the format of the numbers
  45   allows some faster comparisons when dealing with zero, the template
  46   functions in the <code>interval_lib::user</code> namespace can be
  47   specialized:</p>
  48   <pre>
  49 namespace user {
  50 template&lt;class T&gt; inline bool is_zero(T const &amp;v) { return v == static_cast&lt;T&gt;(0); }
  51 template&lt;class T&gt; inline bool is_neg (T const &amp;v) { return v &lt;  static_cast&lt;T&gt;(0); }
  52 template&lt;class T&gt; inline bool is_pos (T const &amp;v) { return v &gt;  static_cast&lt;T&gt;(0); }
  53 }
  54 </pre>
  55
  56   <h3>Numeric limits</h3>
  57
  58   <p>Another remark about the checking policy. It normally is powerful enough
  59   to handle the exceptional behavior that the basic type could induce; in
  60   particular infinite and invalid numbers (thanks to the four functions
  61   <code>pos_inf</code>, <code>neg_inf</code>, <code>nan</code> and
  62   <code>is_nan</code>). However, if you use
  63   <code>interval_lib::checking_base</code> (and the default checking policy
  64   uses it), your base type should have a correctly specialized
  65   <code>std::numeric_limits&lt;T&gt;</code>. In particular, the values
  66   <code>has_infinity</code> and <code>has_quiet_NaN</code>, and the functions
  67   <code>infinity</code> and <code>quiet_NaN</code> should be accordingly
  68   defined.</p>
  69
  70   <p>So, to summarize, if you do not rely on the default policy and do not
  71   use <code>interval_lib::checking_base</code>, it is not necessary to have a
  72   specialization of the numeric limits for your base type.</p>
  73
  74   <h3>Mathematical properties</h3>
  75
  76   <p>Ensuring the numbers are correctly ordered is not enough. The basic
  77   operators should also respect some properties depending on the order. Here
  78   they are:</p>
  79
  80   <ul>
  81     <li>0 &le; <i>x</i> &rArr; -<i>x</i> &le; 0</li>
  82
  83     <li><i>x</i> &le; <i>y</i> &rArr; -<i>y</i> &le; -<i>x</i></li>
  84
  85     <li><i>x</i> &le; <i>y</i> &rArr; <i>x</i>+<i>z</i> &le;
  86     <i>y</i>+<i>z</i></li>
  87
  88     <li><i>x</i> &le; <i>y</i> and <i>z</i> &ge; 0 &rArr;
  89     <i>x</i>&times;<i>z</i> &le; <i>y</i>&times;<i>z</i></li>
  90
  91     <li>0 &lt; <i>x</i> &le; <i>y</i> &rArr; 0 &lt; 1/<i>y</i> &le;
  92     1/<i>x</i></li>
  93   </ul>
  94
  95   <p>The previous properties are also used (and enough) for <code>abs</code>,
  96   <code>square</code> and <code>pow</code>. For all the transcendental
  97   functions (including <code>sqrt</code>), other properties are needed. These
  98   functions should have the same properties than the corresponding real
  99   functions. For example, the expected properties for <code>cos</code>
 100   are:</p>
 101
 102   <ul>
 103     <li><code>cos</code> is defined for all the valid numbers;</li>
 104
 105     <li>it is 2&pi;-periodic;</li>
 106
 107     <li><code>cos</code>(2&pi;-<i>x</i>) is equal to
 108     <code>cos</code>(<i>x</i>);</li>
 109
 110     <li><code>cos</code> is a decreasing function on [0,2&pi;].</li>
 111   </ul>
 112
 113   <h3>Rounding</h3>
 114
 115   <p>If you work with a base type and no inexact result is ever computed, you
 116   can skip the rest of this paragraph. You can also skip it if you are not
 117   interested in the inclusion property (if approximate results are enough).
 118   If you are still reading, it is probably because you want to know the basic
 119   properties the rounding policy should validate.</p>
 120
 121   <p>Whichever operation or function you consider, the following property
 122   should be respected: <code>f_down(x,y) &lt;= f(x,y) &lt;= f_up(x,y)</code>.
 123   Here, <code>f</code> denotes the infinitely precise function computed and
 124   <code>f_down</code> and <code>f_up</code> are functions which return
 125   possibly inexact values but of the correct type (the base type). If
 126   possible, they should try to return the nearest representable value, but it
 127   is not always easy.</p>
 128
 129   <h3>Constants</h3>
 130
 131   <p>In order for the trigonometric functions to correctly work, the library
 132   need to know the value of the &pi; constant (and also &pi;/2 and 2&pi;).
 133   Since these constants may not be representable in the base type, the
 134   library does not have to know the exact value: a lower bound and an upper
 135   bound are enough. If these values are not provided by the user, the default
 136   values will be used: they are integer values (so &pi; is bounded by 3 and
 137   4).</p>
 138
 139   <h3>Operators and conversions</h3>
 140
 141   <p>As explained at the beginning, the comparison operators should be
 142   defined for the base type. The rounding policy defines a lot of functions
 143   used by the interval library. So the arithmetic operators do not need to be
 144   defined for the base type (unless required by one of the predefined
 145   classes). However, there is an exception: the unary minus need to be
 146   defined. Moreover, this operator should only provide exact results; it is
 147   the reason why the rounding policy does not provide some negation
 148   functions.</p>
 149
 150   <p>The conversion from <code>int</code> to the base type needs to be
 151   defined (only a few values need to be available: -1, 0, 1, 2). The
 152   conversion the other way around is provided by the rounding policy
 153   (<code>int_down</code> and <code>int_up</code> members); and no other
 154   conversion is strictly needed. However, it may be valuable to provide as
 155   much conversions as possible in the rounding policy (<code>conv_down</code>
 156   and <code>conv_up</code> members) in order to benefit from interval
 157   conversions.</p>
 158   <hr>
 159
 160   <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
 161   "../../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
 162   height="31" width="88"></a></p>
 163
 164   <p>Revised
 165   <!--webbot bot="Timestamp" s-type="EDITED" s-format="%Y-%m-%d" startspan -->2006-12-24<!--webbot bot="Timestamp" endspan i-checksum="12172" --></p>
 166
 167   <p><i>Copyright &copy; 2002 Guillaume Melquiond, Sylvain Pion, Herv&eacute;
 168   Br&ouml;nnimann, Polytechnic University<br>
 169   Copyright &copy; 2004 Guillaume Melquiond</i></p>
 170
 171   <p><i>Distributed under the Boost Software License, Version 1.0. (See
 172   accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
 173   or copy at <a href=
 174   "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
 175 </body>
 176 </html>