123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787 |
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
- <title>Introduction</title>
- <link rel="stylesheet" href="../multiprecision.css" type="text/css">
- <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
- <link rel="home" href="../index.html" title="Chapter 1. Boost.Multiprecision">
- <link rel="up" href="../index.html" title="Chapter 1. Boost.Multiprecision">
- <link rel="prev" href="../index.html" title="Chapter 1. Boost.Multiprecision">
- <link rel="next" href="tut.html" title="Tutorial">
- </head>
- <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
- <table cellpadding="2" width="100%"><tr>
- <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
- <td align="center"><a href="../../../../../index.html">Home</a></td>
- <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
- <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
- <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
- <td align="center"><a href="../../../../../more/index.htm">More</a></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
- </div>
- <div class="section">
- <div class="titlepage"><div><div><h2 class="title" style="clear: both">
- <a name="boost_multiprecision.intro"></a><a class="link" href="intro.html" title="Introduction">Introduction</a>
- </h2></div></div></div>
- <p>
- The Multiprecision Library provides <a class="link" href="tut/ints.html" title="Integer Types">integer</a>,
- <a class="link" href="tut/rational.html" title="Rational Number Types">rational</a>, <a class="link" href="tut/floats.html" title="floating-point Numbers">floating-point</a>,
- and <a class="link" href="tut/complex.html" title="Complex Number Types">complex</a> types in
- C++ that have more range and precision than C++'s ordinary built-in types.
- The big number types in Multiprecision can be used with a wide selection of
- basic mathematical operations, elementary transcendental functions as well
- as the functions in Boost.Math. The Multiprecision types can also interoperate
- with any <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
- (built-in) type</a> in C++ using clearly defined conversion rules. This
- allows Boost.Multiprecision to be used for all kinds of mathematical calculations
- involving integer, rational and floating-point types requiring extended range
- and precision.
- </p>
- <p>
- Multiprecision consists of a generic interface to the mathematics of large
- numbers as well as a selection of big number back-ends, with support for integer,
- rational, floating-point, and complex types. Boost.Multiprecision provides
- a selection of back-ends provided off-the-rack in including interfaces to GMP,
- MPFR, MPIR, MPC, TomMath as well as its own collection of Boost-licensed, header-only
- back-ends for integers, rationals and floats. In addition, user-defined back-ends
- can be created and used with the interface of Multiprecision, provided the
- class implementation adheres to the necessary <a class="link" href="ref/backendconc.html" title="Backend Requirements">concepts</a>.
- </p>
- <p>
- Depending upon the number type, precision may be arbitrarily large (limited
- only by available memory), fixed at compile time (for example, 50 or 100 decimal
- digits), or a variable controlled at run-time by member functions. The types
- are <a href="https://en.wikipedia.org/wiki/Expression_templates" target="_top">expression
- templates</a> - enabled for better performance than naive user-defined
- types.
- </p>
- <p>
- The Multiprecision library comes in two distinct parts:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- An expression-template-enabled front-end <code class="computeroutput"><span class="identifier">number</span></code>
- that handles all the operator overloading, expression evaluation optimization,
- and code reduction.
- </li>
- <li class="listitem">
- A selection of back-ends that implement the actual arithmetic operations,
- and need conform only to the reduced interface requirements of the front-end.
- </li>
- </ul></div>
- <p>
- Separation of front-end and back-end allows use of highly refined, but restricted
- license libraries where possible, but provides Boost license alternatives for
- users who must have a portable unconstrained license. Which is to say some
- back-ends rely on 3rd party libraries, but a header-only Boost license version
- is always available (if somewhat slower).
- </p>
- <h6>
- <a name="boost_multiprecision.intro.h0"></a>
- <span class="phrase"><a name="boost_multiprecision.intro.getting_started"></a></span><a class="link" href="intro.html#boost_multiprecision.intro.getting_started">Getting
- started with Boost.Multiprecision</a>
- </h6>
- <p>
- Should you just wish to 'cut to the chase' just to get bigger integers and/or
- bigger and more precise reals as simply and portably as possible, close to
- 'drop-in' replacements for the <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental
- (built-in) type</a> analogs, then use a fully Boost-licensed number type,
- and skip to one of more of :
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- <a class="link" href="tut/ints/cpp_int.html" title="cpp_int">cpp_int</a> for
- multiprecision integers,
- </li>
- <li class="listitem">
- <a class="link" href="tut/rational/cpp_rational.html" title="cpp_rational">cpp_rational</a>
- for rational types,
- </li>
- <li class="listitem">
- <a class="link" href="tut/floats/cpp_bin_float.html" title="cpp_bin_float">cpp_bin_float</a>
- and <a class="link" href="tut/floats/cpp_dec_float.html" title="cpp_dec_float">cpp_dec_float</a>
- for multiprecision floating-point types,
- </li>
- <li class="listitem">
- <a class="link" href="tut/complex/cpp_complex.html" title="cpp_complex">cpp_complex</a>
- for complex types.
- </li>
- </ul></div>
- <p>
- The library is very often used via one of the predefined convenience <code class="computeroutput"><span class="keyword">typedef</span></code>s like <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">int128_t</span></code>
- or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_float_quad</span></code>.
- </p>
- <p>
- For example, if you want a signed, 128-bit fixed size integer:
- </p>
- <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> <span class="comment">// Integer types.</span>
- <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">int128_t</span> <span class="identifier">my_128_bit_int</span><span class="special">;</span>
- </pre>
- <p>
- Alternatively, and more adventurously, if you wanted an <a href="http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic" target="_top">arbitrary
- precision</a> integer type using <a href="http://gmplib.org" target="_top">GMP</a>
- as the underlying implementation then you could use:
- </p>
- <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">gmp</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="comment">// Defines the wrappers around the GMP library's types</span>
- <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">mpz_int</span> <span class="identifier">myint</span><span class="special">;</span> <span class="comment">// Arbitrary precision integer type.</span>
- </pre>
- <p>
- Or for a simple, portable 128-bit floating-point close to a drop-in for a
- <a href="https://en.cppreference.com/w/cpp/language/types" target="_top">fundamental (built-in)
- type</a> like <code class="computeroutput"><span class="keyword">double</span></code>, usually
- 64-bit
- </p>
- <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>
- <span class="identifier">boost</span><span class="special">::</span><span class="identifier">multiprecision</span><span class="special">::</span><span class="identifier">cpp_bin_float_quad</span> <span class="identifier">my_quad_real</span><span class="special">;</span>
- </pre>
- <p>
- Alternatively, you can compose your own 'custom' multiprecision type, by combining
- <code class="computeroutput"><span class="identifier">number</span></code> with one of the predefined
- back-end types. For example, suppose you wanted a 300 decimal digit floating-point
- type based on the <a href="http://www.mpfr.org" target="_top">MPFR</a> library. In
- this case, there's no predefined <code class="computeroutput"><span class="keyword">typedef</span></code>
- with that level of precision, so instead we compose our own:
- </p>
- <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">mpfr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="comment">// Defines the Backend type that wraps MPFR.</span>
- <span class="keyword">namespace</span> <span class="identifier">mp</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="comment">// Reduce the typing a bit later...</span>
- <span class="keyword">typedef</span> <span class="identifier">mp</span><span class="special">::</span><span class="identifier">number</span><span class="special"><</span><span class="identifier">mp</span><span class="special">::</span><span class="identifier">mpfr_float_backend</span><span class="special"><</span><span class="number">300</span><span class="special">></span> <span class="special">></span> <span class="identifier">my_float</span><span class="special">;</span>
- <span class="identifier">my_float</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">c</span><span class="special">;</span> <span class="comment">// These variables have 300 decimal digits precision.</span>
- </pre>
- <p>
- We can repeat the above example, but with the expression templates disabled
- (for faster compile times, but slower runtimes) by passing a second template
- argument to <code class="computeroutput"><span class="identifier">number</span></code>:
- </p>
- <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">mpfr</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> <span class="comment">// Defines the Backend type that wraps MPFR.</span>
- <span class="keyword">namespace</span> <span class="identifier">mp</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="comment">// Reduce the typing a bit later...</span>
- <span class="keyword">typedef</span> <span class="identifier">mp</span><span class="special">::</span><span class="identifier">number</span><span class="special"><</span><span class="identifier">mp</span><span class="special">::</span><span class="identifier">mpfr_float_backend</span><span class="special"><</span><span class="number">300</span><span class="special">>,</span> <span class="identifier">et_off</span><span class="special">></span> <span class="identifier">my_float</span><span class="special">;</span>
- <span class="identifier">my_float</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">c</span><span class="special">;</span> <span class="comment">// These variables have 300 decimal digits precision</span>
- </pre>
- <p>
- We can also mix arithmetic operations between different types, provided there
- is an unambiguous implicit conversion from one type to the other:
- </p>
- <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>
- <span class="keyword">namespace</span> <span class="identifier">mp</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="comment">// Reduce the typing a bit later...</span>
- <span class="identifier">mp</span><span class="special">::</span><span class="identifier">int128_t</span> <span class="identifier">a</span><span class="special">(</span><span class="number">3</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(</span><span class="number">4</span><span class="special">);</span>
- <span class="identifier">mp</span><span class="special">::</span><span class="identifier">int512_t</span> <span class="identifier">c</span><span class="special">(</span><span class="number">50</span><span class="special">),</span> <span class="identifier">d</span><span class="special">;</span>
- <span class="identifier">d</span> <span class="special">=</span> <span class="identifier">c</span> <span class="special">*</span> <span class="identifier">a</span><span class="special">;</span> <span class="comment">// OK, result of mixed arithmetic is an int512_t</span>
- </pre>
- <p>
- Conversions are also allowed:
- </p>
- <pre class="programlisting"><span class="identifier">d</span> <span class="special">=</span> <span class="identifier">a</span><span class="special">;</span> <span class="comment">// OK, widening conversion.</span>
- <span class="identifier">d</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">*</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// OK, can convert from an expression template too.</span>
- </pre>
- <p>
- However conversions that are inherently lossy are either declared explicit
- or else forbidden altogether:
- </p>
- <pre class="programlisting"><span class="identifier">d</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">;</span> <span class="comment">// Error implicit conversion from double not allowed.</span>
- <span class="identifier">d</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special"><</span><span class="identifier">mp</span><span class="special">::</span><span class="identifier">int512_t</span><span class="special">>(</span><span class="number">3.14</span><span class="special">);</span> <span class="comment">// OK explicit construction is allowed</span>
- </pre>
- <p>
- Mixed arithmetic will fail if the conversion is either ambiguous or explicit:
- </p>
- <pre class="programlisting"><span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><>,</span> <span class="identifier">et_off</span><span class="special">></span> <span class="identifier">a</span><span class="special">(</span><span class="number">2</span><span class="special">);</span>
- <span class="identifier">number</span><span class="special"><</span><span class="identifier">cpp_int_backend</span><span class="special"><>,</span> <span class="identifier">et_on</span><span class="special">></span> <span class="identifier">b</span><span class="special">(</span><span class="number">3</span><span class="special">);</span>
- <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">*</span> <span class="identifier">b</span><span class="special">;</span> <span class="comment">// Error, implicit conversion could go either way.</span>
- <span class="identifier">b</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">*</span> <span class="number">3.14</span><span class="special">;</span> <span class="comment">// Error, no operator overload if the conversion would be explicit.</span>
- </pre>
- <h5>
- <a name="boost_multiprecision.intro.h1"></a>
- <span class="phrase"><a name="boost_multiprecision.intro.move_semantics"></a></span><a class="link" href="intro.html#boost_multiprecision.intro.move_semantics">Move
- Semantics</a>
- </h5>
- <p>
- On compilers that support rvalue-references, class <code class="computeroutput"><span class="identifier">number</span></code>
- is move-enabled if the underlying backend is.
- </p>
- <p>
- In addition the non-expression template operator overloads (see below) are
- move aware and have overloads that look something like:
- </p>
- <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">B</span><span class="special">></span>
- <span class="identifier">number</span><span class="special"><</span><span class="identifier">B</span><span class="special">,</span> <span class="identifier">et_off</span><span class="special">></span> <span class="keyword">operator</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">number</span><span class="special"><</span><span class="identifier">B</span><span class="special">,</span> <span class="identifier">et_off</span><span class="special">>&&</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">B</span><span class="special">,</span> <span class="identifier">et_off</span><span class="special">>&</span> <span class="identifier">b</span><span class="special">)</span>
- <span class="special">{</span>
- <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">a</span> <span class="special">+=</span> <span class="identifier">b</span><span class="special">);</span>
- <span class="special">}</span>
- </pre>
- <p>
- These operator overloads ensure that many expressions can be evaluated without
- actually generating any temporaries. However, there are still many simple expressions
- such as
- </p>
- <pre class="programlisting"><span class="identifier">a</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">*</span> <span class="identifier">c</span><span class="special">;</span>
- </pre>
- <p>
- which don't noticeably benefit from move support. Therefore, optimal performance
- comes from having both move-support, and expression templates enabled.
- </p>
- <p>
- Note that while "moved-from" objects are left in a sane state, they
- have an unspecified value, and the only permitted operations on them are destruction
- or the assignment of a new value. Any other operation should be considered
- a programming error and all of our backends will trigger an assertion if any
- other operation is attempted. This behavior allows for optimal performance
- on move-construction (i.e. no allocation required, we just take ownership of
- the existing object's internal state), while maintaining usability in the standard
- library containers.
- </p>
- <h5>
- <a name="boost_multiprecision.intro.h2"></a>
- <span class="phrase"><a name="boost_multiprecision.intro.expression_templates"></a></span><a class="link" href="intro.html#boost_multiprecision.intro.expression_templates">Expression
- Templates</a>
- </h5>
- <p>
- Class <code class="computeroutput"><span class="identifier">number</span></code> is expression-template-enabled:
- that means that rather than having a multiplication operator that looks like
- this:
- </p>
- <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Backend</span><span class="special">></span>
- <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">></span> <span class="keyword">operator</span> <span class="special">*</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">>&</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">>&</span> <span class="identifier">b</span><span class="special">)</span>
- <span class="special">{</span>
- <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">></span> <span class="identifier">result</span><span class="special">(</span><span class="identifier">a</span><span class="special">);</span>
- <span class="identifier">result</span> <span class="special">*=</span> <span class="identifier">b</span><span class="special">;</span>
- <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
- <span class="special">}</span>
- </pre>
- <p>
- Instead the operator looks more like this:
- </p>
- <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">Backend</span><span class="special">></span>
- <span class="emphasis"><em>unmentionable-type</em></span> <span class="keyword">operator</span> <span class="special">*</span> <span class="special">(</span><span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">>&</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">number</span><span class="special"><</span><span class="identifier">Backend</span><span class="special">>&</span> <span class="identifier">b</span><span class="special">);</span>
- </pre>
- <p>
- Where the '<span class="emphasis"><em>unmentionable</em></span>' return type is an implementation
- detail that, rather than containing the result of the multiplication, contains
- instructions on how to compute the result. In effect it's just a pair of references
- to the arguments of the function, plus some compile-time information that stores
- what the operation is.
- </p>
- <p>
- The great advantage of this method is the <span class="emphasis"><em>elimination of temporaries</em></span>:
- for example, the "naive" implementation of <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code> above, requires one temporary for computing
- the result, and at least another one to return it. It's true that sometimes
- this overhead can be reduced by using move-semantics, but it can't be eliminated
- completely. For example, lets suppose we're evaluating a polynomial via Horner's
- method, something like this:
- </p>
- <pre class="programlisting"><span class="identifier">T</span> <span class="identifier">a</span><span class="special">[</span><span class="number">7</span><span class="special">]</span> <span class="special">=</span> <span class="special">{</span> <span class="comment">/* some values */</span> <span class="special">};</span>
- <span class="comment">//....</span>
- <span class="identifier">y</span> <span class="special">=</span> <span class="special">(((((</span><span class="identifier">a</span><span class="special">[</span><span class="number">6</span><span class="special">]</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">5</span><span class="special">])</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">4</span><span class="special">])</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">3</span><span class="special">])</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">2</span><span class="special">])</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">1</span><span class="special">])</span> <span class="special">*</span> <span class="identifier">x</span> <span class="special">+</span> <span class="identifier">a</span><span class="special">[</span><span class="number">0</span><span class="special">];</span>
- </pre>
- <p>
- If type <code class="computeroutput"><span class="identifier">T</span></code> is a <code class="computeroutput"><span class="identifier">number</span></code>, then this expression is evaluated
- <span class="emphasis"><em>without creating a single temporary value</em></span>. In contrast,
- if we were using the <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a>
- C++ wrapper for <a href="http://www.mpfr.org" target="_top">MPFR</a> - then this expression
- would result in no less than 11 temporaries (this is true even though <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a> does
- use expression templates to reduce the number of temporaries somewhat). Had
- we used an even simpler wrapper around <a href="http://www.mpfr.org" target="_top">MPFR</a>
- like <a href="http://www.holoborodko.com/pavel/mpfr/" target="_top">mpreal</a> things
- would have been even worse and no less that 24 temporaries are created for
- this simple expression (note - we actually measure the number of memory allocations
- performed rather than the number of temporaries directly, note also that the
- <a href="http://gmplib.org/manual/C_002b_002b-Interface-Floats.html#C_002b_002b-Interface-Floats" target="_top">mpf_class</a>
- wrapper that will be supplied with GMP-5.1 reduces the number of temporaries
- to pretty much zero). Note that if we compile with expression templates disabled
- and rvalue-reference support on, then actually still have no wasted memory
- allocations as even though temporaries are created, their contents are moved
- rather than copied. <a href="#ftn.boost_multiprecision.intro.f0" class="footnote" name="boost_multiprecision.intro.f0"><sup class="footnote">[1]</sup></a>
- </p>
- <div class="important"><table border="0" summary="Important">
- <tr>
- <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../doc/src/images/important.png"></td>
- <th align="left">Important</th>
- </tr>
- <tr><td align="left" valign="top">
- <p>
- Expression templates can radically reorder the operations in an expression,
- for example:
- </p>
- <p>
- a = (b * c) * a;
- </p>
- <p>
- Will get transformed into:
- </p>
- <p>
- a *= c; a *= b;
- </p>
- <p>
- If this is likely to be an issue for a particular application, then they
- should be disabled.
- </p>
- </td></tr>
- </table></div>
- <p>
- This library also extends expression template support to standard library functions
- like <code class="computeroutput"><span class="identifier">abs</span></code> or <code class="computeroutput"><span class="identifier">sin</span></code>
- with <code class="computeroutput"><span class="identifier">number</span></code> arguments. This
- means that an expression such as:
- </p>
- <pre class="programlisting"><span class="identifier">y</span> <span class="special">=</span> <span class="identifier">abs</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
- </pre>
- <p>
- can be evaluated without a single temporary being calculated. Even expressions
- like:
- </p>
- <pre class="programlisting"><span class="identifier">y</span> <span class="special">=</span> <span class="identifier">sin</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
- </pre>
- <p>
- get this treatment, so that variable 'y' is used as "working storage"
- within the implementation of <code class="computeroutput"><span class="identifier">sin</span></code>,
- thus reducing the number of temporaries used by one. Of course, should you
- write:
- </p>
- <pre class="programlisting"><span class="identifier">x</span> <span class="special">=</span> <span class="identifier">sin</span><span class="special">(</span><span class="identifier">x</span><span class="special">);</span>
- </pre>
- <p>
- Then we clearly can't use <code class="computeroutput"><span class="identifier">x</span></code>
- as working storage during the calculation, so then a temporary variable is
- created in this case.
- </p>
- <p>
- Given the comments above, you might be forgiven for thinking that expression-templates
- are some kind of universal-panacea: sadly though, all tricks like this have
- their downsides. For one thing, expression template libraries like this one,
- tend to be slower to compile than their simpler cousins, they're also harder
- to debug (should you actually want to step through our code!), and rely on
- compiler optimizations being turned on to give really good performance. Also,
- since the return type from expressions involving <code class="computeroutput"><span class="identifier">number</span></code>s
- is an "unmentionable implementation detail", you have to be careful
- to cast the result of an expression to the actual number type when passing
- an expression to a template function. For example, given:
- </p>
- <pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
- <span class="keyword">void</span> <span class="identifier">my_proc</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&);</span>
- </pre>
- <p>
- Then calling:
- </p>
- <pre class="programlisting"><span class="identifier">my_proc</span><span class="special">(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">);</span>
- </pre>
- <p>
- Will very likely result in obscure error messages inside the body of <code class="computeroutput"><span class="identifier">my_proc</span></code> - since we've passed it an expression
- template type, and not a number type. Instead we probably need:
- </p>
- <pre class="programlisting"><span class="identifier">my_proc</span><span class="special">(</span><span class="identifier">my_number_type</span><span class="special">(</span><span class="identifier">a</span><span class="special">+</span><span class="identifier">b</span><span class="special">));</span>
- </pre>
- <p>
- Having said that, these situations don't occur that often - or indeed not at
- all for non-template functions. In addition, all the functions in the Boost.Math
- library will automatically convert expression-template arguments to the underlying
- number type without you having to do anything, so:
- </p>
- <pre class="programlisting"><span class="identifier">mpfr_float_100</span> <span class="identifier">a</span><span class="special">(</span><span class="number">20</span><span class="special">),</span> <span class="identifier">delta</span><span class="special">(</span><span class="number">0.125</span><span class="special">);</span>
- <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">gamma_p</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">delta</span><span class="special">);</span>
- </pre>
- <p>
- Will work just fine, with the <code class="computeroutput"><span class="identifier">a</span> <span class="special">+</span> <span class="identifier">delta</span></code> expression
- template argument getting converted to an <code class="computeroutput"><span class="identifier">mpfr_float_100</span></code>
- internally by the Boost.Math library.
- </p>
- <div class="caution"><table border="0" summary="Caution">
- <tr>
- <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../doc/src/images/caution.png"></td>
- <th align="left">Caution</th>
- </tr>
- <tr><td align="left" valign="top">
- <p>
- In C++11 you should never store an expression template using:
- </p>
- <p>
- <code class="computeroutput"><span class="keyword">auto</span> <span class="identifier">my_expression</span>
- <span class="special">=</span> <span class="identifier">a</span> <span class="special">+</span> <span class="identifier">b</span> <span class="special">-</span>
- <span class="identifier">c</span><span class="special">;</span></code>
- </p>
- <p>
- unless you're absolutely sure that the lifetimes of <code class="computeroutput"><span class="identifier">a</span></code>,
- <code class="computeroutput"><span class="identifier">b</span></code> and <code class="computeroutput"><span class="identifier">c</span></code>
- will outlive that of <code class="computeroutput"><span class="identifier">my_expression</span></code>.
- </p>
- <p>
- In fact, it is particularly easy to create dangling references by mixing
- expression templates with the <code class="computeroutput"><span class="keyword">auto</span></code>
- keyword, for example:
- </p>
- <p>
- <code class="computeroutput"><span class="keyword">auto</span> <span class="identifier">val</span>
- <span class="special">=</span> <span class="identifier">cpp_dec_float_50</span><span class="special">(</span><span class="string">"23.1"</span><span class="special">)</span> <span class="special">*</span> <span class="number">100</span><span class="special">;</span></code>
- </p>
- <p>
- In this situation, the integer literal is stored directly in the expression
- template - so its use is OK here - but the <code class="computeroutput"><span class="identifier">cpp_dec_float_50</span></code>
- temporary is stored by reference and then destructed when the statement completes,
- leaving a dangling reference.
- </p>
- <p>
- <span class="bold"><strong><span class="emphasis"><em>If in doubt, do not ever mix expression templates
- with the <code class="computeroutput"><span class="keyword">auto</span></code> keyword.</em></span></strong></span>
- </p>
- </td></tr>
- </table></div>
- <p>
- And finally... the performance improvements from an expression template library
- like this are often not as dramatic as the reduction in number of temporaries
- would suggest. For example, if we compare this library with <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a>
- and <a href="http://www.holoborodko.com/pavel/mpfr/" target="_top">mpreal</a>, with
- all three using the underlying <a href="http://www.mpfr.org" target="_top">MPFR</a>
- library at 50 decimal digits precision then we see the following typical results
- for polynomial execution:
- </p>
- <div class="table">
- <a name="boost_multiprecision.intro.evaluation_of_order_6_polynomial"></a><p class="title"><b>Table 1.1. Evaluation of Order 6 Polynomial.</b></p>
- <div class="table-contents"><table class="table" summary="Evaluation of Order 6 Polynomial.">
- <colgroup>
- <col>
- <col>
- <col>
- </colgroup>
- <thead><tr>
- <th>
- <p>
- Library
- </p>
- </th>
- <th>
- <p>
- Relative Time
- </p>
- </th>
- <th>
- <p>
- Relative number of memory allocations
- </p>
- </th>
- </tr></thead>
- <tbody>
- <tr>
- <td>
- <p>
- number
- </p>
- </td>
- <td>
- <p>
- 1.0 (0.00957s)
- </p>
- </td>
- <td>
- <p>
- 1.0 (2996 total)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a>
- </p>
- </td>
- <td>
- <p>
- 1.1 (0.0102s)
- </p>
- </td>
- <td>
- <p>
- 4.3 (12976 total)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://www.holoborodko.com/pavel/mpfr/" target="_top">mpreal</a>
- </p>
- </td>
- <td>
- <p>
- 1.6 (0.0151s)
- </p>
- </td>
- <td>
- <p>
- 9.3 (27947 total)
- </p>
- </td>
- </tr>
- </tbody>
- </table></div>
- </div>
- <br class="table-break"><p>
- As you can see, the execution time increases a lot more slowly than the number
- of memory allocations. There are a number of reasons for this:
- </p>
- <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
- <li class="listitem">
- The cost of extended-precision multiplication and division is so great,
- that the times taken for these tend to swamp everything else.
- </li>
- <li class="listitem">
- The cost of an in-place multiplication (using <code class="computeroutput"><span class="keyword">operator</span><span class="special">*=</span></code>) tends to be more than an out-of-place
- <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code>
- (typically <code class="computeroutput"><span class="keyword">operator</span> <span class="special">*=</span></code>
- has to create a temporary workspace to carry out the multiplication, where
- as <code class="computeroutput"><span class="keyword">operator</span><span class="special">*</span></code>
- can use the target variable as workspace). Since the expression templates
- carry out their magic by converting out-of-place operators to in-place
- ones, we necessarily take this hit. Even so the transformation is more
- efficient than creating the extra temporary variable, just not by as much
- as one would hope.
- </li>
- </ul></div>
- <p>
- Finally, note that <code class="computeroutput"><span class="identifier">number</span></code> takes
- a second template argument, which, when set to <code class="computeroutput"><span class="identifier">et_off</span></code>
- disables all the expression template machinery. The result is much faster to
- compile, but slower at runtime.
- </p>
- <p>
- We'll conclude this section by providing some more performance comparisons
- between these three libraries, again, all are using <a href="http://www.mpfr.org" target="_top">MPFR</a>
- to carry out the underlying arithmetic, and all are operating at the same precision
- (50 decimal digits):
- </p>
- <div class="table">
- <a name="boost_multiprecision.intro.evaluation_of_boost_math_s_besse"></a><p class="title"><b>Table 1.2. Evaluation of Boost.Math's Bessel function test data</b></p>
- <div class="table-contents"><table class="table" summary="Evaluation of Boost.Math's Bessel function test data">
- <colgroup>
- <col>
- <col>
- <col>
- </colgroup>
- <thead><tr>
- <th>
- <p>
- Library
- </p>
- </th>
- <th>
- <p>
- Relative Time
- </p>
- </th>
- <th>
- <p>
- Relative Number of Memory Allocations
- </p>
- </th>
- </tr></thead>
- <tbody>
- <tr>
- <td>
- <p>
- mpfr_float_50
- </p>
- </td>
- <td>
- <p>
- 1.0 (5.78s)
- </p>
- </td>
- <td>
- <p>
- 1.0 (1611963)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- number<mpfr_float_backend<50>, et_off><br> (but with
- rvalue reference support)
- </p>
- </td>
- <td>
- <p>
- 1.1 (6.29s)
- </p>
- </td>
- <td>
- <p>
- 2.64 (4260868)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a>
- </p>
- </td>
- <td>
- <p>
- 1.1 (6.28s)
- </p>
- </td>
- <td>
- <p>
- 2.45 (3948316)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://www.holoborodko.com/pavel/mpfr/" target="_top">mpreal</a>
- </p>
- </td>
- <td>
- <p>
- 1.65 (9.54s)
- </p>
- </td>
- <td>
- <p>
- 8.21 (13226029)
- </p>
- </td>
- </tr>
- </tbody>
- </table></div>
- </div>
- <br class="table-break"><div class="table">
- <a name="boost_multiprecision.intro.evaluation_of_boost_math_s_non_c"></a><p class="title"><b>Table 1.3. Evaluation of Boost.Math's Non-Central T distribution test data</b></p>
- <div class="table-contents"><table class="table" summary="Evaluation of Boost.Math's Non-Central T distribution test data">
- <colgroup>
- <col>
- <col>
- <col>
- </colgroup>
- <thead><tr>
- <th>
- <p>
- Library
- </p>
- </th>
- <th>
- <p>
- Relative Time
- </p>
- </th>
- <th>
- <p>
- Relative Number of Memory Allocations
- </p>
- </th>
- </tr></thead>
- <tbody>
- <tr>
- <td>
- <p>
- number
- </p>
- </td>
- <td>
- <p>
- 1.0 (263s)
- </p>
- </td>
- <td>
- <p>
- 1.0 (127710873)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- number<mpfr_float_backend<50>, et_off><br> (but with
- rvalue reference support)
- </p>
- </td>
- <td>
- <p>
- 1.0 (260s)
- </p>
- </td>
- <td>
- <p>
- 1.2 (156797871)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://math.berkeley.edu/~wilken/code/gmpfrxx/" target="_top">mpfr_class</a>
- </p>
- </td>
- <td>
- <p>
- 1.1 (287s)
- </p>
- </td>
- <td>
- <p>
- 2.1 (268336640)
- </p>
- </td>
- </tr>
- <tr>
- <td>
- <p>
- <a href="http://www.holoborodko.com/pavel/mpfr/" target="_top">mpreal</a>
- </p>
- </td>
- <td>
- <p>
- 1.5 (389s)
- </p>
- </td>
- <td>
- <p>
- 3.6 (466960653)
- </p>
- </td>
- </tr>
- </tbody>
- </table></div>
- </div>
- <br class="table-break"><p>
- The above results were generated on Win32 compiling with Visual C++ 2010, all
- optimizations on (/Ox), with MPFR 3.0 and MPIR 2.3.0.
- </p>
- <div class="footnotes">
- <br><hr style="width:100; text-align:left;margin-left: 0">
- <div id="ftn.boost_multiprecision.intro.f0" class="footnote"><p><a href="#boost_multiprecision.intro.f0" class="para"><sup class="para">[1] </sup></a>
- The actual number generated will depend on the compiler, how well it optimizes
- the code, and whether it supports rvalue references. The number of 11 temporaries
- was generated with Visual C++ 2010.
- </p></div>
- </div>
- </div>
- <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
- <td align="left"></td>
- <td align="right"><div class="copyright-footer">Copyright © 2002-2019 John Maddock
- and Christopher Kormanyos<p>
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- 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>)
- </p>
- </div></td>
- </tr></table>
- <hr>
- <div class="spirit-nav">
- <a accesskey="p" href="../index.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="tut.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
- </div>
- </body>
- </html>
|