libs/multiprecision/doc/html/boost_multiprecision/tut/conversions.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Constructing and Interconverting Between Number Types</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&#160;1.&#160;Boost.Multiprecision">
   8 <link rel="up" href="../tut.html" title="Tutorial">
   9 <link rel="prev" href="misc/visualizers.html" title="Visual C++ Debugger Visualizers">
  10 <link rel="next" href="random.html" title="Generating Random Numbers">
  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="misc/visualizers.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="random.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.conversions"></a><a class="link" href="conversions.html" title="Constructing and Interconverting Between Number Types">Constructing and
  28       Interconverting Between Number Types</a>
  29 </h3></div></div></div>
  30 <p>
  31         All of the number types that are based on <code class="computeroutput"><span class="identifier">number</span></code>
  32         have certain conversion rules in common. In particular:
  33       </p>
  34 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  35 <li class="listitem">
  36 <p class="simpara">
  37             Any number type can be constructed (or assigned) from any builtin arithmetic
  38             type, as long as the conversion isn't lossy (for example float to int
  39             conversion):
  40           </p>
  41 <pre class="programlisting"><span class="identifier">cpp_dec_float_50</span> <span class="identifier">df</span><span class="special">(</span><span class="number">0.5</span><span class="special">);</span>   <span class="comment">// OK construction from double</span>
  42 <span class="identifier">cpp_int</span>          <span class="identifier">i</span><span class="special">(</span><span class="number">450</span><span class="special">);</span>    <span class="comment">// OK constructs from signed int</span>
  43 <span class="identifier">cpp_int</span>          <span class="identifier">j</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">;</span>  <span class="comment">// Error, lossy conversion.</span>
  44 </pre>
  45 </li>
  46 <li class="listitem">
  47 <p class="simpara">
  48             A number can be explicitly constructed from an arithmetic type, even
  49             when the conversion is lossy:
  50           </p>
  51 <pre class="programlisting"><span class="identifier">cpp_int</span>          <span class="identifier">i</span><span class="special">(</span><span class="number">3.14</span><span class="special">);</span>       <span class="comment">// OK explicit conversion</span>
  52 <span class="identifier">i</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">cpp_int</span><span class="special">&gt;(</span><span class="number">3.14</span><span class="special">)</span>  <span class="comment">// OK explicit conversion</span>
  53 <span class="identifier">i</span><span class="special">.</span><span class="identifier">assign</span><span class="special">(</span><span class="number">3.14</span><span class="special">);</span>                 <span class="comment">// OK, explicit assign and avoid a temporary from the cast above</span>
  54 <span class="identifier">i</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">;</span>                       <span class="comment">// Error, no implicit assignment operator for lossy conversion.</span>
  55 <span class="identifier">cpp_int</span>          <span class="identifier">j</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">;</span>      <span class="comment">// Error, no implicit constructor for lossy conversion.</span>
  56 </pre>
  57 </li>
  58 <li class="listitem">
  59 <p class="simpara">
  60             A <code class="computeroutput"><span class="identifier">number</span></code> can be converted
  61             to any built in type, via the <code class="computeroutput"><span class="identifier">convert_to</span></code>
  62             member function:
  63           </p>
  64 <pre class="programlisting"><span class="identifier">mpz_int</span> <span class="identifier">z</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
  65 <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">z</span><span class="special">.</span><span class="identifier">convert_to</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;();</span> <span class="comment">// sets i to 2</span>
  66 </pre>
  67 </li>
  68 <li class="listitem">
  69             Conversions to rational numbers from floating-point ones are always allowed,
  70             and are exact and implicit as long as the rational number uses an unbounded
  71             integer type. Please be aware that constructing a rational number from
  72             an extended precision floating-point type with a large exponent range
  73             can effectively run the system out of memory, as in the extreme case
  74             <span class="emphasis"><em>2<sup>max_exponent</sup> / CHAR_BITS</em></span> bytes of storage may be
  75             required. This does not represent a problem for built in floating-point
  76             types however, as the exponent range for these is rather limited.
  77           </li>
  78 <li class="listitem">
  79             Conversions to floating-point numbers from rational ones are rounded
  80             to nearest (less than 0.5ulp error) as long as the floating-point number
  81             is binary, and the integer type used by the rational number is unbounded.
  82           </li>
  83 </ul></div>
  84 <p>
  85         Additional conversions may be supported by particular backends.
  86       </p>
  87 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  88 <li class="listitem">
  89 <p class="simpara">
  90             A <code class="computeroutput"><span class="identifier">number</span></code> can be converted
  91             to any built in type, via an explicit conversion operator: this functionality
  92             is only available on compilers supporting C++11's explicit conversion
  93             syntax.
  94           </p>
  95 <pre class="programlisting"><span class="identifier">mpz_int</span> <span class="identifier">z</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
  96 <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">z</span><span class="special">;</span>                     <span class="comment">// Error, implicit conversion not allowed.</span>
  97 <span class="keyword">int</span> <span class="identifier">j</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">z</span><span class="special">);</span>   <span class="comment">// OK explicit conversion.</span>
  98 </pre>
  99 </li>
 100 <li class="listitem">
 101 <p class="simpara">
 102             Any number type can be <span class="emphasis"><em>explicitly</em></span> constructed (or
 103             assigned) from a <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span></code>
 104             or a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>:
 105           </p>
 106 <pre class="programlisting"><span class="comment">// pi to 50 places from a string:</span>
 107 <span class="identifier">cpp_dec_float_50</span> <span class="identifier">df</span><span class="special">(</span><span class="string">"3.14159265358979323846264338327950288419716939937510"</span><span class="special">);</span>
 108 <span class="comment">// Integer type will automatically detect "0x" and "0" prefixes and parse the string accordingly:</span>
 109 <span class="identifier">cpp_int</span>          <span class="identifier">i</span><span class="special">(</span><span class="string">"0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFF000000000000000"</span><span class="special">);</span>
 110 <span class="comment">// Invalid input always results in a std::runtime_error being thrown:</span>
 111 <span class="identifier">i</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">cpp_int</span><span class="special">&gt;(</span><span class="string">"3.14"</span><span class="special">);</span>
 112 <span class="comment">// implicit conversions from strings are not allowed:</span>
 113 <span class="identifier">i</span> <span class="special">=</span> <span class="string">"23"</span><span class="special">;</span> <span class="comment">// Error, no assignment operator for implicit conversion from string</span>
 114 <span class="comment">// assign member function, avoids having to create a temporary via a static_cast:</span>
 115 <span class="identifier">i</span><span class="special">.</span><span class="identifier">assign</span><span class="special">(</span><span class="string">"23"</span><span class="special">);</span>  <span class="comment">// OK</span>
 116 </pre>
 117 </li>
 118 <li class="listitem">
 119 <p class="simpara">
 120             Any number type will interoperate with the builtin types in arithmetic
 121             expressions as long as the conversions are not lossy:
 122           </p>
 123 <pre class="programlisting"><span class="comment">// pi to 50 places from a string:</span>
 124 <span class="identifier">cpp_dec_float_50</span> <span class="identifier">df</span> <span class="special">=</span> <span class="string">"3.14159265358979323846264338327950288419716939937510"</span><span class="special">;</span>
 125 <span class="comment">// Multiply by 2 - using an integer literal here is usually more efficient</span>
 126 <span class="comment">// than constructing a temporary:</span>
 127 <span class="identifier">df</span> <span class="special">*=</span> <span class="number">2</span><span class="special">;</span>
 128
 129 <span class="comment">// You can't mix integer types with floats though:</span>
 130 <span class="identifier">cpp_int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
 131 <span class="identifier">i</span> <span class="special">*=</span> <span class="number">3.14</span><span class="special">;</span>  <span class="comment">// Error, no *= operator will be found.</span>
 132 </pre>
 133 </li>
 134 <li class="listitem">
 135 <p class="simpara">
 136             Any number type can be streamed to and from the C++ iostreams:
 137           </p>
 138 <pre class="programlisting"><span class="identifier">cpp_dec_float_50</span> <span class="identifier">df</span> <span class="special">=</span> <span class="string">"3.14159265358979323846264338327950288419716939937510"</span><span class="special">;</span>
 139 <span class="comment">// Now print at full precision:</span>
 140 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;::</span><span class="identifier">max_digits10</span><span class="special">)</span>
 141    <span class="special">&lt;&lt;</span> <span class="identifier">df</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span>
 142 <span class="identifier">cpp_int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">1</span><span class="special">;</span>
 143 <span class="identifier">i</span> <span class="special">&lt;&lt;=</span> <span class="number">256</span><span class="special">;</span>
 144 <span class="comment">// Now print in hex format with prefix:</span>
 145 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">hex</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">showbase</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 146 </pre>
 147 </li>
 148 <li class="listitem">
 149 <p class="simpara">
 150             Interconversions between number types of the same family are allowed
 151             and are implicit conversions if no loss of precision is involved, and
 152             explicit if it is:
 153           </p>
 154 <pre class="programlisting"><span class="identifier">int128_t</span>     <span class="identifier">i128</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 155 <span class="identifier">int266_t</span>     <span class="identifier">i256</span> <span class="special">=</span> <span class="identifier">i128</span><span class="special">;</span>  <span class="comment">// OK implicit widening conversion</span>
 156 <span class="identifier">i128_t</span>            <span class="special">=</span> <span class="identifier">i256</span><span class="special">;</span>  <span class="comment">// Error, no assignment operator found, narrowing conversion is explicit.</span>
 157 <span class="identifier">i128_t</span>            <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">int128_t</span><span class="special">&gt;(</span><span class="identifier">i256</span><span class="special">);</span> <span class="comment">// OK, explicit narrowing conversion.</span>
 158
 159 <span class="identifier">mpz_int</span>      <span class="identifier">z</span>    <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
 160 <span class="identifier">mpf_float</span>    <span class="identifier">f</span>    <span class="special">=</span> <span class="identifier">z</span><span class="special">;</span>    <span class="comment">// OK, GMP handles this conversion natively, and it's not lossy and therefore implicit.</span>
 161
 162 <span class="identifier">mpf_float_50</span> <span class="identifier">f50</span>  <span class="special">=</span> <span class="number">2</span><span class="special">;</span>
 163 <span class="identifier">f</span>                 <span class="special">=</span> <span class="identifier">f50</span><span class="special">;</span>  <span class="comment">// OK, conversion from fixed to variable precision, f will have 50 digits precision.</span>
 164 <span class="identifier">f50</span>               <span class="special">=</span> <span class="identifier">f</span><span class="special">;</span>    <span class="comment">// Error, conversion from variable to fixed precision is potentially lossy, explicit cast required.</span>
 165 </pre>
 166 </li>
 167 <li class="listitem">
 168 <p class="simpara">
 169             Some interconversions between number types are completely generic, and
 170             are always available, albeit the conversions are always <span class="emphasis"><em>explicit</em></span>:
 171           </p>
 172 <pre class="programlisting"><span class="identifier">cpp_int</span> <span class="identifier">cppi</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
 173 <span class="comment">// We can always convert between numbers of the same category -</span>
 174 <span class="comment">// int to int, rational to rational, or float to float, so this is OK</span>
 175 <span class="comment">// as long as we use an explicit conversion:</span>
 176 <span class="identifier">mpz_int</span> <span class="identifier">z</span><span class="special">(</span><span class="identifier">cppi</span><span class="special">);</span>
 177 <span class="comment">// We can always promote from int to rational, int to float, or rational to float:</span>
 178 <span class="identifier">cpp_rational</span>     <span class="identifier">cppr</span><span class="special">(</span><span class="identifier">cppi</span><span class="special">);</span>  <span class="comment">// OK, int to rational</span>
 179 <span class="identifier">cpp_dec_float_50</span> <span class="identifier">df</span><span class="special">(</span><span class="identifier">cppi</span><span class="special">);</span>    <span class="comment">// OK, int to float</span>
 180 <span class="identifier">df</span>                  <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">cpp_dec_float_50</span><span class="special">&gt;(</span><span class="identifier">cppr</span><span class="special">);</span>  <span class="comment">// OK, explicit rational to float conversion</span>
 181 <span class="comment">// However narrowing and/or implicit conversions always fail:</span>
 182 <span class="identifier">cppi</span>                <span class="special">=</span>   <span class="identifier">df</span><span class="special">;</span>    <span class="comment">// Compiler error, conversion not allowed</span>
 183 </pre>
 184 </li>
 185 <li class="listitem">
 186 <p class="simpara">
 187             Other interconversions may be allowed as special cases, whenever the
 188             backend allows it:
 189           </p>
 190 <pre class="programlisting"><span class="identifier">mpf_t</span>     <span class="identifier">m</span><span class="special">;</span>           <span class="comment">// Native GMP type.</span>
 191 <span class="identifier">mpf_init_set_ui</span><span class="special">(</span><span class="identifier">m</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span> <span class="comment">// set to a value;</span>
 192 <span class="identifier">mpf_float</span> <span class="identifier">i</span><span class="special">(</span><span class="identifier">m</span><span class="special">);</span>        <span class="comment">// copies the value of the native type.</span>
 193 </pre>
 194 </li>
 195 </ul></div>
 196 <p>
 197         More information on what additional types a backend supports conversions
 198         from are given in the tutorial for each backend. The converting constructor
 199         will be implicit if the backend's converting constructor is also implicit,
 200         and explicit if the backends converting constructor is also explicit.
 201       </p>
 202 </div>
 203 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 204 <td align="left"></td>
 205 <td align="right"><div class="copyright-footer">Copyright &#169; 2002-2019 John Maddock
 206       and Christopher Kormanyos<p>
 207         Distributed under the Boost Software License, Version 1.0. (See accompanying
 208         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>)
 209       </p>
 210 </div></td>
 211 </tr></table>
 212 <hr>
 213 <div class="spirit-nav">
 214 <a accesskey="p" href="misc/visualizers.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="random.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 215 </div>
 216 </body>
 217 </html>