| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Introduction</title> |
| <link rel="stylesheet" href="../../math.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.77.1"> |
| <link rel="home" href="../../index.html" title="Math Toolkit 2.2.0"> |
| <link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs"> |
| <link rel="prev" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs"> |
| <link rel="next" href="reference.html" title="Reference"> |
| </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="../fp_facets.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="reference.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.facets_intro"></a><a class="link" href="facets_intro.html" title="Introduction">Introduction</a> |
| </h3></div></div></div> |
| <h6> |
| <a name="math_toolkit.fp_facets.facets_intro.h0"></a> |
| <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.the_problem"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.the_problem">The |
| Problem</a> |
| </h6> |
| <p> |
| The C++98 standard does not specify how <span class="emphasis"><em>infinity</em></span> and |
| <span class="emphasis"><em>NaN</em></span> are represented in text streams. As a result, different |
| platforms use different string representations. This can cause undefined |
| behavior when text files are moved between different platforms. Some platforms |
| cannot even input parse their own output! So 'route-tripping' or loopback |
| of output to input is not possible. For instance, the following test fails |
| with MSVC: |
| </p> |
| <pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</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"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">infinity</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"><<</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span> |
| <span class="identifier">ss</span> <span class="special">>></span> <span class="identifier">r</span><span class="special">;</span> <span class="comment">// Read back in.</span> |
| |
| <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"infinity output was "</span> <span class="special"><<</span> <span class="identifier">inf</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1.#INF</span> |
| <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"infinity input was "</span> <span class="special"><<</span> <span class="identifier">r</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1</span> |
| |
| <span class="identifier">assert</span><span class="special">(</span><span class="identifier">inf</span> <span class="special">==</span> <span class="identifier">y</span><span class="special">);</span> <span class="comment">// Fails!</span> |
| </pre> |
| <h6> |
| <a name="math_toolkit.fp_facets.facets_intro.h1"></a> |
| <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.the_solution"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.the_solution">The |
| Solution</a> |
| </h6> |
| <p> |
| 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> format |
| and parse all floating-point numbers, including <code class="computeroutput"><span class="identifier">infinity</span></code> |
| and <code class="computeroutput"><span class="identifier">NaN</span></code>, in a consistent |
| and portable manner. |
| </p> |
| <p> |
| The following test succeeds with MSVC. |
| </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"><</span><span class="keyword">char</span><span class="special">>);</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"><</span><span class="keyword">char</span><span class="special">>);</span> |
| </pre> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| To add two facets, <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> |
| and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>, |
| you may have to add one at a time, using a temporary locale. |
| </p> |
| <p> |
| Or you can create a new locale in one step |
| </p> |
| <p> |
| <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span> <span class="identifier">new_locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_put</span><span class="special"><</span><span class="keyword">char</span><span class="special">>),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_get</span><span class="special"><</span><span class="keyword">char</span><span class="special">>));</span></code> |
| </p> |
| <p> |
| and, for example, use it to imbue an input and output stringstream. |
| </p> |
| </td></tr> |
| </table></div> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| To just change an input or output stream, you can concisely write <code class="computeroutput"><span class="identifier">cout</span><span class="special">.</span><span class="identifier">imbue</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_put</span><span class="special"><</span><span class="keyword">char</span><span class="special">>));</span></code> or <code class="computeroutput"><span class="identifier">cin</span><span class="special">.</span><span class="identifier">imbue</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">locale</span><span class="special">(),</span> <span class="keyword">new</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">nonfinite_num_get</span><span class="special"><</span><span class="keyword">char</span><span class="special">>));</span></code> |
| </p></td></tr> |
| </table></div> |
| <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"><</span><span class="keyword">double</span><span class="special">>::</span><span class="identifier">infinity</span><span class="special">();</span> |
| <span class="identifier">ss</span> <span class="special"><<</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span> |
| <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> |
| <span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span> |
| <span class="identifier">ss</span> <span class="special">>></span> <span class="identifier">r</span><span class="special">;</span> <span class="comment">// Read back in.</span> |
| <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> |
| |
| <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"infinity output was "</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="identifier">endl</span><span class="special">;</span> |
| <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"infinity input was "</span> <span class="special"><<</span> <span class="identifier">r</span> <span class="special"><<</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> |
| <h5> |
| <a name="math_toolkit.fp_facets.facets_intro.h2"></a> |
| <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.c_0x_standard_for_output_of_infi"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.c_0x_standard_for_output_of_infi">C++0X |
| standard for output of infinity and NaN</a> |
| </h5> |
| <p> |
| <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X |
| (final) draft standard</a> does not explicitly specify the representation |
| (and input) of nonfinite values, leaving it implementation-defined. So without |
| some specific action, input and output of nonfinite values is not portable. |
| </p> |
| <h5> |
| <a name="math_toolkit.fp_facets.facets_intro.h3"></a> |
| <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.c99_standard_for_output_of_infin"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.c99_standard_for_output_of_infin">C99 |
| standard for output of infinity and NaN</a> |
| </h5> |
| <p> |
| The <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99 |
| standard</a> <span class="bold"><strong>does</strong></span> specify how infinity |
| and NaN are formatted by printf and similar output functions, and parsed |
| by scanf and similar input functions. |
| </p> |
| <p> |
| The following string representations are used: |
| </p> |
| <div class="table"> |
| <a name="math_toolkit.fp_facets.facets_intro.c99_representation_of_infinity_a"></a><p class="title"><b>Table 2.1. C99 Representation of Infinity and NaN</b></p> |
| <div class="table-contents"><table class="table" summary="C99 Representation of Infinity and NaN"> |
| <colgroup> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> |
| <p> |
| number |
| </p> |
| </th> |
| <th> |
| <p> |
| string |
| </p> |
| </th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td> |
| <p> |
| Positive infinity |
| </p> |
| </td> |
| <td> |
| <p> |
| "inf" or "infinity" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Positive NaN |
| </p> |
| </td> |
| <td> |
| <p> |
| "nan" or "nan(...)" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Negative infinity |
| </p> |
| </td> |
| <td> |
| <p> |
| "-inf" or "-infinity" |
| </p> |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <p> |
| Negative NaN |
| </p> |
| </td> |
| <td> |
| <p> |
| "-nan" or "-nan(...)" |
| </p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><p> |
| So following C99 provides a sensible 'standard' way of handling input and |
| output of nonfinites in C++, and this implementation follows most of these |
| formats. |
| </p> |
| <h6> |
| <a name="math_toolkit.fp_facets.facets_intro.h4"></a> |
| <span class="phrase"><a name="math_toolkit.fp_facets.facets_intro.signaling_nans"></a></span><a class="link" href="facets_intro.html#math_toolkit.fp_facets.facets_intro.signaling_nans">Signaling |
| NaNs</a> |
| </h6> |
| <p> |
| A particular type of NaN is the signaling NaN. The usual mechanism of signaling |
| is by raising a floating-point exception. Signaling NaNs are defined by |
| <a href="http://en.wikipedia.org/wiki/IEEE_floating-point_standard" target="_top">IEEE |
| 754-2008</a>. |
| </p> |
| <p> |
| Floating-point values with layout <span class="emphasis"><em>s</em></span>111 1111 1<span class="emphasis"><em>a</em></span>xx |
| xxxx xxxx xxxx xxxx xxxx where <span class="emphasis"><em>s</em></span> is the sign, <span class="emphasis"><em>x</em></span> |
| is the payload, and bit <span class="emphasis"><em>a</em></span> determines the type of NaN. |
| </p> |
| <p> |
| If bit <span class="emphasis"><em>a</em></span> = 1, it is a quiet NaN. |
| </p> |
| <p> |
| If bit <span class="emphasis"><em>a</em></span> is zero and the payload <span class="emphasis"><em>x</em></span> |
| is nonzero, then it is a signaling NaN. |
| </p> |
| <p> |
| Although there has been theoretical interest in the ability of a signaling |
| NaN to raise an exception, for example to prevent use of an uninitialised |
| variable, in practice there appears to be no useful application of signaling |
| NaNs for most current processors. <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X |
| 18.3.2.2</a> still specifies a (implementation-defined) representation |
| for signaling NaN, and <code class="computeroutput"><span class="keyword">static</span> <span class="keyword">constexpr</span> <span class="keyword">bool</span> <span class="identifier">has_signaling_NaN</span></code> a method of checking |
| if a floating-point type has a representation for signaling NaN. |
| </p> |
| <p> |
| But in practice, most platforms treat signaling NaNs in the same as quiet |
| NaNs. So, for example, they are represented by "nan" on output |
| in <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99</a> |
| format, and output as <code class="computeroutput"><span class="number">1.</span><span class="special">#</span><span class="identifier">QNAN</span></code> by Microsoft compilers. |
| </p> |
| <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> |
| The C99 standard does not distinguish between the quiet NaN and signaling |
| NaN values. A quiet NaN propagates through almost every arithmetic operation |
| without raising a floating-point exception; a signaling NaN generally raises |
| a floating-point exception when occurring as an arithmetic operand. |
| </p> |
| <p> |
| C99 specification does not define the behavior of signaling NaNs. NaNs |
| created by IEC 60559 operations are always quiet. Therefore this implementation |
| follows C99, and treats the signaling NaN bit as just a part of the NaN |
| payload field. So this implementation does not distinguish between the |
| two classes of NaN. |
| </p> |
| </td></tr> |
| </table></div> |
| <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> |
| An implementation may give zero and non-numeric values (such as infinities |
| and NaNs) a sign or may leave them unsigned. Wherever such values are unsigned, |
| any requirement in the C99 Standard to retrieve the sign shall produce |
| an unspecified sign, and any requirement to set the sign shall be ignored. |
| </p> |
| <p> |
| This might apply to user-defined types, but in practice built-in floating-point |
| types <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> |
| <span class="keyword">double</span></code> have well-behaved signs. |
| </p> |
| </td></tr> |
| </table></div> |
| <p> |
| The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>, |
| <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> |
| <span class="keyword">double</span></code>. An optional + sign can be |
| used with positive numbers (controlled by ios manipulator <code class="computeroutput"><span class="identifier">showpos</span></code>). |
| The function <code class="computeroutput"><span class="identifier">printf</span></code> and similar |
| C++ functions use standard formatting flags to put all lower or all upper |
| case (controlled by <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios</span></code> manipulator <code class="computeroutput"><span class="identifier">uppercase</span></code> |
| and <code class="computeroutput"><span class="identifier">lowercase</span></code>). |
| </p> |
| <p> |
| The function <code class="computeroutput"><span class="identifier">scanf</span></code> and similar |
| input functions are case-insensitive. |
| </p> |
| <p> |
| The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code> |
| stand for an arbitrary string. The meaning of that string is implementation |
| dependent. It can be used to convey extra information about the NaN, from |
| the 'payload'. A particular value of the payload might be used to indicate |
| a <span class="emphasis"><em>missing value</em></span>, for example. |
| </p> |
| <p> |
| This library uses the string representations specified by the C99 standard. |
| </p> |
| <p> |
| An example of an implementation that optionally includes the NaN payload |
| information is at <a href="http://publib.boulder.ibm.com/infocenter/zos/v1r10/index.jsp?topic=/com.ibm.zos.r10.bpxbd00/fprints.htm" target="_top">AIX |
| NaN fprintf</a>. That implementation specifies for Binary Floating Point |
| NANs: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"> |
| A NaN ordinal sequence is a left-parenthesis character '(', followed |
| by a digit sequence representing an integer n, where 1 <= n <= |
| INT_MAX-1, followed by a right-parenthesis character ')'. |
| </li> |
| <li class="listitem"> |
| The integer value, n, is determined by the fraction bits of the NaN argument |
| value as follows: |
| </li> |
| <li class="listitem"> |
| For a signalling NaN value, NaN fraction bits are reversed (left to right) |
| to produce bits (right to left) of an even integer value, 2*n. Then formatted |
| output functions produce a (signalling) NaN ordinal sequence corresponding |
| to the integer value n. |
| </li> |
| <li class="listitem"> |
| For a quiet NaN value, NaN fraction bits are reversed (left to right) |
| to produce bits (right to left) of an odd integer value, 2*n-1. Then |
| formatted output functions produce a (quiet) NaN ordinal sequence corresponding |
| to the integer value n. |
| </li> |
| </ul></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> |
| This implementation does not (yet) provide output of, or access to, the |
| NaN payload. |
| </p></td></tr> |
| </table></div> |
| </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 © 2006-2010, 2012-2014 Nikhar Agrawal, |
| Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert |
| Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta, |
| 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="../fp_facets.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="reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |
