...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 floating-point
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 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 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 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.
If the signed_zero
flag
is used with nonfinite_num_put
,
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 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
.
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.