| Home | Libraries | People | FAQ | More

### Reference

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

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

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

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.

##### Flags

The constructors for `nonfinite_num_put` and `nonfinite_num_get` take an optional bit flags argument. There are four different bit flags:

- legacy
- signed_zero
- trap_infinity
- trap_nan

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

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

- The numbers can be of type `float`, `double` and `long double`.
- The facet is case-insensitive.
- An optional `+` sign can be used with the positive values.
- The dots in `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.

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