ceph/src/boost/libs/math/doc/html/math_toolkit/fp_facets/examples.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Examples</title>
   5 <link rel="stylesheet" href="../../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
   7 <link rel="home" href="../../index.html" title="Math Toolkit 2.5.1">
   8 <link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
   9 <link rel="prev" href="reference.html" title="Reference">
  10 <link rel="next" href="portability.html" title="Portability">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="reference.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="portability.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="math_toolkit.fp_facets.examples"></a><a class="link" href="examples.html" title="Examples">Examples</a>
  28 </h3></div></div></div>
  29 <h6>
  30 <a name="math_toolkit.fp_facets.examples.h0"></a>
  31         <span class="phrase"><a name="math_toolkit.fp_facets.examples.simple_example_with_std_stringst"></a></span><a class="link" href="examples.html#math_toolkit.fp_facets.examples.simple_example_with_std_stringst">Simple
  32         example with std::stringstreams</a>
  33       </h6>
  34 <pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span>
  35 <span class="identifier">locale</span> <span class="identifier">tmp_locale</span><span class="special">(</span><span class="identifier">old_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
  36 <span class="identifier">locale</span> <span class="identifier">new_locale</span><span class="special">(</span><span class="identifier">tmp_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
  37 </pre>
  38 <pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span>
  39 <span class="identifier">ss</span><span class="special">.</span><span class="identifier">imbue</span><span class="special">(</span><span class="identifier">new_locale</span><span class="special">);</span>
  40 <span class="keyword">double</span> <span class="identifier">inf</span> <span class="special">=</span> <span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">();</span>
  41 <span class="identifier">ss</span> <span class="special">&lt;&lt;</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span>
  42 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">ss</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">==</span> <span class="string">"inf"</span><span class="special">);</span>
  43 <span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span>
  44 <span class="identifier">ss</span> <span class="special">&gt;&gt;</span> <span class="identifier">r</span><span class="special">;</span> <span class="comment">// Read back in.</span>
  45 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">inf</span> <span class="special">==</span> <span class="identifier">r</span><span class="special">);</span> <span class="comment">// Confirms that the double values really are identical.</span>
  46
  47 <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity output was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">ss</span><span class="special">.</span><span class="identifier">str</span><span class="special">()</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
  48 <span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity input was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">r</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span>
  49 <span class="comment">// But the string representation of r displayed will be the native type</span>
  50 <span class="comment">// because, when it was constructed, cout had NOT been imbued</span>
  51 <span class="comment">// with the new locale containing the nonfinite_numput facet.</span>
  52 <span class="comment">// So the cout output will be "1.#INF on MS platforms</span>
  53 <span class="comment">// and may be "inf" or other string representation on other platforms.</span>
  54 </pre>
  55 <h6>
  56 <a name="math_toolkit.fp_facets.examples.h1"></a>
  57         <span class="phrase"><a name="math_toolkit.fp_facets.examples.use_with_lexical_cast"></a></span><a class="link" href="examples.html#math_toolkit.fp_facets.examples.use_with_lexical_cast">Use with
  58         lexical_cast</a>
  59       </h6>
  60 <div class="note"><table border="0" summary="Note">
  61 <tr>
  62 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
  63 <th align="left">Note</th>
  64 </tr>
  65 <tr><td align="left" valign="top"><p>
  66           From Boost 1.48, lexical_cast no longer uses stringstreams internally,
  67           and is now able to handle infinities and NaNs natively on most platforms.
  68         </p></td></tr>
  69 </table></div>
  70 <p>
  71         Without using a new locale that contains the nonfinite facets, previous versions
  72         of <code class="computeroutput"><span class="identifier">lexical_cast</span></code> using stringstream
  73         were not portable (and often failed) if nonfinite values are found.
  74       </p>
  75 <pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span>
  76 <span class="identifier">locale</span> <span class="identifier">tmp_locale</span><span class="special">(</span><span class="identifier">old_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
  77 <span class="identifier">locale</span> <span class="identifier">new_locale</span><span class="special">(</span><span class="identifier">tmp_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
  78 </pre>
  79 <p>
  80         Although other examples imbue individual streams with the new locale, for
  81         the streams constructed inside lexical_cast, it was necesary to assign to
  82         a global locale.
  83       </p>
  84 <pre class="programlisting"><span class="identifier">locale</span><span class="special">::</span><span class="identifier">global</span><span class="special">(</span><span class="identifier">new_locale</span><span class="special">);</span>
  85 </pre>
  86 <p>
  87         <code class="computeroutput"><span class="identifier">lexical_cast</span></code> then works as
  88         expected, even with infinity and NaNs.
  89       </p>
  90 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;(</span><span class="string">"inf"</span><span class="special">);</span>
  91 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">x</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">:</span><span class="identifier">limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">());</span>
  92
  93 <span class="identifier">string</span> <span class="identifier">s</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;(</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">());</span>
  94 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">s</span> <span class="special">==</span> <span class="string">"inf"</span><span class="special">);</span>
  95 </pre>
  96 <div class="warning"><table border="0" summary="Warning">
  97 <tr>
  98 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
  99 <th align="left">Warning</th>
 100 </tr>
 101 <tr><td align="left" valign="top"><p>
 102           If you use stringstream inside your functions, you may still need to use
 103           a global locale to handle nonfinites correctly. Or you need to imbue your
 104           stringstream with suitable get and put facets.
 105         </p></td></tr>
 106 </table></div>
 107 <div class="warning"><table border="0" summary="Warning">
 108 <tr>
 109 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
 110 <th align="left">Warning</th>
 111 </tr>
 112 <tr><td align="left" valign="top"><p>
 113           You should be aware that the C++ specification does not explicitly require
 114           that input from decimal digits strings converts with rounding to the nearest
 115           representable floating-point binary value. (In contrast, decimal digits
 116           read by the compiler, for example by an assignment like <code class="computeroutput"><span class="keyword">double</span>
 117           <span class="identifier">d</span> <span class="special">=</span>
 118           <span class="number">1.234567890123456789</span></code>, are guaranteed
 119           to assign the nearest representable value to double d). This implies that,
 120           no matter how many decimal digits you provide, there is a potential uncertainty
 121           of 1 least significant bit in the resulting binary value.
 122         </p></td></tr>
 123 </table></div>
 124 <p>
 125         See <a href="http://en.wikipedia.org/wiki/Floating_point#Representable_numbers.2C_conversion_and_rounding" target="_top">conversion
 126         and rounding</a> for more information on <span class="emphasis"><em>nearest representable</em></span>
 127         and <span class="emphasis"><em>rounding</em></span> and <a href="http://www.exploringbinary.com/" target="_top">Exploring
 128         Binary</a> for much detail on input and round-tripping difficulties.
 129       </p>
 130 <p>
 131         Most iostream libraries do in fact achieve the desirable <span class="emphasis"><em>nearest
 132         representable floating-point binary value</em></span> for all values of input.
 133         However one popular STL library does not quite achieve this for 64-bit doubles.
 134         See <a href="http://connect.microsoft.com/VisualStudio/feedback/details/98770/decimal-digit-string-input-to-double-may-be-1-bit-wrong" target="_top">Decimal
 135         digit string input to double may be 1 bit wrong</a> for the bizarre full
 136         details.
 137       </p>
 138 <p>
 139         If you are expecting to 'round-trip' <code class="computeroutput"><span class="identifier">lexical_cast</span></code>
 140         or <code class="computeroutput"><span class="identifier">serialization</span></code>, for example
 141         archiving and loading, and want to be <span class="bold"><strong>absolutely certain
 142         that you will always get an exactly identical double value binary pattern</strong></span>,
 143         you should use the suggested 'workaround' below that is believed to work
 144         on all platforms.
 145       </p>
 146 <p>
 147         You should output using all potentially significant decimal digits, by setting
 148         stream precision to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span></code>, (or for the appropriate floating-point
 149         type, if not double) and crucially, <span class="bold"><strong>require <code class="computeroutput"><span class="identifier">scientific</span></code> format</strong></span>, not <code class="computeroutput"><span class="identifier">fixed</span></code> or automatic (default), for example:
 150       </p>
 151 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">output_value</span> <span class="special">=</span> <span class="identifier">any</span> <span class="identifier">value</span><span class="special">;</span>
 152 <span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">s</span><span class="special">;</span>
 153 <span class="identifier">s</span> <span class="special">&lt;&lt;</span> <span class="identifier">setprecison</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">scientific</span> <span class="special">&lt;&lt;</span> <span class="identifier">output_value</span><span class="special">;</span>
 154 <span class="identifier">s</span> <span class="special">&gt;&gt;</span> <span class="identifier">input_value</span><span class="special">;</span>
 155 </pre>
 156 <h5>
 157 <a name="math_toolkit.fp_facets.examples.h2"></a>
 158         <span class="phrase"><a name="math_toolkit.fp_facets.examples.use_with_serialization_archives"></a></span><a class="link" href="examples.html#math_toolkit.fp_facets.examples.use_with_serialization_archives">Use
 159         with serialization archives</a>
 160       </h5>
 161 <p>
 162         It is vital that the same locale is used when an archive is saved and when
 163         it is loaded. Otherwise, loading the archive may fail. By default, archives
 164         are saved and loaded with a classic C locale with a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">archive</span><span class="special">::</span><span class="identifier">codecvt_null</span></code>
 165         facet added. Normally you do not have to worry about that.
 166       </p>
 167 <p>
 168         The constructors for the archive classes, as a side-effect, imbue the stream
 169         with such a locale. However, if you want to use the facets <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
 170         with archives, then you have to manage the locale manually. That is done
 171         by calling the archive constructor with the flag <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">archive</span><span class="special">::</span><span class="identifier">no_codecvt</span></code>,
 172         thereby ensuring that the archive constructor will <span class="bold"><strong>not
 173         imbue the stream with a new locale</strong></span>.
 174       </p>
 175 <p>
 176         The following code shows how to use <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
 177         with a <code class="computeroutput"><span class="identifier">text_oarchive</span></code>.
 178       </p>
 179 <pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">default_locale</span><span class="special">(</span><span class="identifier">locale</span><span class="special">::</span><span class="identifier">classic</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">archive</span><span class="special">::</span><span class="identifier">codecvt_null</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
 180 <span class="identifier">locale</span> <span class="identifier">my_locale</span><span class="special">(</span><span class="identifier">default_locale</span><span class="special">,</span> <span class="keyword">new</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;);</span>
 181
 182 <span class="identifier">ofstream</span> <span class="identifier">ofs</span><span class="special">(</span><span class="string">"test.txt"</span><span class="special">);</span>
 183 <span class="identifier">ofs</span><span class="special">.</span><span class="identifier">imbue</span><span class="special">(</span><span class="identifier">my_locale</span><span class="special">);</span>
 184
 185 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">archive</span><span class="special">::</span><span class="identifier">text_oarchive</span> <span class="identifier">oa</span><span class="special">(</span><span class="identifier">ofs</span><span class="special">,</span> <span class="identifier">no_codecvt</span><span class="special">);</span>
 186
 187 <span class="keyword">double</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</span><span class="identifier">infinity</span><span class="special">();</span>
 188 <span class="identifier">oa</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">;</span>
 189 </pre>
 190 <p>
 191         The same method works with <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
 192         and <code class="computeroutput"><span class="identifier">text_iarchive</span></code>.
 193       </p>
 194 <p>
 195         If you use the <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
 196         with <code class="computeroutput"><span class="identifier">trap_infinity</span></code> and/or
 197         <code class="computeroutput"><span class="identifier">trap_nan</span></code> flag with a serialization
 198         archive, then you must set the exception mask of the stream. Serialization
 199         archives do not check the stream state.
 200       </p>
 201 <h6>
 202 <a name="math_toolkit.fp_facets.examples.h3"></a>
 203         <span class="phrase"><a name="math_toolkit.fp_facets.examples.other_examples"></a></span><a class="link" href="examples.html#math_toolkit.fp_facets.examples.other_examples">Other
 204         examples</a>
 205       </h6>
 206 <p>
 207         <a href="../../../../example/nonfinite_facet_simple.cpp" target="_top">nonfinite_facet_simple.cpp</a>
 208         give some more simple demonstrations of the difference between using classic
 209         C locale and constructing a C99 infinty and NaN compliant locale for input
 210         and output.
 211       </p>
 212 <p>
 213         See <a href="../../../../example/nonfinite_facet_sstream.cpp" target="_top">nonfinite_facet_sstream.cpp</a>
 214         for this example of use with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>s.
 215       </p>
 216 <p>
 217         For an example of how to enforce the MSVC 'legacy' "1.#INF" and
 218         "1.#QNAN" representations of infinity and NaNs, for input and output,
 219         see <a href="../../../../example/nonfinite_legacy.cpp" target="_top">nonfinite_legacy.cpp</a>.
 220       </p>
 221 <p>
 222         Treatment of signaling NaN is demonstrated at <a href="../../../../example/nonfinite_signaling_NaN.cpp" target="_top">../../example/nonfinite_signaling_NaN.cpp</a>
 223       </p>
 224 <p>
 225         Example <a href="../../../../example/nonfinite_loopback_ok.cpp" target="_top">../../example/nonfinite_loopback_ok.cpp</a>
 226         shows loopback works OK.
 227       </p>
 228 <p>
 229         Example <a href="../../../../example/nonfinite_num_facet.cpp" target="_top">../../example/nonfinite_num_facet.cpp</a>
 230         shows output and re-input of various finite and nonfinite values.
 231       </p>
 232 <p>
 233         A simple example of trapping nonfinite output is at <a href="../../../../example/nonfinite_num_facet_trap.cpp" target="_top">nonfinite_num_facet_trap.cpp</a>.
 234       </p>
 235 <p>
 236         A very basic example of using Boost.Archive is at <a href="../../../../example/nonfinite_serialization_archives.cpp" target="_top">../../example/nonfinite_serialization_archives.cpp</a>.
 237       </p>
 238 <p>
 239         A full demonstration of serialization by Francois Mauger is at <a href="../../../../example/nonfinite_num_facet_serialization.cpp" target="_top">../../example/nonfinite_num_facet_serialization.cpp</a>
 240       </p>
 241 </div>
 242 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 243 <td align="left"></td>
 244 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 245       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 246       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 247       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 248         Distributed under the Boost Software License, Version 1.0. (See accompanying
 249         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 250       </p>
 251 </div></td>
 252 </tr></table>
 253 <hr>
 254 <div class="spirit-nav">
 255 <a accesskey="p" href="reference.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../fp_facets.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="portability.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 256 </div>
 257 </body>
 258 </html>