3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Input Output</title>
5 <link rel="stylesheet" href="../../multiprecision.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../index.html" title="Chapter 1. Boost.Multiprecision">
8 <link rel="up" href="../tut.html" title="Tutorial">
9 <link rel="prev" href="limits/how_to_tell.html" title="How to Determine the Kind of a Number From std::numeric_limits">
10 <link rel="next" href="hash.html" title="Hash Function Support">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="limits/how_to_tell.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hash.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h3 class="title">
27 <a name="boost_multiprecision.tut.input_output"></a><a class="link" href="input_output.html" title="Input Output">Input Output</a>
28 </h3></div></div></div>
30 <a name="boost_multiprecision.tut.input_output.h0"></a>
31 <span class="phrase"><a name="boost_multiprecision.tut.input_output.loopback_testing"></a></span><a class="link" href="input_output.html#boost_multiprecision.tut.input_output.loopback_testing">Loopback
35 <span class="emphasis"><em>Loopback</em></span> or <span class="emphasis"><em>round-tripping</em></span> refers
36 to writing out a value as a decimal digit string using <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">iostream</span></code>,
37 usually to a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>, and then reading the string
38 back in to another value, and confirming that the two values are identical.
39 A trivial example using <code class="computeroutput"><span class="keyword">float</span></code>
42 <pre class="programlisting"><span class="keyword">float</span> <span class="identifier">write</span><span class="special">;</span> <span class="comment">// Value to round-trip.</span>
43 <span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span> <span class="comment">// Read and write std::stringstream.</span>
44 <span class="identifier">ss</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">max_digits10</span><span class="special">);</span> <span class="comment">// Ensure all potentially significant bits are output.</span>
45 <span class="identifier">ss</span><span class="special">.</span><span class="identifier">flags</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">fmtflags</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">scientific</span><span class="special">));</span> <span class="comment">// Use scientific format.</span>
46 <span class="identifier">ss</span> <span class="special"><<</span> <span class="identifier">write</span><span class="special">;</span> <span class="comment">// Output to string.</span>
47 <span class="keyword">float</span> <span class="identifier">read</span><span class="special">;</span> <span class="comment">// Expected.</span>
48 <span class="identifier">ss</span> <span class="special">>></span> <span class="identifier">read</span><span class="special">;</span> <span class="comment">// Read decimal digits string from stringstream.</span>
49 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span><span class="identifier">write</span><span class="special">,</span> <span class="identifier">read</span><span class="special">);</span> <span class="comment">// Should be the same.</span>
52 and this can be run in a loop for all possible values of a 32-bit float.
53 For other floating-point types <code class="computeroutput"><span class="identifier">T</span></code>,
54 including built-in <code class="computeroutput"><span class="keyword">double</span></code>, it
55 takes far too long to test all values, so a reasonable test strategy is to
56 use a large number of random values.
58 <pre class="programlisting"><span class="identifier">T</span> <span class="identifier">write</span><span class="special">;</span>
59 <span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span> <span class="identifier">ss</span><span class="special">;</span>
60 <span class="identifier">ss</span><span class="special">.</span><span class="identifier">precision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">max_digits10</span><span class="special">);</span> <span class="comment">// Ensure all potentially significant bits are output.</span>
61 <span class="identifier">ss</span><span class="special">.</span><span class="identifier">flags</span><span class="special">(</span><span class="identifier">f</span><span class="special">);</span> <span class="comment">// Changed from default iostream format flags if desired.</span>
62 <span class="identifier">ss</span> <span class="special"><<</span> <span class="identifier">write</span><span class="special">;</span> <span class="comment">// Output to stringstream.</span>
64 <span class="identifier">T</span> <span class="identifier">read</span><span class="special">;</span>
65 <span class="identifier">ss</span> <span class="special">>></span> <span class="identifier">read</span><span class="special">;</span> <span class="comment">// Get read using operator>> from stringstream.</span>
66 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span><span class="identifier">read</span><span class="special">,</span> <span class="identifier">write</span><span class="special">);</span>
68 <span class="identifier">read</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">T</span><span class="special">>(</span><span class="identifier">ss</span><span class="special">.</span><span class="identifier">str</span><span class="special">());</span> <span class="comment">// Get read by converting from decimal digits string representation of write.</span>
69 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span><span class="identifier">read</span><span class="special">,</span> <span class="identifier">write</span><span class="special">);</span>
71 <span class="identifier">read</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">T</span><span class="special">>(</span><span class="identifier">write</span><span class="special">.</span><span class="identifier">str</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="identifier">f</span><span class="special">));</span> <span class="comment">// Get read using format specified when written.</span>
72 <span class="identifier">BOOST_CHECK_EQUAL</span><span class="special">(</span><span class="identifier">read</span><span class="special">,</span> <span class="identifier">write</span><span class="special">);</span>
75 The test at <a href="../../../../test/test_cpp_bin_float_io.cpp" target="_top">test_cpp_bin_float_io.cpp</a>
76 allows any floating-point type to be <span class="emphasis"><em>round_tripped</em></span> using
77 a wide range of fairly random values. It also includes tests compared a collection
78 of <a href="../../../../test/string_data.ipp" target="_top">stringdata</a> test cases
82 <a name="boost_multiprecision.tut.input_output.h1"></a>
83 <span class="phrase"><a name="boost_multiprecision.tut.input_output.comparing_with_output_using_buil"></a></span><a class="link" href="input_output.html#boost_multiprecision.tut.input_output.comparing_with_output_using_buil">Comparing
84 with output using Built-in types</a>
87 One can make some comparisons with the output of
89 <pre class="programlisting"><span class="special"><</span><span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_bin_float</span><span class="special"><</span><span class="number">53</span><span class="special">,</span> <span class="identifier">digit_count_2</span><span class="special">></span> <span class="special">></span>
92 which has the same number of significant bits (53) as 64-bit double precision
96 However, although most outputs are identical, there are differences on some
97 platforms caused by the implementation-dependent behaviours allowed by the
98 C99 specification <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf" target="_top">C99
99 ISO/IEC 9899:TC2</a>, incorporated by C++.
101 <div class="blockquote"><blockquote class="blockquote"><p>
102 <span class="emphasis"><em>"For e, E, f, F, g, and G conversions, if the number of
103 significant decimal digits is at most DECIMAL_DIG, then the result should
104 be correctly rounded. If the number of significant decimal digits is more
105 than DECIMAL_DIG but the source value is exactly representable with DECIMAL_DIG
106 digits, then the result should be an exact representation with trailing
107 zeros. Otherwise, the source value is bounded by two adjacent decimal strings
108 L < U, both having DECIMAL_DIG significant digits; the value of the
109 resultant decimal string D should satisfy L<= D <= U, with the extra
110 stipulation that the error should have a correct sign for the current rounding
111 direction."</em></span>
112 </p></blockquote></div>
114 So not only is correct rounding for the full number of digits not required,
115 but even if the <span class="bold"><strong>optional</strong></span> recommended practice
116 is followed, then the value of these last few digits is unspecified as long
117 as the value is within certain bounds.
119 <div class="note"><table border="0" summary="Note">
121 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
122 <th align="left">Note</th>
124 <tr><td align="left" valign="top"><p>
125 Do not expect the output from different platforms to be <span class="bold"><strong>identical</strong></span>,
126 but <code class="computeroutput"><span class="identifier">cpp_dec_float</span></code>, <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code> (and other backends) outputs
127 should be correctly rounded to the number of digits requested by the set
128 precision and format.
132 <a name="boost_multiprecision.tut.input_output.h2"></a>
133 <span class="phrase"><a name="boost_multiprecision.tut.input_output.macro_boost_mp_min_exponent_digi"></a></span><a class="link" href="input_output.html#boost_multiprecision.tut.input_output.macro_boost_mp_min_exponent_digi">Macro
134 BOOST_MP_MIN_EXPONENT_DIGITS</a>
137 <a href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf" target="_top">C99
138 Standard</a> for format specifiers, 7.19.6 Formatted input/output functions
142 "The exponent always contains at least two digits, and only as many
143 more digits as necessary to represent the exponent."
146 So to conform to the C99 standard (incorporated by C++)
148 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MP_MIN_EXPONENT_DIGITS</span> <span class="number">2</span>
151 Confusingly, Microsoft (and MinGW) do not conform to this standard and provide
152 <span class="bold"><strong>at least three digits</strong></span>, for example <code class="computeroutput"><span class="number">1e+001</span></code>. So if you want the output to match
153 that from built-in floating-point types on compilers that use Microsofts
156 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MP_MIN_EXPONENT_DIGITS</span> <span class="number">3</span>
159 Also useful to get the minimum exponent field width is
161 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MP_MIN_EXPONENT_DIGITS</span> <span class="number">1</span>
164 producing a compact output like <code class="computeroutput"><span class="number">2e+4</span></code>,
165 useful when conserving space is important.
168 Larger values are also supported, for example, value 4 for <code class="computeroutput"><span class="number">2e+0004</span></code> which may be useful to ensure that
172 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
173 <td align="left"></td>
174 <td align="right"><div class="copyright-footer">Copyright © 2002-2019 John Maddock
175 and Christopher Kormanyos<p>
176 Distributed under the Boost Software License, Version 1.0. (See accompanying
177 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
182 <div class="spirit-nav">
183 <a accesskey="p" href="limits/how_to_tell.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tut.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="hash.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>