townforge/math
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
cc
math/doc/html/math_toolkit/fp_facets/reference.html
jzmaddock 72e469da0a Update version number in docs. 
[CI SKIP]
2019-10-31 17:55:35 +00:00

493 lines
26 KiB
HTML
Raw Permalink Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Reference</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="facets_intro.html" title="Introduction">
<link rel="next" href="examples.html" title="Examples">
</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="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>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="math_toolkit.fp_facets.reference"></a><a class="link" href="reference.html" title="Reference">Reference</a>
</h3></div></div></div>
<h6>
<a name="math_toolkit.fp_facets.reference.h0"></a>
<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
Facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code></a>
</h6>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span>
<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">&lt;</span><span class="identifier">CharType</span><span class="special">&gt;</span>
<span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special">;</span>
</pre>
<p>
The <code class="computeroutput"><span class="keyword">class</span> <span class="identifier">nonfinite_num_put</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</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">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">OutputIterator</span><span class="special">&gt;</span></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"><span class="keyword">char</span></code> or <code class="computeroutput"><span class="keyword">wchar_t</span></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"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostreambuf_iterator</span></code>
is used. The public interface of the class consists of a single constructor
only:
</p>
<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>
</pre>
<p>
The flags argument (effectively optional because a default of <code class="computeroutput"> <span class="identifier">no_flags</span></code> is provided) is discussed below.
The class template <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
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>.
</p>
<p>
Unlike the C++ Standard facet <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_put</span></code>,
the facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
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.
It uses the following string representations:
</p>
<div class="informaltable"><table class="table">
<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
</p>
</td>
</tr>
<tr>
<td>
<p>
Positive NaN
</p>
</td>
<td>
<p>
nan
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative infinity
</p>
</td>
<td>
<p>
-inf
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative NaN
</p>
</td>
<td>
<p>
-nan
</p>
</td>
</tr>
</tbody>
</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>. 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"><span class="identifier">uppercase</span></code>,
<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>
manipulators. Formatting of integers, boolean values and finite floating-point
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>.
</p>
<h6>
<a name="math_toolkit.fp_facets.reference.h1"></a>
<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
<code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code></a>
</h6>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</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">&lt;</span><span class="identifier">CharType</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">nonfinite_num_get</span><span class="special">;</span>
</pre>
<p>
The class <code class="computeroutput"><span class="identifier">nonfinite_num_get</span><span class="special">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">InputIterator</span><span class="special">&gt;</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">&lt;</span><span class="identifier">CharType</span><span class="special">,</span> <span class="identifier">IntputIterator</span><span class="special">&gt;</span></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"><span class="keyword">char</span></code>
or <code class="computeroutput"><span class="keyword">wchar_t</span></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:
</p>
<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>
</pre>
<p>
The flags argument is discussed below. The <code class="computeroutput"><span class="keyword">class</span>
<span class="keyword">template</span> <span class="identifier">nonfinite_num_get</span></code>
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>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>.
</p>
<p>
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>
parses strings that represent <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. It recognizes precisely the string representations specified
by the C99 standard:
</p>
<div class="informaltable"><table class="table">
<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, infinity
</p>
</td>
</tr>
<tr>
<td>
<p>
Positive NaN
</p>
</td>
<td>
<p>
nan, nan(...)
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative infinity
</p>
</td>
<td>
<p>
-inf, -infinity
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative NaN
</p>
</td>
<td>
<p>
-nan, -nan(...)
</p>
</td>
</tr>
</tbody>
</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>. 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 <span class="emphasis"><em>NaN payload</em></span>.
Parsing of strings that represent integers, boolean values and finite floating-point
numbers is delegated to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">num_get</span></code>.
</p>
<p>
When the facet parses a string that represents <code class="computeroutput"><span class="identifier">infinity</span></code>
on a platform that lacks infinity, then the fail bit of the stream is set.
</p>
<p>
When the facet parses a string that represents <code class="computeroutput"><span class="identifier">NaN</span></code>
on a platform that lacks NaN, then the fail bit of the stream is set.
</p>
<h5>
<a name="math_toolkit.fp_facets.reference.h2"></a>
<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>
</h5>
<p>
The constructors for <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>
and <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code> take
an optional bit flags argument. There are four different bit flags:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
legacy
</li>
<li class="listitem">
signed_zero
</li>
<li class="listitem">
trap_infinity
</li>
<li class="listitem">
trap_nan
</li>
</ul></div>
<p>
The flags can be combined with the OR <code class="computeroutput"><span class="keyword">operator</span><span class="special">|</span></code>.
</p>
<p>
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>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span></code>.
</p>
<h6>
<a name="math_toolkit.fp_facets.reference.h3"></a>
<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>
</h6>
<p>
The legacy flag has no effect with the output facet <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>.
</p>
<p>
If the legacy flag is used with the <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
input facet, then the facet will recognize all the following string representations
of <code class="computeroutput"><span class="identifier">infinity</span></code> and <code class="computeroutput"><span class="identifier">NaN</span></code>:
</p>
<div class="informaltable"><table class="table">
<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, infinity, one#inf
</p>
</td>
</tr>
<tr>
<td>
<p>
Positive NaN
</p>
</td>
<td>
<p>
nan, nan(...), nanq, nans, qnan, snan, one#ind, one#qnan, one#snan
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative infinity
</p>
</td>
<td>
<p>
-inf, -infinity, -one#inf
</p>
</td>
</tr>
<tr>
<td>
<p>
Negative NaN
</p>
</td>
<td>
<p>
-nan, -nan(...), -nanq, -nans, -qnan, -snan, -one#ind, - one#qnan,
-one#snan
</p>
</td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
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>.
</li>
<li class="listitem">
The facet is case-insensitive.
</li>
<li class="listitem">
An optional <code class="computeroutput"><span class="special">+</span></code> sign can be
used with the positive values.
</li>
<li class="listitem">
The dots in <code class="computeroutput"><span class="identifier">nan</span><span class="special">(...)</span></code>
stand for an arbitrary string.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">one</span></code> stands for any string
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"
but also "000001.#INF"...
</li>
</ul></div>
<p>
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.
</p>
<h6>
<a name="math_toolkit.fp_facets.reference.h4"></a>
<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>
</h6>
<p>
If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag is
used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>,
then the facet will always 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"><span class="identifier">showpos</span></code>
and <code class="computeroutput"><span class="identifier">noshowpos</span></code> manipulators.
</p>
<p>
The <code class="computeroutput"><span class="identifier">signed_zero</span> <span class="identifier">flag</span></code>
has no effect with the input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>.
The input facet <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>
always parses "0" and "+0" as positive zero and "-0"
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>.
</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>
If the <code class="computeroutput"><span class="identifier">signed_zero</span></code> flag
is not set (the default), then a negative zero value will be displayed
on output in whatever way the platform normally handles it. For most platforms,
this it will format positive zero as "0" or "+0" and
negative zero as "-0". But setting the <code class="computeroutput"><span class="identifier">signed_zero</span></code>
flag may be more portable.
</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>
A negative zero value can be portably produced using the changesign function
<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">&lt;</span><span class="identifier">ValType</span><span class="special">&gt;(</span><span class="number">0</span><span class="special">))</span></code>
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>
or <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>,
or a User-Defined floating-point type (UDT) provided that this UDT has
a sign and that the changesign function is implemented.
</p></td></tr>
</table></div>
<h6>
<a name="math_toolkit.fp_facets.reference.h5"></a>
<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>
</h6>
<p>
If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag
is used with <code class="computeroutput"><span class="identifier">nonfinite_num_put</span></code>,
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>
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"><span class="identifier">fail</span>
<span class="identifier">bit</span></code> or its <code class="computeroutput"><span class="identifier">bad</span>
<span class="identifier">bit</span></code>. Which bit is set is platform
dependent.
</p>
<p>
If the <code class="computeroutput"><span class="identifier">trap_infinity</span></code> flag
is used with <code class="computeroutput"><span class="identifier">nonfinite_num_get</span></code>,
then the facet will set the <code class="computeroutput"><span class="identifier">fail</span>
<span class="identifier">bit</span></code> of the stream when an attempt
is made to parse a string that represents positive or negative infinity.
</p>
<p>
(See Design Rationale below for a discussion of this inconsistency.)
</p>
<h6>
<a name="math_toolkit.fp_facets.reference.h6"></a>
<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>
</h6>
<p>
Same as <code class="computeroutput"><span class="identifier">trap_infinity</span></code>, but
positive and negative NaN are trapped instead.
</p>
</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="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>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink