Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r71395 - trunk/libs/math/doc/sf_and_dist/html/math_toolkit/utils
From: pbristow_at_[hidden]
Date: 2011-04-20 13:05:40

Next message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r71396 - trunk/libs/math/doc/sf_and_dist"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r71394 - trunk/libs/type_traits/test"

Author: pbristow
Date: 2011-04-20 13:05:40 EDT (Wed, 20 Apr 2011)
New Revision: 71395
URL: http://svn.boost.org/trac/boost/changeset/71395

Log:
Added to docs for fp_facets
Added:
trunk/libs/math/doc/sf_and_dist/html/math_toolkit/utils/fp_facets.html (contents, props changed)

Added: trunk/libs/math/doc/sf_and_dist/html/math_toolkit/utils/fp_facets.html
==============================================================================
--- (empty file)
+++ trunk/libs/math/doc/sf_and_dist/html/math_toolkit/utils/fp_facets.html 2011-04-20 13:05:40 EDT (Wed, 20 Apr 2011)
@@ -0,0 +1,1056 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Facets for Floating-Point Infinities and NaNs</title>
+<link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
+<link rel="home" href="../../index.html" title="Math Toolkit">
+<link rel="up" href="../utils.html" title="Floating Point Utilities">
+<link rel="prev" href="sign_functions.html" title="Sign Manipulation Functions">
+<link rel="next" href="next_float.html" title="Floating-Point Representation Distance (ULP), and Finding Adjacent Floating-Point Values">
+</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">Home</td>
+<td align="center">Libraries</td>
+<td align="center">People</td>
+<td align="center">FAQ</td>
+<td align="center">More</td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sign_functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.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="next_float.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="math_toolkit.utils.fp_facets"></a><a class="link" href="fp_facets.html" title="Facets for Floating-Point Infinities and NaNs">Facets for Floating-Point
+ Infinities and NaNs</a>
+</h3></div></div></div>
+<a name="math_toolkit.utils.fp_facets.synopsis"></a><h5>
+<a name="id1123356"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.synopsis">Synopsis</a>
+ </h5>
+<pre class="programlisting">namespace boost{ namespace math
+{
+ // Values for flags.
+ const int legacy;
+ const int signed_zero;
+ const int trap_infinity;
+ const int trap_nan;
+
+ template<
+ class CharType,
+ class OutputIterator = std::ostreambuf_iterator<CharType>
+ >
+ class nonfinite_num_put : public std::num_put<CharType, OutputIterator>
+ {
+ public:
+ explicit nonfinite_num_put(int flags = 0);
+ };
+
+ template<
+ class CharType,
+ class InputIterator = std::istreambuf_iterator<CharType>
+ >
+ class nonfinite_num_get : public std::num_get<CharType, InputIterator>
+ {
+ public:
+ explicit nonfinite_num_get(int flags = 0); // legacy, sign_zero ...
+ };
+}} // namespace boost namespace math
+</pre>
+
+ To use these facets
+ 
+<pre class="programlisting">#include <boost\math\special_functions\nonfinite_num_facets.hpp>
+</pre>
+<a name="math_toolkit.utils.fp_facets.introduction"></a><h5>
+<a name="id1123877"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.introduction">Introduction</a>
+ </h5>
+<a name="math_toolkit.utils.fp_facets.the_problem"></a><h6>
+<a name="id1123890"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.the_problem">The Problem</a>
+ </h6>
+
+ The C++98 standard does not specify how infinity and NaN 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:
+ 
+<pre class="programlisting">stringstream ss;
+double inf = numeric_limits<double>::infinity();
+double r;
+ss << inf; // Write out.
+ss >> r; // Read back in.
+
+cout << "infinity output was " << inf << endl; // 1.#INF
+cout << "infinity input was " << r << endl; // 1
+
+assert(inf == y); // Fails!
+</pre>
+<a name="math_toolkit.utils.fp_facets.the_solution"></a><h6>
+<a name="id1124130"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.the_solution">The Solution</a>
+ </h6>
+
+ The facets <code class="computeroutput">nonfinite_num_put</code>
+ and <code class="computeroutput">nonfinite_num_get</code> format
+ and parse all floating-point numbers, including <code class="computeroutput">infinity</code>
+ and <code class="computeroutput">NaN</code>, in a consistent
+ and portable manner.
+ 
+
+ The following test succeeds with MSVC.
+ 
+
+
+
+<pre class="programlisting">locale old_locale;
+locale tmp_locale(old_locale, new nonfinite_num_put<char>);
+locale new_locale(tmp_locale, new nonfinite_num_get<char>);
+</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">
+ To add two facets, <code class="computeroutput">nonfinite_num_put</code>
+ and <code class="computeroutput">nonfinite_num_get</code>,
+ you have to add one at a time, using a temporary locale.
+ </td></tr>
+</table></div>
+
+
+
+<pre class="programlisting">stringstream ss;
+ss.imbue(new_locale);
+double inf = numeric_limits<double>::infinity();
+ss << inf; // Write out.
+assert(ss.str() == "inf");
+ double r;
+ss >> r; // Read back in.
+assert(inf == r); // Confirms that the double values really are identical.
+
+cout << "infinity output was " << ss.str() << endl;
+cout << "infinity input was " << r << endl;
+// But the string representation of r displayed will be the native type
+// because, when it was constructed, cout had NOT been imbued
+// with the new locale containing the nonfinite_numput facet.
+// So the cout output will be "1.#INF on MS platforms
+// and may be "inf" or other string representation on other platforms.
+
+</pre>
+
+ 
+<a name="math_toolkit.utils.fp_facets.c__0x_standard_for_output_of_infinity_and_nan"></a><h5>
+<a name="id1124613"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.c__0x_standard_for_output_of_infinity_and_nan">C++0X
+ standard for output of infinity and NaN</a>
+ </h5>
+
+ <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.
+ 
+<a name="math_toolkit.utils.fp_facets.c99_standard_for_output_of_infinity_and_nan"></a><h5>
+<a name="id1124635"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.c99_standard_for_output_of_infinity_and_nan">C99
+ standard for output of infinity and NaN</a>
+ </h5>
+
+ The <a href="http://www.open-std.org/JTC1/SC22/WG14/www/docs/n1256.pdf" target="_top">C99
+ standard</a> does specify how infinity
+ and NaN are formatted by printf and similar output functions, and parsed
+ by scanf and similar input functions.
+ 
+
+ The following string representations are used:
+ 
+<div class="table">
+<a name="math_toolkit.utils.fp_facets.c99_representation_of_infinity_and_nan"></a>Table 50. C99 Representation of Infinity and NaN
+<div class="table-contents"><table class="table" summary="C99 Representation of Infinity and NaN">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ number
+ 
+ </th>
+<th>
+ 
+ string
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Positive infinity
+ 
+ </td>
+<td>
+ 
+ "inf" or "infinity"
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Positive NaN
+ 
+ </td>
+<td>
+ 
+ "nan" or "nan(...)"
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative infinity
+ 
+ </td>
+<td>
+ 
+ "-inf" or "-infinity"
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative NaN
+ 
+ </td>
+<td>
+ 
+ "-nan" or "-nan(...)"
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+</div>
+ 
+ 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.
+ 
+<a name="math_toolkit.utils.fp_facets.signaling_nans"></a><h6>
+<a name="id1124785"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.signaling_nans">Signaling NaNs</a>
+ </h6>
+
+ 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>.
+ 
+
+ Floating-point values with layout s111 1111 1axx
+ xxxx xxxx xxxx xxxx xxxx where s is the sign, x
+ is the payload, and bit a determines the type of NaN.
+ 
+
+ If bit a = 1, it is a quiet NaN.
+ 
+
+ If bit a is zero and the payload x
+ is nonzero, then it is a signaling NaN.
+ 
+
+ 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">static constexpr bool
+ has_signaling_NaN</code> a method of checking
+ if a floating-point type has a representation for signaling NaN.
+ 
+
+ 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 C99
+ format, and output as <code class="computeroutput">1.#QNAN</code>
+ by Microsoft compilers.
+ 
+<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">
+
+ 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.
+ 
+
+ 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.
+ 
+</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">
+
+ 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.
+ 
+
+ This might apply to user-defined types, but in practice built-in floating-point
+ types <code class="computeroutput">float</code>, <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code> have well-behaved signs.
+ 
+</td></tr>
+</table></div>
+
+ The numbers can be of type <code class="computeroutput">float</code>,
+ <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>. An optional + sign can be
+ used with positive numbers (controlled by ios manipulator <code class="computeroutput">showpos</code>).
+ The function <code class="computeroutput">printf</code> and similar
+ C++ functions use standard formatting flags to put all lower or all upper
+ case (controlled by <code class="computeroutput">std::ios</code> manipulator <code class="computeroutput">uppercase</code>
+ and <code class="computeroutput">lowercase</code>).
+ 
+
+ The function <code class="computeroutput">scanf</code> and similar
+ input functions are case-insensitive.
+ 
+
+ The dots in <code class="computeroutput">nan(...)</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 missing value, for example.
+ 
+
+ This library uses the string representations specified by the C99 standard.
+ 
+
+ 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:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ 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>
+ The integer value, n, is determined by the fraction bits of the NaN argument
+ value as follows:
+ </li>
+<li>
+ 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>
+ 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">
+ This implementation does not (yet) provide output of, or access to, the
+ NaN payload.
+ </td></tr>
+</table></div>
+<a name="math_toolkit.utils.fp_facets.reference"></a><h5>
+<a name="id1126220"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.reference">Reference</a>
+ </h5>
+<a name="math_toolkit.utils.fp_facets.the_facet__code__phrase_role__identifier__nonfinite_num_put__phrase___code_"></a><h6>
+<a name="id1126233"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.the_facet__code__phrase_role__identifier__nonfinite_num_put__phrase___code_">The
+ Facet <code class="computeroutput">nonfinite_num_put</code></a>
+ </h6>
+<pre class="programlisting">template<
+ class CharType, class OutputIterator = std::ostreambuf_iterator<CharType>
+ >
+class nonfinite_num_put;
+</pre>
+
+ The <code class="computeroutput">class nonfinite_num_put<CharType, OutputIterator></code> is derived from <code class="computeroutput">std::num_put<CharType, OutputIterator></code>. Thus it is a facet that formats numbers.
+ The first template argument is the character type of the formatted strings,
+ usually <code class="computeroutput">char</code> or <code class="computeroutput">wchar_t</code>. The second template argument is the
+ type of iterator used to write the strings. It is required to be an output
+ iterator. Usually the default <code class="computeroutput">std::ostreambuf_iterator</code>
+ is used. The public interface of the class consists of a single constructor
+ only:
+ 
+<pre class="programlisting">nonfinite_num_put(int flags = 0);
+</pre>
+
+ The flags argument (effectively optional because a default of <code class="computeroutput"> no_flags</code> is provided) is discussed below.
+ The class template <code class="computeroutput">nonfinite_num_put</code>
+ is defined in the header <code class="computeroutput">boost/math/nonfinite_num_facets.hpp</code> and lives in the namespace <code class="computeroutput">boost::math</code>.
+ 
+
+ Unlike the C++ Standard facet <code class="computeroutput">std::num_put</code>,
+ the facet <code class="computeroutput">nonfinite_num_put</code>
+ formats <code class="computeroutput">infinity</code> and <code class="computeroutput">NaN</code> in a consistent and portable manner.
+ It uses the following string representations:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Number
+ 
+ </th>
+<th>
+ 
+ String
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Positive infinity
+ 
+ </td>
+<td>
+ 
+ inf
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Positive NaN
+ 
+ </td>
+<td>
+ 
+ nan
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative infinity
+ 
+ </td>
+<td>
+ 
+ -inf
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative NaN
+ 
+ </td>
+<td>
+ 
+ -nan
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ The numbers can be of type <code class="computeroutput">float</code>,
+ <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>. The strings can be in all
+ lower case or all upper case. An optional + sign can be used with positive
+ numbers. This can be controlled with the <code class="computeroutput">uppercase</code>,
+ <code class="computeroutput">lowercase</code>, <code class="computeroutput">showpos</code> and <code class="computeroutput">noshowpos</code>
+ manipulators. Formatting of integers, boolean values and finite floating-point
+ numbers is simply delegated to the normal <code class="computeroutput">std::num_put</code>.
+ 
+<a name="math_toolkit.utils.fp_facets.facet__code__phrase_role__identifier__nonfinite_num_get__phrase___code_"></a><h6>
+<a name="id1126746"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.facet__code__phrase_role__identifier__nonfinite_num_get__phrase___code_">Facet
+ <code class="computeroutput">nonfinite_num_get</code></a>
+ </h6>
+<pre class="programlisting">template<class CharType, class InputIterator = std::istreambuf_iterator<CharType> > class nonfinite_num_get;
+</pre>
+
+ The class <code class="computeroutput">nonfinite_num_get<CharType, InputIterator></code> is derived from <code class="computeroutput">std::num_get<CharType, IntputIterator></code>. Thus it is a facet that parses strings
+ that represent numbers. The first template argument is the character type
+ of the strings, usually <code class="computeroutput">char</code>
+ or <code class="computeroutput">wchar_t</code>. The second template
+ argument is the type of iterator used to read the strings. It is required
+ to be an input iterator. Usually the default is used. The public interface
+ of the class consists of a single constructor only:
+ 
+<pre class="programlisting">nonfinite_num_get(int flags = 0);
+</pre>
+
+ The flags argument is discussed below. The <code class="computeroutput">class
+ template nonfinite_num_get</code>
+ is defined in the header <code class="computeroutput">boost/math/nonfinite_num_facets.hpp</code> and lives in the <code class="computeroutput">namespace
+ boost::math</code>.
+ 
+
+ Unlike the facet <code class="computeroutput">std::num_get</code>, the facet <code class="computeroutput">nonfinite_num_get</code>
+ parses strings that represent <code class="computeroutput">infinity</code>
+ and <code class="computeroutput">NaN</code> in a consistent and
+ portable manner. It recognizes precisely the string representations specified
+ by the C99 standard:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Number
+ 
+ </th>
+<th>
+ 
+ String
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Positive infinity
+ 
+ </td>
+<td>
+ 
+ inf, infinity
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Positive NaN
+ 
+ </td>
+<td>
+ 
+ nan, nan(...)
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative infinity
+ 
+ </td>
+<td>
+ 
+ -inf, -infinity
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative NaN
+ 
+ </td>
+<td>
+ 
+ -nan, -nan(...)
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ The numbers can be of type <code class="computeroutput">float</code>,
+ <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>. The facet is case-insensitive.
+ An optional + sign can be used with positive numbers. The dots in nan(...)
+ stand for an arbitrary string usually containing the NaN payload.
+ Parsing of strings that represent integers, boolean values and finite floating-point
+ numbers is delegated to <code class="computeroutput">std::num_get</code>.
+ 
+
+ When the facet parses a string that represents <code class="computeroutput">infinity</code>
+ on a platform that lacks infinity, then the fail bit of the stream is set.
+ 
+
+ When the facet parses a string that represents <code class="computeroutput">NaN</code>
+ on a platform that lacks NaN, then the fail bit of the stream is set.
+ 
+<a name="math_toolkit.utils.fp_facets.flags"></a><h5>
+<a name="id1127243"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.flags">Flags</a>
+ </h5>
+
+ The constructors for <code class="computeroutput">nonfinite_num_put</code>
+ and <code class="computeroutput">nonfinite_num_get</code> take
+ an optional bit flags argument. There are four different bit flags:
+ 
+<div class="itemizedlist"><ul type="disc">
+<li>
+ legacy
+ </li>
+<li>
+ signed_zero
+ </li>
+<li>
+ trap_infinity
+ </li>
+<li>
+ trap_nan
+ </li>
+</ul></div>
+
+ The flags can be combined with the OR <code class="computeroutput">operator|</code>.
+ 
+
+ The flags are defined in the header <code class="computeroutput">boost/math/nonfinite_num_facets.hpp</code> and live in the <code class="computeroutput">namespace
+ boost::math</code>.
+ 
+<a name="math_toolkit.utils.fp_facets.legacy"></a><h6>
+<a name="id1127373"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.legacy">legacy</a>
+ </h6>
+
+ The legacy flag has no effect with the output facet <code class="computeroutput">nonfinite_num_put</code>.
+ 
+
+ If the legacy flag is used with the <code class="computeroutput">nonfinite_num_get</code>
+ input facet, then the facet will recognize all the following string representations
+ of <code class="computeroutput">infinity</code> and <code class="computeroutput">NaN</code>:
+ 
+<div class="informaltable"><table class="table">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>
+ 
+ Number
+ 
+ </th>
+<th>
+ 
+ String
+ 
+ </th>
+</tr></thead>
+<tbody>
+<tr>
+<td>
+ 
+ Positive infinity
+ 
+ </td>
+<td>
+ 
+ inf, infinity, one#inf
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Positive NaN
+ 
+ </td>
+<td>
+ 
+ nan, nan(...), nanq, nans, qnan, snan, one#ind, one#qnan, one#snan
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative infinity
+ 
+ </td>
+<td>
+ 
+ -inf, -infinity, -one#inf
+ 
+ </td>
+</tr>
+<tr>
+<td>
+ 
+ Negative NaN
+ 
+ </td>
+<td>
+ 
+ -nan, -nan(...), -nanq, -nans, -qnan, -snan, -one#ind, - one#qnan,
+ -one#snan
+ 
+ </td>
+</tr>
+</tbody>
+</table></div>
+
+ The numbers can be of type <code class="computeroutput">float</code>,
+ <code class="computeroutput">double</code> and <code class="computeroutput">long
+ double</code>. The facet is case-insensitive.
+ An optional <code class="computeroutput">+</code> sign can be used
+ with the positive values. The dots in <code class="computeroutput">nan(...)</code> stand for an arbitrary string. <code class="computeroutput">one</code> stands for any string that <code class="computeroutput">std::num_get</code>
+ parses as the number <code class="computeroutput">1.</code>.
+ 
+
+ The list includes a number of non-standard string representations of infinity
+ and NaN that are used by various existing implementations of the C++ standard
+ library, and also string representations used by other programming languages.
+ 
+<a name="math_toolkit.utils.fp_facets.signed_zero"></a><h6>
+<a name="id1127613"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.signed_zero">signed_zero</a>
+ </h6>
+
+ If the <code class="computeroutput">signed_zero</code> flag is
+ used with <code class="computeroutput">nonfinite_num_put</code>,
+ then the facet will distinguish between positive and negative zero. It will
+ format positive zero as "0" or "+0" and negative zero
+ as "-0". The string representation of positive zero can be controlled
+ with the <code class="computeroutput">showpos</code> and <code class="computeroutput">noshowpos</code> manipulators.
+ 
+
+ The <code class="computeroutput">signed_zero flag</code>
+ has no effect with the input facet <code class="computeroutput">nonfinite_num_get</code>.
+ The input facet <code class="computeroutput">nonfinite_num_get</code>
+ always parses "0" and "+0" as positive zero and "-0"
+ as negative zero, as do most implementations of <code class="computeroutput">std::num_get</code>.
+ 
+<a name="math_toolkit.utils.fp_facets.trap_infinity"></a><h6>
+<a name="id1127703"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.trap_infinity">trap_infinity</a>
+ </h6>
+
+ If the <code class="computeroutput">trap_infinity</code> flag
+ is used with <code class="computeroutput">nonfinite_num_put</code>,
+ then the facet will throw an exception of type <code class="computeroutput">std::ios_base::failure</code>
+ when an attempt is made to format positive or negative infinity. If the facet
+ is called from a stream insertion operator, then the stream will catch that
+ exception and set either its <code class="computeroutput">fail
+ bit</code> or its <code class="computeroutput">bad
+ bit</code>. Which bit is set is platform
+ dependent.
+ 
+
+ If the <code class="computeroutput">trap_infinity</code> flag
+ is used with <code class="computeroutput">nonfinite_num_get</code>,
+ then the facet will set the <code class="computeroutput">fail
+ bit</code> of the stream when an attempt
+ is made to parse a string that represents positive or negative infinity.
+ 
+
+ (See Design Rationale below for a discussion of this inconsistency.)
+ 
+<a name="math_toolkit.utils.fp_facets.trap_nan"></a><h6>
+<a name="id1127816"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.trap_nan">trap_nan</a>
+ </h6>
+
+ Same as <code class="computeroutput">trap_infinity</code>, but
+ positive and negative NaN are trapped instead.
+ 
+<a name="math_toolkit.utils.fp_facets.examples"></a><h4>
+<a name="id1127840"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.examples">Examples</a>
+ </h4>
+<a name="math_toolkit.utils.fp_facets.simple_example_with_std__stringstreams"></a><h6>
+<a name="id1127853"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.simple_example_with_std__stringstreams">Simple
+ example with std::stringstreams</a>
+ </h6>
+
+
+
+<pre class="programlisting">locale old_locale;
+locale tmp_locale(old_locale, new nonfinite_num_put<char>);
+locale new_locale(tmp_locale, new nonfinite_num_get<char>);
+</pre>
+
+ 
+
+
+
+<pre class="programlisting">stringstream ss;
+ss.imbue(new_locale);
+double inf = numeric_limits<double>::infinity();
+ss << inf; // Write out.
+assert(ss.str() == "inf");
+ double r;
+ss >> r; // Read back in.
+assert(inf == r); // Confirms that the double values really are identical.
+
+cout << "infinity output was " << ss.str() << endl;
+cout << "infinity input was " << r << endl;
+// But the string representation of r displayed will be the native type
+// because, when it was constructed, cout had NOT been imbued
+// with the new locale containing the nonfinite_numput facet.
+// So the cout output will be "1.#INF on MS platforms
+// and may be "inf" or other string representation on other platforms.
+
+</pre>
+
+ 
+<a name="math_toolkit.utils.fp_facets.use_with_lexical_cast"></a><h6>
+<a name="id1129645"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.use_with_lexical_cast">Use with
+ lexical_cast</a>
+ </h6>
+
+ Without using a new locale that contains the nonfinite facets, <code class="computeroutput">lexical_cast</code> is not portable (and often
+ fails) if nonfinite values are found.
+ 
+
+
+
+<pre class="programlisting">locale old_locale;
+locale tmp_locale(old_locale, new nonfinite_num_put<char>);
+locale new_locale(tmp_locale, new nonfinite_num_get<char>);
+</pre>
+
+ 
+
+ Although other examples imbue individual streams with the new locale, for
+ the streams constructed inside lexical_cast, it is necesary to assign to
+ a global locale.
+ 
+<pre class="programlisting">locale::global(new_locale);
+</pre>
+
+ <code class="computeroutput">lexical_cast</code> then works as
+ expected, even with infinity and NaNs.
+ 
+<pre class="programlisting">double x = boost::lexical_cast<double>("inf");
+assert(x == std::numeric:limits<double>::infinity());
+
+string s = boost::lexical_cast<string>(numeric_limits<double>::infinity());
+assert(s == "inf");
+</pre>
+<div class="warning"><table border="0" summary="Warning">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
+<th align="left">Warning</th>
+</tr>
+<tr><td align="left" valign="top">
+ You should be aware that the C++ specification does not explicitly require
+ that input from decimal digits strings converts with rounding to the nearest
+ representable floating-point binary value. (In contrast, decimal digits
+ read by the compiler, for example by an assignment like <code class="computeroutput">double
+ d =
+ 1.234567890123456789</code>, are guaranteed
+ to assign the nearest representable value to double d). This implies that,
+ no matter how many decimal digits you provide, there is a potential uncertainty
+ of 1 least significant bit in the resulting binary value.
+ </td></tr>
+</table></div>
+
+ See <a href="http://en.wikipedia.org/wiki/Floating_point#Representable_numbers.2C_conversion_and_rounding" target="_top">for
+ more information on nearest representable and rounding</a>.
+ 
+
+ Most iostream libraries do in fact achieve the desirable nearest
+ representable floating-point binary value for all values of input.
+ However one popular STL library does not quite achieve this for 64-bit doubles.
+ See <a href="http://connect.microsoft.com/VisualStudio/feedback/details/98770/decimal-digit-string-input-to-double-may-be-1-bit-wrong" target="_top">Decimal
+ digit string input to double may be 1 bit wrong</a> for the bizarre full
+ details.
+ 
+
+ If you are expecting to 'round-trip' <code class="computeroutput">lexical_cast</code>
+ or <code class="computeroutput">serialization</code>, for example
+ archiving and loading, and want to be absolutely certain
+ that you will always get an exactly identical double value binary pattern,
+ you should use the suggested 'workaround' below that is believed to work
+ on all platforms.
+ 
+
+ You should output using all potentially significant decimal digits, by setting
+ stream precision to <code class="computeroutput">std::numeric_limits<double>::max_digits10</code>, (or for the appropriate floating-point
+ type, if not double) and crucially, require <code class="computeroutput">scientific</code> format, not <code class="computeroutput">fixed</code> or automatic (default), for example:
+ 
+<pre class="programlisting">double output_value = any value;
+std::stringstream s;
+s << setprecison(std::numeric_limits<double>::max_digits10) << scientific << output_value;
+s >> input_value;
+</pre>
+<a name="math_toolkit.utils.fp_facets.use_with_serialization_archives"></a><h5>
+<a name="id1130272"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.use_with_serialization_archives">Use
+ with serialization archives</a>
+ </h5>
+
+ It is vital that the same locale is used when an archive is saved and when
+ it is loaded. Otherwise, loading the archive may fail. By default, archives
+ are saved and loaded with a classic C locale with a <code class="computeroutput">boost::archive::codecvt_null</code>
+ facet added. Normally you do not have to worry about that.
+ 
+
+ The constructors for the archive classes, as a side-effect, imbue the stream
+ with such a locale. However, if you want to use the facets <code class="computeroutput">nonfinite_num_put</code> and <code class="computeroutput">nonfinite_num_get</code>
+ with archives, then you have to manage the locale manually. That is done
+ by calling the archive constructor with the flag <code class="computeroutput">boost::archive::no_codecvt</code>,
+ thereby ensuring that the archive constructor will not
+ imbue the stream with a new locale.
+ 
+
+ The following code shows how to use <code class="computeroutput">nonfinite_num_put</code>
+ with a <code class="computeroutput">text_oarchive</code>.
+ 
+<pre class="programlisting">locale default_locale(locale::classic(), new boost::archive::codecvt_null<char>);
+locale my_locale(default_locale, new nonfinite_num_put<char>);
+
+ofstream ofs("test.txt");
+ofs.imbue(my_locale);
+
+boost::archive::text_oarchive oa(ofs, no_codecvt);
+
+double x = numeric_limits<double>::infinity();
+oa & x;
+</pre>
+
+ The same method works with <code class="computeroutput">nonfinite_num_get</code>
+ and <code class="computeroutput">text_iarchive</code>.
+ 
+
+ If you use the <code class="computeroutput">nonfinite_num_put</code>
+ with <code class="computeroutput">trap_infinity</code> and/or
+ <code class="computeroutput">trap_nan</code> flag with a serialization
+ archive, then you must set the exception mask of the stream. Serialization
+ archives do not check the stream state.
+ 
+<a name="math_toolkit.utils.fp_facets.other_examples"></a><h6>
+<a name="id1130668"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.other_examples">Other examples</a>
+ </h6>
+
+ nonfinite_facet_simple.cpp
+ give some more simple demonstrations of the difference between using classic
+ C locale and constructing a C99 infinty and NaN compliant locale for input
+ and output.
+ 
+
+ See nonfinite_facet_sstream.cpp
+ for this example of use with <code class="computeroutput">std::stringstream</code>s.
+ 
+
+ For an example of how to enforce the MSVC 'legacy' "1.#INF" and
+ "1.#QNAN" representations of infinity and NaNs, for input and output,
+ see nonfinite_legacy.cpp.
+ 
+
+ Treatment of signaling NaN is demonstrated at ../../../example/nonfinite_signaling_NaN.cpp
+ 
+
+ Example ../../../example/nonfinite_loopback_ok.cpp
+ shows loopback works OK.
+ 
+
+ Example ../../../example/nonfinite_num_facet.cpp
+ shows output and re-input of various finite and nonfinite values.
+ 
+
+ A very basic example of using Boost.Archive is at ../../../example/nonfinite_serialization_archives.cpp.
+ 
+
+ A full demonstration of serialization by Francois Mauger is at ../../../example/nonfinite_num_facet_serialization.cpp
+ 
+<a name="math_toolkit.utils.fp_facets.portability"></a><h5>
+<a name="id1130764"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.portability">Portability</a>
+ </h5>
+
+ This library uses the floating-point number classification and sign-bit from
+ Boost.Math library, and should work on all platforms where that library works.
+ See the portability information for that library.
+ 
+<a name="math_toolkit.utils.fp_facets.design_rationale"></a><h5>
+<a name="id1130781"></a>
+ <a class="link" href="fp_facets.html#math_toolkit.utils.fp_facets.design_rationale">Design Rationale</a>
+ </h5>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ The flags are implemented as a const data member of the facet. Facets
+ are reference counted, and locales can share facets. Therefore changing
+ the flags of a facet would have effects that are hard to predict. An
+ alternative design would be to implement the flags using <code class="computeroutput">std::ios_base::xalloc</code> and <code class="computeroutput">std::ios_base::iword</code>.
+ Then one could safely modify the flags, and one could define manipulators
+ that do so. However, for that to work with dynamically linked libraries,
+ a <code class="computeroutput">.cpp</code>
+ file would have to be added to the library. It was judged be more desirable
+ to have a headers only library, than to have mutable flags and manipulators.
+ </li>
+<li>
+ The facet <code class="computeroutput">nonfinite_num_put</code>
+ throws an exception when the <code class="computeroutput">trap_infinity</code>
+ or <code class="computeroutput">trap_nan</code> flag is set
+ and an attempt is made to format infinity or NaN. It would be better
+ if the facet set the fail bit of the stream. However, facets derived
+ from <code class="computeroutput">std::num_put</code> do not have access to the stream
+ state.
+ </li>
+</ul></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 , 2007, 2008, 2009, 2010 John Maddock, Paul A. Bristow,
+ Hubert Holin, Xiaogang Zhang, Bruno Lalande, Johan Råde, Gautam Sewani and
+ Thijs van den Berg
+ Distributed under the Boost Software License, Version 1.0. (See accompanying
+ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ 
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="sign_functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../utils.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="next_float.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

Next message: pbristow_at_[hidden]: "[Boost-commit] svn:boost r71396 - trunk/libs/math/doc/sf_and_dist"
Previous message: john_at_[hidden]: "[Boost-commit] svn:boost r71394 - trunk/libs/type_traits/test"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk