
Documentation of the class templates num_put_extended and num_get_extended

By Johan Rde, rade@maths.lth.se

Copyright (c) 2006 Johan Rde
Distributed under the Boost Software License, Version 1.0. 
(See http://www.boost.org/LICENSE_1_0.txt)

----- The Problem -----

The standard num_put and num_get facets often do a poor job
reading and writing non-finite floating point numbers.

For instance, the following test fails with VC++ 7.1.

	std::stringstream s;
	double x = std::numeric_limits<double>::infinity();
	double y;
	ss << x;
	ss >> y;
	assert(x == y);

The string "1.#INF" is written to the stream,
but then only "1" is read and the number 1 is returned.

The situation gets worse when text files are required to
be portable between different platforms.

----- The Solution -----

The facets num_put_extended and num_get_extended
write and read non-finite floating point numbers
to text streams in a consistent and portable manner.
The floating point type can be float, double and long double.
The character type can be char and wchar_t.

For an example of how to use the class templates num_put_extended
and num_get_extended, see the file non_finite_num_facets_test.cpp.

----- Details ------

The facets num_put_extended and num_get_extended write and read
finite floating point numbers the same way as std::num_put and std::num_get.
They write and read non-finite floating point numbers as follows:

num_put_extended:

	floating point value        ->         string value

	numeric_limits::infinity<T>()          "inf"
	-numeric_limits::infinity<T>()         "-inf"
	numeric_limits::quite_NaN<T>()         "nan"
	numeric_limits::signaling_NaN<T>()     "nan"

num_get_extended:

	string value  ->  floating point value

	"inf"             numeric_limits::infinity<T>() 
	"-inf"            -numeric_limits::infinity<T>()
	"+inf"            numeric_limits::infinity<T>() 
	"nan"             numeric_limits::quite_NaN<T>()
	
----- Limitations -----

If the string "inf", "-inf" or "+inf" is read on a platform
for which numeric_limits<T>::has_infinity is false,
then the fail bit of the stream is set.

If the string "nan" is read on a platform
for which numeric_limits<T>::has_quite_NaN is false,
then the fail bit of the stream is set.

----- Rationale -----

On some platforms the expression x == x evaluates to false
when x is quite_NaN or signaling_NaN.
This makes it difficult to distinguish between quite_NaN and signaling_NaN.

----- Supported Platforms -----

The code has been tested with VC++ 7.1.

If you test the code on another platform,
please report the result (good or bad) to me.
If you write a patch to make the code work on some platform,
please send the patch to me.
You can reach me at rade@maths.lth.se

----- Acknowledgemnts ------

Thanks to Robert Ramey for telling me about the classes std::put_num and std::get_num.



