1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Reference</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="facets_intro.html" title="Introduction"> 10<link rel="next" href="examples.html" title="Examples"> 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="facets_intro.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="examples.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.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a> 28</h3></div></div></div> 29<h6> 30<a name="math_toolkit.fp_facets.reference.h0"></a> 31 <span class="phrase"><a name="math_toolkit.fp_facets.reference.the_facet_nonfinite_num_put"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.the_facet_nonfinite_num_put">The 32 Facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code></a> 33 </h6> 34<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span> 35 <span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OutputIterator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostreambuf_iterator</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">></span> 36 <span class="special">></span> 37<span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special">;</span> 38</pre> 39<p> 40 The <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">></span></code> is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">></span></code>. Thus it is a facet that formats numbers. 41 The first template argument is the character type of the formatted strings, 42 usually <code class="computeroutput"><span class="keyword">char</span></code> or <code class="computeroutput"><span class="keyword">wchar_t</span></code>. The second template argument is the 43 type of iterator used to write the strings. It is required to be an output 44 iterator. Usually the default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostreambuf_iterator</span></code> 45 is used. The public interface of the class consists of a single constructor 46 only: 47 </p> 48<pre class="programlisting"><span class="identifier">nonfinite_num_put</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> 49</pre> 50<p> 51 The flags argument (effectively optional because a default of <code class="computeroutput"> <span class="identifier">no_flags</span></code> is provided) is discussed below. 52 The class template <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> 53 is defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and lives in the namespace <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>. 54 </p> 55<p> 56 Unlike the C++ Standard facet <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span></code>, 57 the facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> 58 formats <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. 59 It uses the following string representations: 60 </p> 61<div class="informaltable"><table class="table"> 62<colgroup> 63<col> 64<col> 65</colgroup> 66<thead><tr> 67<th> 68 <p> 69 Number 70 </p> 71 </th> 72<th> 73 <p> 74 String 75 </p> 76 </th> 77</tr></thead> 78<tbody> 79<tr> 80<td> 81 <p> 82 Positive infinity 83 </p> 84 </td> 85<td> 86 <p> 87 inf 88 </p> 89 </td> 90</tr> 91<tr> 92<td> 93 <p> 94 Positive NaN 95 </p> 96 </td> 97<td> 98 <p> 99 nan 100 </p> 101 </td> 102</tr> 103<tr> 104<td> 105 <p> 106 Negative infinity 107 </p> 108 </td> 109<td> 110 <p> 111 -inf 112 </p> 113 </td> 114</tr> 115<tr> 116<td> 117 <p> 118 Negative NaN 119 </p> 120 </td> 121<td> 122 <p> 123 -nan 124 </p> 125 </td> 126</tr> 127</tbody> 128</table></div> 129<p> 130 The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>, 131 <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> 132 <span class="keyword">double</span></code>. The strings can be in all 133 lower case or all upper case. An optional + sign can be used with positive 134 numbers. This can be controlled with the <code class="computeroutput"><span class="identifier">uppercase</span></code>, 135 <code class="computeroutput"><span class="identifier">lowercase</span></code>, <code class="computeroutput"><span class="identifier">showpos</span></code> and <code class="computeroutput"><span class="identifier">noshowpos</span></code> 136 manipulators. Formatting of integers, boolean values and finite floating-point 137 numbers is simply delegated to the normal <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span></code>. 138 </p> 139<h6> 140<a name="math_toolkit.fp_facets.reference.h1"></a> 141 <span class="phrase"><a name="math_toolkit.fp_facets.reference.facet_nonfinite_num_get"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.facet_nonfinite_num_get">Facet 142 <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code></a> 143 </h6> 144<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">InputIterator</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">istreambuf_iterator</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">></span> <span class="special">></span> <span class="keyword">class</span> <span class="identifier">nonfinite_num_get</span><span class="special">;</span> 145</pre> 146<p> 147 The class <code class="computeroutput"><span class="identifier">nonfinite_num_get</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">InputIterator</span><span class="special">></span></code> is derived from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span><span class="special"><</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">IntputIterator</span><span class="special">></span></code>. Thus it is a facet that parses strings 148 that represent numbers. The first template argument is the character type 149 of the strings, usually <code class="computeroutput"><span class="keyword">char</span></code> 150 or <code class="computeroutput"><span class="keyword">wchar_t</span></code>. The second template 151 argument is the type of iterator used to read the strings. It is required 152 to be an input iterator. Usually the default is used. The public interface 153 of the class consists of a single constructor only: 154 </p> 155<pre class="programlisting"><span class="identifier">nonfinite_num_get</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">flags</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span> 156</pre> 157<p> 158 The flags argument is discussed below. The <code class="computeroutput"><span class="keyword">class</span> 159 <span class="keyword">template</span> <span class="identifier">nonfinite_num_get</span></code> 160 is defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and lives in the <code class="computeroutput"><span class="keyword">namespace</span> 161 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>. 162 </p> 163<p> 164 Unlike the facet <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>, the facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> 165 parses strings that represent <code class="computeroutput"><span class="identifier">infinity</span></code> 166 and <code class="computeroutput"><span class="identifier">NaN</span></code> in a consistent and 167 portable manner. It recognizes precisely the string representations specified 168 by the C99 standard: 169 </p> 170<div class="informaltable"><table class="table"> 171<colgroup> 172<col> 173<col> 174</colgroup> 175<thead><tr> 176<th> 177 <p> 178 Number 179 </p> 180 </th> 181<th> 182 <p> 183 String 184 </p> 185 </th> 186</tr></thead> 187<tbody> 188<tr> 189<td> 190 <p> 191 Positive infinity 192 </p> 193 </td> 194<td> 195 <p> 196 inf, infinity 197 </p> 198 </td> 199</tr> 200<tr> 201<td> 202 <p> 203 Positive NaN 204 </p> 205 </td> 206<td> 207 <p> 208 nan, nan(...) 209 </p> 210 </td> 211</tr> 212<tr> 213<td> 214 <p> 215 Negative infinity 216 </p> 217 </td> 218<td> 219 <p> 220 -inf, -infinity 221 </p> 222 </td> 223</tr> 224<tr> 225<td> 226 <p> 227 Negative NaN 228 </p> 229 </td> 230<td> 231 <p> 232 -nan, -nan(...) 233 </p> 234 </td> 235</tr> 236</tbody> 237</table></div> 238<p> 239 The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>, 240 <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> 241 <span class="keyword">double</span></code>. The facet is case-insensitive. 242 An optional + sign can be used with positive numbers. The dots in nan(...) 243 stand for an arbitrary string usually containing the <span class="emphasis"><em>NaN payload</em></span>. 244 Parsing of strings that represent integers, boolean values and finite floating-point 245 numbers is delegated to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>. 246 </p> 247<p> 248 When the facet parses a string that represents <code class="computeroutput"><span class="identifier">infinity</span></code> 249 on a platform that lacks infinity, then the fail bit of the stream is set. 250 </p> 251<p> 252 When the facet parses a string that represents <code class="computeroutput"><span class="identifier">NaN</span></code> 253 on a platform that lacks NaN, then the fail bit of the stream is set. 254 </p> 255<h5> 256<a name="math_toolkit.fp_facets.reference.h2"></a> 257 <span class="phrase"><a name="math_toolkit.fp_facets.reference.flags"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.flags">Flags</a> 258 </h5> 259<p> 260 The constructors for <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code> 261 and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> take 262 an optional bit flags argument. There are four different bit flags: 263 </p> 264<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 265<li class="listitem"> 266 legacy 267 </li> 268<li class="listitem"> 269 signed_zero 270 </li> 271<li class="listitem"> 272 trap_infinity 273 </li> 274<li class="listitem"> 275 trap_nan 276 </li> 277</ul></div> 278<p> 279 The flags can be combined with the OR <code class="computeroutput"><span class="keyword">operator</span><span class="special">|</span></code>. 280 </p> 281<p> 282 The flags are defined in the header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">nonfinite_num_facets</span><span class="special">.</span><span class="identifier">hpp</span></code> and live in the <code class="computeroutput"><span class="keyword">namespace</span> 283 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>. 284 </p> 285<h6> 286<a name="math_toolkit.fp_facets.reference.h3"></a> 287 <span class="phrase"><a name="math_toolkit.fp_facets.reference.legacy"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.legacy">legacy</a> 288 </h6> 289<p> 290 The legacy flag has no effect with the output facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>. 291 </p> 292<p> 293 If the legacy flag is used with the <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> 294 input facet, then the facet will recognize all the following string representations 295 of <code class="computeroutput"><span class="identifier">infinity</span></code> and <code class="computeroutput"><span class="identifier">NaN</span></code>: 296 </p> 297<div class="informaltable"><table class="table"> 298<colgroup> 299<col> 300<col> 301</colgroup> 302<thead><tr> 303<th> 304 <p> 305 Number 306 </p> 307 </th> 308<th> 309 <p> 310 String 311 </p> 312 </th> 313</tr></thead> 314<tbody> 315<tr> 316<td> 317 <p> 318 Positive infinity 319 </p> 320 </td> 321<td> 322 <p> 323 inf, infinity, one#inf 324 </p> 325 </td> 326</tr> 327<tr> 328<td> 329 <p> 330 Positive NaN 331 </p> 332 </td> 333<td> 334 <p> 335 nan, nan(...), nanq, nans, qnan, snan, one#ind, one#qnan, one#snan 336 </p> 337 </td> 338</tr> 339<tr> 340<td> 341 <p> 342 Negative infinity 343 </p> 344 </td> 345<td> 346 <p> 347 -inf, -infinity, -one#inf 348 </p> 349 </td> 350</tr> 351<tr> 352<td> 353 <p> 354 Negative NaN 355 </p> 356 </td> 357<td> 358 <p> 359 -nan, -nan(...), -nanq, -nans, -qnan, -snan, -one#ind, - one#qnan, 360 -one#snan 361 </p> 362 </td> 363</tr> 364</tbody> 365</table></div> 366<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 367<li class="listitem"> 368 The numbers can be of type <code class="computeroutput"><span class="keyword">float</span></code>, 369 <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>. 370 </li> 371<li class="listitem"> 372 The facet is case-insensitive. 373 </li> 374<li class="listitem"> 375 An optional <code class="computeroutput"><span class="special">+</span></code> sign can be 376 used with the positive values. 377 </li> 378<li class="listitem"> 379 The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code> 380 stand for an arbitrary string. 381 </li> 382<li class="listitem"> 383 <code class="computeroutput"><span class="identifier">one</span></code> stands for any string 384 that <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code> parses as the number <code class="computeroutput"><span class="number">1</span></code>, typically "1.#INF", "1.QNAN" 385 but also "000001.#INF"... 386 </li> 387</ul></div> 388<p> 389 The list includes a number of non-standard string representations of infinity 390 and NaN that are used by various existing implementations of the C++ standard 391 library, and also string representations used by other programming languages. 392 </p> 393<h6> 394<a name="math_toolkit.fp_facets.reference.h4"></a> 395 <span class="phrase"><a name="math_toolkit.fp_facets.reference.signed_zero"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.signed_zero">signed_zero</a> 396 </h6> 397<p> 398 If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag is 399 used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>, 400 then the facet will always distinguish between positive and negative zero. 401 It will format positive zero as "0" or "+0" and negative 402 zero as "-0". The string representation of positive zero can be 403 controlled with the <code class="computeroutput"><span class="identifier">showpos</span></code> 404 and <code class="computeroutput"><span class="identifier">noshowpos</span></code> manipulators. 405 </p> 406<p> 407 The <code class="computeroutput"><span class="identifier">signed_zero</span> <span class="identifier">flag</span></code> 408 has no effect with the input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>. 409 The input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> 410 always parses "0" and "+0" as positive zero and "-0" 411 as negative zero, as do most implementations of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>. 412 </p> 413<div class="note"><table border="0" summary="Note"> 414<tr> 415<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 416<th align="left">Note</th> 417</tr> 418<tr><td align="left" valign="top"><p> 419 If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag 420 is not set (the default), then a negative zero value will be displayed 421 on output in whatever way the platform normally handles it. For most platforms, 422 this it will format positive zero as "0" or "+0" and 423 negative zero as "-0". But setting the <code class="computeroutput"><span class="identifier">signed_zero</span></code> 424 flag may be more portable. 425 </p></td></tr> 426</table></div> 427<div class="tip"><table border="0" summary="Tip"> 428<tr> 429<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 430<th align="left">Tip</th> 431</tr> 432<tr><td align="left" valign="top"><p> 433 A negative zero value can be portably produced using the changesign function 434 <code class="computeroutput"><span class="special">(</span><span class="identifier">changesign</span><span class="special">)(</span><span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">ValType</span><span class="special">>(</span><span class="number">0</span><span class="special">))</span></code> 435 where <code class="computeroutput"><span class="identifier">ValType</span></code> is <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> 436 or <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>, 437 or a User-Defined floating-point type (UDT) provided that this UDT has 438 a sign and that the changesign function is implemented. 439 </p></td></tr> 440</table></div> 441<h6> 442<a name="math_toolkit.fp_facets.reference.h5"></a> 443 <span class="phrase"><a name="math_toolkit.fp_facets.reference.trap_infinity"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.trap_infinity">trap_infinity</a> 444 </h6> 445<p> 446 If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag 447 is used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>, 448 then the facet will throw an exception of type <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">failure</span></code> 449 when an attempt is made to format positive or negative infinity. If the facet 450 is called from a stream insertion operator, then the stream will catch that 451 exception and set either its <code class="computeroutput"><span class="identifier">fail</span> 452 <span class="identifier">bit</span></code> or its <code class="computeroutput"><span class="identifier">bad</span> 453 <span class="identifier">bit</span></code>. Which bit is set is platform 454 dependent. 455 </p> 456<p> 457 If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag 458 is used with <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>, 459 then the facet will set the <code class="computeroutput"><span class="identifier">fail</span> 460 <span class="identifier">bit</span></code> of the stream when an attempt 461 is made to parse a string that represents positive or negative infinity. 462 </p> 463<p> 464 (See Design Rationale below for a discussion of this inconsistency.) 465 </p> 466<h6> 467<a name="math_toolkit.fp_facets.reference.h6"></a> 468 <span class="phrase"><a name="math_toolkit.fp_facets.reference.trap_nan"></a></span><a class="link" href="reference.html#math_toolkit.fp_facets.reference.trap_nan">trap_nan</a> 469 </h6> 470<p> 471 Same as <code class="computeroutput"><span class="identifier">trap_infinity</span></code>, but 472 positive and negative NaN are trapped instead. 473 </p> 474</div> 475<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 476<td align="left"></td> 477<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 478 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 479 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 480 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 481 Daryle Walker and Xiaogang Zhang<p> 482 Distributed under the Boost Software License, Version 1.0. (See accompanying 483 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>) 484 </p> 485</div></td> 486</tr></table> 487<hr> 488<div class="spirit-nav"> 489<a accesskey="p" href="facets_intro.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="examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 490</div> 491</body> 492</html> 493
