...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
nonfinite_num_put
template< class CharType, class OutputIterator = std::ostreambuf_iterator<CharType> > class nonfinite_num_put;
The class nonfinite_num_put<CharType, OutputIterator>
is derived from std::num_put<CharType, OutputIterator>
. Thus it is a facet that formats numbers.
The first template argument is the character type of the formatted strings,
usually char
or wchar_t
. 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 std::ostreambuf_iterator
is used. The public interface of the class consists of a single constructor
only:
nonfinite_num_put(int flags = 0);
The flags argument (effectively optional because a default of no_flags
is provided) is discussed below.
The class template nonfinite_num_put
is defined in the header boost/math/nonfinite_num_facets.hpp
and lives in the namespace boost::math
.
Unlike the C++ Standard facet std::num_put
,
the facet nonfinite_num_put
formats infinity
and NaN
in a consistent and portable manner.
It uses the following string representations:
Number 
String 

Positive infinity 
inf 
Positive NaN 
nan 
Negative infinity 
inf 
Negative NaN 
nan 
The numbers can be of type float
,
double
and long
double
. 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 uppercase
,
lowercase
, showpos
and noshowpos
manipulators. Formatting of integers, boolean values and finite floatingpoint
numbers is simply delegated to the normal std::num_put
.
nonfinite_num_get
template<class CharType, class InputIterator = std::istreambuf_iterator<CharType> > class nonfinite_num_get;
The class nonfinite_num_get<CharType, InputIterator>
is derived from std::num_get<CharType, IntputIterator>
. Thus it is a facet that parses strings
that represent numbers. The first template argument is the character type
of the strings, usually char
or wchar_t
. 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:
nonfinite_num_get(int flags = 0);
The flags argument is discussed below. The class
template nonfinite_num_get
is defined in the header boost/math/nonfinite_num_facets.hpp
and lives in the namespace
boost::math
.
Unlike the facet std::num_get
, the facet nonfinite_num_get
parses strings that represent infinity
and NaN
in a consistent and
portable manner. It recognizes precisely the string representations specified
by the C99 standard:
Number 
String 

Positive infinity 
inf, infinity 
Positive NaN 
nan, nan(...) 
Negative infinity 
inf, infinity 
Negative NaN 
nan, nan(...) 
The numbers can be of type float
,
double
and long
double
. The facet is caseinsensitive.
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 floatingpoint
numbers is delegated to std::num_get
.
When the facet parses a string that represents infinity
on a platform that lacks infinity, then the fail bit of the stream is set.
When the facet parses a string that represents NaN
on a platform that lacks NaN, then the fail bit of the stream is set.
The constructors for nonfinite_num_put
and nonfinite_num_get
take
an optional bit flags argument. There are four different bit flags:
The flags can be combined with the OR operator
.
The flags are defined in the header boost/math/nonfinite_num_facets.hpp
and live in the namespace
boost::math
.
The legacy flag has no effect with the output facet nonfinite_num_put
.
If the legacy flag is used with the nonfinite_num_get
input facet, then the facet will recognize all the following string representations
of infinity
and NaN
:
Number 
String 

Positive infinity 
inf, infinity, one#inf 
Positive NaN 
nan, nan(...), nanq, nans, qnan, snan, one#ind, one#qnan, one#snan 
Negative infinity 
inf, infinity, one#inf 
Negative NaN 
nan, nan(...), nanq, nans, qnan, snan, one#ind,  one#qnan, one#snan 
float
,
double
and long double
.
+
sign can be
used with the positive values.
nan(...)
stand for an arbitrary string.
one
stands for any string
that std::num_get
parses as the number 1
, typically "1.#INF", "1.QNAN"
but also "000001.#INF"...
The list includes a number of nonstandard 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.
If the signed_zero
flag is
used with nonfinite_num_put
,
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 showpos
and noshowpos
manipulators.
The signed_zero flag
has no effect with the input facet nonfinite_num_get
.
The input facet nonfinite_num_get
always parses "0" and "+0" as positive zero and "0"
as negative zero, as do most implementations of std::num_get
.
Note  

If the 
Tip  

A negative zero value can be portably produced using the changesign function

If the trap_infinity
flag
is used with nonfinite_num_put
,
then the facet will throw an exception of type std::ios_base::failure
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 fail
bit
or its bad
bit
. Which bit is set is platform
dependent.
If the trap_infinity
flag
is used with nonfinite_num_get
,
then the facet will set the fail
bit
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.)
Same as trap_infinity
, but
positive and negative NaN are trapped instead.