townforge/math
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
cc
math/doc/html/math_toolkit/fp_facets/examples.html
jzmaddock 72e469da0a Update version number in docs. 
[CI SKIP]
2019-10-31 17:55:35 +00:00

260 lines
23 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Examples</title>
<link rel="stylesheet" href="../../math.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Math Toolkit 2.11.0">
<link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">
<link rel="prev" href="reference.html" title="Reference">
<link rel="next" href="portability.html" title="Portability">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.fp_facets.examples"></a><a class="link" href="examples.html" title="Examples">Examples</a>
</h3></div></div></div>
<h6>
<a name="math_toolkit.fp_facets.examples.h0"></a>
<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
example with std::stringstreams</a>
</h6>
<pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span>
<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>
<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>
</pre>
<pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span>
<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>
<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>
<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>
<span class="identifier">BOOST_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>
<span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span>
<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>
<span class="identifier">BOOST_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>
<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>
<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>
<span class="comment">// But the string representation of r displayed will be the native type</span>
<span class="comment">// because, when it was constructed, cout had NOT been imbued</span>
<span class="comment">// with the new locale containing the nonfinite_numput facet.</span>
<span class="comment">// So the cout output will be "1.#INF on MS platforms</span>
<span class="comment">// and may be "inf" or other string representation on other platforms.</span>
</pre>
<h6>
<a name="math_toolkit.fp_facets.examples.h1"></a>
<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
lexical_cast</a>
</h6>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
From Boost 1.48, lexical_cast no longer uses stringstreams internally,
and is now able to handle infinities and NaNs natively on most platforms.
</p></td></tr>
</table></div>
<p>
Without using a new locale that contains the nonfinite facets, previous versions
of <code class="computeroutput"><span class="identifier">lexical_cast</span></code> using stringstream
were not portable (and often failed) if nonfinite values are found.
</p>
<pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span>
<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>
<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>
</pre>
<p>
Although other examples imbue individual streams with the new locale, for
the streams constructed inside lexical_cast, it was necesary to assign to
a global locale.
</p>
<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>
</pre>
<p>
<code class="computeroutput"><span class="identifier">lexical_cast</span></code> then works as
expected, even with infinity and NaNs.
</p>
<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>
<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>
<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>
<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>
</pre>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
If you use stringstream inside your functions, you may still need to use
a global locale to handle nonfinites correctly. Or you need to imbue your
stringstream with suitable get and put facets.
</p></td></tr>
</table></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
You should be aware that the C++ specification does not explicitly require
that input from decimal digits strings converts with rounding to the nearest
representable floating-point binary value. (In contrast, decimal digits
read by the compiler, for example by an assignment like <code class="computeroutput"><span class="keyword">double</span>
<span class="identifier">d</span> <span class="special">=</span>
<span class="number">1.234567890123456789</span></code>, are guaranteed
to assign the nearest representable value to double d). This implies that,
no matter how many decimal digits you provide, there is a potential uncertainty
of 1 least significant bit in the resulting binary value.
</p></td></tr>
</table></div>
<p>
See <a href="http://en.wikipedia.org/wiki/Floating_point#Representable_numbers.2C_conversion_and_rounding" target="_top">conversion
and rounding</a> for more information on <span class="emphasis"><em>nearest representable</em></span>
and <span class="emphasis"><em>rounding</em></span> and <a href="http://www.exploringbinary.com/" target="_top">Exploring
Binary</a> for much detail on input and round-tripping difficulties.
</p>
<p>
Most iostream libraries do in fact achieve the desirable <span class="emphasis"><em>nearest
representable floating-point binary value</em></span> for all values of input.
However one popular STL library does not quite achieve this for 64-bit doubles.
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
digit string input to double may be 1 bit wrong</a> for the bizarre full
details.
</p>
<p>
If you are expecting to 'round-trip' <code class="computeroutput"><span class="identifier">lexical_cast</span></code>
or <code class="computeroutput"><span class="identifier">serialization</span></code>, for example
archiving and loading, and want to be <span class="bold"><strong>absolutely certain
that you will always get an exactly identical double value binary pattern</strong></span>,
you should use the suggested 'workaround' below that is believed to work
on all platforms.
</p>
<p>
You should output using all potentially significant decimal digits, by setting
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
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:
</p>
<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>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">s</span><span class="special">;</span>
<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>
<span class="identifier">s</span> <span class="special">&gt;&gt;</span> <span class="identifier">input_value</span><span class="special">;</span>
</pre>
<h5>
<a name="math_toolkit.fp_facets.examples.h2"></a>
<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
with serialization archives</a>
</h5>
<p>
It is vital that the same locale is used when an archive is saved and when
it is loaded. Otherwise, loading the archive may fail. By default, archives
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>
facet added. Normally you do not have to worry about that.
</p>
<p>
The constructors for the archive classes, as a side-effect, imbue the stream
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>
with archives, then you have to manage the locale manually. That is done
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>,
thereby ensuring that the archive constructor will <span class="bold"><strong>not
imbue the stream with a new locale</strong></span>.
</p>
<p>
The following code shows how to use <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
with a <code class="computeroutput"><span class="identifier">text_oarchive</span></code>.
</p>
<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>
<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>
<span class="identifier">ofstream</span> <span class="identifier">ofs</span><span class="special">(</span><span class="string">"test.txt"</span><span class="special">);</span>
<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>
<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>
<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>
<span class="identifier">oa</span> <span class="special">&amp;</span> <span class="identifier">x</span><span class="special">;</span>
</pre>
<p>
The same method works with <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
and <code class="computeroutput"><span class="identifier">text_iarchive</span></code>.
</p>
<p>
If you use the <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
with <code class="computeroutput"><span class="identifier">trap_infinity</span></code> and/or
<code class="computeroutput"><span class="identifier">trap_nan</span></code> flag with a serialization
archive, then you must set the exception mask of the stream. Serialization
archives do not check the stream state.
</p>
<h6>
<a name="math_toolkit.fp_facets.examples.h3"></a>
<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
examples</a>
</h6>
<p>
<a href="../../../../example/nonfinite_facet_simple.cpp" target="_top">nonfinite_facet_simple.cpp</a>
give some more simple demonstrations of the difference between using classic
C locale and constructing a C99 infinty and NaN compliant locale for input
and output.
</p>
<p>
See <a href="../../../../example/nonfinite_facet_sstream.cpp" target="_top">nonfinite_facet_sstream.cpp</a>
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.
</p>
<p>
For an example of how to enforce the MSVC 'legacy' "1.#INF" and
"1.#QNAN" representations of infinity and NaNs, for input and output,
see <a href="../../../../example/nonfinite_legacy.cpp" target="_top">nonfinite_legacy.cpp</a>.
</p>
<p>
Treatment of signaling NaN is demonstrated at <a href="../../../../example/nonfinite_signaling_NaN.cpp" target="_top">../../example/nonfinite_signaling_NaN.cpp</a>
</p>
<p>
Example <a href="../../../../example/nonfinite_loopback_ok.cpp" target="_top">../../example/nonfinite_loopback_ok.cpp</a>
shows loopback works OK.
</p>
<p>
Example <a href="../../../../example/nonfinite_num_facet.cpp" target="_top">../../example/nonfinite_num_facet.cpp</a>
shows output and re-input of various finite and nonfinite values.
</p>
<p>
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>.
</p>
<p>
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>.
</p>
<p>
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>
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2006-2019 Nikhar
Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
R&#229;de, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
Daryle Walker and Xiaogang Zhang<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
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>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<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>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink