1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Introduction</title> 5<link rel="stylesheet" href="../../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Math Toolkit 2.12.0"> 8<link rel="up" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs"> 9<link rel="prev" href="../fp_facets.html" title="Facets for Floating-Point Infinities and NaNs"> 10<link rel="next" href="reference.html" title="Reference"> 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="../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> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="math_toolkit.fp_facets.facets_intro"></a><a class="link" href="facets_intro.html" title="Introduction">Introduction</a> 28</h3></div></div></div> 29<h6> 30<a name="math_toolkit.fp_facets.facets_intro.h0"></a> 31 <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 32 Problem</a> 33 </h6> 34<p> 35 The C++98 standard does not specify how <span class="emphasis"><em>infinity</em></span> and 36 <span class="emphasis"><em>NaN</em></span> are represented in text streams. As a result, different 37 platforms use different string representations. This can cause undefined 38 behavior when text files are moved between different platforms. Some platforms 39 cannot even input parse their own output! So 'route-tripping' or loopback 40 of output to input is not possible. For instance, the following test fails 41 with MSVC: 42 </p> 43<pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span> 44<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> 45<span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span> 46<span class="identifier">ss</span> <span class="special"><<</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span> 47<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> 48 49<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> 50<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> 51 52<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> 53</pre> 54<h6> 55<a name="math_toolkit.fp_facets.facets_intro.h1"></a> 56 <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 57 Solution</a> 58 </h6> 59<p> 60 The facets <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> 61 and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> format 62 and parse all floating-point numbers, including <code class="computeroutput"><span class="identifier">infinity</span></code> 63 and <code class="computeroutput"><span class="identifier">NaN</span></code>, in a consistent 64 and portable manner. 65 </p> 66<p> 67 The following test succeeds with MSVC. 68 </p> 69<pre class="programlisting"><span class="identifier">locale</span> <span class="identifier">old_locale</span><span class="special">;</span> 70<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> 71<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> 72</pre> 73<div class="tip"><table border="0" summary="Tip"> 74<tr> 75<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 76<th align="left">Tip</th> 77</tr> 78<tr><td align="left" valign="top"> 79<p> 80 To add two facets, <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> 81 and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>, 82 you may have to add one at a time, using a temporary locale. 83 </p> 84<p> 85 Or you can create a new locale in one step 86 </p> 87<p> 88 <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> 89 </p> 90<p> 91 and, for example, use it to imbue an input and output stringstream. 92 </p> 93</td></tr> 94</table></div> 95<div class="tip"><table border="0" summary="Tip"> 96<tr> 97<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 98<th align="left">Tip</th> 99</tr> 100<tr><td align="left" valign="top"><p> 101 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> 102 </p></td></tr> 103</table></div> 104<pre class="programlisting"><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span> 105<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> 106<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> 107<span class="identifier">ss</span> <span class="special"><<</span> <span class="identifier">inf</span><span class="special">;</span> <span class="comment">// Write out.</span> 108<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> 109<span class="keyword">double</span> <span class="identifier">r</span><span class="special">;</span> 110<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> 111<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> 112 113<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> 114<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> 115<span class="comment">// But the string representation of r displayed will be the native type</span> 116<span class="comment">// because, when it was constructed, cout had NOT been imbued</span> 117<span class="comment">// with the new locale containing the nonfinite_numput facet.</span> 118<span class="comment">// So the cout output will be "1.#INF on MS platforms</span> 119<span class="comment">// and may be "inf" or other string representation on other platforms.</span> 120</pre> 121<h5> 122<a name="math_toolkit.fp_facets.facets_intro.h2"></a> 123 <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 124 standard for output of infinity and NaN</a> 125 </h5> 126<p> 127 <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X 128 (final) draft standard</a> does not explicitly specify the representation 129 (and input) of nonfinite values, leaving it implementation-defined. So without 130 some specific action, input and output of nonfinite values is not portable. 131 </p> 132<h5> 133<a name="math_toolkit.fp_facets.facets_intro.h3"></a> 134 <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 135 standard for output of infinity and NaN</a> 136 </h5> 137<p> 138 The <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99 139 standard</a> <span class="bold"><strong>does</strong></span> specify how infinity 140 and NaN are formatted by printf and similar output functions, and parsed 141 by scanf and similar input functions. 142 </p> 143<p> 144 The following string representations are used: 145 </p> 146<div class="table"> 147<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> 148<div class="table-contents"><table class="table" summary="C99 Representation of Infinity and NaN"> 149<colgroup> 150<col> 151<col> 152</colgroup> 153<thead><tr> 154<th> 155 <p> 156 number 157 </p> 158 </th> 159<th> 160 <p> 161 string 162 </p> 163 </th> 164</tr></thead> 165<tbody> 166<tr> 167<td> 168 <p> 169 Positive infinity 170 </p> 171 </td> 172<td> 173 <p> 174 "inf" or "infinity" 175 </p> 176 </td> 177</tr> 178<tr> 179<td> 180 <p> 181 Positive NaN 182 </p> 183 </td> 184<td> 185 <p> 186 "nan" or "nan(...)" 187 </p> 188 </td> 189</tr> 190<tr> 191<td> 192 <p> 193 Negative infinity 194 </p> 195 </td> 196<td> 197 <p> 198 "-inf" or "-infinity" 199 </p> 200 </td> 201</tr> 202<tr> 203<td> 204 <p> 205 Negative NaN 206 </p> 207 </td> 208<td> 209 <p> 210 "-nan" or "-nan(...)" 211 </p> 212 </td> 213</tr> 214</tbody> 215</table></div> 216</div> 217<br class="table-break"><p> 218 So following C99 provides a sensible 'standard' way of handling input and 219 output of nonfinites in C++, and this implementation follows most of these 220 formats. 221 </p> 222<h6> 223<a name="math_toolkit.fp_facets.facets_intro.h4"></a> 224 <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 225 NaNs</a> 226 </h6> 227<p> 228 A particular type of NaN is the signaling NaN. The usual mechanism of signaling 229 is by raising a floating-point exception. Signaling NaNs are defined by 230 <a href="http://en.wikipedia.org/wiki/IEEE_floating-point_standard" target="_top">IEEE 231 754-2008</a>. 232 </p> 233<p> 234 Floating-point values with layout <span class="emphasis"><em>s</em></span>111 1111 1<span class="emphasis"><em>a</em></span>xx 235 xxxx xxxx xxxx xxxx xxxx where <span class="emphasis"><em>s</em></span> is the sign, <span class="emphasis"><em>x</em></span> 236 is the payload, and bit <span class="emphasis"><em>a</em></span> determines the type of NaN. 237 </p> 238<p> 239 If bit <span class="emphasis"><em>a</em></span> = 1, it is a quiet NaN. 240 </p> 241<p> 242 If bit <span class="emphasis"><em>a</em></span> is zero and the payload <span class="emphasis"><em>x</em></span> 243 is nonzero, then it is a signaling NaN. 244 </p> 245<p> 246 Although there has been theoretical interest in the ability of a signaling 247 NaN to raise an exception, for example to prevent use of an uninitialised 248 variable, in practice there appears to be no useful application of signaling 249 NaNs for most current processors. <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3242.pdf" target="_top">C++0X 250 18.3.2.2</a> still specifies a (implementation-defined) representation 251 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 252 if a floating-point type has a representation for signaling NaN. 253 </p> 254<p> 255 But in practice, most platforms treat signaling NaNs in the same as quiet 256 NaNs. So, for example, they are represented by "nan" on output 257 in <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99</a> 258 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. 259 </p> 260<div class="note"><table border="0" summary="Note"> 261<tr> 262<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 263<th align="left">Note</th> 264</tr> 265<tr><td align="left" valign="top"> 266<p> 267 The C99 standard does not distinguish between the quiet NaN and signaling 268 NaN values. A quiet NaN propagates through almost every arithmetic operation 269 without raising a floating-point exception; a signaling NaN generally raises 270 a floating-point exception when occurring as an arithmetic operand. 271 </p> 272<p> 273 C99 specification does not define the behavior of signaling NaNs. NaNs 274 created by IEC 60559 operations are always quiet. Therefore this implementation 275 follows C99, and treats the signaling NaN bit as just a part of the NaN 276 payload field. So this implementation does not distinguish between the 277 two classes of NaN. 278 </p> 279</td></tr> 280</table></div> 281<div class="note"><table border="0" summary="Note"> 282<tr> 283<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 284<th align="left">Note</th> 285</tr> 286<tr><td align="left" valign="top"> 287<p> 288 An implementation may give zero and non-numeric values (such as infinities 289 and NaNs) a sign or may leave them unsigned. Wherever such values are unsigned, 290 any requirement in the C99 Standard to retrieve the sign shall produce 291 an unspecified sign, and any requirement to set the sign shall be ignored. 292 </p> 293<p> 294 This might apply to user-defined types, but in practice built-in floating-point 295 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> 296 <span class="keyword">double</span></code> have well-behaved signs. 297 </p> 298</td></tr> 299</table></div> 300<p> 301 The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>, 302 <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> 303 <span class="keyword">double</span></code>. An optional + sign can be 304 used with positive numbers (controlled by ios manipulator <code class="computeroutput"><span class="identifier">showpos</span></code>). 305 The function <code class="computeroutput"><span class="identifier">printf</span></code> and similar 306 C++ functions use standard formatting flags to put all lower or all upper 307 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> 308 and <code class="computeroutput"><span class="identifier">lowercase</span></code>). 309 </p> 310<p> 311 The function <code class="computeroutput"><span class="identifier">scanf</span></code> and similar 312 input functions are case-insensitive. 313 </p> 314<p> 315 The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code> 316 stand for an arbitrary string. The meaning of that string is implementation 317 dependent. It can be used to convey extra information about the NaN, from 318 the 'payload'. A particular value of the payload might be used to indicate 319 a <span class="emphasis"><em>missing value</em></span>, for example. 320 </p> 321<p> 322 This library uses the string representations specified by the C99 standard. 323 </p> 324<p> 325 An example of an implementation that optionally includes the NaN payload 326 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 327 NaN fprintf</a>. That implementation specifies for Binary Floating Point 328 NANs: 329 </p> 330<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 331<li class="listitem"> 332 A NaN ordinal sequence is a left-parenthesis character '(', followed 333 by a digit sequence representing an integer n, where 1 <= n <= 334 INT_MAX-1, followed by a right-parenthesis character ')'. 335 </li> 336<li class="listitem"> 337 The integer value, n, is determined by the fraction bits of the NaN argument 338 value as follows: 339 </li> 340<li class="listitem"> 341 For a signalling NaN value, NaN fraction bits are reversed (left to right) 342 to produce bits (right to left) of an even integer value, 2*n. Then formatted 343 output functions produce a (signalling) NaN ordinal sequence corresponding 344 to the integer value n. 345 </li> 346<li class="listitem"> 347 For a quiet NaN value, NaN fraction bits are reversed (left to right) 348 to produce bits (right to left) of an odd integer value, 2*n-1. Then 349 formatted output functions produce a (quiet) NaN ordinal sequence corresponding 350 to the integer value n. 351 </li> 352</ul></div> 353<div class="warning"><table border="0" summary="Warning"> 354<tr> 355<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td> 356<th align="left">Warning</th> 357</tr> 358<tr><td align="left" valign="top"><p> 359 This implementation does not (yet) provide output of, or access to, the 360 NaN payload. 361 </p></td></tr> 362</table></div> 363</div> 364<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 365<td align="left"></td> 366<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 367 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 368 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 369 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 370 Daryle Walker and Xiaogang Zhang<p> 371 Distributed under the Boost Software License, Version 1.0. (See accompanying 372 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>) 373 </p> 374</div></td> 375</tr></table> 376<hr> 377<div class="spirit-nav"> 378<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> 379</div> 380</body> 381</html> 382
