1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Importing and Exporting Data to and from cpp_int and cpp_bin_float</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="lits.html" title="Literal Types and constexpr Support"> 10<link rel="next" href="rounding.html" title="Rounding Rules for Conversions"> 11</head> 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> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="lits.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="rounding.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="boost_multiprecision.tut.import_export"></a><a class="link" href="import_export.html" title="Importing and Exporting Data to and from cpp_int and cpp_bin_float">Importing and 28 Exporting Data to and from <code class="computeroutput"><span class="identifier">cpp_int</span></code> 29 and <code class="computeroutput"><span class="identifier">cpp_bin_float</span></code></a> 30</h3></div></div></div> 31<p> 32 Any integer number type that uses <code class="computeroutput"><span class="identifier">cpp_int_backend</span></code> 33 as its implementation layer can import or export its bits via two non-member 34 functions: 35 </p> 36<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span><span class="special">,</span> 37 <span class="identifier">expression_template_option</span> <span class="identifier">ExpressionTemplates</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OutputIterator</span><span class="special">></span> 38<span class="identifier">OutputIterator</span> <span class="identifier">export_bits</span><span class="special">(</span> 39 <span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> <span class="identifier">val</span><span class="special">,</span> 40 <span class="identifier">OutputIterator</span> <span class="identifier">out</span><span class="special">,</span> 41 <span class="keyword">unsigned</span> <span class="identifier">chunk_size</span><span class="special">,</span> 42 <span class="keyword">bool</span> <span class="identifier">msv_first</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">);</span> 43 44<span class="keyword">template</span> <span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span><span class="special">,</span> 45 <span class="identifier">expression_template_option</span> <span class="identifier">ExpressionTemplates</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Iterator</span><span class="special">></span> 46<span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> 47 <span class="identifier">import_bits</span><span class="special">(</span> 48 <span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> <span class="identifier">val</span><span class="special">,</span> 49 <span class="identifier">Iterator</span> <span class="identifier">i</span><span class="special">,</span> 50 <span class="identifier">Iterator</span> <span class="identifier">j</span><span class="special">,</span> 51 <span class="keyword">unsigned</span> <span class="identifier">chunk_size</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> 52 <span class="keyword">bool</span> <span class="identifier">msv_first</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">);</span> 53</pre> 54<p> 55 These functions are designed for data-interchange with other storage formats, 56 and since <a class="link" href="floats/cpp_bin_float.html" title="cpp_bin_float">cpp_bin_float</a> 57 uses <a class="link" href="ints/cpp_int.html" title="cpp_int">cpp_int</a> 58 internally, by extension they can be used for floating-point numbers based 59 on that backend as well (see example below). Parameters and use are as follows: 60 </p> 61<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span><span class="special">,</span> 62 <span class="identifier">expression_template_option</span> <span class="identifier">ExpressionTemplates</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">OutputIterator</span><span class="special">></span> 63<span class="identifier">OutputIterator</span> <span class="identifier">export_bits</span><span class="special">(</span> 64 <span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> <span class="identifier">val</span><span class="special">,</span> 65 <span class="identifier">OutputIterator</span> <span class="identifier">out</span><span class="special">,</span> 66 <span class="keyword">unsigned</span> <span class="identifier">chunk_size</span><span class="special">,</span> 67 <span class="keyword">bool</span> <span class="identifier">msv_first</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">);</span> 68</pre> 69<p> 70 Exports the absolute value of <code class="computeroutput"><span class="identifier">val</span></code> 71 to OutputIterator <code class="computeroutput"><span class="identifier">out</span></code>. The 72 function will write <code class="computeroutput"><span class="identifier">chunk_size</span></code> 73 bits at a time to the OutputIterator, and if <code class="computeroutput"><span class="identifier">msv_first</span></code> 74 is true, will write the most-significant block first. Byte and bit order 75 within each <code class="computeroutput"><span class="identifier">chunk_size</span></code> block 76 is always in the machines native format. Further, each block is stored in 77 a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">uintmax_t</span></code> when it's assigned to <code class="computeroutput"><span class="special">*</span><span class="identifier">out</span></code>. 78 </p> 79<div class="note"><table border="0" summary="Note"> 80<tr> 81<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 82<th align="left">Note</th> 83</tr> 84<tr><td align="left" valign="top"><p> 85 Unfortunately, the standard's OutputIterator concept provides no means 86 of deducing the type to output since <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">OutputIteratorType</span><span class="special">>::</span><span class="identifier">value_type</span></code> 87 is type <code class="computeroutput"><span class="keyword">void</span></code>. This is why 88 the bit count for each block has to be specified manually. It may also 89 result in compiler warnings about the value being narrowed. 90 </p></td></tr> 91</table></div> 92<div class="tip"><table border="0" summary="Tip"> 93<tr> 94<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 95<th align="left">Tip</th> 96</tr> 97<tr><td align="left" valign="top"><p> 98 If you're exporting to non-native byte layout, then use <a href="http://www.boost.org/doc/libs/release/libs/endian/doc/index.html" target="_top">Boost.Endian</a> 99 to create a custom OutputIterator that reverses the byte order of each 100 chunk prior to actually storing the result. 101 </p></td></tr> 102</table></div> 103<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">unsigned</span> <span class="identifier">MinBits</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">cpp_integer_type</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">cpp_int_check_type</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Allocator</span><span class="special">,</span> 104 <span class="identifier">expression_template_option</span> <span class="identifier">ExpressionTemplates</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ForwardIterator</span><span class="special">></span> 105<span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> 106 <span class="identifier">import_bits</span><span class="special">(</span> 107 <span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><</span><span class="identifier">MinBits</span><span class="special">,</span> <span class="identifier">MaxBits</span><span class="special">,</span> <span class="identifier">SignType</span><span class="special">,</span> <span class="identifier">Checked</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">>,</span> <span class="identifier">ExpressionTemplates</span><span class="special">>&</span> <span class="identifier">val</span><span class="special">,</span> 108 <span class="identifier">ForwardIterator</span> <span class="identifier">i</span><span class="special">,</span> 109 <span class="identifier">ForwardIterator</span> <span class="identifier">j</span><span class="special">,</span> 110 <span class="keyword">unsigned</span> <span class="identifier">chunk_size</span> <span class="special">=</span> <span class="number">0</span><span class="special">,</span> 111 <span class="keyword">bool</span> <span class="identifier">msv_first</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">);</span> 112</pre> 113<p> 114 Imports bits from the iterator range <span class="emphasis"><em>[i,j)</em></span> and stores 115 them in <code class="computeroutput"><span class="identifier">val</span></code> to produce an 116 unsigned result (if the result is to be signed you will need to handle that 117 separately). When <code class="computeroutput"><span class="identifier">msv_first</span></code> 118 is true, takes <code class="computeroutput"><span class="special">*</span><span class="identifier">i</span></code> 119 as the most significant chunk. Assumes there are <code class="computeroutput"><span class="identifier">chunk_size</span></code> 120 bits in each value read from the iterator range, and that these are in machine 121 native bit/byte order. When <code class="computeroutput"><span class="identifier">chunk_size</span></code> 122 is zero, then assumes that each chunk contains <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier">ForwardIterator</span><span class="special">>::</span><span class="identifier">value_type</span><span class="special">>::</span><span class="identifier">digits</span></code>, 123 note that this will give the wrong result if dereferencing the iterators 124 leads to a signed-integer type, <span class="bold"><strong>and</strong></span> the 125 sign bit is significant (be particularly careful if you expect type <code class="computeroutput"><span class="keyword">char</span></code> to contain 8-bit values, as by default 126 it will extract only 7-bits at a time if <code class="computeroutput"><span class="keyword">char</span></code> 127 is signed). As with exporting, if the external data is to be in a non-native 128 byte order (within each chunk), then you will need to create an iterator 129 adaptor that presents it in native order (see <a href="http://www.boost.org/doc/libs/release/libs/endian/doc/index.html" target="_top">Boost.Endian</a>). 130 </p> 131<div class="note"><table border="0" summary="Note"> 132<tr> 133<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 134<th align="left">Note</th> 135</tr> 136<tr><td align="left" valign="top"><p> 137 Note that this function is optimized for the case where the data can be 138 <code class="computeroutput"><span class="identifier">memcpy</span></code>ed from the source 139 to the integer - in this case both iterators much be pointers, and everything 140 must be little-endian. 141 </p></td></tr> 142</table></div> 143<h5> 144<a name="boost_multiprecision.tut.import_export.h0"></a> 145 <span class="phrase"><a name="boost_multiprecision.tut.import_export.examples"></a></span><a class="link" href="import_export.html#boost_multiprecision.tut.import_export.examples">Examples</a> 146 </h5> 147<p> 148 In this simple example, we'll import/export the bits of a cpp_int to a vector 149 of 8-bit unsigned values: 150 </p> 151<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_int</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 152<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 153<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iomanip</span><span class="special">></span> 154<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> 155<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iterator</span><span class="special">></span> 156 157 158<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 159<span class="special">{</span> 160 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_int</span><span class="special">;</span> 161 <span class="comment">// Create a cpp_int with just a couple of bits set:</span> 162 <span class="identifier">cpp_int</span> <span class="identifier">i</span><span class="special">;</span> 163 <span class="identifier">bit_set</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="number">5000</span><span class="special">);</span> <span class="comment">// set the 5000'th bit</span> 164 <span class="identifier">bit_set</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="number">200</span><span class="special">);</span> 165 <span class="identifier">bit_set</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="number">50</span><span class="special">);</span> 166 <span class="comment">// export into 8-bit unsigned values, most significant bit first:</span> 167 <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="keyword">char</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> 168 <span class="identifier">export_bits</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="number">8</span><span class="special">);</span> 169 <span class="comment">// import back again, and check for equality:</span> 170 <span class="identifier">cpp_int</span> <span class="identifier">j</span><span class="special">;</span> 171 <span class="identifier">import_bits</span><span class="special">(</span><span class="identifier">j</span><span class="special">,</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> 172 <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="identifier">i</span> <span class="special">==</span> <span class="identifier">j</span><span class="special">);</span> 173<span class="special">}</span> 174</pre> 175<p> 176 Importing or exporting cpp_bin_float is similar, but we must proceed via 177 an intermediate integer: 178 </p> 179<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">multiprecision</span><span class="special">/</span><span class="identifier">cpp_bin_float</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 180<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 181<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iomanip</span><span class="special">></span> 182<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> 183<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iterator</span><span class="special">></span> 184 185 186<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 187<span class="special">{</span> 188 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_float_100</span><span class="special">;</span> 189 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_int</span><span class="special">;</span> 190 <span class="comment">// Create a cpp_bin_float to import/export:</span> 191 <span class="identifier">cpp_bin_float_100</span> <span class="identifier">f</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 192 <span class="identifier">f</span> <span class="special">/=</span> <span class="number">3</span><span class="special">;</span> 193 <span class="comment">// export into 8-bit unsigned values, most significant bit first:</span> 194 <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="keyword">char</span><span class="special">></span> <span class="identifier">v</span><span class="special">;</span> 195 <span class="identifier">export_bits</span><span class="special">(</span><span class="identifier">cpp_int</span><span class="special">(</span><span class="identifier">f</span><span class="special">.</span><span class="identifier">backend</span><span class="special">().</span><span class="identifier">bits</span><span class="special">()),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">v</span><span class="special">),</span> <span class="number">8</span><span class="special">);</span> 196 <span class="comment">// Grab the exponent as well:</span> 197 <span class="keyword">int</span> <span class="identifier">e</span> <span class="special">=</span> <span class="identifier">f</span><span class="special">.</span><span class="identifier">backend</span><span class="special">().</span><span class="identifier">exponent</span><span class="special">();</span> 198 <span class="comment">// Import back again, and check for equality, we have to proceed via</span> 199 <span class="comment">// an intermediate integer:</span> 200 <span class="identifier">cpp_int</span> <span class="identifier">i</span><span class="special">;</span> 201 <span class="identifier">import_bits</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> 202 <span class="identifier">cpp_bin_float_100</span> <span class="identifier">g</span><span class="special">(</span><span class="identifier">i</span><span class="special">);</span> 203 <span class="identifier">g</span><span class="special">.</span><span class="identifier">backend</span><span class="special">().</span><span class="identifier">exponent</span><span class="special">()</span> <span class="special">=</span> <span class="identifier">e</span><span class="special">;</span> 204 <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="identifier">f</span> <span class="special">==</span> <span class="identifier">g</span><span class="special">);</span> 205<span class="special">}</span> 206</pre> 207</div> 208<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 209<td align="left"></td> 210<td align="right"><div class="copyright-footer">Copyright © 2002-2020 John 211 Maddock and Christopher Kormanyos<p> 212 Distributed under the Boost Software License, Version 1.0. (See accompanying 213 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>) 214 </p> 215</div></td> 216</tr></table> 217<hr> 218<div class="spirit-nav"> 219<a accesskey="p" href="lits.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="rounding.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 220</div> 221</body> 222</html> 223
