The Facet 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:

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.

Facet 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:

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.

Flags

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.

legacy

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:

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.

signed_zero

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 signed_zero 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 signed_zero flag may be more portable.

	Tip
	A negative zero value can be portably produced using the changesign function (changesign)(static_cast<ValType>(0)) where ValType is float, double or long double, or a User-Defined floating-point type (UDT) provided that this UDT has a sign and that the changesign function is implemented.

trap_infinity

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.)

trap_nan

Same as trap_infinity, but positive and negative NaN are trapped instead.