math/doc/html/math_toolkit/fp_facets/facets_intro.html
2019-10-31 17:55:35 +00:00

382 lines
25 KiB
HTML

<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.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="../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">&lt;</span><span class="keyword">double</span><span class="special">&gt;::</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">&lt;&lt;</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</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">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"infinity output was "</span> <span class="special">&lt;&lt;</span> <span class="identifier">inf</span> <span class="special">&lt;&lt;</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// 1.#INF</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">// 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">&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>
<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">&lt;</span><span class="keyword">char</span><span class="special">&gt;),</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">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</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">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</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">&lt;</span><span class="keyword">char</span><span class="special">&gt;));</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">&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>
<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&#160;2.1.&#160;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 &lt;= n &lt;=
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 &#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="../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>