ceph/src/boost/libs/numeric/interval/doc/comparisons.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>Comparisons</title>
  11 </head>
  12
  13 <body>
  14   <h1>Comparisons</h1>
  15
  16   <p>As was said before, the definition of the comparison operators induces a
  17   slight problem. There are many ways to define them, depending of the return
  18   type or the expected order. It is the reason why the meaning of the
  19   operators is not fixed once and for all.</p>
  20
  21   <p>The way the operators are defined could have been influenced by a
  22   policy, as it is already the case for the rounding and the checking.
  23   However, comparisons are more an external property of the the class rather
  24   than an internal one. They are meant to be locally modified, independantly
  25   of the type of the intervals.</p>
  26
  27   <p>The operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>,
  28   <code>&gt;=</code>, <code>==</code>, <code>!=</code> are defined each time;
  29   and like the arithmetic operators they can take an argument of the base
  30   type. However, due to technical limitations, this base type can only be the
  31   second argument; so the operators are unfortunately not fully symmetric.
  32   The return type is not always <code>bool</code>, since some interesting
  33   results can be achieved by using a tri-state return type. So here is the
  34   common signatures of the operators:</p>
  35   <pre>
  36 template&lt;class T, class Policies1, class Policies2&gt;
  37 return_type operator== (const interval&lt;T, Policies1&gt;&amp;, const interval&lt;T, Policies2&gt;&amp;);
  38
  39 template&lt;class T, class Policies&gt;
  40 return_type operator== (const interval&lt;T, Policies&gt;&amp;, const T&amp;);
  41 </pre>
  42
  43   <h2>vided comparisons</h2>
  44
  45   <h3>Default comparison</h3>
  46
  47   <p>If nothing is specified, the meaning of the comparison operators are an
  48   extension of the operator on the base type. More precisely, if one of the
  49   argument is invalid or empty, an exception is thrown. If the arguments are
  50   valid, the following rules are applied to determine the result of
  51   [<i>a</i>,<i>b</i>] <code>op</code> [<i>c</i>,<i>d</i>] (just consider
  52   <i>c</i> <code>==</code> <i>d</i> if the second argument is of type
  53   <code>T</code>):</p>
  54
  55   <ul>
  56     <li>if &forall; <i>x</i> &isin; [<i>a</i>,<i>b</i>] &forall; <i>y</i>
  57     &isin; [<i>c</i>,<i>d</i>] <code>(</code><i>x</i> <code>op</code>
  58     y<code>)</code>, then <code>true</code></li>
  59
  60     <li>if &forall; <i>x</i> &isin; [<i>a</i>,<i>b</i>] &forall; <i>y</i>
  61     &isin; [<i>c</i>,<i>d</i>] <code>!(</code><i>x</i> <code>op</code>
  62     y<code>)</code>, then <code>false</code></li>
  63
  64     <li>otherwise throw an exception.</li>
  65   </ul>
  66
  67   <p>This comparison allows to replace base types by interval types without
  68   changing the meaning of a program. Indeed, if no exception is thrown, the
  69   result is the same as before; and if an exception is thrown, the previous
  70   comparison was unsure and should have been rewritten.</p>
  71
  72   <h3>Other comparisons</h3>
  73
  74   <p>The other comparisons are selected by using a namespace. These
  75   namespaces are located under
  76   <code>boost::numeric::interval_lib::compare</code> and are invoked by:</p>
  77   <pre>
  78 using namespace boost::numeric::interval_lib::compare::the_comparison_to_select;
  79 </pre>
  80
  81   <p>After this line, the default meaning of the operators will have been
  82   replaced by the meaning located in the namespace. Please note that because
  83   of C++ lookup rules, it is not possible to use two namespaces one after
  84   another and they must be used in different block hierarchies. Otherwise the
  85   compiler will complain about ambiguous operators. To summarize:</p>
  86   <pre>
  87 // example 1: BAD
  88 using namespace compare1;
  89 ...
  90 using namespace compare2;
  91 ...
  92
  93 // example 2: GOOD
  94 { using namespace compare1;
  95   ...                       }
  96 { using namespace compare2;
  97   ...                       }
  98
  99 // example 3: BAD
 100 using namespace compare1;
 101 ...
 102 { using namespace compare2;
 103   ...                       }
 104 </pre>
 105
 106   <p>Now comes the list of the provided comparisons. They all are located in
 107   their respective header files under
 108   <code>&lt;boost/numeric/interval/compare/...&gt;</code>. And as for the
 109   default comparison, the operators will generally complain by throwing an
 110   exception if feed by invalid values.</p>
 111
 112   <ul>
 113     <li><code>certain</code>: this comparison is equivalent to the default
 114     scheme with the exceptional case mapped to <code>false</code>. So these
 115     operators answer <code>true</code> only when the comparison is verified
 116     for all pairs of elements.</li>
 117
 118     <li><code>possible</code>: this time, the exceptional case is mapped to
 119     <code>true</code>. The operators answer <code>true</code> as soon as the
 120     comparison is verified for a pair of elements.<br></li>
 121
 122     <li><code>lexicographic</code>: the lexicographic order (the lower bounds
 123     are first compared, and if it is not enough to know the result, the upper
 124     bounds are then compared). This order does not have a meaning in interval
 125     arithmetic. However, since it is the natural total order on pair of
 126     (totally ordered) numbers, it may be handy in some cases.</li>
 127
 128     <li><code>set</code>: the set inclusion partial order. This time, an
 129     empty interval is not considered to be invalid (but an invalid number is
 130     still invalid). <code>&lt;=</code> and <code>&lt;</code> are the subset
 131     and proper subset relations; and <code>&gt;=</code> and <code>&gt;</code>
 132     are the superset and proper superset relations.</li>
 133
 134     <li><code>tribool</code>: this comparison relies on the Boost tristate
 135     boolean library and changes the default operators so that an explicit
 136     indeterminate value is returned in the third case instead of throwing an
 137     exception.</li>
 138   </ul>
 139
 140   <h3>Exception</h3>
 141   <pre>
 142 namespace boost {
 143 namespace numeric {
 144 namespace interval_lib {
 145
 146 class comparison_error: std::runtime_error; // "boost::interval: uncertain comparison"
 147
 148 } // namespace interval_lib
 149 } // namespace numeric
 150 } // namespace boost
 151 </pre>
 152
 153   <h2>Explicit comparison functions</h2>
 154
 155   <p>In some situation, you may want to perform direct comparisons on the
 156   bounds and avoid the indeterminate case that appears with default
 157   operators. Some functions are provided for this purpose. They expect their
 158   arguments to be valid and return a result after only one comparison. Their
 159   names are composed by <code>cer</code> (for "certain", if the default
 160   comparison is true, the result is true) or <code>pos</code> (for
 161   "possible", if the default comparison is false, the result is false)
 162   followed by <code>lt</code>, <code>le</code>, <code>gt</code>,
 163   <code>ge</code>, <code>eq</code> or <code>ne</code>. They are located in
 164   <code>&lt;boost/numeric/interval/compare/explicit.hpp&gt;</code>. Each of
 165   these functions takes two parameters and returns a boolean; the parameters
 166   are expected to be valid, undefined behavior may result otherwise. For
 167   example, the definition of the "certainly less than" comparison is:</p>
 168   <pre>
 169 namespace boost {
 170 namespace numeric {
 171 namespace interval_lib {
 172
 173 template&lt;class T, class Policies1, class Policies2&gt;
 174 bool cerlt(const interval&lt;T, Policies1&gt;&amp; x, const interval&lt;T, Policies2&gt;&amp; y);
 175
 176 template&lt;class T, class Policies&gt;
 177 bool cerlt(const interval&lt;T, Policies&gt;&amp; x, const T&amp; y);
 178
 179 template&lt;class T, class Policies&gt;
 180 bool cerlt(const T&amp; x, const interval&lt;T, Policies&gt;&amp; y);
 181
 182 } // namespace interval_lib
 183 } // namespace numeric
 184 } // namespace boost
 185 </pre>
 186   <hr>
 187
 188   <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
 189   "../../../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
 190   height="31" width="88"></a></p>
 191
 192   <p>Revised
 193   <!--webbot bot="Timestamp" s-type="EDITED" s-format="%Y-%m-%d" startspan -->2006-12-24<!--webbot bot="Timestamp" endspan i-checksum="12172" --></p>
 194
 195   <p><i>Copyright &copy; 2002 Guillaume Melquiond, Sylvain Pion, Herv&eacute;
 196   Br&ouml;nnimann, Polytechnic University<br>
 197   Copyright &copy; 2003 Guillaume Melquiond</i></p>
 198
 199   <p><i>Distributed under the Boost Software License, Version 1.0. (See
 200   accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
 201   or copy at <a href=
 202   "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
 203 </body>
 204 </html>