2 Copyright 2011, 2013 John Maddock.
3 Copyright 2013 - 2019 Paul A. Bristow.
4 Copyright 2013 Christopher Kormanyos.
6 Distributed under the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE_1_0.txt or copy at
8 http://www.boost.org/LICENSE_1_0.txt).
11 [library Boost.Multiprecision
13 [copyright 2002-2019 John Maddock and Christopher Kormanyos]
14 [purpose Multiprecision Number library]
16 Distributed under the Boost Software License, Version 1.0.
17 (See accompanying file LICENSE_1_0.txt or copy at
18 [@http://www.boost.org/LICENSE_1_0.txt])
20 [authors [Maddock, John], [Kormanyos, Christopher]]
21 [/last-revision $Date: 2011-07-08 18:51:46 +0100 (Fri, 08 Jul 2011) $]
24 [import html4_symbols.qbk] [/Ideally this should be the same as Boost.Math I:\boost\libs\math\doc]
26 [import ../example/gmp_snips.cpp]
27 [import ../example/mpfr_snips.cpp]
28 [import ../example/mpfi_snips.cpp]
29 [import ../example/float128_snips.cpp]
30 [import ../example/cpp_dec_float_snips.cpp]
31 [import ../example/cpp_bin_float_snips.cpp]
32 [import ../example/cpp_int_import_export.cpp]
33 [import ../example/cpp_bin_float_import_export.cpp]
34 [import ../example/tommath_snips.cpp]
35 [import ../example/cpp_int_snips.cpp]
36 [import ../example/random_snips.cpp]
37 [import ../example/safe_prime.cpp]
38 [import ../example/mixed_integer_arithmetic.cpp]
39 [import ../example/logged_adaptor.cpp]
40 [import ../example/numeric_limits_snips.cpp]
41 [import ../example/hashing_examples.cpp]
42 [import ../example/cpp_complex_examples.cpp]
43 [import ../example/mpc_examples.cpp]
44 [import ../example/complex128_examples.cpp]
45 [import ../example/eigen_example.cpp]
46 [import ../example/mpfr_precision.cpp]
47 [import ../example/constexpr_float_arithmetic_examples.cpp]
48 [import ../test/constexpr_test_cpp_int_5.cpp]
50 [/External links as templates (see also some defs below)]
51 [template mpfr[] [@http://www.mpfr.org MPFR]]
52 [template mpc[] [@http://www.multiprecision.org MPC]]
53 [template mpfi[] [@http://perso.ens-lyon.fr/nathalie.revol/software.html MPFI]]
54 [template gmp[] [@http://gmplib.org GMP]]
55 [template mpf_class[] [@http://gmplib.org/manual/C_002b_002b-Interface-Floats.html#C_002b_002b-Interface-Floats mpf_class]]
56 [template mpfr_class[] [@http://math.berkeley.edu/~wilken/code/gmpfrxx/ mpfr_class]]
57 [template mpreal[] [@http://www.holoborodko.com/pavel/mpfr/ mpreal]]
58 [template mpir[] [@http://mpir.org/ MPIR]]
59 [template tommath[] [@http://libtom.net libtommath]]
60 [template quadmath[] [@http://gcc.gnu.org/onlinedocs/libquadmath/ libquadmath]]
62 [template super[x]'''<superscript>'''[x]'''</superscript>''']
63 [template sub[x]'''<subscript>'''[x]'''</subscript>''']
66 [/insert Equation as a PNG or SVG image, previous generated with an external tool like Latex.]
67 [/Used thus [equation ellint6] - without the file type suffix which will chosen automatically.]
69 [template equation[name] '''<inlinemediaobject>
70 <imageobject role="html">
71 <imagedata fileref="../'''[name]'''.png"></imagedata>
73 <imageobject role="print">
74 <imagedata fileref="../'''[name]'''.svg"></imagedata>
76 </inlinemediaobject>''']
78 [/insert Indented one-line expression italic and serif font probably using Unicode symbols for Greek and symbols.]
79 [/Example: [expression [sub 1]F[sub 0](a, z) = (1-z)[super -a]]]
80 [template expression[equation]
82 [role serif_italic [equation]]
84 [/ Hint you may need to enclose equation in brackets if it contains comma(s) to avoid "error invalid number of arguments"]
87 [def __tick [role aligncenter [role green \u2714]]] [/ u2714 is a HEAVY CHECK MARK tick (2713 check mark), green]
88 [def __cross [role aligncenter [role red \u2718]]] [/ u2718 is a heavy cross, red]
89 [def __star [role aligncenter [role red \u2736]]] [/ 6-point star red ]
91 [/Boost.Multiprecision internals links]
92 [def __cpp_int [link boost_multiprecision.tut.ints.cpp_int cpp_int]]
93 [def __gmp_int [link boost_multiprecision.tut.ints.gmp_int gmp_int]]
94 [def __tom_int [link boost_multiprecision.tut.ints.tom_int tom_int]]
95 [def __gmp_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]]
96 [def __mpf_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]]
97 [def __mpfr_float_backend [link boost_multiprecision.tut.floats.mpfr_float mpfr_float]]
98 [def __cpp_bin_float [link boost_multiprecision.tut.floats.cpp_bin_float cpp_bin_float]]
99 [def __cpp_dec_float [link boost_multiprecision.tut.floats.cpp_dec_float cpp_dec_float]]
100 [def __gmp_rational [link boost_multiprecision.tut.rational.gmp_rational gmp_rational]]
101 [def __cpp_rational [link boost_multiprecision.tut.rational.cpp_rational cpp_rational]]
102 [def __tommath_rational [link boost_multiprecision.tut.rational.tommath_rational tommath_rational]]
103 [def __number [link boost_multiprecision.ref.number number]]
104 [def __float128 [link boost_multiprecision.tut.floats.float128 float128]]
105 [def __cpp_complex [link boost_multiprecision.tut.complex.cpp_complex cpp_complex]]
106 [def __mpc_complex [link boost_multiprecision.tut.complex.mpc_complex mpc_complex]]
107 [def __debug_adaptor [link boost_multiprecision.tut.misc.debug_adaptor debug_adaptor]]
108 [def __logged_adaptor [link boost_multiprecision.tut.misc.logged_adaptor logged_adaptor]]
109 [def __rational_adaptor [link boost_multiprecision.tut.rational.rational_adaptor rational_adaptor]]
110 [def __cpp_complex [link boost_multiprecision.tut.complex.cpp_complex cpp_complex]]
111 [def __mpc_complex [link boost_multiprecision.tut.complex.mpc_complex mpc_complex]]
112 [def __complex128 [link boost_multiprecision.tut.complex.complex128 complex128]]
113 [def __complex_adaptor [link boost_multiprecision.tut.complex.complex_adaptor complex_adaptor]]
115 [/External links as macro definitions.]
116 [def __expression_template [@https://en.wikipedia.org/wiki/Expression_templates expression template]]
117 [def __expression_templates [@https://en.wikipedia.org/wiki/Expression_templates expression templates]] [/plural version]
118 [def __UDT [@http://eel.is/c++draft/definitions#defns.prog.def.type program-defined type]]
119 [def __fundamental_type [@https://en.cppreference.com/w/cpp/language/types fundamental (built-in) type]]
121 [section:intro Introduction]
123 The Multiprecision Library provides [link boost_multiprecision.tut.ints integer],
124 [link boost_multiprecision.tut.rational rational],
125 [link boost_multiprecision.tut.floats floating-point],
126 and [link boost_multiprecision.tut.complex complex] types in C++ that have more
127 range and precision than C++'s ordinary built-in types.
128 The big number types in Multiprecision can be used with a wide
129 selection of basic mathematical operations, elementary transcendental
130 functions as well as the functions in Boost.Math.
131 The Multiprecision types can also interoperate with any
132 __fundamental_type in C++ using clearly defined conversion rules.
133 This allows Boost.Multiprecision to be used for all
134 kinds of mathematical calculations involving integer,
135 rational and floating-point types requiring extended
138 Multiprecision consists of a generic interface to the
139 mathematics of large numbers as well as a selection of
140 big number back-ends, with support for integer, rational,
141 floating-point, and complex types. Boost.Multiprecision provides a selection
142 of back-ends provided off-the-rack in including
143 interfaces to GMP, MPFR, MPIR, MPC, TomMath as well as
144 its own collection of Boost-licensed, header-only back-ends for
145 integers, rationals and floats. In addition, user-defined back-ends
146 can be created and used with the interface of Multiprecision,
147 provided the class implementation adheres to the necessary
148 [link boost_multiprecision.ref.backendconc concepts].
150 Depending upon the number type, precision may be arbitrarily large
151 (limited only by available memory), fixed at compile time
152 (for example, 50 or 100 decimal digits), or a variable controlled at run-time
153 by member functions. The types are __expression_templates - enabled for
154 better performance than naive user-defined types.
156 The Multiprecision library comes in two distinct parts:
158 * An expression-template-enabled front-end `number`
159 that handles all the operator overloading, expression evaluation optimization, and code reduction.
160 * A selection of back-ends that implement the actual arithmetic operations, and need conform only to the
161 reduced interface requirements of the front-end.
163 Separation of front-end and back-end allows use of highly refined, but restricted license libraries
164 where possible, but provides Boost license alternatives for users who must have a portable
165 unconstrained license.
166 Which is to say some back-ends rely on 3rd party libraries,
167 but a header-only Boost license version is always available (if somewhat slower).
169 [h5:getting_started Getting started with Boost.Multiprecision]
171 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,
172 close to 'drop-in' replacements for the __fundamental_type analogs,
173 then use a fully Boost-licensed number type, and skip to one of more of :
175 * __cpp_int for multiprecision integers,
176 * __cpp_rational for rational types,
177 * __cpp_bin_float and __cpp_dec_float for multiprecision floating-point types,
178 * __cpp_complex for complex types.
180 The library is very often used via one of the predefined convenience `typedef`s
181 like `boost::multiprecision::int128_t` or `boost::multiprecision::cpp_bin_float_quad`.
183 For example, if you want a signed, 128-bit fixed size integer:
185 #include <boost/multiprecision/cpp_int.hpp> // Integer types.
187 boost::multiprecision::int128_t my_128_bit_int;
189 Alternatively, and more adventurously, if you wanted an
190 [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision]
191 integer type using [gmp] as the underlying implementation then you could use:
193 #include <boost/multiprecision/gmp.hpp> // Defines the wrappers around the GMP library's types
195 boost::multiprecision::mpz_int myint; // Arbitrary precision integer type.
197 Or for a simple, portable 128-bit floating-point close to a drop-in for a __fundamental_type like `double`, usually 64-bit
199 #include <boost/multiprecision/cpp_bin_float.hpp>
201 boost::multiprecision::cpp_bin_float_quad my_quad_real;
203 Alternatively, you can compose your own 'custom' multiprecision type, by combining `number` with one of the
204 predefined back-end types. For example, suppose you wanted a 300 decimal digit floating-point type
205 based on the [mpfr] library. In this case, there's no predefined `typedef` with that level of precision,
206 so instead we compose our own:
208 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR.
210 namespace mp = boost::multiprecision; // Reduce the typing a bit later...
212 typedef mp::number<mp::mpfr_float_backend<300> > my_float;
214 my_float a, b, c; // These variables have 300 decimal digits precision.
216 We can repeat the above example, but with the expression templates disabled (for faster compile times, but slower runtimes)
217 by passing a second template argument to `number`:
219 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR.
221 namespace mp = boost::multiprecision; // Reduce the typing a bit later...
223 typedef mp::number<mp::mpfr_float_backend<300>, et_off> my_float;
225 my_float a, b, c; // These variables have 300 decimal digits precision
227 We can also mix arithmetic operations between different types, provided there is an unambiguous implicit conversion from one
230 #include <boost/multiprecision/cpp_int.hpp>
232 namespace mp = boost::multiprecision; // Reduce the typing a bit later...
234 mp::int128_t a(3), b(4);
235 mp::int512_t c(50), d;
237 d = c * a; // OK, result of mixed arithmetic is an int512_t
239 Conversions are also allowed:
241 d = a; // OK, widening conversion.
242 d = a * b; // OK, can convert from an expression template too.
244 However conversions that are inherently lossy are either declared explicit or else forbidden altogether:
246 d = 3.14; // Error implicit conversion from double not allowed.
247 d = static_cast<mp::int512_t>(3.14); // OK explicit construction is allowed
249 Mixed arithmetic will fail if the conversion is either ambiguous or explicit:
251 number<cpp_int_backend<>, et_off> a(2);
252 number<cpp_int_backend<>, et_on> b(3);
254 b = a * b; // Error, implicit conversion could go either way.
255 b = a * 3.14; // Error, no operator overload if the conversion would be explicit.
259 On compilers that support rvalue-references, class `number` is move-enabled if the underlying backend is.
261 In addition the non-expression template operator overloads (see below) are move aware and have overloads
262 that look something like:
265 number<B, et_off> operator + (number<B, et_off>&& a, const number<B, et_off>& b)
267 return std::move(a += b);
270 These operator overloads ensure that many expressions can be evaluated without actually generating any temporaries.
271 However, there are still many simple expressions such as
275 which don't noticeably benefit from move support. Therefore, optimal performance comes from having both
276 move-support, and expression templates enabled.
278 Note that while "moved-from" objects are left in a sane state, they have an unspecified value, and the only permitted
279 operations on them are destruction or the assignment of a new value. Any other operation should be considered
280 a programming error and all of our backends will trigger an assertion if any other operation is attempted. This behavior
281 allows for optimal performance on move-construction (i.e. no allocation required, we just take ownership of the existing
282 object's internal state), while maintaining usability in the standard library containers.
284 [h4:expression_templates Expression Templates]
286 Class `number` is expression-template-enabled: that means that rather than having a multiplication
287 operator that looks like this:
289 template <class Backend>
290 number<Backend> operator * (const number<Backend>& a, const number<Backend>& b)
292 number<Backend> result(a);
297 Instead the operator looks more like this:
299 template <class Backend>
300 ``['unmentionable-type]`` operator * (const number<Backend>& a, const number<Backend>& b);
302 Where the '['unmentionable]' return type is an implementation detail that, rather than containing the result
303 of the multiplication, contains instructions on how to compute the result. In effect it's just a pair
304 of references to the arguments of the function, plus some compile-time information that stores what the operation
307 The great advantage of this method is the ['elimination of temporaries]: for example, the "naive" implementation
308 of `operator*` above, requires one temporary for computing the result, and at least another one to return it. It's true
309 that sometimes this overhead can be reduced by using move-semantics, but it can't be eliminated completely. For example,
310 lets suppose we're evaluating a polynomial via Horner's method, something like this:
312 T a[7] = { /* some values */ };
314 y = (((((a[6] * x + a[5]) * x + a[4]) * x + a[3]) * x + a[2]) * x + a[1]) * x + a[0];
316 If type `T` is a `number`, then this expression is evaluated ['without creating a single temporary value]. In contrast,
317 if we were using the [mpfr_class] C++ wrapper for [mpfr] - then this expression would result in no less than 11
318 temporaries (this is true even though [mpfr_class] does use expression templates to reduce the number of temporaries somewhat). Had
319 we used an even simpler wrapper around [mpfr] like [mpreal] things would have been even worse and no less that 24 temporaries
320 are created for this simple expression (note - we actually measure the number of memory allocations performed rather than
321 the number of temporaries directly, note also that the [mpf_class] wrapper that will be supplied with GMP-5.1 reduces the number of
322 temporaries to pretty much zero). Note that if we compile with expression templates disabled and rvalue-reference support
323 on, then actually still have no wasted memory allocations as even though temporaries are created, their contents are moved
325 [footnote The actual number generated will depend on the compiler, how well it optimizes the code, and whether it supports
326 rvalue references. The number of 11 temporaries was generated with Visual C++ 2010.]
329 Expression templates can radically reorder the operations in an expression, for example:
333 Will get transformed into:
338 If this is likely to be an issue for a particular application, then they should be disabled.
341 This library also extends expression template support to standard library functions like `abs` or `sin` with `number`
342 arguments. This means that an expression such as:
346 can be evaluated without a single temporary being calculated. Even expressions like:
350 get this treatment, so that variable 'y' is used as "working storage" within the implementation of `sin`,
351 thus reducing the number of temporaries used by one. Of course, should you write:
355 Then we clearly can't use `x` as working storage during the calculation, so then a temporary variable
356 is created in this case.
358 Given the comments above, you might be forgiven for thinking that expression-templates are some kind of universal-panacea:
359 sadly though, all tricks like this have their downsides. For one thing, expression template libraries
360 like this one, tend to be slower to compile than their simpler cousins, they're also harder to debug
361 (should you actually want to step through our code!), and rely on compiler optimizations being turned
362 on to give really good performance. Also, since the return type from expressions involving `number`s
363 is an "unmentionable implementation detail", you have to be careful to cast the result of an expression
364 to the actual number type when passing an expression to a template function. For example, given:
367 void my_proc(const T&);
373 Will very likely result in obscure error messages inside the body of `my_proc` - since we've passed it
374 an expression template type, and not a number type. Instead we probably need:
376 my_proc(my_number_type(a+b));
378 Having said that, these situations don't occur that often - or indeed not at all for non-template functions.
379 In addition, all the functions in the Boost.Math library will automatically convert expression-template arguments
380 to the underlying number type without you having to do anything, so:
382 mpfr_float_100 a(20), delta(0.125);
383 boost::math::gamma_p(a, a + delta);
385 Will work just fine, with the `a + delta` expression template argument getting converted to an `mpfr_float_100`
386 internally by the Boost.Math library.
388 [caution In C++11 you should never store an expression template using:
390 `auto my_expression = a + b - c;`
392 unless you're absolutely sure that the lifetimes of `a`, `b` and `c` will outlive that of `my_expression`.
394 In fact, it is particularly easy to create dangling references by mixing expression templates with the `auto`
395 keyword, for example:
397 `auto val = cpp_dec_float_50("23.1") * 100;`
399 In this situation, the integer literal is stored directly in the expression template - so its use is OK here -
400 but the `cpp_dec_float_50` temporary is stored by reference and then destructed when the statement completes,
401 leaving a dangling reference.
403 [*['If in doubt, do not ever mix expression templates with the `auto` keyword.]]
406 And finally... the performance improvements from an expression template library like this are often not as
407 dramatic as the reduction in number of temporaries would suggest. For example, if we compare this library with
408 [mpfr_class] and [mpreal], with all three using the underlying [mpfr] library at 50 decimal digits precision then
409 we see the following typical results for polynomial execution:
411 [table Evaluation of Order 6 Polynomial.
412 [[Library] [Relative Time] [Relative number of memory allocations]]
413 [[number] [1.0 (0.00957s)] [1.0 (2996 total)]]
414 [[[mpfr_class]] [1.1 (0.0102s)] [4.3 (12976 total)]]
415 [[[mpreal]] [1.6 (0.0151s)] [9.3 (27947 total)]]
418 As you can see, the execution time increases a lot more slowly than the number of memory allocations. There are
419 a number of reasons for this:
421 * The cost of extended-precision multiplication and division is so great, that the times taken for these tend to
422 swamp everything else.
423 * The cost of an in-place multiplication (using `operator*=`) tends to be more than an out-of-place
424 `operator*` (typically `operator *=` has to create a temporary workspace to carry out the multiplication, where
425 as `operator*` can use the target variable as workspace). Since the expression templates carry out their
426 magic by converting out-of-place operators to in-place ones, we necessarily take this hit. Even so the
427 transformation is more efficient than creating the extra temporary variable, just not by as much as
430 Finally, note that `number` takes a second template argument, which, when set to `et_off` disables all
431 the expression template machinery. The result is much faster to compile, but slower at runtime.
433 We'll conclude this section by providing some more performance comparisons between these three libraries,
434 again, all are using [mpfr] to carry out the underlying arithmetic, and all are operating at the same precision
437 [table Evaluation of Boost.Math's Bessel function test data
438 [[Library] [Relative Time] [Relative Number of Memory Allocations]]
439 [[mpfr_float_50] [1.0 (5.78s)] [1.0 (1611963)]]
440 [[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)]
441 [1.1 (6.29s)] [2.64 (4260868)]]
442 [[[mpfr_class]] [1.1 (6.28s)] [2.45 (3948316)]]
443 [[[mpreal]] [1.65 (9.54s)] [8.21 (13226029)]]
446 [table Evaluation of Boost.Math's Non-Central T distribution test data
447 [[Library][Relative Time][Relative Number of Memory Allocations]]
448 [[number] [1.0 (263s)][1.0 (127710873)]]
449 [[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)]
450 [1.0 (260s)][1.2 (156797871)]]
451 [[[mpfr_class]] [1.1 (287s)][2.1 (268336640)]]
452 [[[mpreal]] [1.5 (389s)][3.6 (466960653)]]
455 The above results were generated on Win32 compiling with Visual C++ 2010, all optimizations on (/Ox),
456 with MPFR 3.0 and MPIR 2.3.0.
458 [endsect] [/section:intro Introduction]
460 [section:tut Tutorial]
462 In order to use this library you need to make two choices:
464 * What kind of number do I want ([link boost_multiprecision.tut.ints integer],
465 [link boost_multiprecision.tut.floats floating-point], [link boost_multiprecision.tut.rational rational], or [link boost_multiprecision.tut.complex complex]).
466 * Which back-end do I want to perform the actual arithmetic (Boost-supplied, GMP, MPFR, MPC, Tommath etc)?
468 [section:ints Integer Types]
470 The following back-ends provide integer arithmetic:
473 [[Backend Type][Header][Radix][Dependencies][Pros][Cons]]
474 [[`cpp_int`][boost/multiprecision/cpp_int.hpp][2][None]
475 [Very versatile, Boost licensed, all C++ integer type which support both [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] and fixed precision integer types.][Slower than [gmp], though typically not as slow as [tommath]]]
476 [[`gmp_int`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]]
477 [[`tom_int`][boost/multiprecision/tommath.hpp][2][[tommath]][Public domain back-end with no licence restrictions.][Slower than [gmp].]]
480 [section:cpp_int cpp_int]
482 `#include <boost/multiprecision/cpp_int.hpp>`
484 namespace boost{ namespace multiprecision{
486 typedef unspecified-type limb_type;
488 enum cpp_integer_type { signed_magnitude, unsigned_magnitude };
489 enum cpp_int_check_type { checked, unchecked };
491 template <unsigned MinBits = 0,
492 unsigned MaxBits = 0,
493 cpp_integer_type SignType = signed_magnitude,
494 cpp_int_check_type Checked = unchecked,
495 class Allocator = std::allocator<limb_type> >
496 class cpp_int_backend;
498 // Expression templates default to et_off if there is no allocator:
500 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked>
501 struct expression_template_default<cpp_int_backend<MinBits, MaxBits, SignType, Checked, void> >
502 { static const expression_template_option value = et_off; };
504 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer
505 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend;
506 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number
508 // Fixed precision unsigned types:
509 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t;
510 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t;
511 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t;
512 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t;
514 // Fixed precision signed types:
515 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t;
516 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t;
517 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t;
518 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t;
520 // Over again, but with checking enabled this time:
521 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int;
522 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend;
523 typedef number<cpp_rational_backend> checked_cpp_rational;
525 // Checked fixed precision unsigned types:
526 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t;
527 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t;
528 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t;
529 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t;
531 // Fixed precision signed types:
532 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t;
533 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t;
534 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t;
535 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t;
539 The `cpp_int_backend` type is normally used via one of the convenience typedefs given above.
541 This back-end is the "Swiss Army Knife" of integer types as it can represent both fixed and
542 [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision]
543 integer types, and both signed and unsigned types. There are five template arguments:
546 [[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory
547 allocation. When zero, this field is determined automatically based on how many bits can be stored
548 in union with the dynamic storage header: setting a larger value may improve performance as larger integer
549 values will be stored internally before memory allocation is required.]]
550 [[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type.
551 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic
552 memory allocation will ever be performed: in this situation the Allocator parameter should be set to
553 type `void`. Note that this parameter should not be used simply to prevent large memory
554 allocations, not only is that role better performed by the allocator, but fixed precision
555 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]]
556 [[SignType][Determines whether the resulting type is signed or not. Note that for
557 [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types
558 this parameter must be `signed_magnitude`. For fixed precision
559 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]]
560 [[Checked][This parameter has two values: `checked` or `unchecked`. See below.]]
561 [[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]]
564 When the template parameter Checked is set to `checked` then the result is a ['checked-integer], checked
565 and unchecked integers have the following properties:
568 [[Condition][Checked-Integer][Unchecked-Integer]]
569 [[Numeric overflow in fixed precision arithmetic][Throws a `std::overflow_error`.][Performs arithmetic modulo 2[super MaxBits]]]
570 [[Constructing an integer from a value that can not be represented in the target type][Throws a `std::range_error`.]
571 [Converts the value modulo 2[super MaxBits], signed to unsigned conversions extract the last MaxBits bits of the
572 2's complement representation of the input value.]]
573 [[Unsigned subtraction yielding a negative value.][Throws a `std::range_error`.][Yields the value that would
574 result from treating the unsigned type as a 2's complement signed type.]]
575 [[Attempting a bitwise operation on a negative value.][Throws a `std::range_error`][Yields the value, but not the bit pattern,
576 that would result from performing the operation on a 2's complement integer type.]]
579 Things you should know when using this type:
581 * Default constructed `cpp_int_backend`s have the value zero.
582 * Division by zero results in a `std::overflow_error` being thrown.
583 * Construction from a string that contains invalid non-numeric characters results in a `std::runtime_error` being thrown.
584 * Since the precision of `cpp_int_backend` is necessarily limited when the allocator parameter is void,
585 care should be taken to avoid numeric overflow when using this type
586 unless you actually want modulo-arithmetic behavior.
587 * The type uses a sign-magnitude representation internally, so type `int128_t` has 128-bits of precision plus an extra sign bit.
588 In this respect the behaviour of these types differs from built-in 2's complement types. In might be tempting to use a
589 127-bit type instead, and indeed this does work, but behaviour is still slightly different from a 2's complement built-in type
590 as the min and max values are identical (apart from the sign), where as they differ by one for a true 2's complement type.
591 That said it should be noted that there's no requirement for built-in types to be 2's complement either - it's simply that this
592 is the most common format by far.
593 * Attempting to print negative values as either an Octal or Hexadecimal string results in a `std::runtime_error` being thrown,
594 this is a direct consequence of the sign-magnitude representation.
595 * The fixed precision types `[checked_][u]intXXX_t` have expression template support turned off - it seems to make little
596 difference to the performance of these types either way - so we may as well have the faster compile times by turning
598 * Unsigned types support subtraction - the result is "as if" a 2's complement operation had been performed as long as they are not
599 ['checked-integers] (see above).
600 In other words they behave pretty much as a built in integer type would in this situation. So for example if we were using
601 `uint128_t` then `uint128_t(1)-4` would result in the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD`
602 of type `uint128_t`. However, had this operation been performed on `checked_uint128_t` then a `std::range_error` would have
604 * Unary negation of unsigned types results in a compiler error (static assertion).
605 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
606 * When used at fixed precision, the size of this type is always one machine word (plus any compiler-applied alignment padding)
607 larger than you would expect for an N-bit integer:
608 the extra word stores both the sign, and how many machine words in the integer are actually in use.
609 The latter is an optimisation for larger fixed precision integers, so that a 1024-bit integer has almost the same performance
610 characteristics as a 128-bit integer, rather than being 4 times slower for addition and 16 times slower for multiplication
611 (assuming the values involved would always fit in 128 bits).
612 Typically this means you can use
613 an integer type wide enough for the "worst case scenario" with only minor performance degradation even if most of the time
614 the arithmetic could in fact be done with a narrower type.
615 Also note that unsigned fixed precision types small enough to fit inside the largest native integer become a simple wrapper around that type,
616 this includes the "checked" variants. Small signed types will always have an extra sign word and so be larger than their native equivalent.
617 * When used at fixed precision and MaxBits is smaller than the number of bits in the largest native integer type, then
618 internally `cpp_int_backend` switches to a "trivial" implementation where it is just a thin wrapper around a single
619 integer. Note that it will still be slightly slower than a bare native integer, as it emulates a
620 signed-magnitude representation rather than simply using the platforms native sign representation: this ensures
621 there is no step change in behavior as a cpp_int grows in size.
622 * Fixed precision `cpp_int`'s have some support for `constexpr` values and user-defined literals, see
623 [link boost_multiprecision.tut.lits here] for the full description. For example `0xfffff_cppi1024`
624 specifies a 1024-bit integer with the value 0xffff. This can be used to generate compile time constants that are
625 too large to fit into any built in number type.
626 * The __cpp_int types support constexpr arithmetic, provided it is a fixed precision type with no allocator. It may also
627 be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition
628 the free functions `abs`, `swap`, `multiply`, `add`, `subtract`, `divide_qr`, `integer_modulus`, `powm`, `lsb`, `msb`,
629 `bit_test`, `bit_set`, `bit_unset`, `bit_flip`, `sqrt`, `gcd`, `lcm` are all supported. Use of __cpp_int in this way
630 requires either a C++2a compiler (one which supports `std::is_constant_evaluated()`), or GCC-6 or later in C++14 mode.
631 Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations:
632 expect to hit roadblocks rather easily.
633 * You can import/export the raw bits of a __cpp_int to and from external storage via the `import_bits` and `export_bits`
634 functions. More information is in the [link boost_multiprecision.tut.import_export section on import/export].
636 [h5:cpp_int_eg Example:]
640 [endsect] [/section:cpp_int cpp_int]
642 [section:gmp_int gmp_int]
644 `#include <boost/multiprecision/gmp.hpp>`
646 namespace boost{ namespace multiprecision{
650 typedef number<gmp_int > mpz_int;
654 The `gmp_int` back-end is used via the typedef `boost::multiprecision::mpz_int`. It acts as a thin wrapper around the [gmp] `mpz_t`
655 to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision.
657 As well as the usual conversions from arithmetic and string types, type `mpz_int` is copy constructible and assignable from:
659 * The [gmp] native types: `mpf_t`, `mpz_t`, `mpq_t`.
660 * Instances of `number<T>` that are wrappers around those types: `number<gmp_float<N> >`, `number<gmp_rational>`.
662 It's also possible to access the underlying `mpz_t` via the `data()` member function of `gmp_int`.
664 Things you should know when using this type:
666 * No changes are made to the GMP library's global settings - so you can safely mix this type with
667 existing code that uses [gmp].
668 * Default constructed `gmp_int`s have the value zero (this is GMP's default behavior).
669 * Formatted IO for this type does not support octal or hexadecimal notation for negative values,
670 as a result performing formatted output on this type when the argument is negative and either of the flags
671 `std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown.
672 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
674 * Division by zero results in a `std::overflow_error` being thrown.
675 * Although this type is a wrapper around [gmp] it will work equally well with [mpir]. Indeed use of [mpir]
676 is recommended on Win32.
677 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
683 [endsect] [/section:gmp_int gmp_int]
685 [section:tom_int tom_int]
687 `#include <boost/multiprecision/tommath.hpp>`
689 namespace boost{ namespace multiprecision{
693 typedef number<tommath_int > tom_int;
697 The `tommath_int` back-end is used via the typedef `boost::multiprecision::tom_int`. It acts as a thin wrapper around the [tommath] `tom_int`
698 to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision.
700 Things you should know when using this type:
702 * Default constructed objects have the value zero (this is [tommath]'s default behavior).
703 * Although `tom_int` is mostly a drop in replacement for the builtin integer types, it should be noted that it is a
704 rather strange beast as it's a signed type that is not a 2's complement type. As a result the bitwise operations
705 `| & ^` will throw a `std::runtime_error` exception if either of the arguments is negative. Similarly the complement
706 operator`~` is deliberately not implemented for this type.
707 * Formatted IO for this type does not support octal or hexadecimal notation for negative values,
708 as a result performing formatted output on this type when the argument is negative and either of the flags
709 `std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown.
710 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
712 * Division by zero results in a `std::overflow_error` being thrown.
718 [endsect] [/section:tom_int tom_int]
720 [section:egs Examples]
722 [import ../example/integer_examples.cpp]
724 [section:factorials Factorials]
726 [endsect] [/section:factorials Factorials]
729 [section:bitops Bit Operations]
731 [endsect] [/section:bitops Bit Operations]
738 [section:floats floating-point Numbers]
740 The following back-ends provide floating-point arithmetic:
743 [[Backend Type][Header][Radix][Dependencies][Pros][Cons]]
744 [[`cpp_bin_float<N>`][boost/multiprecision/cpp_bin_float.hpp][2][None][Header only, all C++ implementation. Boost licence.][Approximately 2x slower than the [mpfr] or [gmp] libraries.]]
745 [[`cpp_dec_float<N>`][boost/multiprecision/cpp_dec_float.hpp][10][None][Header only, all C++ implementation. Boost licence.][Approximately 2x slower than the [mpfr] or [gmp] libraries.]]
746 [[`mpf_float<N>`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]]
747 [[`mpfr_float<N>`][boost/multiprecision/mpfr.hpp][2][[gmp] and [mpfr]][Very fast and efficient back-end, with its own standard library implementation.][Dependency on GNU licensed [gmp] and [mpfr] libraries.]]
748 [[`float128`][boost/multiprecision/float128.hpp][2][Either [quadmath] or the Intel C++ Math library.][Very fast and efficient back-end for 128-bit floating-point values (113-bit mantissa, equivalent to FORTRAN's QUAD real)][Depends on the compiler being either recent GCC or Intel C++ versions.]]
751 [section:cpp_bin_float cpp_bin_float]
753 `#include <boost/multiprecision/cpp_bin_float.hpp>`
755 namespace boost{ namespace multiprecision{
763 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0>
766 typedef number<cpp_bin_float<50> > cpp_bin_float_50;
767 typedef number<cpp_bin_float<100> > cpp_bin_float_100;
769 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single;
770 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double;
771 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended;
772 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad;
773 typedef number<backends::cpp_bin_float<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143>, et_off> cpp_bin_float_oct;
777 The `cpp_bin_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free)
778 floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with
779 much greater precision.
781 Type `cpp_bin_float` can be used at fixed precision by specifying a non-zero `Digits` template parameter.
782 The typedefs `cpp_bin_float_50` and `cpp_bin_float_100` provide arithmetic types at 50 and 100 decimal digits precision
785 Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example
786 to declare a `cpp_bin_float` with exactly the same precision as `double` one would use
787 `number<cpp_bin_float<53, digit_base_2> >`. The typedefs `cpp_bin_float_single`, `cpp_bin_float_double`,
788 `cpp_bin_float_quad`, `cpp_bin_float_oct` and `cpp_bin_float_double_extended` provide
789 software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively.
790 Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size
791 or bit-layout as true IEEE compatible types.
793 Normally `cpp_bin_float` allocates no memory: all of the space required for its digits are allocated
794 directly within the class. As a result care should be taken not to use the class with too high a digit count
795 as stack space requirements can grow out of control. If that represents a problem then providing an allocator
796 as a template parameter causes `cpp_bin_float` to dynamically allocate the memory it needs: this
797 significantly reduces the size of `cpp_bin_float` and increases the viable upper limit on the number of digits
798 at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive
799 as the digit count grows: the current implementation really isn't optimized or designed for large digit counts.
800 Note that since the actual type of the objects allocated
801 is completely opaque, the suggestion would be to use an allocator with `void` `value_type`, for example:
802 `number<cpp_bin_float<1000, digit_base_10, std::allocator<void> > >`.
804 The final template parameters determine the type and range of the exponent: parameter `Exponent` can be
805 any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits
806 of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will
807 get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then
808 the library will choose suitable values that are as large as possible given the constraints of the type
809 and need for extra headroom for internal calculations.
811 There is full standard library and `numeric_limits` support available for this type.
813 Things you should know when using this type:
815 * Default constructed `cpp_bin_float`s have a value of zero.
816 * The radix of this type is 2, even when the precision is specified as decimal digits.
817 * The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow,
818 and a NaN is generated for any mathematically undefined operation.
819 * There is a `std::numeric_limits` specialisation for this type.
820 * Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type -
821 for example you can convert from `number<cpp_bin_float<50> >` to `number<cpp_bin_float<SomeOtherValue> >`.
822 Narrowing conversions round to nearest and are `explicit`.
823 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
824 as a valid floating-point number.
825 * All arithmetic operations are correctly rounded to nearest. String conversions and the `sqrt` function
826 are also correctly rounded, but transcendental functions (sin, cos, pow, exp etc) are not.
828 [h5 cpp_bin_float example:]
834 [section:cpp_dec_float cpp_dec_float]
836 `#include <boost/multiprecision/cpp_dec_float.hpp>`
838 namespace boost{ namespace multiprecision{
840 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void>
843 typedef number<cpp_dec_float<50> > cpp_dec_float_50;
844 typedef number<cpp_dec_float<100> > cpp_dec_float_100;
848 The `cpp_dec_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free)
849 floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with
850 much greater precision.
852 Type `cpp_dec_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter.
853 The typedefs `cpp_dec_float_50` and `cpp_dec_float_100` provide arithmetic types at 50 and 100 decimal digits precision
854 respectively. Optionally, you can specify an integer type to use for the exponent, this defaults to a 32-bit integer type
855 which is more than large enough for the vast majority of use cases, but larger types such as `long long` can also be specified
856 if you need a truly huge exponent range. In any case the ExponentType must be a built in signed integer type at least 2 bytes
859 Normally `cpp_dec_float` allocates no memory: all of the space required for its digits are allocated
860 directly within the class. As a result care should be taken not to use the class with too high a digit count
861 as stack space requirements can grow out of control. If that represents a problem then providing an allocator
862 as the final template parameter causes `cpp_dec_float` to dynamically allocate the memory it needs: this
863 significantly reduces the size of `cpp_dec_float` and increases the viable upper limit on the number of digits
864 at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive
865 as the digit count grows: the current implementation really isn't optimized or designed for large digit counts.
867 There is full standard library and `numeric_limits` support available for this type.
869 Things you should know when using this type:
871 * Default constructed `cpp_dec_float`s have a value of zero.
872 * The radix of this type is 10. As a result it can behave subtly differently from base-2 types.
873 * The type has a number of internal guard digits over and above those specified in the template argument.
874 Normally these should not be visible to the user.
875 * The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow,
876 and a NaN is generated for any mathematically undefined operation.
877 * There is a `std::numeric_limits` specialisation for this type.
878 * Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type -
879 for example you can convert from `number<cpp_dec_float<50> >` to `number<cpp_dec_float<SomeOtherValue> >`.
880 Narrowing conversions are truncating and `explicit`.
881 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
882 as a valid floating-point number.
883 * The actual precision of a `cpp_dec_float` is always slightly higher than the number of digits specified in
884 the template parameter, actually how much higher is an implementation detail but is always at least 8 decimal
886 * Operations involving `cpp_dec_float` are always truncating. However, note that since their are guard digits
887 in effect, in practice this has no real impact on accuracy for most use cases.
889 [h5 cpp_dec_float example:]
895 [section:gmp_float gmp_float]
897 `#include <boost/multiprecision/gmp.hpp>`
899 namespace boost{ namespace multiprecision{
901 template <unsigned Digits10>
904 typedef number<gmp_float<50> > mpf_float_50;
905 typedef number<gmp_float<100> > mpf_float_100;
906 typedef number<gmp_float<500> > mpf_float_500;
907 typedef number<gmp_float<1000> > mpf_float_1000;
908 typedef number<gmp_float<0> > mpf_float;
912 The `gmp_float` back-end is used in conjunction with `number` : it acts as a thin wrapper around the [gmp] `mpf_t`
913 to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with
914 much greater precision.
916 Type `gmp_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or
917 at variable precision by setting the template argument to zero. The typedefs mpf_float_50, mpf_float_100,
918 mpf_float_500, mpf_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision
919 respectively. The typedef mpf_float provides a variable precision type whose precision can be controlled via the
920 `number`s member functions.
922 [note This type only provides standard library and `numeric_limits` support when the precision is fixed at compile time.]
924 As well as the usual conversions from arithmetic and string types, instances of `number<mpf_float<N> >` are
925 copy constructible and assignable from:
927 * The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`.
928 * The `number` wrappers around those types: `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`.
930 It's also possible to access the underlying `mpf_t` via the `data()` member function of `gmp_float`.
932 Things you should know when using this type:
934 * Default constructed `gmp_float`s have the value zero (this is the [gmp] library's default behavior).
935 * No changes are made to the [gmp] library's global settings, so this type can be safely mixed with
937 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
938 * It is not possible to round-trip objects of this type to and from a string and get back
939 exactly the same value. This appears to be a limitation of [gmp].
940 * Since the underlying [gmp] types have no notion of infinities or NaN's, care should be taken
941 to avoid numeric overflow or division by zero. That latter will result in a std::overflow_error being thrown,
942 while generating excessively large exponents may result in instability of the underlying [gmp]
943 library (in testing, converting a number with an excessively large or small exponent
944 to a string caused [gmp] to segfault).
945 * This type can equally be used with [mpir] as the underlying implementation - indeed that is
946 the recommended option on Win32.
947 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
948 as a valid floating-point number.
949 * Division by zero results in a `std::overflow_error` being thrown.
957 [section:mpfr_float mpfr_float]
959 `#include <boost/multiprecision/mpfr.hpp>`
961 namespace boost{ namespace multiprecision{
963 enum mpfr_allocation_type
969 template <unsigned Digits10, mpfr_allocation_type AllocateType = allocate_dynamic>
970 class mpfr_float_backend;
972 typedef number<mpfr_float_backend<50> > mpfr_float_50;
973 typedef number<mpfr_float_backend<100> > mpfr_float_100;
974 typedef number<mpfr_float_backend<500> > mpfr_float_500;
975 typedef number<mpfr_float_backend<1000> > mpfr_float_1000;
976 typedef number<mpfr_float_backend<0> > mpfr_float;
978 typedef number<mpfr_float_backend<50, allocate_stack> > static_mpfr_float_50;
979 typedef number<mpfr_float_backend<100, allocate_stack> > static_mpfr_float_100;
983 The `mpfr_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfr] `mpfr_t`
984 to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with
985 much greater precision.
987 Type `mpfr_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or
988 at variable precision by setting the template argument to zero. The typedefs mpfr_float_50, mpfr_float_100,
989 mpfr_float_500, mpfr_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision
990 respectively. The typedef mpfr_float provides a variable precision type whose precision can be controlled via the
991 `number`s member functions.
993 In addition the second template parameter lets you choose between dynamic allocation (the default,
994 and uses MPFR's normal allocation routines),
995 or stack allocation (where all the memory required for the underlying data types is stored
996 within `mpfr_float_backend`). The latter option can result in significantly faster code, at the
997 expense of growing the size of `mpfr_float_backend`. It can only be used at fixed precision, and
998 should only be used for lower digit counts. Note that we can not guarantee that using `allocate_stack`
999 won't cause any calls to mpfr's allocation routines, as mpfr may call these inside it's own code.
1000 The following table gives an idea of the performance tradeoff's at 50 decimal digits
1001 precision[footnote Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0]:
1004 [[Type][Bessel function evaluation, relative times]]
1005 [[`number<mpfr_float_backend<50, allocate_static>, et_on>`][1.0 (5.5s)]]
1006 [[`number<mpfr_float_backend<50, allocate_static>, et_off>`][1.05 (5.8s)]]
1007 [[`number<mpfr_float_backend<50, allocate_dynamic>, et_on>`][1.05 (5.8s)]]
1008 [[`number<mpfr_float_backend<50, allocate_dynamic>, et_off>`][1.16 (6.4s)]]
1011 [note This type only provides `numeric_limits` support when the precision is fixed at compile time.]
1013 As well as the usual conversions from arithmetic and string types, instances of `number<mpfr_float_backend<N> >` are
1014 copy constructible and assignable from:
1016 * The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`.
1017 * The [mpfr] native type `mpfr_t`.
1018 * The `number` wrappers around those types: `number<mpfr_float_backend<M> >`, `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`.
1020 It's also possible to access the underlying `mpfr_t` via the data() member function of `mpfr_float_backend`.
1022 Things you should know when using this type:
1024 * A default constructed `mpfr_float_backend` is set to zero (['Note that this is [*not] the default [mpfr] behavior]).
1025 * All operations use round to nearest.
1026 * No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing
1027 [mpfr] or [gmp] code.
1028 * The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32.
1029 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
1030 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1031 as a valid floating-point number.
1032 * Division by zero results in an infinity.
1033 * When using the variable precision type `mpfr_float`, then copy construction and assignment ['copies the precision
1034 of the source variable]. Likewise move construction and assignment.
1035 * When constructing the variable precision type `mpfr_float` you can specify two arguments to the constructor - the first
1036 is the value to assign to the variable, the second is an unsigned integer specifying the precision in decimal places. The
1037 `assign` member function similarly has a 2-argument overload taking the value to assign and the precision. You can use this
1038 to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a`
1039 but preserves the precision of `a`.
1041 [h5 [mpfr] example:]
1047 [section:float128 float128]
1049 `#include <boost/multiprecision/float128.hpp>`
1051 namespace boost{ namespace multiprecision{
1053 class float128_backend;
1055 typedef number<float128_backend, et_off> float128;
1059 The `float128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types
1060 and provides an real-number type that is a drop-in replacement for the native C++ floating-point types, but with
1061 a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real.
1063 All the usual standard library and `numeric_limits` support are available, performance should be equivalent
1064 to the underlying native types: for example the LINPACK benchmarks for GCC's `__float128` and
1065 `boost::multiprecision::float128` both achieved 5.6 MFLOPS[footnote On 64-bit Ubuntu 11.10, GCC-4.8.0, Intel Core 2 Duo T5800.].
1067 As well as the usual conversions from arithmetic and string types, instances of `float128` are
1068 copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types.
1070 It's also possible to access the underlying `__float128` or `_Quad` type via the `data()` member
1071 function of `float128_backend`.
1073 Things you should know when using this type:
1075 * Default constructed `float128`s have the value zero.
1076 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
1077 * This type is fully `constexpr` aware - basic constexpr arithmetic is supported from C++14 and onwards, comparisons,
1078 plus the functions `fabs`, `abs`, `fpclassify`, `isnormal`, `isfinite`, `isinf` and `isnan` are also supported if either
1079 the compiler implements C++20's `std::is_constant_evaluated()`, or if the compiler is GCC.
1080 * It is not possible to round-trip objects of this type to and from a string and get back
1081 exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of
1082 our code. Round tripping when using `__float128` as the underlying type is possible (both for GCC and Intel).
1083 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1084 as a valid floating-point number.
1085 * Division by zero results in an infinity being produced.
1086 * Type `float128` can be used as a literal type (constexpr support).
1087 * Type `float128` can be used for full `constexpr` arithmetic from C++14 and later with GCC. The functions `abs`, `fabs`,
1088 `fpclassify`, `isnan`, `isinf`, `isfinite` and `isnormal` are also `constexpr`, but the transcendental functions are not.
1089 * When using the Intel compiler, the underlying type defaults to `__float128` if it's available and `_Quad` if not. You can override
1090 the default by defining either `BOOST_MP_USE_FLOAT128` or `BOOST_MP_USE_QUAD`.
1091 * When the underlying type is Intel's `_Quad` type, the code must be compiled with the compiler option `-Qoption,cpp,--extended_float_type`.
1092 * When compiling with `gcc`, you need to use the flag `--std=gnu++11/14/17`, as the suffix 'Q' is a GNU extension. Compilation fails with the flag `--std=c++11/14/17`
1093 unless you also use `-fext-numeric-literals`.
1095 [h5 float128 example:]
1101 [section:fp_eg Examples]
1103 [import ../example/floating_point_examples.cpp]
1105 [section:aos Area of Circle]
1113 [section:jel Defining a Special Function.]
1119 [section:nd Calculating a Derivative]
1127 [section:gi Calculating an Integral]
1134 [section:poly_eg Polynomial Evaluation]
1138 [endsect] [/section:poly_eg Polynomial Evaluation]
1140 [section:variable_precision Variable Precision Newton Evaluation]
1146 [endsect] [/section:fp_eg Examples]
1148 [endsect] [/section:floats floating-point Numbers]
1150 [section:interval Interval Number Types]
1152 There is one currently only one interval number type supported - [mpfi].
1154 [section:mpfi mpfi_float]
1156 `#include <boost/multiprecision/mpfi.hpp>`
1158 namespace boost{ namespace multiprecision{
1160 template <unsigned Digits10>
1161 class mpfi_float_backend;
1163 typedef number<mpfi_float_backend<50> > mpfi_float_50;
1164 typedef number<mpfi_float_backend<100> > mpfifloat_100;
1165 typedef number<mpfi_float_backend<500> > mpfifloat_500;
1166 typedef number<mpfi_float_backend<1000> > mpfi_float_1000;
1167 typedef number<mpfi_float_backend<0> > mpfi_float;
1171 The `mpfi_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfi] `mpfi_t`
1172 to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with
1173 much greater precision and implementing interval arithmetic.
1175 Type `mpfi_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or
1176 at variable precision by setting the template argument to zero. The `typedef`s `mpfi_float_50`, `mpfi_float_100`,
1177 `mpfi_float_500`, `mpfi_float_1000` provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision
1178 respectively. The `typedef mpfi_float` provides a variable precision type whose precision can be controlled via the
1179 `number`s member functions.
1181 [note This type only provides `numeric_limits` support when the precision is fixed at compile time.]
1183 As well as the usual conversions from arithmetic and string types, instances of `number<mpfi_float_backend<N> >` are
1184 copy constructible and assignable from:
1186 * The [mpfi] native type `mpfi_t`.
1187 * The `number` wrappers around [mpfi] or [mpfr]: `number<mpfi_float_backend<M> >` and `number<mpfr_float<M> >`.
1188 * There is a two argument constructor taking two `number<mpfr_float<M> >` arguments specifying the interval.
1190 It's also possible to access the underlying `mpfi_t` via the data() member function of `mpfi_float_backend`.
1192 Things you should know when using this type:
1194 * A default constructed `mpfi_float_backend` is set to zero (['Note that this is [*not] the default [mpfi] behavior]).
1195 * No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing
1196 [mpfr] or [gmp] code.
1197 * The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32.
1198 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
1199 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1200 as a valid floating-point number.
1201 * Division by zero results in an infinity.
1203 There are some additional non member functions for working on intervals:
1205 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1206 number<mpfr_float_backend<Digits10>, ExpressionTemplates> lower(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);
1208 Returns the lower end of the interval.
1210 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1211 number<mpfr_float_backend<Digits10>, ExpressionTemplates> upper(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);
1213 Returns the upper end of the interval.
1215 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1216 number<mpfr_float_backend<Digits10>, ExpressionTemplates> median(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);
1218 Returns the mid point of the interval.
1220 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1221 number<mpfr_float_backend<Digits10>, ExpressionTemplates> width(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val);
1223 Returns the absolute width of the interval.
1225 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1226 number<mpfi_float_backend<Digits10>, ExpressionTemplates> intersect(
1227 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
1228 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);
1230 Returns the interval which is the intersection of the ['a] and ['b]. Returns an
1231 unspecified empty interval if there is no such intersection.
1233 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1234 number<mpfi_float_backend<Digits10>, ExpressionTemplates> hull(
1235 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
1236 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);
1238 Returns the interval which is the union of ['a] and ['b].
1240 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1241 bool overlap(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
1242 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);
1244 Returns `true` only if the intervals ['a] and ['b] overlap.
1246 template <unsigned Digits10, expression_template_option ExpressionTemplates1, expression_template_option ExpressionTemplates2>
1247 bool in(const number<mpfr_float_backend<Digits10>, ExpressionTemplates1>& a,
1248 const number<mpfi_float_backend<Digits10>, ExpressionTemplates2>& b);
1250 Returns `true` only if point ['a] is contained within the interval ['b].
1252 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1253 bool zero_in(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);
1255 Returns `true` only if the interval ['a] contains the value zero.
1257 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1258 bool subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
1259 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);
1261 Returns `true` only if ['a] is a subset of ['b].
1263 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1264 bool proper_subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a,
1265 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b);
1267 Returns `true` only if ['a] is a proper subset of ['b].
1269 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1270 bool empty(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);
1272 Returns `true` only if ['a] is an empty interval, equivalent to `upper(a) < lower(a)`.
1274 template <unsigned Digits10, expression_template_option ExpressionTemplates>
1275 bool singleton(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a);
1277 Returns `true` if `lower(a) == upper(a)`.
1279 [h5 [mpfi] example:]
1287 [section:complex Complex Number Types]
1289 The following backends provide complex number arithmetic:
1292 [[Backend Type][Header][Radix][Dependencies][Pros][Cons]]
1293 [[`cpp_complex`][boost/multiprecision/cpp_complex.hpp][2][None][An all C++ Boost-licensed implementation.][Slower than [mpc].]]
1294 [[`mpc`][boost/multiprecision/mpc.hpp][2][[mpc]][Very fast and efficient back-end.][Dependency on LGLP-licensed [MPC] library.]]
1295 [[`compplex128`][boost/multiprecision/complex128.hpp][2][`__float128` and libquadmath][Very fast and efficient number type.][128-bit precision only, and resticted to GCC.]]
1296 [[`complex_adaptor`][boost/multiprecision/complex_adaptor.hpp][-][none][Can convert any backend type into a complex number backend.][Not a numbe rin it's own right, and hard to use as a result.]]
1299 [section:cpp_complex cpp_complex]
1301 `#include <boost/multiprecision/cpp_complex.hpp>`
1303 namespace boost{ namespace multiprecision{
1305 template <unsigned Digits, backends::digit_base_type DigitBase = backends::digit_base_10, class Allocator = void, class Exponent = int, Exponent MinExponent = 0, Exponent MaxExponent = 0>
1306 using cpp_complex_backend = complex_adaptor<cpp_bin_float<Digits, DigitBase, Allocator, Exponent, MinExponent, MaxExponent> >;
1308 template <unsigned Digits, backends::digit_base_type DigitBase = digit_base_10, class Allocator = void, class Exponent = int, Exponent MinExponent = 0, Exponent MaxExponent = 0, expression_template_option ExpressionTemplates = et_off>
1309 using cpp_complex = number<complex_adaptor<cpp_bin_float<Digits, DigitBase, Allocator, Exponent, MinExponent, MaxExponent> >, ExpressionTemplates>;
1311 typedef cpp_complex<50> cpp_complex_50;
1312 typedef cpp_complex<100> cpp_complex_100;
1314 typedef cpp_complex<24, backends::digit_base_2, void, boost::int16_t, -126, 127> cpp_complex_single;
1315 typedef cpp_complex<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023> cpp_complex_double;
1316 typedef cpp_complex<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383> cpp_complex_extended;
1317 typedef cpp_complex<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383> cpp_complex_quad;
1318 typedef cpp_complex<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143> cpp_complex_oct;
1323 The `cpp_complex_backend` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free)
1324 complex number type that is a drop-in replacement for `std::complex`, but with much greater precision.
1326 The template alias `cpp_complex` avoids the need to use class `number` directly.
1328 Type `cpp_complex` can be used at fixed precision by specifying a non-zero `Digits` template parameter.
1329 The typedefs `cpp_complex_50` and `cpp_complex_100` provide complex number types at 50 and 100 decimal digits precision
1332 Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example
1333 to declare a `cpp_complex` with exactly the same precision as `std::complex<double>` one would use
1334 `cpp_complex<53, digit_base_2>`. The typedefs `cpp_complex_single`, `cpp_complex_double`,
1335 `cpp_complex_quad`, `cpp_complex_oct` and `cpp_complex_double_extended` provide
1336 software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively.
1337 Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size
1338 or bit-layout as true IEEE compatible types.
1340 Normally `cpp_complex` allocates no memory: all of the space required for its digits are allocated
1341 directly within the class. As a result care should be taken not to use the class with too high a digit count
1342 as stack space requirements can grow out of control. If that represents a problem then providing an allocator
1343 as a template parameter causes `cpp_complex` to dynamically allocate the memory it needs: this
1344 significantly reduces the size of `cpp_complex` and increases the viable upper limit on the number of digits
1345 at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive
1346 as the digit count grows: the current implementation really isn't optimized or designed for large digit counts.
1347 Note that since the actual type of the objects allocated
1348 is completely opaque, the suggestion would be to use an allocator with `char` `value_type`, for example:
1349 `cpp_complex<1000, digit_base_10, std::allocator<char> >`.
1351 The next template parameters determine the type and range of the exponent: parameter `Exponent` can be
1352 any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits
1353 of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will
1354 get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then
1355 the library will choose suitable values that are as large as possible given the constraints of the type
1356 and need for extra headroom for internal calculations.
1358 Finally, as with class `number`, the final template parameter determines whether expression templates are turn
1359 on or not. Since by default this type allocates no memory, expression template support is off by default.
1360 However, you should probably turn it on if you specify an allocator.
1362 There is full standard library support available for this type, comparable with what `std::complex` provides.
1364 Things you should know when using this type:
1366 * Default constructed `cpp_complex`s have a value of zero.
1367 * The radix of this type is 2, even when the precision is specified as decimal digits.
1368 * The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow,
1369 and a NaN is generated for any mathematically undefined operation.
1370 * There is no `std::numeric_limits` specialisation for this type: this is the same behaviour as `std::complex`. If you need
1371 `std::numeric_limits` support you need to look at `std::numeric_limits<my_complex_number_type::value_type>`.
1372 * Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type -
1373 for example you can convert from `number<cpp_complex<50> >` to `number<cpp_bin_float<SomeOtherValue> >`.
1374 Narrowing conversions round to nearest and are `explicit`.
1375 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1376 as a valid complex number.
1382 Which produces the output (for the multiprecision type):
1388 [section:mpc_complex mpc_complex]
1390 `#include <boost/multiprecision/mpc.hpp>`
1392 namespace boost{ namespace multiprecision{
1394 template <unsigned Digits10>
1395 class mpc_complex_backend;
1397 typedef number<mpc_complex_backend<50> > mpc_complex_50;
1398 typedef number<mpc_complex_backend<100> > mpc_complex_100;
1399 typedef number<mpc_complex_backend<500> > mpc_complex_500;
1400 typedef number<mpc_complex_backend<1000> > mpc_complex_1000;
1401 typedef number<mpc_complex_backend<0> > mpc_complex;
1405 The `mpc_complex_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpc] `mpc_t`
1406 to provide an real-number type that is a drop-in replacement for `std::complex`, but with
1407 much greater precision.
1409 Type `mpc_complex_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or
1410 at variable precision by setting the template argument to zero. The typedefs mpc_complex_50, mpc_complex_100,
1411 mpc_complex_500, mpc_complex_1000 provide complex types at 50, 100, 500 and 1000 decimal digits precision
1412 respectively. The typedef mpc_complex provides a variable precision type whose precision can be controlled via the
1413 `number`s member functions.
1415 The `mpc` backend should allow use of the same syntax as the C++ standard library complex type.
1416 When using this backend, remember to link with the flags `-lmpc -lmpfr -lgmp`.
1418 As well as the usual conversions from arithmetic and string types, instances of `number<mpc_complex_backend<N> >` are
1419 copy constructible and assignable from:
1421 * The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`.
1422 * The [mpfr] native type `mpfr_t`.
1423 * The [mpc] native type `mpc_t`.
1424 * The `number` wrappers around those types: `number<mpfr_float_backend<M> >`, `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`.
1426 It's also possible to access the underlying `mpc_t` via the data() member function of `mpfr_float_backend`.
1428 Things you should know when using this type:
1430 * A default constructed `mpc_complex_backend` is set to zero (['Note that this is [*not] the default [mpc] behavior]).
1431 * All operations use round to nearest.
1432 * No changes are made to [mpc], [gmp] or [mpfr] global settings, so this type can coexist with existing
1433 [mpc], [mpfr] or [gmp] code.
1434 * The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32.
1435 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
1436 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1437 as a valid complex number.
1438 * Division by zero results in a complex-infinity.
1439 * Unlike `std::complex`, you can not use `reinterpret_cast` to treat this type as an array of the underlying floating point type.
1440 * Unlike `std::complex`, there are no literals for imaginary values.
1441 * When using the variable precision type `mpc_complex`, then copy construction and assignment ['copies the precision
1442 of the source variable]. Likewise move construction and assignment.
1443 * When constructing the variable precision type `mpc_complex` you can specify two arguments to the constructor - the first
1444 is the value to assign to the variable, the second is an unsigned integer specifying the precision in decimal places. The
1445 `assign` member function similarly has a 2-argument overload taking the value to assign and the precision. You can use this
1446 to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a`
1447 but preserves the precision of `a`.
1453 Which produces the output (for the multiprecision type):
1459 [section:complex128 complex128]
1461 `#include <boost/multiprecision/complex128.hpp>`
1463 namespace boost{ namespace multiprecision{
1465 class complex128_backend;
1467 typedef number<complex128_backend, et_off> complex128;
1471 The `complex128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types
1472 and provides a complex-number type that is a drop-in replacement for the native C++ floating-point types, but with
1473 a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real.
1475 All the usual standard library functions are available, performance should be equivalent
1476 to the underlying native types.
1478 As well as the usual conversions from arithmetic and string types, instances of `float128` are
1479 copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types.
1481 Things you should know when using this type:
1483 * Default constructed `complex128`s have the value zero.
1484 * This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware.
1485 * It is not possible to round-trip objects of this type to and from a string and get back
1486 exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of
1487 our code. Round tripping when using `__float128` as the underlying type is possible (both for GCC and Intel).
1488 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted
1489 as a valid floating-point number.
1490 * Division by zero results in an infinity being produced.
1491 * When using the Intel compiler, the underlying type defaults to `__float128` if it's available and `_Quad` if not. You can override
1492 the default by defining either `BOOST_MP_USE_FLOAT128` or `BOOST_MP_USE_QUAD`.
1493 * When the underlying type is Intel's `_Quad` type, the code must be compiled with the compiler option `-Qoption,cpp,--extended_float_type`.
1495 [h5 complex128 example:]
1499 Which results in the output:
1505 [section:complex_adaptor complex_adaptor]
1507 namespace boost{ namespace multiprecision{
1509 template <class Backend>
1510 struct complex_adaptor;
1514 Class template `complex_adaptor` is designed to sit inbetween class `number` and an actual floating point backend,
1515 in order to create a new complex number type.
1517 It is the means by which we implement __cpp_complex and __complex128.
1523 [section:rational Rational Number Types]
1525 The following back-ends provide rational number arithmetic:
1528 [[Backend Type][Header][Radix][Dependencies][Pros][Cons]]
1529 [[`cpp_rational`][boost/multiprecision/cpp_int.hpp][2][None][An all C++ Boost-licensed implementation.][Slower than [gmp].]]
1530 [[`gmp_rational`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]]
1531 [[`tommath_rational`][boost/multiprecision/tommath.hpp][2][[tommath]][All C/C++ implementation that's Boost Software Licence compatible.][Slower than [gmp].]]
1532 [[`rational_adaptor`][boost/multiprecision/rational_adaptor.hpp][N/A][none][All C++ adaptor that allows any integer back-end type to be used as a rational type.][Requires an underlying integer back-end type.]]
1533 [[`boost::rational`][boost/rational.hpp][N/A][None][A C++ rational number type that can used with any `number` integer type.][The expression templates used by `number` end up being "hidden" inside `boost::rational`: performance may well suffer as a result.]]
1536 [section:cpp_rational cpp_rational]
1538 `#include <boost/multiprecision/cpp_int.hpp>`
1540 namespace boost{ namespace multiprecision{
1542 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend;
1544 typedef number<cpp_rational_backend> cpp_rational;
1548 The `cpp_rational_backend` type is used via the typedef `boost::multiprecision::cpp_rational`. It provides
1549 a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision.
1551 As well as the usual conversions from arithmetic and string types, instances of `cpp_rational` are copy constructible
1552 and assignable from type `cpp_int`.
1554 There is also a two argument constructor that accepts a numerator and denominator: both of type `cpp_int`.
1556 There are also non-member functions:
1558 cpp_int numerator(const cpp_rational&);
1559 cpp_int denominator(const cpp_rational&);
1561 which return the numerator and denominator of the number.
1563 Things you should know when using this type:
1565 * Default constructed `cpp_rational`s have the value zero.
1566 * Division by zero results in a `std::overflow_error` being thrown.
1567 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be
1568 interpreted as a valid rational number.
1576 [section:gmp_rational gmp_rational]
1578 `#include <boost/multiprecision/gmp.hpp>`
1580 namespace boost{ namespace multiprecision{
1584 typedef number<gmp_rational > mpq_rational;
1588 The `gmp_rational` back-end is used via the typedef `boost::multiprecision::mpq_rational`. It acts as a thin wrapper around the [gmp] `mpq_t`
1589 to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision.
1591 As well as the usual conversions from arithmetic and string types, instances of `number<gmp_rational>` are copy constructible
1592 and assignable from:
1594 * The [gmp] native types: `mpz_t`, `mpq_t`.
1595 * `number<gmp_int>`.
1597 There is also a two-argument constructor that accepts a numerator and denominator (both of type `number<gmp_int>`).
1599 There are also non-member functions:
1601 mpz_int numerator(const mpq_rational&);
1602 mpz_int denominator(const mpq_rational&);
1604 which return the numerator and denominator of the number.
1606 It's also possible to access the underlying `mpq_t` via the `data()` member function of `mpq_rational`.
1608 Things you should know when using this type:
1610 * Default constructed `mpq_rational`s have the value zero (this is the [gmp] default behavior).
1611 * Division by zero results in a `std::overflow_error` being thrown.
1612 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be
1613 interpreted as a valid rational number.
1614 * No changes are made to the [gmp] library's global settings, so this type can coexist with existing
1616 * The code can equally be used with [mpir] as the underlying library - indeed that is the preferred option on Win32.
1624 [section:tommath_rational tommath_rational]
1626 `#include <boost/multiprecision/tommath.hpp>`
1628 namespace boost{ namespace multiprecision{
1630 typedef rational_adpater<tommath_int> tommath_rational;
1631 typedef number<tommath_rational > tom_rational;
1635 The `tommath_rational` back-end is used via the typedef `boost::multiprecision::tom_rational`. It acts as a thin wrapper around
1636 `boost::rational<tom_int>`
1637 to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision.
1639 The advantage of using this type rather than `boost::rational<tom_int>` directly, is that it is expression-template enabled,
1640 greatly reducing the number of temporaries created in complex expressions.
1642 There are also non-member functions:
1644 tom_int numerator(const tom_rational&);
1645 tom_int denominator(const tom_rational&);
1647 which return the numerator and denominator of the number.
1649 Things you should know when using this type:
1651 * Default constructed `tom_rational`s have the value zero (this the inherited Boost.Rational behavior).
1652 * Division by zero results in a `std::overflow_error` being thrown.
1653 * Conversion from a string results in a `std::runtime_error` being thrown if the string can not be
1654 interpreted as a valid rational number.
1655 * No changes are made to [tommath]'s global state, so this type can safely coexist with other [tommath] code.
1656 * Performance of this type has been found to be pretty poor - this need further investigation - but it appears that Boost.Rational
1657 needs some improvement in this area.
1665 [section:br Use With Boost.Rational]
1667 All of the integer types in this library can be used as template arguments to `boost::rational<IntType>`.
1669 Note that using the library in this way largely negates the effect of the expression templates in `number`.
1673 [section:rational_adaptor rational_adaptor]
1675 namespace boost{ namespace multiprecision{
1677 template <class IntBackend>
1678 class rational_adpater;
1682 The class template `rational_adaptor` is a back-end for `number` which converts any existing integer back-end
1683 into a rational-number back-end.
1685 So for example, given an integer back-end type `MyIntegerBackend`, the use would be something like:
1687 typedef number<MyIntegerBackend> MyInt;
1688 typedef number<rational_adaptor<MyIntegerBackend> > MyRational;
1692 MyInt i = numerator(r);
1699 [section:misc Miscellaneous Number Types.]
1701 Backend types listed in this section are predominantly designed to aid debugging.
1703 [section:logged_adaptor logged_adaptor]
1705 `#include <boost/multiprecision/logged_adaptor.hpp>`
1707 namespace boost{ namespace multiprecision{
1709 template <class Backend>
1710 void log_postfix_event(const Backend& result, const char* event_description);
1711 template <class Backend, class T>
1712 void log_postfix_event(const Backend& result1, const T& result2, const char* event_description);
1714 template <class Backend>
1715 void log_prefix_event(const Backend& arg1, const char* event_description);
1716 template <class Backend, class T>
1717 void log_prefix_event(const Backend& arg1, const T& arg2, const char* event_description);
1718 template <class Backend, class T, class U>
1719 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const char* event_description);
1720 template <class Backend, class T, class U, class V>
1721 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const V& arg4, const char* event_description);
1724 class logged_adaptor;
1728 The `logged_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around
1729 some other backend to class `number` and logs all the events that take place on that object. Before any number operation takes
1730 place, it calls `log_prefix_event` with the arguments to the operation (up to 4), plus a string describing the operation.
1731 Then after the operation it calls `log_postfix_event` with the result of the operation, plus a string describing the operation.
1732 Optionally, `log_postfix_event` takes a second result argument: this occurs when the result of the operation is not a `number`,
1733 for example when `fpclassify` is called, `log_postfix_event` will be called with `result1` being the argument to the function, and
1734 `result2` being the integer result of `fpclassify`.
1736 The default versions of `log_prefix_event` and `log_postfix_event` do nothing, it is therefore up to the user to overload these
1737 for the particular backend being observed.
1739 This type provides `numeric_limits` support whenever the template argument Backend does so.
1741 This type is particularly useful when combined with an interval number type - in this case we can use `log_postfix_event`
1742 to monitor the error accumulated after each operation. We could either set some kind of trap whenever the accumulated error
1743 exceeds some threshold, or simply print out diagnostic information. Using this technique we can quickly locate the cause of
1744 numerical instability in a particular routine. The following example demonstrates this technique in a trivial algorithm
1745 that deliberately introduces cancellation error:
1749 When we examine program output we can clearly see that the diameter of the interval increases after each subtraction:
1751 [logged_adaptor_output]
1755 [section:debug_adaptor debug_adaptor]
1757 `#include <boost/multiprecision/debug_adaptor.hpp>`
1759 namespace boost{ namespace multiprecision{
1762 class debug_adaptor;
1766 The `debug_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around
1767 some other backend to class `number` and intercepts all operations on that object storing the result as a string within itself.
1769 This type provides `numeric_limits` support whenever the template argument Backend does so.
1771 This type is particularly useful when your debugger provides a good view of `std::string`: when this is the case
1772 multiprecision values can easily be inspected in the debugger by looking at the `debug_value` member of `debug_adaptor`.
1773 The down side of this approach is that runtimes are much slower when using this type. Set against that it can make
1774 debugging very much easier, certainly much easier than sprinkling code with `printf` statements.
1776 When used in conjunction with the Visual C++ debugger visualisers, the value of a multiprecision type that uses this
1777 backend is displayed in the debugger just a builtin value would be, here we're inspecting a value of type
1778 `number<debug_adaptor<cpp_dec_float<50> > >`:
1782 Otherwise you will need to expand out the view and look at the "debug_value" member:
1786 It works for all the backend types equally too, here it is inspecting a `number<debug_adaptor<gmp_rational> >`:
1793 [section:visualizers Visual C++ Debugger Visualizers]
1795 Let's face it debugger multiprecision numbers is hard - simply because we can't easily inspect the value of the numbers.
1796 Visual C++ provides a partial solution in the shape of "visualizers" which provide improved views of complex data structures,
1797 these visualizers need to be added to the `[Visualizer]` section of `autoexp.dat` located in the `Common7/Packages/Debugger`
1798 directory of your Visual Studio installation. The actual visualizer code is in the sandbox
1799 [@https://svn.boost.org/svn/boost/sandbox/boost_docs/subprojects/DebuggerVisualizers/multiprecision.vis.txt here] - just cut and paste the code
1800 into your `autoexp.dat` file.
1802 [note These visualizers have only been tested with VC10, also given the ability of buggy visualizers to crash your Visual C++
1803 debugger, make sure you back up `autoexp.dat` file before using these!!]
1805 The first visualizer provides improved views of `debug_adaptor`:
1809 The next visualizer provides improved views of cpp_int: small numbers are displayed as actual values, while larger numbers are
1810 displayed as an array of hexadecimal parts, with the most significant part first.
1812 Here's what it looks like for small values:
1816 And for larger values:
1820 There is also a `~raw` child member that
1821 lets you see the actual members of the class:
1825 The visualizer for `cpp_dec_float` shows the first few digits of the value in the preview field, and the full array of digits
1826 when you expand the view. As before the `~raw` child gives you access to the actual data members:
1834 [section:conversions Constructing and Interconverting Between Number Types]
1836 All of the number types that are based on `number` have certain conversion rules in common.
1839 * Any number type can be constructed (or assigned) from any builtin arithmetic type, as long
1840 as the conversion isn't lossy (for example float to int conversion):
1842 cpp_dec_float_50 df(0.5); // OK construction from double
1843 cpp_int i(450); // OK constructs from signed int
1844 cpp_int j = 3.14; // Error, lossy conversion.
1846 * A number can be explicitly constructed from an arithmetic type, even when the conversion is lossy:
1848 cpp_int i(3.14); // OK explicit conversion
1849 i = static_cast<cpp_int>(3.14) // OK explicit conversion
1850 i.assign(3.14); // OK, explicit assign and avoid a temporary from the cast above
1851 i = 3.14; // Error, no implicit assignment operator for lossy conversion.
1852 cpp_int j = 3.14; // Error, no implicit constructor for lossy conversion.
1854 * A `number` can be converted to any built in type, via the `convert_to` member function:
1857 int i = z.convert_to<int>(); // sets i to 2
1859 * Conversions to rational numbers from floating-point ones are always allowed, and are exact and implicit
1860 as long as the rational number uses an unbounded integer type. Please be aware that constructing a rational
1861 number from an extended precision floating-point type with a large exponent range can effectively run the system
1862 out of memory, as in the extreme case ['2[super max_exponent] / CHAR_BITS] bytes of storage may be required. This
1863 does not represent a problem for built in floating-point types however, as the exponent range for these is rather
1866 * Conversions to floating-point numbers from rational ones are rounded to nearest (less than 0.5ulp error)
1867 as long as the floating-point number is binary, and the integer type used by the rational number is unbounded.
1869 Additional conversions may be supported by particular backends.
1871 * A `number` can be converted to any built in type, via an explicit conversion operator:
1872 this functionality is only available on compilers supporting C++11's explicit conversion syntax.
1875 int i = z; // Error, implicit conversion not allowed.
1876 int j = static_cast<int>(z); // OK explicit conversion.
1878 * Any number type can be ['explicitly] constructed (or assigned) from a `const char*` or a `std::string`:
1880 // pi to 50 places from a string:
1881 cpp_dec_float_50 df("3.14159265358979323846264338327950288419716939937510");
1882 // Integer type will automatically detect "0x" and "0" prefixes and parse the string accordingly:
1883 cpp_int i("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFF000000000000000");
1884 // Invalid input always results in a std::runtime_error being thrown:
1885 i = static_cast<cpp_int>("3.14");
1886 // implicit conversions from strings are not allowed:
1887 i = "23"; // Error, no assignment operator for implicit conversion from string
1888 // assign member function, avoids having to create a temporary via a static_cast:
1889 i.assign("23"); // OK
1891 * Any number type will interoperate with the builtin types in arithmetic expressions as long as the conversions
1894 // pi to 50 places from a string:
1895 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510";
1896 // Multiply by 2 - using an integer literal here is usually more efficient
1897 // than constructing a temporary:
1900 // You can't mix integer types with floats though:
1902 i *= 3.14; // Error, no *= operator will be found.
1904 * Any number type can be streamed to and from the C++ iostreams:
1906 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510";
1907 // Now print at full precision:
1908 std::cout << std::setprecision(std::numeric_limits<cpp_dec_float_50>::max_digits10)
1912 // Now print in hex format with prefix:
1913 std::cout << std::hex << std::showbase << i << std::endl;
1915 * Interconversions between number types of the same family are allowed and are implicit conversions if no
1916 loss of precision is involved, and explicit if it is:
1919 int266_t i256 = i128; // OK implicit widening conversion
1920 i128_t = i256; // Error, no assignment operator found, narrowing conversion is explicit.
1921 i128_t = static_cast<int128_t>(i256); // OK, explicit narrowing conversion.
1924 mpf_float f = z; // OK, GMP handles this conversion natively, and it's not lossy and therefore implicit.
1926 mpf_float_50 f50 = 2;
1927 f = f50; // OK, conversion from fixed to variable precision, f will have 50 digits precision.
1928 f50 = f; // Error, conversion from variable to fixed precision is potentially lossy, explicit cast required.
1930 * Some interconversions between number types are completely generic, and are always available, albeit the conversions are always ['explicit]:
1933 // We can always convert between numbers of the same category -
1934 // int to int, rational to rational, or float to float, so this is OK
1935 // as long as we use an explicit conversion:
1937 // We can always promote from int to rational, int to float, or rational to float:
1938 cpp_rational cppr(cppi); // OK, int to rational
1939 cpp_dec_float_50 df(cppi); // OK, int to float
1940 df = static_cast<cpp_dec_float_50>(cppr); // OK, explicit rational to float conversion
1941 // However narrowing and/or implicit conversions always fail:
1942 cppi = df; // Compiler error, conversion not allowed
1944 * Other interconversions may be allowed as special cases, whenever the backend allows it:
1946 mpf_t m; // Native GMP type.
1947 mpf_init_set_ui(m, 0); // set to a value;
1948 mpf_float i(m); // copies the value of the native type.
1950 More information on what additional types a backend supports conversions from are given in the tutorial for each backend.
1951 The converting constructor will be implicit if the backend's converting constructor is also implicit, and explicit if the
1952 backends converting constructor is also explicit.
1956 [section:random Generating Random Numbers]
1958 Random numbers are generated in conjunction with Boost.Random.
1960 There is a single generator that supports generating random integers with large bit counts:
1961 [@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`].
1962 This type can be used with either ['unbounded] integer types, or with ['bounded] (ie fixed precision) unsigned integers:
1970 In addition, the generator adaptors [@http://www.boost.org/doc/html/boost/random/discard_block_engine.html `discard_block`],
1971 [@http://www.boost.org/doc/html/boost/random/xor_combine_engine.html `xor_combine_engine`] and
1972 [@http://www.boost.org/doc/html/boost/random/discrete_distribution.html `discrete_distribution`] can be used
1973 with multiprecision types. Note that if you seed an `independent_bits_engine`, then you are actually seeding
1974 the underlying generator, and should therefore provide a sequence of unsigned 32-bit values as the seed.
1976 Alternatively we can generate integers in a given range using
1977 [@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`], this will
1978 invoke the underlying engine multiple times to build up the required number of bits in the result:
1984 It is also possible to use [@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`]
1985 with a multiprecision generator such as [@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`].
1986 Or to use [@http://www.boost.org/doc/html/boost/random/uniform_smallint.html `uniform_smallint`] or
1987 [@http://www.boost.org/doc/html/boost/random/random_number_generator.html `random_number_generator`] with multiprecision types.
1989 floating-point values in \[0,1) are most easily generated using [@http://www.boost.org/doc/html/boost/random/generate_canonical.html `generate_canonical`],
1990 note that `generate_canonical` will call the generator multiple times to produce the requested number of bits, for example we can use
1991 it with a regular generator like so:
1997 Note however, the distributions do not invoke the generator multiple times to fill up the mantissa of a multiprecision floating-point type
1998 with random bits. For these therefore, we should probably use a multiprecision generator (ie `independent_bits_engine`) in combination
1999 with the distribution:
2005 And finally, it is possible to use the floating-point generators [@http://www.boost.org/doc/html/boost/random/lagged_fibonacci_01_engine.html `lagged_fibonacci_01_engine`]
2006 and [@http://www.boost.org/doc/html/boost/random/subtract_with_idp144360752.html `subtract_with_carry_01_engine`] directly with multiprecision floating-point types.
2007 It's worth noting however, that there is a distinct lack of literature on generating high bit-count random numbers, and therefore a lack of "known good" parameters to
2008 use with these generators in this situation. For this reason, these should probably be used for research purposes only:
2014 [section:primetest Primality Testing]
2016 The library implements a Miller-Rabin test for primality:
2018 #include <boost/multiprecision/miller_rabin.hpp>
2020 template <class Backend, expression_template_option ExpressionTemplates, class Engine>
2021 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials, Engine& gen);
2023 template <class Backend, expression_template_option ExpressionTemplates, class Engine>
2024 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials);
2026 These functions perform a Miller-Rabin test for primality, if the result is `false` then /n/ is definitely composite,
2027 while if the result is true then n is probably prime. The probability to declare a composite n as probable prime is
2028 at most 0.25[super trials]. Note that this does not allow a statement about the probability of n being actually
2029 prime (for that, the prior probability would have to be known). The algorithm used performs some
2030 trial divisions to exclude small prime factors, does one Fermat test to exclude many more composites, and then
2031 uses the Miller-Rabin algorithm straight out of
2032 Knuth Vol 2, which recommends 25 trials for a pretty strong likelihood that /n/ is prime.
2034 The third optional argument is for a Uniform Random Number Generator from Boost.Random. When not provided the `mt19937`
2035 generator is used. Note that when producing random primes then you should probably use a different random number generator
2036 to produce candidate prime numbers for testing, than is used internally by `miller_rabin_test` for determining
2037 whether the value is prime. It also helps of course to seed the generators with some source of randomness.
2039 The following example searches for a prime `p` for which `(p-1)/2` is also probably prime:
2045 [section:lits Literal Types and `constexpr` Support]
2047 There are two kinds of `constexpr` support in this library:
2049 * The more basic version requires only C++11 and allow the construction of some number types as literals.
2050 * The more advanced support permits constexpr arithmetic and requires at least C++14
2051 constexpr support, and for many operations C++2a support
2053 [h4 Declaring numeric literals]
2055 There are two backend types which are literals:
2057 * __float128 (which requires GCC), and
2058 * Instantiations of `cpp_int_backend` where the Allocator parameter is type `void`.
2059 In addition, prior to C++14 the Checked parameter must be `boost::multiprecision::unchecked`.
2063 using namespace boost::multiprecision;
2065 constexpr float128 f = 0.1Q // OK, float128's are always literals in C++11
2067 constexpr int128_t i = 0; // OK, fixed precision int128_t has no allocator.
2068 constexpr uint1024_t j = 0xFFFFFFFF00000000uLL; // OK, fixed precision uint1024_t has no allocator.
2070 constexpr checked_uint128_t k = 1; // OK from C++14 and later, not supported for C++11.
2071 constexpr checked_uint128_t k = -1; // Error, as this would normally lead to a runtime failure (exception).
2072 constexpr cpp_int l = 2; // Error, type is not a literal as it performs memory management.
2074 There is also support for user defined-literals with __cpp_int - these are limited to unchecked, fixed precision `cpp_int`'s
2075 which are specified in hexadecimal notation. The suffixes supported are:
2079 [[_cppi][Specifies a value of type: `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`, where N is chosen
2080 to contain just enough digits to hold the number specified.]]
2081 [[_cppui][Specifies a value of type: `number<cpp_int_backend<N,N,unsigned_magnitude,unchecked,void> >`, where N is chosen
2082 to contain just enough digits to hold the number specified.]]
2083 [[_cppi['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]]
2084 [[_cppui['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]]
2087 In each case, use of these suffixes with hexadecimal values produces a `constexpr` result.
2092 // Any use of user defined literals requires that we import the literal-operators
2093 // into current scope first:
2094 using namespace boost::multiprecision::literals;
2096 // To keep things simple in the example, we'll make our types used visible to this scope as well:
2097 using namespace boost::multiprecision;
2099 // The value zero as a number<cpp_int_backend<4,4,signed_magnitude,unchecked,void> >:
2100 constexpr auto a = 0x0_cppi;
2101 // The type of each constant has 4 bits per hexadecimal digit,
2102 // so this is of type uint256_t (ie number<cpp_int_backend<256,256,unsigned_magnitude,unchecked,void> >):
2103 constexpr auto b = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui;
2105 // Smaller values can be assigned to larger values:
2106 int256_t c = 0x1234_cppi; // OK
2108 // However, this only works in constexpr contexts from C++14 onwards:
2109 constexpr int256_t d = 0x1_cppi; // Compiler error in C++11, requires C++14
2111 // Constants can be padded out with leading zeros to generate wider types:
2112 constexpr uint256_t e = 0x0000000000000000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFF_cppui; // OK
2114 // However, specific width types are best produced with specific-width suffixes,
2115 // ones supported by default are `_cpp[u]i128`, `_cpp[u]i256`, `_cpp[u]i512`, `_cpp[u]i1024`.
2117 constexpr int128_t f = 0x1234_cppi128; // OK, always produces an int128_t as the result.
2118 constexpr uint1024_t g = 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbccccccccccccccccccccc_cppui1024;
2120 // If other specific width types are required, then there is a macro for generating the operators
2121 // for these. The macro can be used at namespace scope only:
2123 BOOST_MP_DEFINE_SIZED_CPP_INT_LITERAL(2048);
2125 // Now we can create 2048-bit literals as well:
2126 constexpr auto h = 0xff_cppi2048; // h is of type number<cpp_int_backend<2048,2048,signed_magnitude,unchecked,void> >
2128 // Finally negative values are handled via the unary minus operator:
2130 constexpr int1024_t i = -0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui1024;
2132 // Which means this also works:
2133 constexpr int1024_t j = -g; // OK: unary minus operator is constexpr.
2135 [h4 constexpr arithmetic]
2137 The front end of the library is all `constexpr` from C++14 and later. Currently there are only two
2138 back end types that are `constexpr` aware: __float128 and __cpp_int. More backends will follow at a later date.
2140 Provided the compiler is GCC, type __float128 support `constexpr` operations on all arithmetic operations from C++14, comparisons,
2141 `abs`, `fabs`, `fpclassify`, `isnan`, `isinf`, `isfinite` and `isnormal` are also fully supported, but the transcendental functions are not.
2143 The __cpp_int types support constexpr arithmetic, provided it is a fixed precision type with no allocator. It may also
2144 be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition
2145 the free functions `abs`, `swap`, `multiply`, `add`, `subtract`, `divide_qr`, `integer_modulus`, `powm`, `lsb`, `msb`,
2146 `bit_test`, `bit_set`, `bit_unset`, `bit_flip`, `sqrt`, `gcd`, `lcm` are all supported. Use of __cpp_int in this way
2147 requires either a C++2a compiler (one which supports `std::is_constant_evaluated()` - currently only gcc-9 or clang-9 or later),
2148 or GCC-6 or later in C++14 mode.
2149 Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations:
2150 expect to hit roadblocks rather easily.
2156 We can now calculate areas and circumferences using all constexpr arithmetic:
2158 [constexpr_circle_usage]
2160 Note that these make use of the numeric constants from the Math library, which also happen to be `constexpr`.
2162 For a more interesting example, in [@../../example/constexpr_float_arithmetic_examples.cpp constexpr_float_arithmetic_examples.cpp]
2163 we define a simple class for `constexpr` polynomial arithmetic:
2165 template <class T, unsigned Order>
2166 struct const_polynomial;
2168 Given this, we can use recurrence relations to calculate the coefficients for various orthogonal
2169 polynomials - in the example we use the Hermite polynomials, only the constructor does any work -
2170 it uses the recurrence relations to calculate the coefficient array:
2174 Now we just need to define H[sub 0] and H[sub 1] as termination conditions for the recurrence:
2178 We can now declare H[sub 9] as a constexpr object, access the coefficients, and evaluate
2179 at an abscissa value, all using `constexpr` arithmetic:
2183 Also since the coefficients to the Hermite polynomials are integers, we can also generate the Hermite
2184 coefficients using (fixed precision) cpp_int's: see [@../../test/constexpr_test_cpp_int_6.cpp constexpr_test_cpp_int_6.cpp].
2186 We can also generate factorials (and validate the result) like so:
2190 constexpr uint1024_t f1 = factorial(uint1024_t(31));
2191 static_assert(f1 == 0x1956ad0aae33a4560c5cd2c000000_cppi);
2193 Another example in [@../../test/constexpr_test_cpp_int_7.cpp constexpr_test_cpp_int_7.cpp] generates
2194 a fresh multiprecision random number each time the file is compiled.
2199 [section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`]
2201 Any integer number type that uses `cpp_int_backend` as it's implementation layer can import or export its bits via two non-member functions:
2203 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator,
2204 expression_template_option ExpressionTemplates, class OutputIterator>
2205 OutputIterator export_bits(
2206 const number<const cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val,
2208 unsigned chunk_size,
2209 bool msv_first = true);
2211 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator,
2212 expression_template_option ExpressionTemplates, class Iterator>
2213 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>&
2215 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val,
2218 unsigned chunk_size = 0,
2219 bool msv_first = true);
2221 These functions are designed for data-interchange with other storage formats, and since __cpp_bin_float uses __cpp_int internally,
2222 by extension they can be used for floating-point numbers based on that backend as well (see example below).
2223 Parameters and use are as follows:
2225 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator,
2226 expression_template_option ExpressionTemplates, class OutputIterator>
2227 OutputIterator export_bits(
2228 const number<const cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val,
2230 unsigned chunk_size,
2231 bool msv_first = true);
2233 Exports the absolute value of `val` to OutputIterator `out`. The function will write `chunk_size` bits at a time
2234 to the OutputIterator, and if `msv_first` is true, will write the most-significant block first. Byte and bit order
2235 within each `chunk_size` block is always in the machines native format. Further, each block is stored in a
2236 `boost::uintmax_t` when it's assigned to `*out`.
2238 [note Unfortunately, the standard's OutputIterator concept provides no means of deducing the type to output since
2239 `std::iterator_traits<OutputIteratorType>::value_type` is type `void`. This is why the bit count for each block
2240 has to be specified manually. It may also result in compiler warnings about the value being narrowed.]
2242 [tip If you're exporting to non-native byte layout, then use
2243 [@http://www.boost.org/doc/libs/release/libs/endian/doc/index.html Boost.Endian]
2244 to create a custom OutputIterator that reverses the byte order of each chunk prior to actually storing the result.]
2246 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator,
2247 expression_template_option ExpressionTemplates, class ForwardIterator>
2248 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>&
2250 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val,
2253 unsigned chunk_size = 0,
2254 bool msv_first = true);
2256 Imports bits from the iterator range ['\[i,j)] and stores them in `val` to produce an unsigned result (if the result
2257 is to be signed you will need to handle that separately). When `msv_first` is true, takes `*i` as the most significant
2258 chunk. Assumes there are `chunk_size` bits in each value read from the iterator range, and that these are in machine native
2259 bit/byte order. When `chunk_size` is zero, then assumes that each chunk contains
2260 `std::numeric_limits<std::iterator_traits<ForwardIterator>::value_type>::digits`, note that this will give the wrong result
2261 if dereferencing the iterators leads to a signed-integer type, [*and] the sign bit is significant (be particularly careful
2262 if you expect type `char` to contain 8-bit values, as by default it will extract only 7-bits at a time if `char` is signed).
2263 As with exporting, if the external data is to be in a non-native byte order (within each chunk), then you will need to create an iterator adaptor
2264 that presents it in native order (see [@http://www.boost.org/doc/libs/release/libs/endian/doc/index.html Boost.Endian]).
2267 Note that this function is optimized for the case where the data can be `memcpy`ed from the source to the integer - in this case both
2268 iterators much be pointers, and everything must be little-endian.]
2276 [endsect] [/section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`]
2278 [section:rounding Rounding Rules for Conversions]
2280 As a general rule, all conversions between unrelated types are performed using basic arithmetic operations, therefore
2281 conversions are either exact, or follow the same rounding rules as arithmetic for the type in question.
2283 The following table summarises the situation for conversions from native types:
2286 [[Backend][Rounding Rules]]
2287 [[__cpp_int][Conversions from integer types are exact if the target has sufficient precision, otherwise they
2288 truncate to the first 2^MaxBits bits (modulo arithmetic). Conversions from floating-point types
2289 are truncating to the nearest integer.]]
2290 [[__gmp_int][Conversions are performed by the GMP library except for conversion from `long double` which is truncating.]]
2291 [[__tom_int][Conversions from floating-point types are truncating, all others are performed by libtommath and are exact.]]
2292 [[__gmp_float][Conversions are performed by the GMP library except for conversion from `long double` which should be exact
2293 provided the target type has as much precision as a `long double`.]]
2294 [[__mpfr_float_backend][All conversions are performed by the underlying MPFR library.]]
2295 [[__cpp_dec_float][All conversions are performed using basic arithmetic operations and are truncating.]]
2296 [[__gmp_rational][See __gmp_int]]
2297 [[__cpp_rational][See __cpp_int]]
2298 [[__tommath_rational][See __tom_int]]
2301 [endsect] [/section:rounding Rounding Rules for Conversions]
2303 [section:mixed Mixed Precision Arithmetic]
2305 Mixed precision arithmetic is fully supported by the library.
2307 There are two different forms:
2309 * Where the operands are of different precision.
2310 * Where the operands are of the same precision, but yield a higher precision result.
2312 [h4 Mixing Operands of Differing Precision]
2314 If the arguments to a binary operator are of different precision, then the operation is allowed
2315 as long as there is an unambiguous implicit conversion from one argument type to the other.
2316 In all cases the arithmetic is performed "as if" the lower precision type is promoted to the
2317 higher precision type before applying the operator. However, particular backends may optimise
2318 this and avoid actually creating a temporary if they are able to do so.
2322 mpfr_float_50 a(2), b;
2323 mpfr_float_100 c(3), d;
2324 static_mpfr_float_50 e(5), f;
2327 d = a * c; // OK, result of operand is an mpfr_float_100.
2328 b = a * c; // Error, can't convert the result to an mpfr_float_50 as it will lose digits.
2329 f = a * e; // Error, operator is ambiguous, result could be of either type.
2330 f = e * i; // OK, unambiguous conversion from mpz_int to static_mpfr_float_50
2332 [h4 Operands of the Same Precision]
2334 Sometimes you want to apply an operator to two arguments of the same precision in
2335 such a way as to obtain a result of higher precision. The most common situation
2336 occurs with fixed precision integers, where you want to multiply two N-bit numbers
2337 to obtain a 2N-bit result. This is supported in this library by the following
2340 template <class ResultType, class Source1 class Source2>
2341 ResultType& add(ResultType& result, const Source1& a, const Source2& b);
2343 template <class ResultType, class Source1 class Source2>
2344 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b);
2346 template <class ResultType, class Source1 class Source2>
2347 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b);
2349 These functions apply the named operator to the arguments ['a] and ['b] and store the
2350 result in ['result], returning ['result]. In all cases they behave "as if"
2351 arguments ['a] and ['b] were first promoted to type `ResultType` before applying the
2352 operator, though particular backends may well avoid that step by way of an optimization.
2354 The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2`
2355 may be either instances of class `number` or native integer types. The latter is an optimization
2356 that allows arithmetic to be performed on native integer types producing an extended precision result.
2362 Produces the output:
2366 [h4 Backends With Optimized Mixed Precision Arithmetic]
2368 The following backends have at least some direct support for mixed precision arithmetic,
2369 and therefore avoid creating unnecessary temporaries when using the interfaces above.
2370 Therefore when using these types it's more efficient to use mixed precision arithmetic,
2371 than it is to explicitly cast the operands to the result type:
2373 __mpfr_float_backend, __mpf_float, __cpp_int.
2375 [endsect] [/section:mixed Mixed Precision Arithmetic]
2377 [section:gen_int Generic Integer Operations]
2379 All of the [link boost_multiprecision.ref.number.integer_functions non-member integer operations] are overloaded for the
2380 built in integer types in
2381 `<boost/multiprecision/integer.hpp>`.
2382 Where these operations require a temporary increase in precision (such as for `powm`), then
2383 if no built in type is available, a __cpp_int of appropriate precision will be used.
2385 Some of these functions are trivial, others use compiler intrinsics (where available) to ensure optimal evaluation.
2387 The overloaded functions are:
2389 template <class Integer, class I2>
2390 Integer& multiply(Integer& result, const I2& a, const I2& b);
2392 Multiplies two `I2` values, to produce a wider `Integer` result.
2394 Returns `result = a * b` without overflow or loss of precision in the multiplication.
2396 template <class Integer, class I2>
2397 Integer& add(Integer& result, const I2& a, const I2& b);
2399 Adds two `I2` values, to produce a wider `Integer` result.
2401 Returns `result = a + b` without overflow or loss of precision in the addition.
2403 template <class Integer, class I2>
2404 Integer& subtract(Integer& result, const I2& a, const I2& b);
2406 Subtracts two `I2` values, to produce a wider `Integer` result.
2408 Returns `result = a - b` without overflow or loss of precision in the subtraction.
2410 template <class Integer>
2411 Integer powm(const Integer& b, const Integer& p, const Integer& m);
2413 Returns b[super p] % m.
2415 template <class Integer>
2416 void divide_qr(const Integer& x, const Integer& y, Integer& q, Integer& r);
2418 Sets `q = x / y` and `r = x % y`.
2420 template <class Integer1, class Integer2>
2421 Integer2 integer_modulus(const Integer1& x, Integer2 val);
2425 template <class Integer>
2426 unsigned lsb(const Integer& x);
2428 Returns the (zero-based) index of the least significant bit of `x`.
2430 Throws a `std::domain_error` if `x <= 0`.
2432 template <class Integer>
2433 unsigned msb(const Integer& x);
2435 Returns the (zero-based) index of the most significant bit of `x`.
2437 Throws a `std::domain_error` if `x <= 0`.
2439 template <class Integer>
2440 bool bit_test(const Integer& val, unsigned index);
2442 Returns `true` if bit `index` is set in `val`.
2444 template <class Integer>
2445 Integer& bit_set(Integer& val, unsigned index);
2447 Sets the `index` bit in `val`.
2449 template <class Integer>
2450 Integer& bit_unset(Integer& val, unsigned index);
2452 Unsets the `index` bit in `val`.
2454 template <class Integer>
2455 Integer& bit_flip(Integer& val, unsigned index);
2457 Flips the `index` bit in `val`.
2459 template <class Integer>
2460 Integer sqrt(const Integer& x);
2461 template <class Integer>
2462 Integer sqrt(const Integer& x, Integer& r);
2464 Returns the integer square root `s` of x and sets `r` to the remainder ['x - s[super 2]].
2466 template <class Engine>
2467 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials, Engine& gen);
2468 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials);
2470 The regular Miller-Rabin functions in `<boost/multiprecision/miller_rabin.hpp>` are defined in terms of the above
2471 generic operations, and so function equally well for built-in or __fundamental_types and multiprecision types.
2473 [endsect] [/section:gen_int Generic Integer Operations]
2475 [section:serial Boost.Serialization Support]
2477 Support for serialization comes in two forms:
2479 * Classes __number, __debug_adaptor, __logged_adaptor and __rational_adaptor have "pass through" serialization
2480 support which requires the underlying backend to be serializable.
2481 * Backends __cpp_int, __cpp_bin_float, __cpp_dec_float and __float128 have full support for Boost.Serialization.
2483 [endsect] [/section:serialization Boost Serialization]
2485 [section:limits Numeric Limits]
2487 Boost.Multiprecision tries hard to implement `std::numeric_limits` for all types
2488 as far as possible and meaningful because experience with Boost.Math has shown that this aids portability.
2490 The [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf C++ standard library]
2491 defines `std::numeric_limits` in section 18.3.2.
2493 This in turn refers to the C standard
2494 [@http://www.open-std.org/jtc1/sc22/wg11/docs/n507.pdf SC22/WG11 N507 DRAFT INTERNATIONAL ISO/IEC STANDARD
2496 Information technology Language independent arithmetic Part 1: Integer and floating-point arithmetic.
2498 That C Standard in turn refers to
2500 [@https://doi.org/10.1109/IEEESTD.1985.82928 IEEE754 IEEE Standard for Binary
2501 Floating-Point Arithmetic]
2503 There is a useful summary at
2504 [@http://www.cplusplus.com/reference/limits/numeric_limits/ C++ reference].
2506 The chosen backend often determines how completely `std::numeric_limits` is available.
2508 Compiler options, processor type, and definition of macros or assembler instructions to control denormal numbers will alter
2509 the values in the tables given below.
2511 [warning GMP's `mpf_t` does not have a concept of overflow:
2512 operations that lead to overflow eventually run of out of resources
2513 and terminate with stack overflow (often after several seconds).]
2515 [section:constants std::numeric_limits<> constants]
2519 `true` for all arithmetic types (integer, floating and fixed-point)
2520 for which `std::numeric_limits<T>::numeric_limits` is specialized.
2524 if (std::numeric_limits<T>::is_specialized == false)
2526 std::cout << "type " << typeid(T).name() << " is not specialized for std::numeric_limits!" << std::endl;
2530 Typically `numeric_limits<T>::is_specialized` is `true` for all `T` where the compile-time constant
2531 members of `numeric_limits` are indeed known at compile time, and don't vary at runtime. For example
2532 floating-point types with runtime-variable precision such as `mpfr_float` have no `numeric_limits`
2533 specialization as it would be impossible to define all the members at compile time. In contrast
2534 the precision of a type such as `mpfr_float_50` is known at compile time, and so it ['does] have a
2535 `numeric_limits` specialization.
2537 Note that not all the `std::numeric_limits` member constants and functions are meaningful for all user-defined types (UDT),
2538 such as the decimal and binary multiprecision types provided here. More information on this is given in the sections below.
2542 For floating-point types, [infin] is defined wherever possible,
2543 but clearly infinity is meaningless for __arbitrary_precision arithmetic backends,
2544 and there is one floating-point type (GMP's `mpf_t`, see __mpf_float) which has no notion
2545 of infinity or NaN at all.
2547 A typical test whether infinity is implemented is
2549 if(std::numeric_limits<T>::has_infinity)
2551 std::cout << std::numeric_limits<T>::infinity() << std::endl;
2554 and using tests like this is strongly recommended to improve portability.
2556 If the backend is switched to a type that does not support infinity then,
2557 without checks like this, there will be trouble.
2561 `std::numeric_limits<T>::is_signed == true` if the type `T` is signed.
2563 For built-in binary types, the sign is held in a single bit,
2564 but for other types (cpp_dec_float and cpp_bin_float)
2565 it may be a separate storage element, usually `bool`.
2569 `std::numeric_limits<T>::is_exact == true` if type T uses exact representations.
2571 This is defined as `true` for all integer types and `false` for floating-point types.
2573 [@http://stackoverflow.com/questions/14203654/stdnumeric-limitsis-exact-what-is-a-usable-definition A usable definition]
2576 ISO/IEC 10967-1, Language independent arithmetic, noted by the C++ Standard defines
2578 A floating-point type F shall be a finite subset of [real].
2580 The important practical distinction is that all integers (up to `max()`) can be stored exactly.
2582 [@http://en.wikipedia.org/wiki/Rational_number Rational]
2583 types using two integer types are also exact.
2585 Floating-point types [*cannot store all real values]
2586 (those in the set of [real]) [*exactly].
2587 For example, 0.5 can be stored exactly in a binary floating-point, but 0.1 cannot.
2588 What is stored is the nearest representable real value, that is, rounded to nearest.
2590 Fixed-point types (usually decimal) are also defined as exact, in that they only
2591 store a [*fixed precision], so half cents or pennies (or less) cannot be stored.
2592 The results of computations are rounded up or down,
2593 just like the result of integer division stored as an integer result.
2595 There are number of proposals to
2596 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html
2597 add Decimal floating-point Support to C++].
2599 [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2849.pdf Decimal TR].
2602 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html
2603 C++ Binary Fixed-Point Arithmetic].
2607 `std::numeric_limits<T>::is_bounded == true` if the set of values represented by the type `T` is finite.
2609 This is `true` for all built-in integer, fixed and floating-point types,
2610 and most multi-precision types.
2612 It is only `false` for a few __arbitrary_precision types like `cpp_int`.
2614 Rational and fixed-exponent representations are exact but not integer.
2618 `std::numeric_limits<T>::is_modulo` is defined as `true` if adding two positive values of type T
2619 can yield a result less than either value.
2621 `is_modulo == true` means that the type does not overflow, but, for example,
2622 'wraps around' to zero, when adding one to the `max()` value.
2624 For most built-in integer types, `std::numeric_limits<>::is_modulo` is `true`.
2626 `bool` is the only exception.
2628 The modulo behaviour is sometimes useful,
2629 but also can be unexpected, and sometimes undesired, behaviour.
2631 Overflow of signed integers can be especially unexpected,
2632 possibly causing change of sign.
2634 Boost.Multiprecision integer type `cpp_int` is not modulo
2635 because as an __arbitrary_precision types,
2636 it expands to hold any value that the machine resources permit.
2638 However fixed precision __cpp_int's may be modulo if they are unchecked
2639 (i.e. they behave just like built in integers), but not if they are checked
2640 (overflow causes an exception to be raised).
2642 Built-in and multi-precision floating-point types are normally not modulo.
2644 Where possible, overflow is to `std::numeric_limits<>::infinity()`,
2645 provided `std::numeric_limits<>::has_infinity == true`.
2649 Constant `std::numeric_limits<T>::radix` returns either 2 (for built-in and binary types)
2650 or 10 (for decimal types).
2654 The number of `radix` digits that be represented without change:
2656 * for integer types, the number of [*non-sign bits] in the significand.
2657 * for floating types, the number of [*radix digits] in the significand.
2659 The values include any implicit bit, so for example, for the ubiquious
2660 `double` using 64 bits
2661 ([@http://en.wikipedia.org/wiki/Double_precision_floating-point_format IEEE binary64 ]),
2662 `digits` == 53, even though there are only 52 actual bits of the significand stored in the representation.
2663 The value of `digits` reflects the fact that there is one implicit bit which is always set to 1.
2665 The Boost.Multiprecision binary types do not use an implicit bit, so the
2666 `digits` member reflects exactly how many bits of precision were requested:
2668 typedef number<cpp_bin_float<53, digit_base_2> > float64;
2669 typedef number<cpp_bin_float<113, digit_base_2> > float128;
2670 std::numeric_limits<float64>::digits == 53.
2671 std::numeric_limits<float128>::digits == 113.
2673 For the most common case of `radix == 2`,
2674 `std::numeric_limits<T>::digits` is the number of bits in the representation,
2675 not counting any sign bit.
2677 For a decimal integer type, when `radix == 10`, it is the number of decimal digits.
2681 Constant `std::numeric_limits<T>::digits10` returns the number of
2682 decimal digits that can be represented without change or loss.
2684 For example, `numeric_limits<unsigned char>::digits10` is 2.
2686 This somewhat inscrutable definition means that an `unsigned char`
2687 can hold decimal values `0..99`
2688 without loss of precision or accuracy, usually from truncation.
2690 Had the definition been 3 then that would imply it could hold 0..999,
2691 but as we all know, an 8-bit `unsigned char` can only hold 0..255,
2692 and an attempt to store 256 or more will involve loss or change.
2694 For bounded integers, it is thus [*one less] than number of decimal digits
2695 you need to display the biggest integer `std::numeric_limits<T>::max()`.
2696 This value can be used to predict the layout width required for
2700 For example, `unsigned short` is often stored in 16 bits,
2701 so the maximum value is 0xFFFF or 65535.
2706 For bounded floating-point types,
2707 if we create a `double` with a value with `digits10` (usually 15) decimal digits,
2708 `1e15` or `1000000000000000` :
2712 and we can increment this value to `1000000000000001`
2713 as expected and show the difference too.
2715 But if we try to repeat this with more than `digits10` digits,
2719 then we find that when we add one it has no effect,
2720 and display show that there is loss of precision. See
2721 [@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error].
2723 So `digits10` is the number of decimal digits [*guaranteed] to be correct.
2725 For example, 'round-tripping' for `double`:
2727 * If a decimal string with at most `digits10`( == 15) significant decimal digits
2728 is converted to `double` and then converted back to the
2729 same number of significant decimal digits,
2730 then the final string will match the original 15 decimal digit string.
2731 * If a `double` floating-point number is converted to a decimal string
2732 with at least 17 decimal digits
2733 and then converted back to `double`,
2734 then the result will be binary identical to the original `double` value.
2736 For most purposes, you will much more likely want
2737 `std::numeric_limits<>::max_digits10`,
2738 the number of decimal digits that ensure that a change of one least significant bit (ULP)
2739 produces a different decimal digits string.
2741 For the most common `double` floating-point type,`max_digits10` is `digits10+2`,
2742 but you should use C++11 `max_digits10`
2743 where possible (see [link boost_multiprecision.tut.limits.constants.max_digits10 below]).
2745 [h4:max_digits10 max_digits10]
2747 `std::numeric_limits<T>::max_digits10` was added for floating-point
2748 because `digits10` decimal digits are insufficient to show
2749 a least significant bit (ULP) change giving puzzling displays like
2751 0.666666666666667 != 0.666666666666667
2753 from failure to 'round-trip', for example:
2757 If you wish to ensure that a change of one least significant bit (ULP)
2758 produces a different decimal digits string,
2759 then `max_digits10` is the precision to use.
2765 will display [pi] to the maximum possible precision using a `double`.
2769 For integer types, `max_digits10` is implementation-dependent,
2770 but is usually `digits10 + 2`.
2771 This is the output field-width required for the maximum value of the type T
2772 `std::numeric_limits<T>::max()` ['including a sign and a space].
2774 So this will produce neat columns.
2776 std::cout << std::setw(std::numeric_limits<int>::max_digits10) ...
2778 The extra two or three least-significant digits are 'noisy' and may be junk,
2779 but if you want to 'round-trip' - printing a value out as a decimal digit string and reading it back in -
2780 (most commonly during serialization and de-serialization)
2781 you must use `os.precision(std::numeric_limits<T>::max_digits10)`.
2783 [note For Microsoft Visual Studio 2010,
2784 `std::numeric_limits<float>::max_digits10` is wrongly defined as 8. It should be 9.
2787 [note For Microsoft Visual Studio before 2013 and the default floating-point
2788 format, a small range of double-precision floating-point values with a
2789 significand of approximately 0.0001 to 0.004 and exponent values of 1010 to
2790 1014 do not round-trip exactly being off by one least significant bit,
2791 for probably every third value of the significand.
2793 A workaround is using the scientific or exponential format `std::scientific`.
2795 Other compilers also fail to implement round-tripping entirely fault-free, for example, see
2796 [@https://www.exploringbinary.com/incorrectly-rounded-conversions-in-gcc-and-glibc/ Incorrectly Rounded Conversions in GCC and GLIBC].
2798 For more details see
2799 [@https://www.exploringbinary.com/incorrect-round-trip-conversions-in-visual-c-plus-plus/ Incorrect Round-Trip Conversions in Visual C++],
2800 and references therein
2802 [@https://arxiv.org/pdf/1310.8121.pdf Easy Accurate Reading and Writing of Floating-Point Numbers, Aubrey Jaffer (August 2018)].
2804 Microsoft VS2017 and other recent compilers, now use the
2805 [@https://doi.org/10.1145/3192366.3192369 Ryu fast float-to-string conversion by Ulf Adams]
2806 algorithm, claimed to be both exact and fast for 32 and 64-bit floating-point numbers.
2809 [note BOOST_NO_CXX11_NUMERIC_LIMITS is a suitable feature-test macro to determine if
2810 `std::numeric_limits<float>::max_digits10` is implemented on any platform.
2813 [note ['requires cxx11_numeric_limits] is a suitable test for use of `std::numeric_limits<float>::max_digits10`
2814 to control if a target in a jamfile used by a Boost B2/bjam program is built, or not.
2818 If `max_digits10` is not available, you should use the
2819 [@http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF Kahan formula for floating-point type T].
2821 In C++, the equations for what Kahan (on page 4) describes as 'at least' and 'at most' are:
2823 static long double const log10Two = 0.30102999566398119521373889472449L; // log10(2.)
2825 static_cast<int>(floor((significand_digits - 1) * log10Two)); // == digits10 - 'at least' .
2826 static_cast<int>(ceil(1 + significand_digits * log10Two)); // == max_digits10 - 'at most'.
2828 Unfortunately, these cannot be evaluated (at least by C++03) at [*compile-time].
2829 So the following expression is often used instead.
2831 max_digits10 = 2 + std::numeric_limits<T>::digits * 3010U/10000U;
2833 // == 2 + std::numeric_limits<T>::digits for double and 64-bit long double.
2834 // == 3 + std::numeric_limits<T>::digits for float, 80-bit long-double and __float128.
2836 often the actual values are computed for the C limits macros:
2838 #define FLT_MAXDIG10 (2+FLT_MANT_DIG * 3010U/10000U) // 9
2839 #define DBL_MAXDIG10 (2+ (DBL_MANT_DIG * 3010U)/10000U) // 17
2840 #define LDBL_MAXDIG10 (2+ (LDBL_MANT_DIG * 3010U)/10000U) // 17 for MSVC, 18 for others.
2842 The factor 3010U/10000U is ['log[sub 10](2) = 0.3010]
2843 that can be evaluated at compile-time using only `short unsigned int`s to be a desirable `const` or `constexpr` (and usually also `static`).
2845 Boost macros allow this to be done portably, see
2846 [@http://www.boost.org/doc/libs/1_58_0/libs/config/doc/html/boost_config/boost_macro_reference.html BOOST_CONSTEXPR_OR_CONST or BOOST_STATIC_CONSTEXPR].
2849 [@http://www.loria.fr/~zimmerma/mca/mca-cup-0.5.9.pdf Richard P. Brent and Paul Zimmerman, Modern Computer Arithmetic]
2850 Equation 3.8 on page 116).
2852 [max_digits10_1] [/ example for using max_digits10]
2856 The rounding style determines how the result of floating-point operations
2857 is treated when the result cannot be [*exactly represented] in the significand.
2858 Various rounding modes may be provided:
2860 * round to nearest up or down (default for floating-point types).
2861 * round up (toward positive infinity).
2862 * round down (toward negative infinity).
2863 * round toward zero (integer types).
2864 * no rounding (if decimal radix).
2865 * rounding mode is not determinable.
2867 For integer types, `std::numeric_limits<T>::round_style` is always towards zero, so
2869 std::numeric_limits<T>::round_style == std::round_to_zero;
2871 A decimal type, `cpp_dec_float` rounds in no particular direction,
2872 which is to say it doesn't round at all.
2873 And since there are several guard digits,
2874 it's not really the same as truncation (round toward zero) either.
2876 For floating-point types, it is normal to round to nearest.
2878 std::numeric_limits<T>::round_style == std::round_to_nearest;
2880 See function `std::numeric_limits<T>::round_error` for the maximum error (in ULP)
2881 that rounding can cause.
2883 [h4 has_denorm_loss]
2885 `true` if a loss of precision is detected as a
2886 [@http://en.wikipedia.org/wiki/Denormalization denormalization] loss,
2887 rather than an inexact result.
2889 Always `false` for integer types.
2891 `false` for all types which do not have `has_denorm` == `std::denorm_present`.
2895 [@http://en.wikipedia.org/wiki/Denormal_number Denormalized values] are
2896 representations with a variable number of exponent bits that can permit
2897 gradual underflow, so that, if type T is `double`.
2899 std::numeric_limits<T>::denorm_min() < std::numeric_limits<T>::min()
2901 A type may have any of the following `enum float_denorm_style` values:
2903 * `std::denorm_absent`, if it does not allow denormalized values.
2904 (Always used for all integer and exact types).
2905 * `std::denorm_present`, if the floating-point type allows denormalized values.
2906 *`std::denorm_indeterminate`, if indeterminate at compile time.
2908 [h4 Tinyness before rounding]
2910 `bool std::numeric_limits<T>::tinyness_before`
2912 `true` if a type can determine that a value is too small
2913 to be represent as a normalized value before rounding it.
2915 Generally true for `is_iec559` floating-point built-in types,
2916 but false for integer types.
2918 Standard-compliant IEEE 754 floating-point implementations may detect the floating-point underflow at three predefined moments:
2920 # After computation of a result with absolute value smaller than
2921 `std::numeric_limits<T>::min()`,
2922 such implementation detects ['tinyness before rounding] (e.g. UltraSparc).
2924 # After rounding of the result to `std::numeric_limits<T>::digits` bits,
2925 if the result is tiny, such implementation detects ['tinyness after rounding]
2928 # If the conversion of the rounded tiny result to subnormal form
2929 resulted in the loss of precision, such implementation detects ['denorm loss].
2931 [endsect] [/section:constants std::numeric_limits<> Constants]
2933 [section:functions `std::numeric_limits<>` functions]
2935 [h4:max_function `max` function]
2937 Function `(std::numeric_limits<T>::max)()` returns the largest finite value
2938 that can be represented by the type T. If there is no such value (and
2939 `numeric_limits<T>::bounded` is `false`) then returns `T()`.
2941 For built-in types there is usually a corresponding MACRO value TYPE_MAX,
2942 where TYPE is CHAR, INT, FLOAT etc.
2944 Other types, including those provided by a typedef,
2945 for example `INT64_T_MAX` for `int64_t`, may provide a macro definition.
2947 To cater for situations where no `numeric_limits` specialization is available
2948 (for example because the precision of the type varies at runtime),
2949 packaged versions of this (and other functions) are provided using
2951 #include <boost/math/tools/precision.hpp>
2953 T = boost::math::tools::max_value<T>();
2955 Of course, these simply use `(std::numeric_limits<T>::max)()` if available,
2956 but otherwise 'do something sensible'.
2958 [h4 lowest function]
2960 Since C++11: `std::numeric_limits<T>::lowest()` is
2962 * For integral types, the same as function `min()`.
2963 * For floating-point types, generally the negative of `max()`
2964 (but implementation-dependent).
2968 [h4:min_function `min` function]
2970 Function `(std::numeric_limits<T>::min)()` returns the minimum finite value
2971 that can be represented by the type T.
2973 For built-in types, there is usually a corresponding MACRO value TYPE_MIN,
2974 where TYPE is CHAR, INT, FLOAT etc.
2976 Other types, including those provided by a `typedef`,
2977 for example, `INT64_T_MIN` for `int64_t`, may provide a macro definition.
2979 For floating-point types,
2980 it is more fully defined as the ['minimum positive normalized value].
2982 See `std::numeric_limits<T>::denorm_min()` for the smallest denormalized value, provided
2984 std::numeric_limits<T>::has_denorm == std::denorm_present
2986 To cater for situations where no `numeric_limits` specialization is available
2987 (for example because the precision of the type varies at runtime),
2988 packaged versions of this (and other functions) are provided using
2990 #include <boost/math/tools/precision.hpp>
2992 T = boost::math::tools::min_value<T>();
2994 Of course, these simply use `std::numeric_limits<T>::min()` if available.
2996 [h4 denorm_min function]
2998 Function `std::numeric_limits<T>::denorm_min()`
2999 returns the smallest
3000 [@http://en.wikipedia.org/wiki/Denormal_number denormalized value],
3003 std::numeric_limits<T>::has_denorm == std::denorm_present
3007 The exponent is effectively reduced from -308 to -324
3008 (though it remains encoded as zero and leading zeros appear in the significand,
3009 thereby losing precision until the significand reaches zero).
3013 Function `std::numeric_limits<T>::round_error()` returns the maximum error
3014 (in units of [@http://en.wikipedia.org/wiki/Unit_in_the_last_place ULP])
3015 that can be caused by any basic arithmetic operation.
3017 round_style == std::round_indeterminate;
3019 The rounding style is indeterminable at compile time.
3021 For floating-point types, when rounding is to nearest,
3022 only half a bit is lost by rounding, and `round_error == 0.5`.
3023 In contrast when rounding is towards zero, or plus/minus infinity,
3024 we can loose up to one bit from rounding, and `round_error == 1`.
3026 For integer types, rounding always to zero, so at worst almost one bit can be rounded,
3027 so `round_error == 1`.
3029 `round_error()` can be used with `std::numeric_limits<T>::epsilon()` to estimate
3030 the maximum potential error caused by rounding. For typical floating-point types,
3031 `round_error() = 1/2`, so half epsilon is the maximum potential error.
3035 There are, of course, many occasions when much bigger loss of precision occurs,
3036 for example, caused by
3037 [@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error]
3038 or very many iterations.
3040 [h4:epsilon epsilon]
3042 Function `std::numeric_limits<T>::epsilon()` is meaningful only for non-integral types.
3044 It returns the difference between `1.0` and the next value representable
3045 by the floating-point type T.
3046 So it is a one least-significant-bit change in this floating-point value.
3048 For `double` (`float_64t`) it is `2.2204460492503131e-016`
3049 showing all possibly significant 17 decimal digits.
3053 We can explicitly increment by one bit using the function `boost::math::float_next()`
3054 and the result is the same as adding `epsilon`.
3058 Adding any smaller value, like half `epsilon`, will have no effect on this value.
3062 So this cancellation error leaves the values equal, despite adding half `epsilon`.
3064 To achieve greater portability over platform and floating-point type,
3065 Boost.Math and Boost.Multiprecision provide a package of functions that
3066 'do something sensible' if the standard `numeric_limits` is not available.
3067 To use these `#include <boost/math/tools/precision.hpp>`.
3071 [h5:FP_tolerance Tolerance for Floating-point Comparisons]
3073 [@https://en.wikipedia.org/wiki/Machine_epsilon Machine epsilon [epsilon]]
3074 is very useful to compute a tolerance when comparing floating-point values,
3075 a much more difficult task than is commonly imagined.
3077 The C++ standard specifies [@https://en.cppreference.com/w/cpp/types/numeric_limits/epsilon `std::numeric_limits<>::epsilon()`]
3078 and Boost.Multiprecision implements this (where possible) for its program-defined types analogous to the
3079 __fundamental floating-point types like `double` `float`.
3081 For more information than you probably want (but still need) see
3082 [@http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic]
3084 The naive test comparing the absolute difference between two values and a tolerance
3085 does not give useful results if the values are too large or too small.
3087 So Boost.Test uses an algorithm first devised by Knuth
3088 for reliably checking if floating-point values are close enough.
3090 See Donald. E. Knuth. The art of computer programming (vol II).
3091 Copyright 1998 Addison-Wesley Longman, Inc., 0-201-89684-2.
3092 Addison-Wesley Professional; 3rd edition. (The relevant equations are in paragraph 4.2.2, Eq. 36 and 37.)
3094 See [@https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/testing_tools/extended_comparison/floating_point/floating_points_comparison_theory.html Boost.Math floating_point comparison]
3099 [@http://adtmag.com/articles/2000/03/15/comparing-floats-how-to-determine-if-floating-quantities-are-close-enough-once-a-tolerance-has-been.aspx Alberto Squassia, Comparing floats]
3101 [@http://adtmag.com/articles/2000/03/16/comparing-floats-how-to-determine-if-floating-quantities-are-close-enough-once-a-tolerance-has-been.aspx Alberto Squassia, Comparing floats code]
3103 [@https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/testing_tools/extended_comparison/floating_point.html Boost.Test Floating-Point_Comparison]
3110 BOOST_CHECK_CLOSE_FRACTION(expected, calculated, tolerance);
3112 (There is also a version BOOST_CHECK_CLOSE using tolerance as a [*percentage] rather than a fraction;
3113 usually the fraction version is simpler to use).
3117 [h4:infinity Infinity - positive and negative]
3119 For floating-point types only, for which
3120 `std::numeric_limits<T>::has_infinity == true`,
3121 function `std::numeric_limits<T>::infinity()`
3122 provides an implementation-defined representation for [infin].
3124 The 'representation' is a particular bit pattern reserved for infinity.
3125 For IEEE754 system (for which `std::numeric_limits<T>::is_iec559 == true`)
3126 [@http://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity positive and negative infinity]
3127 are assigned bit patterns for all defined floating-point types.
3129 Confusingly, the string resulting from outputting this representation, is also
3130 implementation-defined. And the string that can be input to generate the representation is also implementation-defined.
3132 For example, the output is `1.#INF` on Microsoft systems, but `inf` on most *nix platforms.
3134 This implementation-defined-ness has hampered use of infinity (and NaNs)
3135 but Boost.Math and Boost.Multiprecision work hard to provide a sensible representation
3136 for [*all] floating-point types, not just the built-in types,
3137 which with the use of suitable facets to define the input and output strings, makes it possible
3138 to use these useful features portably and including Boost.Serialization.
3140 [h4 Not-A-Number NaN]
3144 For floating-point types only, for which
3145 `std::numeric_limits<T>::has_quiet_NaN == true`,
3146 function `std::numeric_limits<T>::quiet_NaN()`
3147 provides an implementation-defined representation for NaN.
3149 [@http://en.wikipedia.org/wiki/NaN NaNs] are values to indicate that the
3150 result of an assignment or computation is meaningless.
3151 A typical example is `0/0` but there are many others.
3153 NaNs may also be used, to represent missing values: for example,
3154 these could, by convention, be ignored in calculations of statistics like means.
3156 Many of the problems with a representation for
3157 [@http://en.wikipedia.org/wiki/NaN Not-A-Number] has hampered portable use,
3158 similar to those with infinity.
3162 But using Boost.Math and suitable facets can permit portable use
3163 of both NaNs and positive and negative infinity.
3169 For floating-point types only, for which
3170 `std::numeric_limits<T>::has_signaling_NaN == true`,
3171 function `std::numeric_limits<T>::signaling_NaN()`
3172 provides an implementation-defined representation for NaN that causes a hardware trap.
3173 It should be noted however, that at least one implementation of this function causes a hardware
3174 trap to be triggered simply by calling `std::numeric_limits<T>::signaling_NaN()`, and not only
3175 by using the value returned.
3177 [endsect] [/section:functions std::numeric_limits<> functions]
3179 [/ Tables of values for numeric_limits for various built-in and cpp_bin_float types]
3180 [include numeric_limits_32_tables.qbk]
3181 [/include numeric_limits_64_tables.qbk]
3183 [section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`]
3185 Based on the information above, one can see that different kinds of numbers can be
3186 differentiated based on the information stored in `std::numeric_limits`. This is
3187 in addition to the traits class [link boost_multiprecision.ref.number.traits_class_support
3188 number_category] provided by this library.
3192 For an integer type T, all of the following conditions hold:
3194 std::numeric_limits<T>::is_specialized == true
3195 std::numeric_limits<T>::is_integer == true
3196 std::numeric_limits<T>::is_exact == true
3197 std::numeric_limits<T>::min_exponent == 0
3198 std::numeric_limits<T>::max_exponent == 0
3199 std::numeric_limits<T>::min_exponent10 == 0
3200 std::numeric_limits<T>::max_exponent10 == 0
3202 In addition the type is /signed/ if:
3204 std::numeric_limits<T>::is_signed == true
3206 If the type is arbitrary precision then:
3208 std::numeric_limits<T>::is_bounded == false
3210 Otherwise the type is bounded, and returns a non zero value
3213 std::numeric_limits<T>::max()
3217 std::numeric_limits<T>::is_modulo == true
3219 if the type implements modulo arithmetic on overflow.
3223 Rational types are just like integers except that:
3225 std::numeric_limits<T>::is_integer == false
3227 [h4 Fixed Precision Types]
3229 There appears to be no way to tell these apart from rational types, unless they set:
3231 std::numeric_limits<T>::is_exact == false
3233 This is because these types are in essence a rational type with a fixed denominator.
3235 [h4 floating-point Types]
3237 For a floating-point type T, all of the following conditions hold:
3239 std::numeric_limits<T>::is_specialized == true
3240 std::numeric_limits<T>::is_integer == false
3241 std::numeric_limits<T>::is_exact == false
3242 std::numeric_limits<T>::min_exponent != 0
3243 std::numeric_limits<T>::max_exponent != 0
3244 std::numeric_limits<T>::min_exponent10 != 0
3245 std::numeric_limits<T>::max_exponent10 != 0
3247 In addition the type is /signed/ if:
3249 std::numeric_limits<T>::is_signed == true
3251 And the type may be decimal or binary depending on the value of:
3253 std::numeric_limits<T>::radix
3255 In general, there are no arbitrary precision floating-point types, and so:
3257 std::numeric_limits<T>::is_bounded == false
3259 [h4 Exact floating-point Types]
3261 Exact floating-point types are a [@http://en.wikipedia.org/wiki/Field_%28mathematics%29 field]
3262 composed of an arbitrary precision integer scaled by an exponent. Such types
3263 have no division operator and are the same as floating-point types except:
3265 std::numeric_limits<T>::is_exact == true
3267 [h4 Complex Numbers]
3269 For historical reasons, complex numbers do not specialize `std::numeric_limits`, instead you must
3270 inspect `std::numeric_limits<typename T::value_type>`.
3272 [endsect] [/section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`]
3274 [endsect] [/section:limits Numeric Limits]
3277 [section:input_output Input Output]
3279 [h4 Loopback testing]
3281 ['Loopback] or ['round-tripping] refers to writing out a value as a decimal digit string using `std::iostream`,
3282 usually to a `std::stringstream`, and then reading the string back in to another value,
3283 and confirming that the two values are identical. A trivial example using `float` is:
3285 float write; // Value to round-trip.
3286 std::stringstream ss; // Read and write std::stringstream.
3287 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output.
3288 ss.flags(std::ios_base::fmtflags(std::ios_base::scientific)); // Use scientific format.
3289 ss << write; // Output to string.
3290 float read; // Expected.
3291 ss >> read; // Read decimal digits string from stringstream.
3292 BOOST_CHECK_EQUAL(write, read); // Should be the same.
3294 and this can be run in a loop for all possible values of a 32-bit float.
3295 For other floating-point types `T`, including built-in `double`,
3296 it takes far too long to test all values,
3297 so a reasonable test strategy is to use a large number of random values.
3300 std::stringstream ss;
3301 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output.
3302 ss.flags(f); // Changed from default iostream format flags if desired.
3303 ss << write; // Output to stringstream.
3306 ss >> read; // Get read using operator>> from stringstream.
3307 BOOST_CHECK_EQUAL(read, write);
3309 read = static_cast<T>(ss.str()); // Get read by converting from decimal digits string representation of write.
3310 BOOST_CHECK_EQUAL(read, write);
3312 read = static_cast<T>(write.str(0, f)); // Get read using format specified when written.
3313 BOOST_CHECK_EQUAL(read, write);
3317 [@../../test/test_cpp_bin_float_io.cpp test_cpp_bin_float_io.cpp]
3318 allows any floating-point type to be ['round_tripped] using a wide range of fairly random values.
3319 It also includes tests compared a collection of
3320 [@../../test/string_data.ipp stringdata] test cases in a file.
3322 [h4 Comparing with output using Built-in types]
3324 One can make some comparisons with the output of
3326 <number<cpp_bin_float<53, digit_count_2> >
3328 which has the same number of significant bits (53) as 64-bit double precision floating-point.
3330 However, although most outputs are identical, there are differences on some platforms
3331 caused by the implementation-dependent behaviours allowed by the C99 specification
3332 [@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 ISO/IEC 9899:TC2],
3333 incorporated by C++.
3335 [:['"For e, E, f, F, g, and G conversions, if the number of significant decimal digits
3336 is at most DECIMAL_DIG, then the result should be correctly rounded.
3337 If the number of significant decimal digits is more than DECIMAL_DIG
3338 but the source value is exactly representable with DECIMAL_DIG digits,
3339 then the result should be an exact representation with trailing zeros.
3340 Otherwise, the source value is bounded by two adjacent decimal strings L < U,
3341 both having DECIMAL_DIG significant digits;
3342 the value of the resultant decimal string D should satisfy L<= D <= U,
3343 with the extra stipulation that the error should have a correct sign
3344 for the current rounding direction."]]
3346 So not only is correct rounding for the full number of digits not required,
3347 but even if the *optional* recommended practice is followed,
3348 then the value of these last few digits is unspecified
3349 as long as the value is within certain bounds.
3351 [note Do not expect the output from different platforms
3352 to be [*identical], but `cpp_dec_float`, `cpp_bin_float` (and other backends) outputs should be
3353 correctly rounded to the number of digits requested by the set precision and format.]
3356 [h4 Macro BOOST_MP_MIN_EXPONENT_DIGITS]
3358 [@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 Standard]
3359 for [/e and E] format specifiers, 7.19.6 Formatted input/output functions requires:
3361 \"The exponent always contains at least two digits,
3362 and only as many more digits as necessary to represent the exponent.\"
3364 So to conform to the C99 standard (incorporated by C++)
3366 #define BOOST_MP_MIN_EXPONENT_DIGITS 2
3368 Confusingly, Microsoft (and MinGW) do not conform to this standard and provide
3369 [*at least three digits], for example `1e+001`.
3370 So if you want the output to match that from
3371 built-in floating-point types on compilers that use Microsofts runtime then use:
3373 #define BOOST_MP_MIN_EXPONENT_DIGITS 3
3375 Also useful to get the minimum exponent field width is
3377 #define BOOST_MP_MIN_EXPONENT_DIGITS 1
3379 producing a compact output like `2e+4`,
3380 useful when conserving space is important.
3382 Larger values are also supported, for example, value 4 for `2e+0004`
3383 which may be useful to ensure that columns line up.
3385 [endsect] [/section:input_output Input Output]
3387 [section:hash Hash Function Support]
3399 [section:eigen Eigen Interoperability]
3401 This library provides the header:
3403 #include <boost/multiprecision/eigen.hpp>
3405 which defines the traits classes and functions that the Eigen library needs all user-defined number types to provide.
3407 For example the following code performs quad-precision matrix solving on complex numbers:
3411 Which produces the following output:
3418 [section:ref Reference]
3420 [section:number number]
3424 namespace boost{ namespace multiprecision{
3426 enum expression_template_option { et_on = 1, et_off = 0 };
3428 template <class Backend> struct expression_template_default
3429 { static const expression_template_option value = et_on; };
3431 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value>
3435 typedef Backend backend_type;
3436 typedef typename component_type<self_type>::type value_type;
3440 number& operator=(see-below);
3441 number& assign(see-below);
3444 number& operator+=(const ``['see-below]``&);
3445 number& operator-=(const ``['see-below]``&);
3446 number& operator*=(const ``['see-below]``&);
3447 number& operator/=(const ``['see-below]``&);
3448 number& operator++();
3449 number& operator--();
3450 number operator++(int);
3451 number operator--(int);
3453 number& operator%=(const ``['see-below]``&);
3454 number& operator&=(const ``['see-below]``&);
3455 number& operator|=(const ``['see-below]``&);
3456 number& operator^=(const ``['see-below]``&);
3457 number& operator<<=(const ``['integer-type]``&);
3458 number& operator>>=(const ``['integer-type]``&);
3460 // Use in Boolean context:
3461 operator ``['convertible-to-bool-type]``()const;
3463 void swap(number& other);
3465 bool is_zero()const;
3467 // string conversion:
3468 std::string str()const;
3469 // Generic conversion mechanism
3471 T convert_to()const;
3473 explicit operator T ()const;
3474 // precision control:
3475 static unsigned default_precision();
3476 static void default_precision(unsigned digits10);
3477 unsigned precision()const;
3478 void precision(unsigned digits10);
3480 int compare(const number<Backend>& o)const;
3482 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type
3483 compare(const V& o)const;
3484 // real and imaginary parts:
3485 value_type real()const;
3486 value_type imag()const;
3488 void real(const T& val);
3490 void imag(const T& val);
3491 // Access to the underlying implementation:
3493 const Backend& backend()const;
3496 // Non member operators:
3497 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&);
3498 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&);
3499 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&);
3500 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&);
3501 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&);
3502 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&);
3503 // Integer only operations:
3504 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&);
3505 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&);
3506 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&);
3507 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&);
3508 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&);
3509 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&);
3510 // Comparison operators:
3511 bool operator==(const ``['see-below]``&, const ``['see-below]``&);
3512 bool operator!=(const ``['see-below]``&, const ``['see-below]``&);
3513 bool operator< (const ``['see-below]``&, const ``['see-below]``&);
3514 bool operator> (const ``['see-below]``&, const ``['see-below]``&);
3515 bool operator<=(const ``['see-below]``&, const ``['see-below]``&);
3516 bool operator>=(const ``['see-below]``&, const ``['see-below]``&);
3519 template <class Backend, expression_template_option ExpressionTemplates>
3520 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b);
3522 // iostream support:
3523 template <class Backend, expression_template_option ExpressionTemplates>
3524 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r);
3525 std::ostream& operator << (std::ostream& os, const ``['unmentionable-expression-template-type]``& r);
3526 template <class Backend, expression_template_option ExpressionTemplates>
3527 std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r);
3529 // Arithmetic with a higher precision result:
3530 template <class ResultType, class Source1 class Source2>
3531 ResultType& add(ResultType& result, const Source1& a, const Source2& b);
3532 template <class ResultType, class Source1 class Source2>
3533 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b);
3534 template <class ResultType, class Source1 class Source2>
3535 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b);
3537 // min and max overloads:
3538 ``['number]`` min (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3539 ``['number]`` max (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3541 // C99 Non-member function standard library support:
3542 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&);
3543 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&);
3544 ``['number]`` acosh (const ``['number-or-expression-template-type]``&);
3545 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&);
3546 ``['number]`` asinh (const ``['number-or-expression-template-type]``&);
3547 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&);
3548 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3549 ``['number]`` atanh (const ``['number-or-expression-template-type]``&);
3550 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&);
3551 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&);
3552 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3553 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&);
3554 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&);
3555 ``['number]`` erf (const ``['number-or-expression-template-type]``&);
3556 ``['number]`` erfc (const ``['number-or-expression-template-type]``&);
3557 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&);
3558 ``['unmentionable-expression-template-type]`` exp2 (const ``['number-or-expression-template-type]``&);
3559 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&);
3560 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&);
3561 ``['unmentionable-expression-template-type]`` fdim (const ``['number-or-expression-template-type]``&);
3562 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&);
3563 ``['unmentionable-expression-template-type]`` fma (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3564 ``['unmentionable-expression-template-type]`` fmin (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3565 ``['unmentionable-expression-template-type]`` fmax (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3566 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3567 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*);
3568 ``['unmentionable-expression-template-type]`` hypot (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3569 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&);
3570 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
3571 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&);
3572 long long llrint (const ``['number-or-expression-template-type]``&);
3573 long long llround (const ``['number-or-expression-template-type]``&);
3574 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&);
3575 ``['unmentionable-expression-template-type]`` log2 (const ``['number-or-expression-template-type]``&);
3576 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&);
3577 ``['number]`` log1p (const ``['number-or-expression-template-type]``&);
3578 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&);
3579 long lrint (const ``['number-or-expression-template-type]``&);
3580 long lround (const ``['number-or-expression-template-type]``&);
3581 ``['unmentionable-expression-template-type]`` modf (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3582 ``['unmentionable-expression-template-type]`` nearbyint (const ``['number-or-expression-template-type]``&);
3583 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3584 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3585 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3586 ``['unmentionable-expression-template-type]`` remainder (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3587 ``['unmentionable-expression-template-type]`` remquo (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, int*);
3588 ``['unmentionable-expression-template-type]`` rint (const ``['number-or-expression-template-type]``&);
3589 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&);
3590 ``['unmentionable-expression-template-type]`` scalbn (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
3591 ``['unmentionable-expression-template-type]`` scalbln (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
3592 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&);
3593 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&);
3594 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&);
3595 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&);
3596 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&);
3597 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&);
3598 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&);
3600 int fpclassify (const ``['number-or-expression-template-type]``&);
3601 bool isfinite (const ``['number-or-expression-template-type]``&);
3602 bool isinf (const ``['number-or-expression-template-type]``&);
3603 bool isnan (const ``['number-or-expression-template-type]``&);
3604 bool isnormal (const ``['number-or-expression-template-type]``&);
3605 int signbit (const ``['number-or-expression-template-type]``&);
3607 bool isgreater (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3608 bool isgreaterequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3609 bool isless (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3610 bool islessequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3611 bool islessgreater(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3612 bool isunordered(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3613 // Complex number functions:
3614 ``['number<...>::value_type]`` real (const ``['number-or-expression-template-type]``&);
3615 ``['number<...>::value_type]`` imag (const ``['number-or-expression-template-type]``&);
3616 ``['number<...>::value_type]`` abs (const ``['number-or-expression-template-type]``&);
3617 ``['number<...>::value_type]`` arg (const ``['number-or-expression-template-type]``&);
3618 ``['number<...>::value_type]`` norm (const ``['number-or-expression-template-type]``&);
3619 ``['number]`` conj (const ``['number-or-expression-template-type]``&);
3620 ``['number]`` proj (const ``['number-or-expression-template-type]``&);
3621 ``['number]`` polar (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3622 // Misc other common C library functions:
3623 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&);
3624 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&);
3625 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&);
3626 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&);
3627 ``['number]`` changesign(const ``['number-or-expression-template-type]``&);
3628 ``['number]`` copysign(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3632 struct component_type;
3634 struct number_category;
3638 struct is_number_expression;
3640 // Integer specific functions:
3641 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3642 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3643 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``&, unsigned);
3644 ``['unmentionable-expression-template-type]`` powm(const ``['number-or-expression-template-type]``& b, const ``['number-or-expression-template-type]``& p, const ``['number-or-expression-template-type]``& m);
3645 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``&);
3646 template <class Backend, expression_template_option ExpressionTemplates>
3647 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``&, number<Backend, EXpressionTemplates>&);
3648 template <class Backend, expression_template_option ExpressionTemplates>
3649 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y,
3650 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r);
3651 template <class Integer>
3652 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val);
3653 unsigned lsb(const ``['number-or-expression-template-type]``& x);
3654 unsigned msb(const ``['number-or-expression-template-type]``& x);
3655 template <class Backend, class ExpressionTemplates>
3656 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index);
3657 template <class Backend, class ExpressionTemplates>
3658 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index);
3659 template <class Backend, class ExpressionTemplates>
3660 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index);
3661 template <class Backend, class ExpressionTemplates>
3662 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index);
3663 template <class Engine>
3664 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen);
3665 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials);
3667 // Rational number support:
3668 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&);
3669 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&);
3673 namespace boost{ namespace math{
3675 // Boost.Math interoperability functions:
3676 int fpclassify (const ``['number-or-expression-template-type]``&, int);
3677 bool isfinite (const ``['number-or-expression-template-type]``&, int);
3678 bool isnan (const ``['number-or-expression-template-type]``&, int);
3679 bool isinf (const ``['number-or-expression-template-type]``&, int);
3680 bool isnormal (const ``['number-or-expression-template-type]``&, int);
3684 // numeric_limits support:
3687 template <class Backend, expression_template_option ExpressionTemplates>
3688 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> >
3690 /* Usual members here */
3697 enum expression_template_option { et_on = 1, et_off = 0 };
3699 This enumerated type is used to specify whether expression templates are turned on (et_on) or turned off (et_off).
3701 template <class Backend> struct expression_template_default
3702 { static const expression_template_option value = et_on; };
3704 This traits class specifies the default expression template option to be used with a particular Backend type.
3705 It defaults to `et_on`.
3707 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value>
3710 Class `number` has two template arguments:
3713 [[Backend][The actual arithmetic back-end that does all the work.]]
3714 [[ExpressionTemplates][A Boolean value: when `et_on`, then expression templates are enabled, otherwise when set to `et_off` they are disabled.
3715 The default for this parameter is computed via the traits class `expression_template_default` whose member `value` defaults to `et_on` unless
3716 the traits class is specialized for a particular backend.]]
3721 number& operator=(see-below);
3722 number& assign(see-below);
3724 Type `number` is default constructible, and both copy constructible and assignable from:
3727 * An expression template which is the result of one of the arithmetic operators.
3728 * Any builtin arithmetic type, as long as the result would not be lossy (for example float to integer conversion).
3729 * Any type that the Backend is implicitly constructible or assignable from.
3730 * An rvalue reference to another `number`. Move-semantics are used for construction if the backend also
3731 supports rvalue reference construction. In the case of assignment, move semantics are always supported
3732 when the argument is an rvalue reference irrespective of the backend.
3733 * Any type in the same family, as long as no loss of precision is involved. For example from `int128_t` to `int256_t`,
3734 or `cpp_dec_float_50` to `cpp_dec_float_100`.
3736 Type `number` is explicitly constructible from:
3738 * Any type mentioned above.
3739 * A `std::string` or any type which is convertible to `const char*`.
3740 * Any arithmetic type (including those that would result in lossy conversions).
3741 * Any type in the same family, including those that result in loss of precision.
3742 * Any type that the Backend is explicitly constructible from.
3743 * Any pair of types for which a generic interconversion exists: that is from integer to integer, integer
3744 to rational, integer to float, rational to rational, rational to float, or float to float.
3746 The assign member function is available for any type for which an explicit converting constructor exists.
3747 It is intended to be used where a temporary generated from an explicit assignment would be expensive, for example:
3750 mpfr_float_100 f100;
3752 f50 = static_cast<mpfr_float_50>(f100); // explicit cast create a temporary
3753 f50.assign(f100); // explicit call to assign create no temporary
3755 In addition, if the type has multiple components (for example rational or complex number types), then there is a
3756 two argument constructor:
3760 Where the two args must either be arithmetic types, or types that are convertible to the two components of `this`.
3762 Finally, when the type has a variable precision, then there are constructors:
3764 number(arg1, precision);
3765 number(arg1, arg2, precision);
3767 Where `precision` is an unsigned value, the 2 arg version is active for scalar types and/or copy-construction with specific precision, and the 3-arg version for complex types.
3769 Likewise `assign` has a 2-arg overloaded, with the second argument being the precision.
3771 number& operator+=(const ``['see-below]``&);
3772 number& operator-=(const ``['see-below]``&);
3773 number& operator*=(const ``['see-below]``&);
3774 number& operator/=(const ``['see-below]``&);
3775 number& operator++();
3776 number& operator--();
3777 number operator++(int);
3778 number operator--(int);
3779 // Integer only operations:
3780 number& operator%=(const ``['see-below]``&);
3781 number& operator&=(const ``['see-below]``&);
3782 number& operator|=(const ``['see-below]``&);
3783 number& operator^=(const ``['see-below]``&);
3784 number& operator<<=(const ``['integer-type]``&);
3785 number& operator>>=(const ``['integer-type]``&);
3787 These operators all take their usual arithmetic meanings.
3789 The arguments to these operators is either:
3791 * Another `number<Backend, ExpressionTemplates>`.
3792 * An expression template derived from `number<Backend>`.
3793 * Any type implicitly convertible to `number<Backend, ExpressionTemplates>`, including some other instance of class `number`.
3795 For the left and right shift operations, the argument must be a builtin
3796 integer type with a positive value (negative values result in a `std::runtime_error` being thrown).
3798 operator ``['convertible-to-bool-type]``()const;
3800 Returns an ['unmentionable-type] that is usable in Boolean contexts (this allows `number` to be used in any
3801 Boolean context - if statements, conditional statements, or as an argument to a logical operator - without
3802 type `number` being convertible to type `bool`.
3804 This operator also enables the use of `number` with any of the following operators:
3805 `!`, `||`, `&&` and `?:`.
3807 void swap(number& other);
3809 Swaps `*this` with `other`.
3811 bool is_zero()const;
3813 Returns `true` is `*this` is zero, otherwise `false`.
3817 Returns a value less than zero if `*this` is negative, a value greater than zero if `*this` is positive, and zero
3820 std::string str(unsigned precision, bool scientific = true)const;
3822 Returns the number formatted as a string, with at least /precision/ digits, and in scientific format
3823 if /scientific/ is true.
3826 T convert_to()const;
3829 explicit operator T ()const;
3831 Provides a generic conversion mechanism to convert `*this` to type `T`. Type `T` may be any arithmetic type.
3832 Optionally other types may also be supported by specific `Backend` types.
3835 static unsigned default_precision();
3836 static void default_precision(unsigned digits10);
3837 unsigned precision()const;
3838 void precision(unsigned digits10);
3840 These functions are only available if the Backend template parameter supports runtime changes to precision. They get and set
3841 the default precision and the precision of `*this` respectively.
3843 int compare(const number<Backend, ExpressionTemplates>& o)const;
3845 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type
3846 compare(const V& other)const;
3850 * A value less that 0 for `*this < other`
3851 * A value greater that 0 for `*this > other`
3852 * Zero for `*this == other`
3854 value_type real()const;
3855 value_type imag()const;
3857 These return the real and imaginary parts respectively. If the number is not a complex type, then the imaginary part is always zero.
3860 void real(const T& val);
3862 void imag(const T& val);
3864 These set the real and imaginary parts respectively of the number. If the number is not a complex type, then setting the real part
3865 is equivalent to assignment, and attempting to set the imaginary part will result in a compile time error.
3868 const Backend& backend()const;
3870 Returns the underlying back-end instance used by `*this`.
3872 [h4 Non-member operators]
3874 // Non member operators:
3875 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&);
3876 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&);
3877 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&);
3878 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&);
3879 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&);
3880 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&);
3881 // Integer only operations:
3882 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&);
3883 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&);
3884 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&);
3885 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&);
3886 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&);
3887 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&);
3888 // Comparison operators:
3889 bool operator==(const ``['see-below]``&, const ``['see-below]``&);
3890 bool operator!=(const ``['see-below]``&, const ``['see-below]``&);
3891 bool operator< (const ``['see-below]``&, const ``['see-below]``&);
3892 bool operator> (const ``['see-below]``&, const ``['see-below]``&);
3893 bool operator<=(const ``['see-below]``&, const ``['see-below]``&);
3894 bool operator>=(const ``['see-below]``&, const ``['see-below]``&);
3896 These operators all take their usual arithmetic meanings.
3898 The arguments to these functions must contain at least one of the following:
3901 * An expression template type derived from `number`.
3902 * Any type for which `number` has an implicit constructor - for example a builtin arithmetic type.
3904 The return type of these operators is either:
3906 * An ['unmentionable-type] expression template type when `ExpressionTemplates` is `true`.
3907 * Type `number<Backend, et_off>` when `ExpressionTemplates` is `false`.
3908 * Type `bool` if the operator is a comparison operator.
3910 Finally note that the second argument to the left and right shift operations must be a builtin integer type,
3911 and that the argument must be positive (negative arguments result in a `std::runtime_error` being thrown).
3915 template <class Backend, ExpressionTemplates>
3916 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b);
3920 [h4 Iostream Support]
3922 template <class Backend, expression_template_option ExpressionTemplates>
3923 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r);
3924 template <class Unspecified...>
3925 std::ostream& operator << (std::ostream& os, const unmentionable-expression-template& r);
3926 template <class Backend, expression_template_option ExpressionTemplates>
3927 inline std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r)
3929 These operators provided formatted input-output operations on `number` types, and expression templates derived from them.
3931 It's down to the back-end type to actually implement string conversion. However, the back-ends provided with
3932 this library support all of the iostream formatting flags, field width and precision settings.
3934 [h4 Arithmetic with a higher precision result]
3936 template <class ResultType, class Source1 class Source2>
3937 ResultType& add(ResultType& result, const Source1& a, const Source2& b);
3939 template <class ResultType, class Source1 class Source2>
3940 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b);
3942 template <class ResultType, class Source1 class Source2>
3943 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b);
3945 These functions apply the named operator to the arguments ['a] and ['b] and store the
3946 result in ['result], returning ['result]. In all cases they behave "as if"
3947 arguments ['a] and ['b] were first promoted to type `ResultType` before applying the
3948 operator, though particular backends may well avoid that step by way of an optimization.
3950 The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2`
3951 may be either instances of class `number` or native integer types. The latter is an optimization
3952 that allows arithmetic to be performed on native integer types producing an extended precision result.
3954 [h4 Non-member standard library function support]
3956 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&);
3957 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&);
3958 ``['number]`` acosh (const ``['number-or-expression-template-type]``&);
3959 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&);
3960 ``['number]`` asinh (const ``['number-or-expression-template-type]``&);
3961 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&);
3962 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3963 ``['number]`` atanh (const ``['number-or-expression-template-type]``&);
3964 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&);
3965 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&);
3966 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3967 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&);
3968 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&);
3969 ``['number]`` erf (const ``['number-or-expression-template-type]``&);
3970 ``['number]`` erfc (const ``['number-or-expression-template-type]``&);
3971 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&);
3972 ``['unmentionable-expression-template-type]`` exp2 (const ``['number-or-expression-template-type]``&);
3973 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&);
3974 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&);
3975 ``['unmentionable-expression-template-type]`` fdim (const ``['number-or-expression-template-type]``&);
3976 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&);
3977 ``['unmentionable-expression-template-type]`` fma (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3978 ``['unmentionable-expression-template-type]`` fmin (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3979 ``['unmentionable-expression-template-type]`` fmax (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3980 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3981 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*);
3982 ``['unmentionable-expression-template-type]`` hypot (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3983 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&);
3984 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
3985 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&);
3986 long long llrint (const ``['number-or-expression-template-type]``&);
3987 long long llround (const ``['number-or-expression-template-type]``&);
3988 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&);
3989 ``['unmentionable-expression-template-type]`` log2 (const ``['number-or-expression-template-type]``&);
3990 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&);
3991 ``['number]`` log1p (const ``['number-or-expression-template-type]``&);
3992 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&);
3993 long lrint (const ``['number-or-expression-template-type]``&);
3994 long lround (const ``['number-or-expression-template-type]``&);
3995 ``['unmentionable-expression-template-type]`` modf (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3996 ``['unmentionable-expression-template-type]`` nearbyint (const ``['number-or-expression-template-type]``&);
3997 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3998 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
3999 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4000 ``['unmentionable-expression-template-type]`` remainder (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4001 ``['unmentionable-expression-template-type]`` remquo (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, int*);
4002 ``['unmentionable-expression-template-type]`` rint (const ``['number-or-expression-template-type]``&);
4003 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&);
4004 ``['unmentionable-expression-template-type]`` scalbn (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
4005 ``['unmentionable-expression-template-type]`` scalbln (const ``['number-or-expression-template-type]``&, ``['integer-type]``);
4006 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&);
4007 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&);
4008 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&);
4009 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&);
4010 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&);
4011 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&);
4012 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&);
4014 int fpclassify (const ``['number-or-expression-template-type]``&);
4015 bool isfinite (const ``['number-or-expression-template-type]``&);
4016 bool isinf (const ``['number-or-expression-template-type]``&);
4017 bool isnan (const ``['number-or-expression-template-type]``&);
4018 bool isnormal (const ``['number-or-expression-template-type]``&);
4019 int signbit (const ``['number-or-expression-template-type]``&);
4021 bool isgreater (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4022 bool isgreaterequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4023 bool isless (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4024 bool islessequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4025 bool islessgreater(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4026 bool isunordered(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4028 These functions all behave exactly as their standard library C++11 counterparts do: their argument is either an instance of `number` or
4029 an expression template derived from it; If the argument is of type `number<Backend, et_off>` then that is also the return type,
4030 otherwise the return type is an expression template unless otherwise stated.
4032 The integer type arguments to `ldexp`, `frexp`, `scalbn` and `ilogb` may be either type `int`, or the actual
4033 type of the exponent of the number type.
4035 Complex number types support the following functions:
4037 // Complex number functions:
4038 ``['number<...>::value_type]`` real (const ``['number-or-expression-template-type]``&);
4039 ``['number<...>::value_type]`` imag (const ``['number-or-expression-template-type]``&);
4040 ``['number<...>::value_type]`` abs (const ``['number-or-expression-template-type]``&);
4041 ``['number<...>::value_type]`` arg (const ``['number-or-expression-template-type]``&);
4042 ``['number<...>::value_type]`` norm (const ``['number-or-expression-template-type]``&);
4043 ``['number]`` conj (const ``['number-or-expression-template-type]``&);
4044 ``['number]`` proj (const ``['number-or-expression-template-type]``&);
4045 ``['number]`` polar (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4047 In addition the functions `real`, `imag`, `arg`, `norm`, `conj` and `proj` are overloaded for scalar (ie non-complex) types in the same
4048 manner as `<complex>` and treat the argument as a value whose imaginary part is zero.
4050 There are also some functions implemented for compatibility with the Boost.Math functions of the same name:
4052 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&);
4053 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&);
4054 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&);
4055 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&);
4056 ``['number]`` changesign(const ``['number-or-expression-template-type]``&);
4057 ``['number]`` copysign(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
4059 All these functions are normally implemented by the Backend type. However, default versions are provided for Backend types that
4060 don't have native support for these functions. Please note however, that this default support requires the precision of the type
4061 to be a compile time constant - this means for example that the [gmp] MPF Backend will not work with these functions when that type is
4062 used at variable precision.
4064 Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types (if any other types
4065 such as fixed precision or complex types are added to the library later, then these functions may be extended to support those number types).
4067 The precision of these functions is generally determined by the backend implementation. For example the precision
4068 of these functions when used with __mpfr_float_backend is determined entirely by [mpfr]. When these functions use our own
4069 implementations, the accuracy of the transcendental functions is generally a few epsilon. Note however, that the trigonometrical
4070 functions incur the usual accuracy loss when reducing arguments by large multiples of [pi]. Also note that both __mpf_float
4071 and __cpp_dec_float have a number of guard digits beyond their stated precision, so the error rates listed for these
4072 are in some sense artificially low.
4074 The following table shows the error rates we observe for these functions with various backend types, functions not listed
4075 here are exact (tested on Win32 with VC++10, MPFR-3.0.0, MPIR-2.1.1):
4078 [[Function][mpfr_float_50][mpf_float_50][cpp_dec_float_50]]
4079 [[sqrt][1eps][0eps][0eps]]
4080 [[exp][1eps][0eps][0eps]]
4081 [[log][1eps][0eps][0eps]]
4082 [[log10][1eps][0eps][0eps]]
4083 [[cos][700eps][0eps][0eps]]
4084 [[sin][1eps][0eps][0eps]]
4085 [[tan][0eps][0eps][0eps]]
4086 [[acos][0eps][0eps][0eps]]
4087 [[asin][0eps][0eps][0eps]]
4088 [[atan][1eps][0eps][0eps]]
4089 [[cosh][1045eps[footnote It's likely that the inherent error in the input values to our test cases are to blame here.]][0eps][0eps]]
4090 [[sinh][2eps][0eps][0eps]]
4091 [[tanh][1eps][0eps][0eps]]
4092 [[pow][0eps][4eps][3eps]]
4093 [[atan2][1eps][0eps][0eps]]
4095 [h4 Traits Class Support]
4098 struct component_type;
4100 If this is a type with multiple components (for example rational or complex types), then this trait has a single member
4101 `type` that is the type of those components.
4104 struct number_category;
4106 A traits class that inherits from `mpl::int_<N>` where `N` is one of the enumerated values `number_kind_integer`, `number_kind_floating_point`,
4107 `number_kind_rational`, `number_kind_fixed_point`, or `number_kind_unknown`. This traits class is specialized for any type that has
4108 `std::numeric_limits` support as well as for classes in this library: which means it can be used for generic code that must work
4109 with built in arithmetic types as well as multiprecision ones.
4114 A traits class that inherits from `mpl::true_` if T is an instance of `number<>`, otherwise from `mpl::false_`.
4117 struct is_number_expression;
4119 A traits class that inherits from `mpl::true_` if T is an expression template type derived from `number<>`, otherwise from `mpl::false_`.
4123 [h4 Integer functions]
4125 In addition to functioning with types from this library, these functions are also overloaded for built in integer
4126 types if you include `<boost/multiprecision/integer.hpp>`. Further, when used with fixed precision types (whether
4127 built in integers or multiprecision ones), the functions will promote to a wider type internally when the algorithm
4128 requires it. Versions overloaded for built in integer types return that integer type rather than an expression
4131 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b);
4133 Returns the largest integer `x` that divides both `a` and `b`.
4135 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b);
4137 Returns the smallest integer `x` that is divisible by both `a` and `b`.
4139 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``& b, unsigned p);
4141 Returns ['b[super p]] as an expression template. Note that this function should be used with extreme care as the result can grow so
4142 large as to take "effectively forever" to compute, or else simply run the host machine out of memory. This is the one function in
4143 this category that is not overloaded for built in integer types, further, it's probably not a good idea to use it with
4144 fixed precision `cpp_int`'s either.
4146 ``['unmentionable-expression-template-type]`` powm(const ``['number-or-expression-template-type]``& b, const ``['number-or-expression-template-type]``& p, const ``['number-or-expression-template-type]``& m);
4148 Returns ['b[super p] mod m] as an expression template. Fixed precision types are promoted internally to ensure accuracy.
4150 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``& a);
4152 Returns the largest integer `x` such that `x * x < a`.
4154 template <class Backend, expression_template_option ExpressionTemplates>
4155 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``& a, number<Backend, EXpressionTemplates>& r);
4157 Returns the largest integer `x` such that `x * x < a`, and sets the remainder `r` such that `r = a - x * x`.
4159 template <class Backend, expression_template_option ExpressionTemplates>
4160 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y,
4161 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r);
4163 Divides x by y and returns both the quotient and remainder. After the call `q = x / y` and `r = x % y`.
4165 template <class Integer>
4166 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val);
4168 Returns the absolute value of `x % val`.
4170 unsigned lsb(const ``['number-or-expression-template-type]``& x);
4172 Returns the (zero-based) index of the least significant bit that is set to 1.
4174 Throws a `std::range_error` if the argument is <= 0.
4176 unsigned msb(const ``['number-or-expression-template-type]``& x);
4178 Returns the (zero-based) index of the most significant bit.
4180 Throws a `std::range_error` if the argument is <= 0.
4182 template <class Backend, class ExpressionTemplates>
4183 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index);
4185 Returns `true` if the bit at /index/ in /val/ is set.
4187 template <class Backend, class ExpressionTemplates>
4188 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index);
4190 Sets the bit at /index/ in /val/, and returns /val/.
4192 template <class Backend, class ExpressionTemplates>
4193 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index);
4195 Unsets the bit at /index/ in /val/, and returns /val/.
4197 template <class Backend, class ExpressionTemplates>
4198 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index);
4200 Flips the bit at /index/ in /val/, and returns /val/.
4202 template <class Engine>
4203 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen);
4204 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials);
4206 Tests to see if the number /n/ is probably prime - the test excludes the vast majority of composite numbers
4207 by excluding small prime factors and performing a single Fermat test. Then performs /trials/ Miller-Rabin
4208 tests. Returns `false` if /n/ is definitely composite, or `true` if /n/ is probably prime with the
4209 probability of it being composite less than 0.25^trials. Fixed precision types are promoted internally
4212 [h4 Rational Number Functions]
4214 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&);
4215 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&);
4217 These functions return the numerator and denominator of a rational number respectively.
4219 [h4 Boost.Math Interoperability Support]
4221 namespace boost{ namespace math{
4223 int fpclassify (const ``['number-or-expression-template-type]``&, int);
4224 bool isfinite (const ``['number-or-expression-template-type]``&, int);
4225 bool isnan (const ``['number-or-expression-template-type]``&, int);
4226 bool isinf (const ``['number-or-expression-template-type]``&, int);
4227 bool isnormal (const ``['number-or-expression-template-type]``&, int);
4231 These floating-point classification functions behave exactly as their Boost.Math equivalents.
4233 Other Boost.Math functions and templates may also be
4234 specialized or overloaded to ensure interoperability.
4236 [h4 std::numeric_limits support]
4240 template <class Backend, ExpressionTemplates>
4241 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> >
4243 /* Usual members here */
4248 Class template `std::numeric_limits` is specialized for all instantiations of `number` whose precision is known at compile time, plus those
4249 types whose precision is unlimited (though it is much less useful in those cases). It is not specialized for types
4250 whose precision can vary at compile time (such as `mpf_float`).
4254 [section:cpp_int_ref cpp_int]
4256 namespace boost{ namespace multiprecision{
4258 typedef unspecified-type limb_type;
4260 enum cpp_integer_type { signed_magnitude, unsigned_magnitude };
4261 enum cpp_int_check_type { checked, unchecked };
4263 template <unsigned MinDigits = 0,
4264 unsigned MaxDits = 0,
4265 cpp_integer_type SignType = signed_magnitude,
4266 cpp_int_check_type Checked = unchecked,
4267 class Allocator = std::allocator<limb_type> >
4268 class cpp_int_backend;
4270 // Expression templates default to et_off if there is no allocator:
4272 template <unsigned MinDigits, unsigned MaxDigits, cpp_integer_type SignType, cpp_int_check_type Checked>
4273 struct expression_template_default<cpp_int_backend<MinDigits, MaxDigits, SignType, Checked, void> >
4274 { static const expression_template_option value = et_off; };
4276 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer
4277 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend;
4278 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number
4280 // Fixed precision unsigned types:
4281 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t;
4282 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t;
4283 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t;
4284 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t;
4286 // Fixed precision signed types:
4287 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t;
4288 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t;
4289 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t;
4290 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t;
4292 // Over again, but with checking enabled this time:
4293 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int;
4294 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend;
4295 typedef number<checked_cpp_rational_backend> checked_cpp_rational;
4297 // Checked fixed precision unsigned types:
4298 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t;
4299 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t;
4300 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t;
4301 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t;
4303 // Fixed precision signed types:
4304 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t;
4305 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t;
4306 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t;
4307 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t;
4311 Class template `cpp_int_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4312 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4315 The template arguments are:
4318 [[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory
4319 allocation. When zero, this field is determined automatically based on how many bits can be stored
4320 in union with the dynamic storage header: setting a larger value may improve performance as larger integer
4321 values will be stored internally before memory allocation is required.]]
4322 [[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type.
4323 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic
4324 memory allocation will ever be performed: in this situation the Allocator parameter should be set to
4325 type `void`. Note that this parameter should not be used simply to prevent large memory
4326 allocations, not only is that role better performed by the allocator, but fixed precision
4327 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]]
4328 [[SignType][Determines whether the resulting type is signed or not. Note that for
4329 [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types
4330 this parameter must be `signed_magnitude`. For fixed precision
4331 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]]
4332 [[Checked][This parameter has two values: `checked` or `unchecked`. See the [link boost_multiprecision.tut.ints.cpp_int tutorial] for more information.]]
4333 [[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]]
4336 The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`.
4338 More information on this type can be found in the [link boost_multiprecision.tut.ints.cpp_int tutorial].
4342 [section:gmp_int_ref gmp_int]
4344 namespace boost{ namespace multiprecision{
4348 typedef number<gmp_int > mpz_int;
4352 Class template `gmp_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4353 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4356 The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`.
4358 More information on this type can be found in the [link boost_multiprecision.tut.ints.gmp_int tutorial].
4362 [section:tom_int_ref tom_int]
4364 namespace boost{ namespace multiprecision{
4368 typedef number<tommath_int > tom_int;
4372 Class template `tommath_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4373 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4376 The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`.
4378 More information on this type can be found in the [link boost_multiprecision.tut.ints.tom_int tutorial].
4382 [section:mpf_ref gmp_float]
4384 namespace boost{ namespace multiprecision{
4386 template <unsigned Digits10>
4389 typedef number<gmp_float<50> > mpf_float_50;
4390 typedef number<gmp_float<100> > mpf_float_100;
4391 typedef number<gmp_float<500> > mpf_float_500;
4392 typedef number<gmp_float<1000> > mpf_float_1000;
4393 typedef number<gmp_float<0> > mpf_float;
4397 Class template `gmp_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4398 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4401 The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type
4402 should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision`
4403 and `number::precision`. Note that this type does not in any way change the GMP library's global state (for example
4404 it does not change the default precision of the mpf_t data type), therefore you can safely mix this type with existing
4405 code that uses GMP, and also mix `gmp_float`s of differing precision.
4407 The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`.
4409 More information on this type can be found in the [link boost_multiprecision.tut.floats.gmp_float tutorial].
4413 [section:mpfr_ref mpfr_float_backend]
4415 namespace boost{ namespace multiprecision{
4417 template <unsigned Digits10>
4418 class mpfr_float_backend;
4420 typedef number<mpfr_float_backend<50> > mpfr_float_50;
4421 typedef number<mpfr_float_backend<100> > mpfr_float_100;
4422 typedef number<mpfr_float_backend<500> > mpfr_float_500;
4423 typedef number<mpfr_float_backend<1000> > mpfr_float_1000;
4424 typedef number<mpfr_float_backend<0> > mpfr_float;
4428 Class template `mpfr_float_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4429 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4432 The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type
4433 should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision`
4434 and `number::precision`. Note that this type does not in any way change the GMP or MPFR library's global state (for example
4435 it does not change the default precision of the mpfr_t data type), therefore you can safely mix this type with existing
4436 code that uses GMP or MPFR, and also mix `mpfr_float_backend`s of differing precision.
4438 The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`.
4440 More information on this type can be found in the [link boost_multiprecision.tut.floats.mpfr_float tutorial].
4444 [section:cpp_bin_float_ref cpp_bin_float]
4446 namespace boost{ namespace multiprecision{
4448 enum digit_base_type
4454 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0>
4455 class cpp_bin_float;
4457 typedef number<cpp_bin_float<50> > cpp_bin_float_50;
4458 typedef number<cpp_bin_float<100> > cpp_bin_float_100;
4460 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single;
4461 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double;
4462 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended;
4463 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad;
4464 typedef number<backends::cpp_bin_float<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143>, et_off> cpp_bin_float_oct;
4468 Class template `cpp_bin_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4469 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4472 The class takes six template parameters:
4475 [[Digits][The number of digits precision the type
4476 should support. This is normally expressed as base-10 digits, but that can be changed via the second template parameter.]]
4477 [[base][An enumerated value (either `digit_base_10` or `digit_base_2`) that indicates whether `Digits` is base-10 or base-2]]
4478 [[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic
4479 allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]]
4480 [[Exponent][A signed integer type to use as the type of the exponent - defaults to `int`.]]
4481 [[ExponentMin][The smallest (most negative) permitted exponent, defaults to zero, meaning "define as small as possible
4482 given the limitations of the type and our internal requirements".]]
4483 [[ExponentMax][The largest (most positive) permitted exponent, defaults to zero, meaning "define as large as possible
4484 given the limitations of the type and our internal requirements".]]
4487 The type of `number_category<cpp_bin_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`.
4489 More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_bin_float tutorial].
4491 [h4 Implementation Notes]
4493 Internally, an N-bit `cpp_bin_float` is represented as an N-bit unsigned integer along with an exponent and a sign.
4494 The integer part is normalized so that it's most significant bit is always 1. The decimal point is assumed to be
4495 directly after the most significant bit of the integer part. The special values zero, infinity and NaN all have
4496 the integer part set to zero, and the exponent to one of 3 special values above the maximum permitted exponent.
4498 Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain a 2N-bit number, then round and
4499 adjust the sign and exponent.
4501 Addition and subtraction proceed similarly - if the exponents are such that there is overlap between the two
4502 values, then left shift the larger value to produce a number with between N and 2N bits, then perform integer
4503 addition or subtraction, round, and adjust the exponent.
4505 Division proceeds as follows: first scale the numerator by some power of 2 so that integer division will
4506 produce either an N-bit or N+1 bit result plus a remainder. If we get an N bit result then the size of
4507 twice the remainder compared to the denominator gives us the rounding direction. Otherwise we have one extra bit
4508 in the result which we can use to determine rounding (in this case ties occur only if the remainder is zero and
4509 the extra bit is a 1).
4511 Square root uses integer square root in a manner analogous to division.
4513 Decimal string to binary conversion proceeds as follows: first parse the digits to
4514 produce an integer multiplied by a decimal exponent. Note that we stop parsing digits
4515 once we have parsed as many as can possibly effect the result - this stops the integer
4516 part growing too large when there are a very large number of input digits provided.
4517 At this stage if the decimal exponent is positive then the result is an integer and we
4518 can in principle simply multiply by 10^N to get an exact integer result. In practice
4519 however, that could produce some very large integers. We also need to be able to divide
4520 by 10^N in the event that the exponent is negative. Therefore calculation of the 10^N
4521 values plus the multiplication or division are performed using limited precision
4522 integer arithmetic, plus an exponent, and a track of the accumulated error. At the end of
4523 the calculation we will either be able to round unambiguously, or the error will be such
4524 that we can't tell which way to round. In the latter case we simply up the precision and try
4525 again until we have an unambiguously rounded result.
4527 Binary to decimal conversion proceeds very similarly to the above, our aim is to calculate
4528 `mantissa * 2^shift * 10^E` where `E` is the decimal exponent and `shift` is calculated
4529 so that the result is an N bit integer assuming we want N digits printed in the result.
4530 As before we use limited precision arithmetic to calculate the result and up the
4531 precision as necessary until the result is unambiguously correctly rounded. In addition
4532 our initial calculation of the decimal exponent may be out by 1, so we have to correct
4533 that and loop as well in the that case.
4537 [section:cpp_dec_ref cpp_dec_float]
4539 namespace boost{ namespace multiprecision{
4541 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void>
4542 class cpp_dec_float;
4544 typedef number<cpp_dec_float<50> > cpp_dec_float_50;
4545 typedef number<cpp_dec_float<100> > cpp_dec_float_100;
4549 Class template `cpp_dec_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type.
4550 Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject
4553 The class takes three template parameters:
4556 [[Digits10][The number of decimal digits precision the type
4557 should support. Note that this type does not normally perform any dynamic memory allocation, and as a result the `Digits10`
4558 template argument should not be set too high or the class's size will grow unreasonably large.]]
4559 [[ExponentType][A signed integer type that represents the exponent of the number]]
4560 [[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic
4561 allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]]
4564 The type of `number_category<cpp_dec_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`.
4566 More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_dec_float tutorial].
4570 [section:internals Internal Support Code]
4572 There are some traits classes which authors of new backends should be aware of:
4574 namespace boost{ namespace multiprecision{ namespace detail{
4576 template<typename From, typename To>
4577 struct is_explicitly_convertible;
4581 Inherits from `boost::integral_constant<bool,true>` if type `From` has an explicit conversion from `To`.
4583 For compilers that support C++11 SFINAE-expressions this trait should "just work". Otherwise it inherits
4584 from `boost::is_convertible<From, To>::type`, and will need to be specialised for Backends that have
4585 constructors marked as `explicit`.
4587 template <class From, class To>
4588 struct is_lossy_conversion
4590 static const bool value = see below;
4593 Member `value` is true if the conversion from `From` to `To` would result in a loss of precision, and `false` otherwise.
4595 The default version of this trait simply checks whether the ['kind] of conversion (for example from a floating-point to an integer type)
4596 is inherently lossy. Note that if either of the types `From` or `To` are of an unknown number category (because `number_category` is not
4597 specialised for that type) then this trait will be `true`.
4599 template<typename From, typename To>
4600 struct is_restricted_conversion
4602 static const bool value = see below;
4605 Member `value` is `true` if `From` is only explicitly convertible to `To` and not implicitly convertible, or
4606 if `is_lossy_conversion<From, To>::value` is `true`. Otherwise `false`.
4608 Note that while this trait is the ultimate arbiter of which constructors are marked as `explicit` in class `number`,
4609 authors of backend types should generally specialise one of the traits above, rather than this one directly.
4616 These two traits inherit from either `mpl::true_` or `mpl::false_`, by default types are assumed to be signed unless
4617 `is_unsigned_number` is specialized for that type.
4621 [section:backendconc Backend Requirements]
4623 The requirements on the `Backend` template argument to `number` are split up into
4624 sections: compulsory and optional.
4626 Compulsory requirements have no default implementation in the library, therefore if the feature
4627 they implement is to be supported at all, then they must be implemented by the backend.
4629 Optional requirements have default implementations that are called if the backend doesn't provide
4630 it's own. Typically the backend will implement these to improve performance.
4632 In the following tables, type B is the `Backend` template argument to `number`, `b` and `b2` are
4633 a variables of type B, `pb` is a variable of type B*, `cb`, `cb2` and `cb3` are constant variables of type `const B`,
4634 `rb` is a variable of type `B&&`, `a` and `a2` are variables of Arithmetic type,
4635 `s` is a variable of type `const char*`, `ui` is a variable of type `unsigned`, `bb` is a variable of type `bool`,
4636 `pa` is a variable of type pointer-to-arithmetic-type, `exp` is a variable of type `B::exp_type`,
4637 `pexp` is a variable of type `B::exp_type*`, `i` is a variable of type `int`, `pi` pointer to a variable of type `int`,
4638 B2 is another type that meets these requirements, b2 is a variable of type B2, `ss` is variable of type `std::streamsize`
4639 and `ff` is a variable of type `std::ios_base::fmtflags`.
4641 [table Compulsory Requirements on the Backend type.
4642 [[Expression][Return Type][Comments][Throws]]
4643 [[`B::signed_types`][`mpl::list<type-list>`][A list of signed integral types that can be assigned to type B. The types shall be
4644 listed in order of size, smallest first, and shall terminate in the type that is `std::intmax_t`.][[space]]]
4645 [[`B::unsigned_types`][`mpl::list<type-list>`][A list of unsigned integral types that can be assigned to type B. The types shall be
4646 listed in order of size, smallest first, and shall terminate in the type that is `std::uintmax_t`.][[space]]]
4647 [[`B::float_types`][`mpl::list<type-list>`][A list of floating-point types that can be assigned to type B.The types shall be
4648 listed in order of size, smallest first, and shall terminate in type `long double`.][[space]]]
4649 [[`B::exponent_type`][A signed integral type.][The type of the exponent of type B. This type is required only for floating-point types.][[space]]]
4650 [[`B()`][ ][Default constructor.][[space]]]
4651 [[`B(cb)`][ ][Copy Constructor.][[space]]]
4652 [[`b = b`][`B&`][Assignment operator.][[space]]]
4653 [[`b = a`][`B&`][Assignment from an Arithmetic type. The type of `a` shall be listed in one of the type lists
4654 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]]
4655 [[`b = s`][`B&`][Assignment from a string.][Throws a `std::runtime_error` if the string could not be interpreted as a valid number.]]
4656 [[`b.swap(b)`][`void`][Swaps the contents of its arguments.][`noexcept`]]
4657 [[`cb.str(ss, ff)`][`std::string`][Returns the string representation of `b` with `ss` digits and formatted according to the flags set in `ff`.
4658 If `ss` is zero, then returns as many digits as are required to reconstruct the original value.][[space]]]
4659 [[`b.negate()`][`void`][Negates `b`.][[space]]]
4660 [[`cb.compare(cb2)`][`int`][Compares `cb` and `cb2`, returns a value less than zero if `cb < cb2`, a value greater than zero if `cb > cb2` and zero
4661 if `cb == cb2`.][`noexcept`]]
4662 [[`cb.compare(a)`][`int`][Compares `cb` and `a`, returns a value less than zero if `cb < a`, a value greater than zero if `cb > a` and zero
4663 if `cb == a`. The type of `a` shall be listed in one of the type lists
4664 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]]
4665 [[`eval_add(b, cb)`][`void`][Adds `cb` to `b`.][[space]]]
4666 [[`eval_subtract(b, cb)`][`void`][Subtracts `cb` from `b`.][[space]]]
4667 [[`eval_multiply(b, cb)`][`void`][Multiplies `b` by `cb`.][[space]]]
4668 [[`eval_divide(b, cb)`][`void`][Divides `b` by `cb`.]
4669 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]]
4670 [[`eval_modulus(b, cb)`][`void`][Computes `b %= cb`, only required when `B` is an integer type.]
4671 [`std::overflow_error` if cb has the value zero.]]
4672 [[`eval_bitwise_and(b, cb)`][`void`][Computes `b &= cb`, only required when `B` is an integer type.][[space]]]
4673 [[`eval_bitwise_or(b, cb)`][`void`][Computes `b |= cb`, only required when `B` is an integer type.][[space]]]
4674 [[`eval_bitwise_xor(b, cb)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type.][[space]]]
4675 [[`eval_complement(b, cb)`][`void`][Computes the ones-complement of `cb` and stores the result in `b`, only required when `B` is an integer type.][[space]]]
4676 [[`eval_left_shift(b, ui)`][`void`][Computes `b <<= ui`, only required when `B` is an integer type.][[space]]]
4677 [[`eval_right_shift(b, ui)`][`void`][Computes `b >>= ui`, only required when `B` is an integer type.][[space]]]
4678 [[`eval_convert_to(pa, cb)`][`void`][Converts `cb` to the type of `*pa` and store the result in `*pa`. Type `B` shall support
4679 conversion to at least types `std::intmax_t`, `std::uintmax_t` and `long long`.
4680 Conversion to other arithmetic types can then be synthesised using other operations.
4681 Conversions to other types are entirely optional.][[space]]]
4682 [[`eval_frexp(b, cb, pexp)`][`void`][Stores values in `b` and `*pexp` such that the value of `cb` is b * 2[super *pexp], only required when `B` is a floating-point type.][[space]]]
4683 [[`eval_ldexp(b, cb, exp)`][`void`][Stores a value in `b` that is cb * 2[super exp], only required when `B` is a floating-point type.][[space]]]
4684 [[`eval_frexp(b, cb, pi)`][`void`][Stores values in `b` and `*pi` such that the value of `cb` is b * 2[super *pi], only required when `B` is a floating-point type.]
4685 [`std::runtime_error` if the exponent of cb is too large to be stored in an `int`.]]
4686 [[`eval_ldexp(b, cb, i)`][`void`][Stores a value in `b` that is cb * 2[super i], only required when `B` is a floating-point type.][[space]]]
4687 [[`eval_floor(b, cb)`][`void`][Stores the floor of `cb` in `b`, only required when `B` is a floating-point type.][[space]]]
4688 [[`eval_ceil(b, cb)`][`void`][Stores the ceiling of `cb` in `b`, only required when `B` is a floating-point type.][[space]]]
4689 [[`eval_sqrt(b, cb)`][`void`][Stores the square root of `cb` in `b`, only required when `B` is a floating-point type.][[space]]]
4690 [[`boost::multiprecision::number_category<B>::type`][`mpl::int_<N>`][`N` is one of the values `number_kind_integer`, `number_kind_floating_point`, `number_kind_complex`, `number_kind_rational` or `number_kind_fixed_point`.
4691 Defaults to `number_kind_floating_point`.][[space]]]
4692 [[`eval_conj(b, cb)`][`void`][Sets `b` to the complex conjugate of `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4693 [[`eval_proj(b, cb)`][`void`][Sets `b` to the Riemann projection of `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4694 [[`eval_real(b, cb)`][`void`][Sets `b` to the real part of `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4695 [[`eval_imag(b, cb)`][`void`][Sets `b` to the imaginary of `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4696 [[`eval_set_real(b, a)`][`void`][Sets the real part of `b` to `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4697 [[`eval_set_imag(b, a)`][`void`][Sets the imaginary part of `b` to `cb`. Required for complex types only - other types have a sensible default.][[space]]]
4700 [table Optional Requirements on the Backend Type
4701 [[Expression][Returns][Comments][Throws]]
4703 [[['Construct and assign:]]]
4704 [[`B(rb)`][`B`][Move constructor. Afterwards variable `rb` shall be in sane state, albeit with unspecified value.
4705 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]]
4706 [[`b = rb`][`B&`][Move-assign. Afterwards variable `rb` shall be in sane state, albeit with unspecified value.
4707 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]]
4708 [[`B(a)`][`B`][Direct construction from an arithmetic type. The type of `a` shall be listed in one of the type lists
4709 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4710 When not provided, this operation is simulated using default-construction followed by assignment.][[space]]]
4711 [[`B(b2)`][`B`][Copy constructor from a different back-end type. When not provided, a generic interconversion routine is used.
4712 This constructor may be `explicit` if the corresponding frontend constructor should also be `explicit`.][[space]]]
4713 [[`b = b2`][`b&`][Assignment operator from a different back-end type. When not provided, a generic interconversion routine is used.][[space]]]
4714 [[`assign_components(b, a, a)`][`void`][Assigns to `b` the two components in the following arguments.
4715 Only applies to rational and complex number types.
4716 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]]
4717 [[`assign_components(b, b2, b2)`][`void`][Assigns to `b` the two components in the following arguments.
4718 Only applies to rational and complex number types.
4719 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]]
4722 [[`eval_eq(cb, cb2)`][`bool`][Returns `true` if `cb` and `cb2` are equal in value.
4723 When not provided, the default implementation returns `cb.compare(cb2) == 0`.][`noexcept`]]
4724 [[`eval_eq(cb, a)`][`bool`][Returns `true` if `cb` and `a` are equal in value.
4725 The type of `a` shall be listed in one of the type lists
4726 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4727 When not provided, return the equivalent of `eval_eq(cb, B(a))`.][[space]]]
4728 [[`eval_eq(a, cb)`][`bool`][Returns `true` if `cb` and `a` are equal in value.
4729 The type of `a` shall be listed in one of the type lists
4730 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4731 When not provided, the default version returns `eval_eq(cb, a)`.][[space]]]
4732 [[`eval_lt(cb, cb2)`][`bool`][Returns `true` if `cb` is less than `cb2` in value.
4733 When not provided, the default implementation returns `cb.compare(cb2) < 0`.][`noexcept`]]
4734 [[`eval_lt(cb, a)`][`bool`][Returns `true` if `cb` is less than `a` in value.
4735 The type of `a` shall be listed in one of the type lists
4736 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4737 When not provided, the default implementation returns `eval_lt(cb, B(a))`.][[space]]]
4738 [[`eval_lt(a, cb)`][`bool`][Returns `true` if `a` is less than `cb` in value.
4739 The type of `a` shall be listed in one of the type lists
4740 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4741 When not provided, the default implementation returns `eval_gt(cb, a)`.][[space]]]
4742 [[`eval_gt(cb, cb2)`][`bool`][Returns `true` if `cb` is greater than `cb2` in value.
4743 When not provided, the default implementation returns `cb.compare(cb2) > 0`.][`noexcept`]]
4744 [[`eval_gt(cb, a)`][`bool`][Returns `true` if `cb` is greater than `a` in value.
4745 The type of `a` shall be listed in one of the type lists
4746 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4747 When not provided, the default implementation returns `eval_gt(cb, B(a))`.][[space]]]
4748 [[`eval_gt(a, cb)`][`bool`][Returns `true` if `a` is greater than `cb` in value.
4749 The type of `a` shall be listed in one of the type lists
4750 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4751 When not provided, the default implementation returns `eval_lt(cb, a)`.][[space]]]
4752 [[`eval_is_zero(cb)`][`bool`][Returns `true` if `cb` is zero, otherwise `false`. The default version of this function
4753 returns `cb.compare(ui_type(0)) == 0`, where `ui_type` is `ui_type` is
4754 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]]
4755 [[`eval_get_sign(cb)`][`int`][Returns a value < zero if `cb` is negative, a value > zero if `cb` is positive, and zero if `cb` is zero.
4756 The default version of this function
4757 returns `cb.compare(ui_type(0))`, where `ui_type` is `ui_type` is
4758 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]]
4760 [[['Basic arithmetic:]]]
4761 [[`eval_add(b, a)`][`void`][Adds `a` to `b`. The type of `a` shall be listed in one of the type lists
4762 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4763 When not provided, the default version calls `eval_add(b, B(a))`][[space]]]
4764 [[`eval_add(b, cb, cb2)`][`void`][Add `cb` to `cb2` and stores the result in `b`.
4765 When not provided, does the equivalent of `b = cb; eval_add(b, cb2)`.][[space]]]
4766 [[`eval_add(b, cb, a)`][`void`][Add `cb` to `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4767 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4768 When not provided, does the equivalent of `eval_add(b, cb, B(a))`.][[space]]]
4769 [[`eval_add(b, a, cb)`][`void`][Add `a` to `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4770 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4771 When not provided, does the equivalent of `eval_add(b, cb, a)`.][[space]]]
4772 [[`eval_subtract(b, a)`][`void`][Subtracts `a` from `b`. The type of `a` shall be listed in one of the type lists
4773 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4774 When not provided, the default version calls `eval_subtract(b, B(a))`][[space]]]
4775 [[`eval_subtract(b, cb, cb2)`][`void`][Subtracts `cb2` from `cb` and stores the result in `b`.
4776 When not provided, does the equivalent of `b = cb; eval_subtract(b, cb2)`.][[space]]]
4777 [[`eval_subtract(b, cb, a)`][`void`][Subtracts `a` from `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4778 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4779 When not provided, does the equivalent of `eval_subtract(b, cb, B(a))`.][[space]]]
4780 [[`eval_subtract(b, a, cb)`][`void`][Subtracts `cb` from `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4781 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4782 When not provided, does the equivalent of `eval_subtract(b, cb, a); b.negate();`.][[space]]]
4783 [[`eval_multiply(b, a)`][`void`][Multiplies `b` by `a`. The type of `a` shall be listed in one of the type lists
4784 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4785 When not provided, the default version calls `eval_multiply(b, B(a))`][[space]]]
4786 [[`eval_multiply(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and stores the result in `b`.
4787 When not provided, does the equivalent of `b = cb; eval_multiply(b, cb2)`.][[space]]]
4788 [[`eval_multiply(b, cb, a)`][`void`][Multiplies `cb` by `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4789 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4790 When not provided, does the equivalent of `eval_multiply(b, cb, B(a))`.][[space]]]
4791 [[`eval_multiply(b, a, cb)`][`void`][Multiplies `a` by `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4792 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4793 When not provided, does the equivalent of `eval_multiply(b, cb, a)`.][[space]]]
4794 [[`eval_multiply_add(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and adds the result to `b`.
4795 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by
4796 `eval_add(b, t)`.][[space]]]
4797 [[`eval_multiply_add(b, cb, a)`][`void`][Multiplies `a` by `cb` and adds the result to `b`.
4798 The type of `a` shall be listed in one of the type lists
4799 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4800 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by
4801 `eval_add(b, t)`.][[space]]]
4802 [[`eval_multiply_add(b, a, cb)`][`void`][Multiplies `a` by `cb` and adds the result to `b`.
4803 The type of `a` shall be listed in one of the type lists
4804 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4805 When not provided does the equivalent of `eval_multiply_add(b, cb, a)`.][[space]]]
4806 [[`eval_multiply_subtract(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and subtracts the result from `b`.
4807 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by
4808 `eval_subtract(b, t)`.][[space]]]
4809 [[`eval_multiply_subtract(b, cb, a)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`.
4810 The type of `a` shall be listed in one of the type lists
4811 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4812 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by
4813 `eval_subtract(b, t)`.][[space]]]
4814 [[`eval_multiply_subtract(b, a, cb)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`.
4815 The type of `a` shall be listed in one of the type lists
4816 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4817 When not provided does the equivalent of `eval_multiply_subtract(b, cb, a)`.][[space]]]
4818 [[`eval_multiply_add(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and adds the result to `cb3` storing the result in `b`.
4819 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by
4821 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of
4822 `cb`, `cb2` and `cb3` with any type listed in one of the type lists
4823 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]]
4824 [[`eval_multiply_subtract(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and subtracts from the result `cb3` storing the result in `b`.
4825 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by
4826 `eval_subtract(b, cb3)`.
4827 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of
4828 `cb`, `cb2` and `cb3` with any type listed in one of the type lists
4829 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]]
4830 [[`eval_divide(b, a)`][`void`][Divides `b` by `a`. The type of `a` shall be listed in one of the type lists
4831 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4832 When not provided, the default version calls `eval_divide(b, B(a))`]
4833 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]]
4834 [[`eval_divide(b, cb, cb2)`][`void`][Divides `cb` by `cb2` and stores the result in `b`.
4835 When not provided, does the equivalent of `b = cb; eval_divide(b, cb2)`.]
4836 [`std::overflow_error` if `cb2` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]]
4837 [[`eval_divide(b, cb, a)`][`void`][Divides `cb` by `a` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4838 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4839 When not provided, does the equivalent of `eval_divide(b, cb, B(a))`.]
4840 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]]
4841 [[`eval_divide(b, a, cb)`][`void`][Divides `a` by `cb` and stores the result in `b`. The type of `a` shall be listed in one of the type lists
4842 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4843 When not provided, does the equivalent of `eval_divide(b, B(a), cb)`.]
4844 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]]
4845 [[`eval_increment(b)`][void][Increments the value of `b` by one.
4846 When not provided, does the equivalent of `eval_add(b, static_cast<ui_type>(1u))`.
4847 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]]
4848 [[`eval_decrement(b)`][void][Decrements the value of `b` by one.
4849 When not provided, does the equivalent of `eval_subtract(b, static_cast<ui_type>(1u))`.
4850 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]]
4852 [[['Integer specific operations:]]]
4853 [[`eval_modulus(b, a)`][`void`][Computes `b %= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4854 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4855 When not provided, the default version calls `eval_modulus(b, B(a))`]
4856 [`std::overflow_error` if `a` has the value zero.]]
4857 [[`eval_modulus(b, cb, cb2)`][`void`][Computes `cb % cb2` and stores the result in `b`, only required when `B` is an integer type.
4858 When not provided, does the equivalent of `b = cb; eval_modulus(b, cb2)`.]
4859 [`std::overflow_error` if `a` has the value zero.]]
4860 [[`eval_modulus(b, cb, a)`][`void`][Computes `cb % a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4861 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4862 When not provided, does the equivalent of `eval_modulus(b, cb, B(a))`.]
4863 [`std::overflow_error` if `a` has the value zero.]]
4864 [[`eval_modulus(b, a, cb)`][`void`][Computes `cb % a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4865 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4866 When not provided, does the equivalent of `eval_modulus(b, B(a), cb)`.]
4867 [`std::overflow_error` if `a` has the value zero.]]
4868 [[`eval_bitwise_and(b, a)`][`void`][Computes `b &= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4869 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4870 When not provided, the default version calls `eval_bitwise_and(b, B(a))`][[space]]]
4871 [[`eval_bitwise_and(b, cb, cb2)`][`void`][Computes `cb & cb2` and stores the result in `b`, only required when `B` is an integer type.
4872 When not provided, does the equivalent of `b = cb; eval_bitwise_and(b, cb2)`.][[space]]]
4873 [[`eval_bitwise_and(b, cb, a)`][`void`][Computes `cb & a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4874 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4875 When not provided, does the equivalent of `eval_bitwise_and(b, cb, B(a))`.][[space]]]
4876 [[`eval_bitwise_and(b, a, cb)`][`void`][Computes `cb & a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4877 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4878 When not provided, does the equivalent of `eval_bitwise_and(b, cb, a)`.][[space]]]
4879 [[`eval_bitwise_or(b, a)`][`void`][Computes `b |= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4880 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4881 When not provided, the default version calls `eval_bitwise_or(b, B(a))`][[space]]]
4882 [[`eval_bitwise_or(b, cb, cb2)`][`void`][Computes `cb | cb2` and stores the result in `b`, only required when `B` is an integer type.
4883 When not provided, does the equivalent of `b = cb; eval_bitwise_or(b, cb2)`.][[space]]]
4884 [[`eval_bitwise_or(b, cb, a)`][`void`][Computes `cb | a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4885 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4886 When not provided, does the equivalent of `eval_bitwise_or(b, cb, B(a))`.][[space]]]
4887 [[`eval_bitwise_or(b, a, cb)`][`void`][Computes `cb | a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4888 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4889 When not provided, does the equivalent of `eval_bitwise_or(b, cb, a)`.][[space]]]
4890 [[`eval_bitwise_xor(b, a)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4891 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4892 When not provided, the default version calls `eval_bitwise_xor(b, B(a))`][[space]]]
4893 [[`eval_bitwise_xor(b, cb, cb2)`][`void`][Computes `cb ^ cb2` and stores the result in `b`, only required when `B` is an integer type.
4894 When not provided, does the equivalent of `b = cb; eval_bitwise_xor(b, cb2)`.][[space]]]
4895 [[`eval_bitwise_xor(b, cb, a)`][`void`][Computes `cb ^ a` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4896 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4897 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, B(a))`.][[space]]]
4898 [[`eval_bitwise_xor(b, a, cb)`][`void`][Computes `a ^ cb` and stores the result in `b`, only required when `B` is an integer type. The type of `a` shall be listed in one of the type lists
4899 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4900 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, a)`.][[space]]]
4901 [[`eval_left_shift(b, cb, ui)`][`void`][Computes `cb << ui` and stores the result in `b`, only required when `B` is an integer type.
4902 When not provided, does the equivalent of `b = cb; eval_left_shift(b, a);`.][[space]]]
4903 [[`eval_right_shift(b, cb, ui)`][`void`][Computes `cb >> ui` and stores the result in `b`, only required when `B` is an integer type.
4904 When not provided, does the equivalent of `b = cb; eval_right_shift(b, a);`.][[space]]]
4905 [[`eval_qr(cb, cb2, b, b2)`][`void`][Sets `b` to the result of `cb / cb2` and `b2` to the result of `cb % cb2`. Only required when `B` is an integer type.
4906 The default version of this function is synthesised from other operations above.]
4907 [`std::overflow_error` if `a` has the value zero.]]
4908 [[`eval_integer_modulus(cb, ui)`][`unsigned`][Returns the result of `cb % ui`. Only required when `B` is an integer type.
4909 The default version of this function is synthesised from other operations above.]
4910 [`std::overflow_error` if `a` has the value zero.]]
4911 [[`eval_lsb(cb)`][`unsigned`][Returns the index of the least significant bit that is set. Only required when `B` is an integer type.
4912 The default version of this function is synthesised from other operations above.][[space]]]
4913 [[`eval_msb(cb)`][`unsigned`][Returns the index of the most significant bit that is set. Only required when `B` is an integer type.
4914 The default version of this function is synthesised from other operations above.][[space]]]
4915 [[`eval_bit_test(cb, ui)`][`bool`][Returns true if `cb` has bit `ui` set. Only required when `B` is an integer type.
4916 The default version of this function is synthesised from other operations above.][[space]]]
4917 [[`eval_bit_set(b, ui)`][`void`][Sets the bit at index `ui` in `b`. Only required when `B` is an integer type.
4918 The default version of this function is synthesised from other operations above.][[space]]]
4919 [[`eval_bit_unset(b, ui)`][`void`][Unsets the bit at index `ui` in `b`. Only required when `B` is an integer type.
4920 The default version of this function is synthesised from other operations above.][[space]]]
4921 [[`eval_bit_flip(b, ui)`][`void`][Flips the bit at index `ui` in `b`. Only required when `B` is an integer type.
4922 The default version of this function is synthesised from other operations above.][[space]]]
4923 [[`eval_gcd(b, cb, cb2)`][`void`][Sets `b` to the greatest common divisor of `cb` and `cb2`. Only required when `B` is an integer type.
4924 The default version of this function is synthesised from other operations above.][[space]]]
4925 [[`eval_lcm(b, cb, cb2)`][`void`][Sets `b` to the least common multiple of `cb` and `cb2`. Only required when `B` is an integer type.
4926 The default version of this function is synthesised from other operations above.][[space]]]
4927 [[`eval_gcd(b, cb, a)`][`void`][Sets `b` to the greatest common divisor of `cb` and `cb2`. Only required when `B` is an integer type.
4928 The type of `a` shall be listed in one of the type lists
4929 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4930 The default version of this function calls `eval_gcd(b, cb, B(a))`.][[space]]]
4931 [[`eval_lcm(b, cb, a)`][`void`][Sets `b` to the least common multiple of `cb` and `cb2`. Only required when `B` is an integer type.
4932 The type of `a` shall be listed in one of the type lists
4933 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4934 The default version of this function calls `eval_lcm(b, cb, B(a))`.][[space]]]
4935 [[`eval_gcd(b, a, cb)`][`void`][Sets `b` to the greatest common divisor of `cb` and `a`. Only required when `B` is an integer type.
4936 The type of `a` shall be listed in one of the type lists
4937 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4938 The default version of this function calls `eval_gcd(b, cb, a)`.][[space]]]
4939 [[`eval_lcm(b, a, cb)`][`void`][Sets `b` to the least common multiple of `cb` and `a`. Only required when `B` is an integer type.
4940 The type of `a` shall be listed in one of the type lists
4941 `B::signed_types`, `B::unsigned_types` or `B::float_types`.
4942 The default version of this function calls `eval_lcm(b, cb, a)`.][[space]]]
4943 [[`eval_powm(b, cb, cb2, cb3)`][`void`][Sets `b` to the result of ['(cb^cb2)%cb3].
4944 The default version of this function is synthesised from other operations above.][[space]]]
4945 [[`eval_powm(b, cb, cb2, a)`][`void`][Sets `b` to the result of ['(cb^cb2)%a].
4946 The type of `a` shall be listed in one of the type lists
4947 `B::signed_types`, `B::unsigned_types`.
4948 The default version of this function is synthesised from other operations above.][[space]]]
4949 [[`eval_powm(b, cb, a, cb2)`][`void`][Sets `b` to the result of ['(cb^a)%cb2].
4950 The type of `a` shall be listed in one of the type lists
4951 `B::signed_types`, `B::unsigned_types`.
4952 The default version of this function is synthesised from other operations above.][[space]]]
4953 [[`eval_powm(b, cb, a, a2)`][`void`][Sets `b` to the result of ['(cb^a)%a2].
4954 The type of `a` shall be listed in one of the type lists
4955 `B::signed_types`, `B::unsigned_types`.
4956 The default version of this function is synthesised from other operations above.][[space]]]
4957 [[`eval_integer_sqrt(b, cb, b2)`][`void`][Sets `b` to the largest integer which when squared is less than `cb`, also
4958 sets `b2` to the remainder, ie to ['cb - b[super 2]].
4959 The default version of this function is synthesised from other operations above.][[space]]]
4961 [[['Sign manipulation:]]]
4962 [[`eval_abs(b, cb)`][`void`][Set `b` to the absolute value of `cb`.
4963 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if
4964 `eval_get_sign(cb) < 0`.][[space]]]
4965 [[`eval_fabs(b, cb)`][`void`][Set `b` to the absolute value of `cb`.
4966 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if
4967 `eval_get_sign(cb) < 0`.][[space]]]
4969 [[['floating-point functions:]]]
4970 [[`eval_fpclassify(cb)`][`int`][Returns one of the same values returned by `std::fpclassify`. Only required when `B` is an floating-point type.
4971 The default version of this function will only test for zero `cb`.][[space]]]
4972 [[`eval_trunc(b, cb)`][`void`][Performs the equivalent operation to `std::trunc` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4973 The default version of this function is synthesised from other operations above.][[space]]]
4974 [[`eval_round(b, cb)`][`void`][Performs the equivalent operation to `std::round` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4975 The default version of this function is synthesised from other operations above.][[space]]]
4976 [[`eval_exp(b, cb)`][`void`][Performs the equivalent operation to `std::exp` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4977 The default version of this function is synthesised from other operations above.][[space]]]
4978 [[`eval_exp2(b, cb)`][`void`][Performs the equivalent operation to `std::exp2` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4979 The default version of this function is implemented in terms of `eval_pow`.][[space]]]
4980 [[`eval_log(b, cb)`][`void`][Performs the equivalent operation to `std::log` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4981 The default version of this function is synthesised from other operations above.][[space]]]
4982 [[`eval_log10(b, cb)`][`void`][Performs the equivalent operation to `std::log10` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4983 The default version of this function is synthesised from other operations above.][[space]]]
4984 [[`eval_sin(b, cb)`][`void`][Performs the equivalent operation to `std::sin` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4985 The default version of this function is synthesised from other operations above.][[space]]]
4986 [[`eval_cos(b, cb)`][`void`][Performs the equivalent operation to `std::cos` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4987 The default version of this function is synthesised from other operations above.][[space]]]
4988 [[`eval_tan(b, cb)`][`void`][Performs the equivalent operation to `std::exp` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4989 The default version of this function is synthesised from other operations above.][[space]]]
4990 [[`eval_asin(b, cb)`][`void`][Performs the equivalent operation to `std::asin` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4991 The default version of this function is synthesised from other operations above.][[space]]]
4992 [[`eval_acos(b, cb)`][`void`][Performs the equivalent operation to `std::acos` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4993 The default version of this function is synthesised from other operations above.][[space]]]
4994 [[`eval_atan(b, cb)`][`void`][Performs the equivalent operation to `std::atan` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4995 The default version of this function is synthesised from other operations above.][[space]]]
4996 [[`eval_sinh(b, cb)`][`void`][Performs the equivalent operation to `std::sinh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4997 The default version of this function is synthesised from other operations above.][[space]]]
4998 [[`eval_cosh(b, cb)`][`void`][Performs the equivalent operation to `std::cosh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
4999 The default version of this function is synthesised from other operations above.][[space]]]
5000 [[`eval_tanh(b, cb)`][`void`][Performs the equivalent operation to `std::tanh` on argument `cb` and stores the result in `b`. Only required when `B` is an floating-point type.
5001 The default version of this function is synthesised from other operations above.][[space]]]
5002 [[`eval_fmod(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::fmod` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type.
5003 The default version of this function is synthesised from other operations above.][[space]]]
5004 [[`eval_modf(b, cb, pb)`][`void`][Performs the equivalent operation to `std::modf` on argument `cb`, and store the integer result in `*pb` and the fractional part in `b`.
5005 Only required when `B` is an floating-point type.
5006 The default version of this function is synthesised from other operations above.][[space]]]
5007 [[`eval_pow(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::pow` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type.
5008 The default version of this function is synthesised from other operations above.][[space]]]
5009 [[`eval_atan2(b, cb, cb2)`][`void`][Performs the equivalent operation to `std::atan` on arguments `cb` and `cb2`, and store the result in `b`. Only required when `B` is an floating-point type.
5010 The default version of this function is synthesised from other operations above.][[space]]]
5011 [[`eval_scalbn(b, cb, e)`][`void`][Scales value `cb` by ['r[super e]], where ['r] is the radix of the type. The default version of this function
5012 is implemented in terms of eval_ldexp, consequently this function must be provided for types with a radix other than 2.]]
5013 [[`eval_scalbln(b, cb, e)`][`void`][Calls `eval_scalbn(b, cb, e)`.]]
5014 [[`eval_ilogb(cb)`][`B::exponent_type`][Returns the exponent ['e] of value `cb` such that ['1 <= cb*r[super -e] < r], where ['r] is the radix of type B.
5015 The default version of this function is implemented in terms of eval_frexp, consequently this function must be provided for types with a radix other than 2.]]
5016 [[`eval_remquo(b, cb, cb2, pi)`][`void`][Sets `b = cb - n * cb2` and stores `n` in `*pi`.]]
5017 [[`eval_remquo(b, cb, a, pi)`][`void`][Default version converts a to type B and calls the overload above.]]
5018 [[`eval_remquo(b, a, cb, pi)`][`void`][Default version converts a to type B and calls the overload above.]]
5019 [[`eval_remainder(b, cb, cb2)`][`void`][Default version calls eval_remquo with a dummy final argument.]]
5020 [[`eval_remainder(b, cb, a)`][`void`][Default version calls eval_remquo with a dummy final argument.]]
5021 [[`eval_remainder(b, a, cb)`][`void`][Default version calls eval_remquo with a dummy final argument.]]
5023 [[`eval_fdim(b, cb, cb2)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]]
5024 [[`eval_fdim(b, cb, a)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]]
5025 [[`eval_fdim(b, a, cb)`][`void`][Default version sets `b = cb - cb2` if `cb > cb2` and zero otherwise. Special cases are handled as in the C99 annex.]]
5027 [[`eval_fmax(b, cb, cb2)`][`void`][Sets `b` to the larger of `cb` and `cb2`.]]
5028 [[`eval_fmax(b, cb, a)`][`void`][Sets `b` to the larger of `cb` and `a`.]]
5029 [[`eval_fmax(b, a, cb)`][`void`][Sets `b` to the larger of `cb` and `a`.]]
5030 [[`eval_fmin(b, cb, cb2)`][`void`][Sets `b` to the smaller of `cb` and `cb2`.]]
5031 [[`eval_fmin(b, cb, a)`][`void`][Sets `b` to the smaller of `cb` and `a`.]]
5032 [[`eval_fmin(b, a, cb)`][`void`][Sets `b` to the smaller of `cb` and `a`.]]
5034 [[`eval_hypot(b, cb, cb2)`][`void`][Sets `b` to the square root of the sum of the squares of `cb` and `cb2` without undue over or under flow.]]
5035 [[`eval_hypot(b, cb, a)`][`void`][As above.]]
5036 [[`eval_hypot(b, a, cb)`][`void`][As above.]]
5038 [[`eval_logb(b, cb)`][`B::exponent_type`][Sets `b` to the exponent ['e] of value `cb` such that ['1 <= cb*r[super -b] < r], where ['r] is the radix of type B.
5039 The default version of this function is implemented in terms of `eval_ilogb`.]]
5040 [[`eval_nearbyint(b, cb)`][`void`][Calls `eval_round(b, cb)`.]]
5041 [[`eval_rint(b, cb)`][`void`][Calls `eval_nearbyint(b, cb)`.]]
5042 [[`eval_log2(b, cb)`][`void`][Sets `b` to the logarithm base 2 of `cb`.]]
5045 [[`hash_value(cb)`][`std::size_t`]
5046 [Returns a hash value for the argument that is suitable for use with `std::hash` etc. If not provided then no automatic hashing support will be available for the number type.]]
5049 When the tables above place no ['throws] requirements on an operation, then it is up to each type modelling this concept to
5050 decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or
5051 inherit from the type `std::runtime_error`. For example, a floating-point type might choose to throw `std::overflow_error`
5052 whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero.
5055 The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name -
5056 in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.]
5058 [h4 Overloadable Functions]
5060 Some of the C99 math functions do not have `eval_` functions but must be overloaded directly: these functions
5061 are either trivial or are forwarded to the Boost.Math implementations by default.
5062 The full list of these functions is:
5064 int sign (const ``['number-or-expression-template-type]``&);
5065 int signbit (const ``['number-or-expression-template-type]``&);
5066 ``['number]`` changesign (const ``['number-or-expression-template-type]``&);
5067 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
5068 ``['number]`` asinh (const ``['number-or-expression-template-type]``&);
5069 ``['number]`` acosh (const ``['number-or-expression-template-type]``&);
5070 ``['number]`` atanh (const ``['number-or-expression-template-type]``&);
5071 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&);
5072 ``['number]`` erf (const ``['number-or-expression-template-type]``&);
5073 ``['number]`` erfc (const ``['number-or-expression-template-type]``&);
5074 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&);
5075 ``['number]`` log1p (const ``['number-or-expression-template-type]``&);
5076 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&);
5077 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&);
5078 long lrint (const ``['number-or-expression-template-type]``&);
5079 long long llrint (const ``['number-or-expression-template-type]``&);
5080 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
5081 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&);
5085 [section:headers Header File Structure]
5087 [table Top level headers
5088 [[Header][Contains]]
5089 [[cpp_int.hpp][The `cpp_int` backend type.]]
5090 [[gmp.hpp][Defines all [gmp] related backends.]]
5091 [[miller_rabin.hpp][Miller Rabin primality testing code.]]
5092 [[number.hpp][Defines the `number` backend, is included by all the backend headers.]]
5093 [[mpfr.hpp][Defines the mpfr_float_backend backend.]]
5094 [[random.hpp][Defines code to interoperate with Boost.Random.]]
5095 [[rational_adaptor.hpp][Defines the `rational_adaptor` backend.]]
5096 [[cpp_dec_float.hpp][Defines the `cpp_dec_float` backend.]]
5097 [[tommath.hpp][Defines the `tommath_int` backend.]]
5098 [[concepts/number_archetypes.hpp][Defines a backend concept archetypes for testing use.]]
5101 [table Implementation Headers
5102 [[Header][Contains]]
5103 [[cpp_int/add.hpp][Add and subtract operators for `cpp_int_backend`.]]
5104 [[cpp_int/bitwise.hpp][Bitwise operators for `cpp_int_backend`.]]
5105 [[cpp_int/checked.hpp][Helper functions for checked arithmetic for `cpp_int_backend`.]]
5106 [[cpp_int/comparison.hpp][Comparison operators for `cpp_int_backend`.]]
5107 [[cpp_int/cpp_int_config.hpp][Basic setup and configuration for `cpp_int_backend`.]]
5108 [[cpp_int/divide.hpp][Division and modulus operators for `cpp_int_backend`.]]
5109 [[cpp_int/limits.hpp][`numeric_limits` support for `cpp_int_backend`.]]
5110 [[cpp_int/misc.hpp][Miscellaneous operators for `cpp_int_backend`.]]
5111 [[cpp_int/multiply.hpp][Multiply operators for `cpp_int_backend`.]]
5112 [[detail/big_lanczos.hpp][Lanczos support for Boost.Math integration.]]
5113 [[detail/default_ops.hpp][Default versions of the optional backend non-member functions.]]
5114 [[detail/generic_interconvert.hpp][Generic interconversion routines.]]
5115 [[detail/number_base.hpp][All the expression template code, metaprogramming, and operator overloads for `number`.]]
5116 [[detail/no_et_ops.hpp][The non-expression template operators.]]
5117 [[detail/functions/constants.hpp][Defines constants used by the floating-point functions.]]
5118 [[detail/functions/pow.hpp][Defines default versions of the power and exponential related floating-point functions.]]
5119 [[detail/functions/trig.hpp][Defines default versions of the trigonometric related floating-point functions.]]
5126 [section:perf Performance Comparison]
5128 [section:overhead The Overhead in the Number Class Wrapper]
5130 Using a simple [@../../performance/arithmetic_backend.hpp backend class] that wraps any built in arithmetic type
5131 we can measure the overhead involved in wrapping a type inside the `number` frontend, and the effect that turning
5132 on expression templates has. The following table compares the performance between `double` and a `double` wrapped
5133 inside class `number`:
5136 [[Type][Bessel Function Evaluation][Non-Central T Evaluation]]
5137 [[`double`] [[*1.0 (0.016s)]] [[*1.0] (0.46s)]]
5138 [[`number<arithmetic_backend<double>, et_off>`] [1.2 (0.019s)] [[*1.0](0.46s)]]
5139 [[`number<arithmetic_backend<double>, et_on>`] [1.2 (0.019s)] [1.7 (0.79s)]]
5142 As you can see whether or not there is an overhead, and how large it is depends on the actual situation,
5143 but the overhead is in any cases small. Expression templates generally add a greater overhead the
5144 more complex the expression becomes due to the logic of figuring out how to best unpack and evaluate
5145 the expression, but of course this is also the situation where you save more temporaries. For a
5146 "trivial" backend like this, saving temporaries has no benefit, but for larger types it becomes
5149 The following table compares arithmetic using either `long long` or `number<arithmetic_backend<long long> >`
5150 for the [@../../performance/voronoi_performance.cpp voronoi-diagram builder test]:
5153 [[Type][Relative time]]
5154 [[`long long`][[*1.0](0.0823s)]]
5155 [[`number<arithmetic_backend<long long>, et_off>`][1.05 (0.0875s)]]
5158 This test involves mainly creating a lot of temporaries and performing a small amount of arithmetic on them,
5159 with very little difference in performance between the native and "wrapped" types.
5161 The test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5162 turned on (/Ox), and used MPIR-2.3.0 and [tommath]-0.42.0. The tests were run on 32-bit
5163 Windows Vista machine.
5167 [section:realworld Floating-Point Real World Tests]
5169 These tests test the total time taken to execute all of Boost.Math's test cases for these functions.
5170 In each case the best performing library gets a relative score of 1, with the total execution time
5171 given in brackets. The first three libraries listed are the various floating-point types provided
5172 by this library, while for comparison, two popular C++ front-ends to [mpfr] ([mpfr_class] and [mpreal])
5175 [table Bessel Function Performance
5176 [[Library][50 Decimal Digits][100 Decimal Digits]]
5177 [[mpfr_float] [1.2 (5.78s)] [1.2 (9.56s)]]
5178 [[static_mpfr_float] [1.1 (5.47s)] [1.1 (9.09s)]]
5179 [[mpf_float] [[*1.0] (4.82s)] [[*1.0](8.07s)]]
5180 [[cpp_dec_float] [1.8 (8.54s)] [2.6 (20.66s)]]
5181 [[[mpfr_class]] [1.3 (6.28s)] [1.2(10.06s)]]
5182 [[[mpreal]] [2.0 (9.54s)] [1.7 (14.08s)]]
5185 [table Non-Central T Distribution Performance
5186 [[Library][50 Decimal Digits]]
5187 [[mpfr_float] [1.3 (263.27s)]]
5188 [[static_mpfr_float] [1.2 (232.88s)]]
5189 [[mpf_float] [[*1.0] (195.73s)]]
5190 [[cpp_dec_float] [1.9 (366.38s)]]
5191 [[[mpfr_class]] [1.5 (286.94s)]]
5192 [[[mpreal]] [2.0 (388.70s)]]
5195 Test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5196 turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit
5197 Windows Vista machine.
5201 [section:int_real_world Integer Real World Tests]
5203 The first set of [@../../performance/voronoi_performance.cpp tests] measure the times taken to
5204 execute the multiprecision part of the Voronoi-diagram builder from Boost.Polygon. The tests
5205 mainly create a large number of temporaries "just in case" multiprecision arithmetic is required,
5206 for comparison, also included in the tests is Boost.Polygon's own partial-multiprecision integer
5207 type which was custom written for this specific task:
5210 [[Integer Type][Relative Performance (Actual time in parenthesis)]]
5211 [[polygon::detail::extended_int][1(0.138831s)]]
5212 [[int256_t][1.19247(0.165551s)]]
5213 [[int512_t][1.23301(0.17118s)]]
5214 [[int1024_t][1.21463(0.168628s)]]
5215 [[checked_int256_t][1.31711(0.182855s)]]
5216 [[checked_int512_t][1.57413(0.218538s)]]
5217 [[checked_int1024_t][1.36992(0.190187s)]]
5218 [[cpp_int][1.63244(0.226632s)]]
5219 [[mpz_int][5.42511(0.753172s)]]
5220 [[tom_int][29.0793(4.03709s)]]
5223 Note how for this use case, any dynamic allocation is a performance killer.
5225 The next [@../../performance/miller_rabin_performance.cpp tests] measure the time taken to generate 1000 128-bit
5226 random numbers and test for primality using the Miller Rabin test. This is primarily a test of modular-exponentiation
5227 since that is the rate limiting step:
5230 [[Integer Type][Relative Performance (Actual time in parenthesis)]]
5231 [[cpp_int][5.25827(0.379597s)]]
5232 [[cpp_int (no Expression templates)][5.15675(0.372268s)]]
5233 [[cpp_int (128-bit cache)][5.10882(0.368808s)]]
5234 [[cpp_int (256-bit cache)][5.50623(0.397497s)]]
5235 [[cpp_int (512-bit cache)][4.82257(0.348144s)]]
5236 [[cpp_int (1024-bit cache)][5.00053(0.360991s)]]
5237 [[int1024_t][4.37589(0.315897s)]]
5238 [[checked_int1024_t][4.52396(0.326587s)]]
5239 [[mpz_int][1(0.0721905s)]]
5240 [[mpz_int (no Expression templates)][1.0248(0.0739806s)]]
5241 [[tom_int][2.60673(0.188181s)]]
5242 [[tom_int (no Expression templates)][2.64997(0.191303s)]]
5245 It's interesting to note that expression templates have little effect here - perhaps because the actual expressions involved
5246 are relatively trivial in this case - so the time taken for multiplication and division tends to dominate. Also note
5247 how increasing the internal cache size used by `cpp_int` is quite effective in this case in cutting out memory allocations
5248 altogether - cutting about a third off the total runtime. Finally the much quicker times from GMP and tommath are down to their
5249 much better modular-exponentiation algorithms (GMP's is about 5x faster). That's an issue which needs to be addressed
5250 in a future release for __cpp_int.
5252 Test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5253 turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit
5254 Windows Vista machine.
5258 [section:float_performance Float Algorithm Performance]
5260 Note that these tests are carefully designed to test performance of the underlying algorithms
5261 and not memory allocation or variable copying. As usual, performance results should be taken
5262 with a healthy dose of scepticism, and real-world performance may vary widely depending upon the
5263 specifics of the program. In each table relative times are given first, with the best performer
5264 given a score of 1. Total actual times are given in brackets, measured in seconds for 500000
5268 [[Backend][50 Bits][100 Bits][500 Bits]]
5269 [[cpp_dec_float][[*1] (0.0575156s)][[*1] (0.0740086s)][[*1] (0.219073s)]]
5270 [[gmp_float][2.45065 (0.14095s)][2.01398 (0.149052s)][1.09608 (0.240122s)]]
5271 [[mpfr_float][2.6001 (0.149546s)][2.12079 (0.156957s)][1.09078 (0.23896s)]]
5273 [table Operator +(int)
5274 [[Backend][50 Bits][100 Bits][500 Bits]]
5275 [[cpp_dec_float][1.46115 (0.0855392s)][2.60353 (0.114398s)][3.62562 (0.264905s)]]
5276 [[gmp_float][[*1] (0.0585424s)][[*1] (0.0439398s)][[*1] (0.0730648s)]]
5277 [[mpfr_float][2.40441 (0.14076s)][3.2877 (0.144461s)][2.40379 (0.175632s)]]
5279 [table Operator +(unsigned long long)
5280 [[Backend][50 Bits][100 Bits][500 Bits]]
5281 [[cpp_dec_float][[*1] (0.118146s)][[*1] (0.144714s)][[*1] (0.315639s)]]
5282 [[gmp_float][4.5555 (0.538213s)][3.83096 (0.554395s)][1.95079 (0.615745s)]]
5283 [[mpfr_float][5.74477 (0.678719s)][4.85295 (0.702291s)][2.70354 (0.853342s)]]
5285 [table Operator +=(unsigned long long)
5286 [[Backend][50 Bits][100 Bits][500 Bits]]
5287 [[cpp_dec_float][[*1] (0.101188s)][[*1] (0.122394s)][[*1] (0.251975s)]]
5288 [[gmp_float][5.199 (0.526079s)][4.39327 (0.537712s)][2.42151 (0.610159s)]]
5289 [[mpfr_float][6.08318 (0.615547s)][5.18525 (0.634645s)][3.1022 (0.781677s)]]
5292 [[Backend][50 Bits][100 Bits][500 Bits]]
5293 [[cpp_dec_float][[*1] (0.0895163s)][[*1] (0.129248s)][1.5088 (0.374512s)]]
5294 [[gmp_float][1.72566 (0.154474s)][1.22567 (0.158415s)][[*1] (0.248219s)]]
5295 [[mpfr_float][1.83764 (0.164499s)][1.34284 (0.173559s)][1.00226 (0.248781s)]]
5297 [table Operator -(int)
5298 [[Backend][50 Bits][100 Bits][500 Bits]]
5299 [[cpp_dec_float][[*1] (0.105285s)][[*1] (0.142741s)][[*1] (0.278718s)]]
5300 [[gmp_float][2.34437 (0.246828s)][1.28814 (0.183871s)][1.00731 (0.280754s)]]
5301 [[mpfr_float][2.8032 (0.295136s)][2.09178 (0.298582s)][1.25213 (0.34899s)]]
5303 [table Operator -(unsigned long long)
5304 [[Backend][50 Bits][100 Bits][500 Bits]]
5305 [[cpp_dec_float][[*1] (0.13719s)][[*1] (0.184428s)][[*1] (0.344212s)]]
5306 [[gmp_float][4.0804 (0.559791s)][3.06776 (0.565781s)][2.07736 (0.715053s)]]
5307 [[mpfr_float][5.10114 (0.699828s)][3.88684 (0.716843s)][2.50074 (0.860784s)]]
5309 [table Operator -=(unsigned long long)
5310 [[Backend][50 Bits][100 Bits][500 Bits]]
5311 [[cpp_dec_float][[*1] (0.100984s)][[*1] (0.123148s)][[*1] (0.246181s)]]
5312 [[gmp_float][5.68353 (0.573944s)][4.68636 (0.577116s)][2.6958 (0.663655s)]]
5313 [[mpfr_float][6.19738 (0.625834s)][5.18544 (0.638577s)][3.18738 (0.784673s)]]
5316 [[Backend][50 Bits][100 Bits][500 Bits]]
5317 [[cpp_dec_float][1.03667 (0.284251s)][1.30576 (0.536527s)][1.44686 (4.81057s)]]
5318 [[gmp_float][[*1] (0.274196s)][[*1] (0.410891s)][[*1] (3.32484s)]]
5319 [[mpfr_float][1.24537 (0.341477s)][1.15785 (0.475749s)][1.1796 (3.92199s)]]
5321 [table Operator *(int)
5322 [[Backend][50 Bits][100 Bits][500 Bits]]
5323 [[cpp_dec_float][3.97453 (0.240262s)][9.91222 (0.463473s)][50.7926 (4.36527s)]]
5324 [[gmp_float][[*1] (0.0604505s)][[*1] (0.0467577s)][[*1] (0.0859431s)]]
5325 [[mpfr_float][2.56974 (0.155342s)][3.56312 (0.166603s)][3.22964 (0.277565s)]]
5327 [table Operator *(unsigned long long)
5328 [[Backend][50 Bits][100 Bits][500 Bits]]
5329 [[cpp_dec_float][[*1] (0.331877s)][1.01058 (0.586122s)][6.688 (4.7931s)]]
5330 [[gmp_float][1.72433 (0.572266s)][[*1] (0.579987s)][[*1] (0.716672s)]]
5331 [[mpfr_float][2.5553 (0.848047s)][1.74987 (1.0149s)][1.80403 (1.2929s)]]
5333 [table Operator *=(unsigned long long)
5334 [[Backend][50 Bits][100 Bits][500 Bits]]
5335 [[cpp_dec_float][[*1] (0.321397s)][1.00772 (0.574887s)][6.65946 (4.7468s)]]
5336 [[gmp_float][1.77419 (0.570218s)][[*1] (0.570482s)][[*1] (0.712791s)]]
5337 [[mpfr_float][2.62172 (0.842611s)][1.77691 (1.01369s)][1.77511 (1.26528s)]]
5340 [[Backend][50 Bits][100 Bits][500 Bits]]
5341 [[cpp_dec_float][2.96096 (4.00777s)][4.53244 (7.86435s)][6.11936 (51.5509s)]]
5342 [[gmp_float][[*1] (1.35354s)][[*1] (1.73512s)][[*1] (8.42422s)]]
5343 [[mpfr_float][1.30002 (1.75963s)][1.39045 (2.41261s)][1.66762 (14.0484s)]]
5345 [table Operator /(int)
5346 [[Backend][50 Bits][100 Bits][500 Bits]]
5347 [[cpp_dec_float][8.60726 (1.8181s)][15.4122 (3.67479s)][34.5119 (24.729s)]]
5348 [[gmp_float][1.24394 (0.262756s)][[*1] (0.238433s)][[*1] (0.716536s)]]
5349 [[mpfr_float][[*1] (0.211229s)][1.12178 (0.26747s)][1.02237 (0.732562s)]]
5351 [table Operator /(unsigned long long)
5352 [[Backend][50 Bits][100 Bits][500 Bits]]
5353 [[cpp_dec_float][2.10976 (1.97569s)][3.73601 (3.9133s)][11.3085 (25.4533s)]]
5354 [[gmp_float][[*1] (0.936452s)][[*1] (1.04746s)][[*1] (2.25081s)]]
5355 [[mpfr_float][1.3423 (1.257s)][1.51575 (1.58768s)][3.31513 (7.46175s)]]
5357 [table Operator /=(unsigned long long)
5358 [[Backend][50 Bits][100 Bits][500 Bits]]
5359 [[cpp_dec_float][2.17401 (1.96883s)][3.79591 (3.8965s)][11.2328 (25.2606s)]]
5360 [[gmp_float][[*1] (0.905621s)][[*1] (1.0265s)][[*1] (2.24882s)]]
5361 [[mpfr_float][1.37953 (1.24933s)][1.53073 (1.57129s)][3.30546 (7.43339s)]]
5363 [table Operator construct
5364 [[Backend][50 Bits][100 Bits][500 Bits]]
5365 [[cpp_dec_float][[*1] (0.00929804s)][[*1] (0.0268321s)][[*1] (0.0310685s)]]
5366 [[gmp_float][30.8781 (0.287106s)][7.59969 (0.203916s)][6.51873 (0.202527s)]]
5367 [[mpfr_float][23.5296 (0.218779s)][8.11058 (0.217624s)][7.16325 (0.222552s)]]
5369 [table Operator construct(unsigned)
5370 [[Backend][50 Bits][100 Bits][500 Bits]]
5371 [[cpp_dec_float][[*1] (0.0603971s)][[*1] (0.0735485s)][[*1] (0.116464s)]]
5372 [[gmp_float][3.91573 (0.236498s)][2.88171 (0.211945s)][1.81075 (0.210887s)]]
5373 [[mpfr_float][4.90052 (0.295977s)][4.01118 (0.295017s)][2.62005 (0.305141s)]]
5375 [table Operator construct(unsigned long long)
5376 [[Backend][50 Bits][100 Bits][500 Bits]]
5377 [[cpp_dec_float][[*1] (0.0610288s)][[*1] (0.0759005s)][[*1] (0.118511s)]]
5378 [[gmp_float][8.26247 (0.504249s)][6.69042 (0.507806s)][4.32819 (0.51294s)]]
5379 [[mpfr_float][10.1593 (0.620013s)][8.45884 (0.64203s)][5.51472 (0.653557s)]]
5382 [[Backend][50 Bits][100 Bits][500 Bits]]
5383 [[cpp_dec_float][2.95848 (0.0223061s)][3.33461 (0.033471s)][3.0159 (0.132732s)]]
5384 [[gmp_float][[*1] (0.00753971s)][[*1] (0.0100374s)][[*1] (0.0440106s)]]
5385 [[mpfr_float][1.25424 (0.00945658s)][1.24943 (0.012541s)][1.09428 (0.0481601s)]]
5388 Test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5389 turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit
5390 Windows Vista machine.
5394 [section:integer_performance Integer Algorithm Performance]
5396 Note that these tests are carefully designed to test performance of the underlying algorithms
5397 and not memory allocation or variable copying. As usual, performance results should be taken
5398 with a healthy dose of scepticism, and real-world performance may vary widely depending upon the
5399 specifics of the program. In each table relative times are given first, with the best performer
5400 given a score of 1. Total actual times are given in brackets, measured in seconds for 500000
5404 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5405 [[cpp_int][1.23704 (0.0274266s)][1.09358 (0.0383278s)][1.26645 (0.0558828s)][1.32188 (0.0916899s)]]
5406 [[cpp_int(fixed)][1.62044 (0.0359271s)][1.5277 (0.053543s)][1.73059 (0.076363s)][1.71537 (0.118983s)]]
5407 [[gmp_int][1.87515 (0.0415741s)][1.21699 (0.042653s)][1.15599 (0.0510088s)][[*1] (0.0693631s)]]
5408 [[tommath_int][[*1] (0.0221711s)][[*1] (0.035048s)][[*1] (0.0441255s)][1.04441 (0.0724435s)]]
5410 [table Operator +(int)
5411 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5412 [[cpp_int][[*1] (0.0155377s)][[*1] (0.0209523s)][[*1] (0.0306377s)][[*1] (0.043125s)]]
5413 [[cpp_int(fixed)][1.31904 (0.0204948s)][1.76211 (0.0369203s)][1.52941 (0.0468577s)][1.60412 (0.0691778s)]]
5414 [[gmp_int][1.96204 (0.0304855s)][2.02569 (0.0424428s)][2.11505 (0.0648002s)][2.65993 (0.114709s)]]
5415 [[tommath_int][14.0654 (0.218543s)][10.8239 (0.226786s)][7.76691 (0.23796s)][6.10039 (0.263079s)]]
5417 [table Operator +(unsigned long long)
5418 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5419 [[cpp_int][[*1] (0.026624s)][[*1] (0.0291407s)][[*1] (0.0373209s)][[*1] (0.0464919s)]]
5420 [[cpp_int(fixed)][1.31378 (0.034978s)][1.54897 (0.045138s)][1.53649 (0.0573431s)][1.27833 (0.0594319s)]]
5421 [[gmp_int][25.5775 (0.680974s)][24.0117 (0.699717s)][19.5633 (0.730121s)][16.8939 (0.785432s)]]
5422 [[tommath_int][19.4694 (0.518354s)][18.4246 (0.536907s)][14.7715 (0.551288s)][12.3637 (0.574812s)]]
5424 [table Operator +=(unsigned long long)
5425 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5426 [[cpp_int][1.18405 (0.0196905s)][1.22304 (0.0206476s)][1.25861 (0.0217397s)][1.29525 (0.0220829s)]]
5427 [[cpp_int(fixed)][[*1] (0.0166298s)][[*1] (0.0168822s)][[*1] (0.0172728s)][[*1] (0.0170492s)]]
5428 [[gmp_int][39.9082 (0.663668s)][39.4584 (0.666147s)][38.5504 (0.665873s)][39.2231 (0.668722s)]]
5429 [[tommath_int][30.6219 (0.509238s)][30.4135 (0.513447s)][30.9077 (0.533863s)][32.3086 (0.550835s)]]
5432 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5433 [[cpp_int][1.06986 (0.0296064s)][[*1] (0.0381508s)][1.05932 (0.053186s)][1.1766 (0.0844721s)]]
5434 [[cpp_int(fixed)][1.3304 (0.0368163s)][1.44506 (0.0551303s)][1.4431 (0.0724545s)][1.57255 (0.112898s)]]
5435 [[gmp_int][1.48072 (0.0409761s)][1.19003 (0.0454007s)][1.0794 (0.0541942s)][[*1] (0.0717934s)]]
5436 [[tommath_int][[*1] (0.0276731s)][1.10891 (0.0423057s)][[*1] (0.0502076s)][1.08479 (0.0778811s)]]
5438 [table Operator -(int)
5439 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5440 [[cpp_int][[*1] (0.0147372s)][[*1] (0.0170001s)][[*1] (0.0232882s)][[*1] (0.0310734s)]]
5441 [[cpp_int(fixed)][1.4267 (0.0210256s)][1.98887 (0.0338109s)][1.83788 (0.0428009s)][1.81269 (0.0563264s)]]
5442 [[gmp_int][2.07504 (0.0305803s)][2.40928 (0.0409579s)][2.58711 (0.0602493s)][3.26438 (0.101435s)]]
5443 [[tommath_int][13.5424 (0.199577s)][12.1793 (0.207048s)][9.28855 (0.216314s)][7.49327 (0.232842s)]]
5445 [table Operator -(unsigned long long)
5446 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5447 [[cpp_int][[*1] (0.0277377s)][[*1] (0.0296807s)][[*1] (0.0372392s)][[*1] (0.0455855s)]]
5448 [[cpp_int(fixed)][1.19867 (0.0332484s)][1.48639 (0.0441169s)][1.43253 (0.0533464s)][1.27697 (0.0582111s)]]
5449 [[gmp_int][24.1794 (0.670683s)][22.9073 (0.679904s)][18.8758 (0.702922s)][16.5837 (0.755975s)]]
5450 [[tommath_int][18.149 (0.503413s)][17.4116 (0.516787s)][14.0411 (0.52288s)][11.8237 (0.538987s)]]
5452 [table Operator -=(unsigned long long)
5453 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5454 [[cpp_int][1.26896 (0.0203467s)][1.25722 (0.0206147s)][1.36108 (0.0225485s)][1.18351 (0.0226161s)]]
5455 [[cpp_int(fixed)][[*1] (0.0160342s)][[*1] (0.0163971s)][[*1] (0.0165667s)][[*1] (0.0191094s)]]
5456 [[gmp_int][41.1339 (0.659547s)][40.3982 (0.662411s)][39.925 (0.661425s)][34.636 (0.661874s)]]
5457 [[tommath_int][31.1543 (0.499533s)][31.0303 (0.508806s)][30.7699 (0.509756s)][27.7054 (0.529434s)]]
5460 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5461 [[cpp_int][1.11839 (0.0757577s)][1.61061 (0.207951s)][1.4501 (0.696912s)][1.72796 (2.64108s)]]
5462 [[cpp_int(fixed)][1.01115 (0.0684934s)][1.28687 (0.166152s)][[*1] (0.480595s)][[*1] (1.52844s)]]
5463 [[gmp_int][[*1] (0.0677384s)][[*1] (0.129113s)][1.09011 (0.523902s)][1.03374 (1.58s)]]
5464 [[tommath_int][1.6322 (0.110562s)][2.71751 (0.350866s)][2.05222 (0.986288s)][2.0644 (3.15531s)]]
5466 [table Operator *(int)
5467 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5468 [[cpp_int][1.01611 (0.0229536s)][1.12175 (0.0298152s)][1.16413 (0.0416439s)][1.31747 (0.0666043s)]]
5469 [[cpp_int(fixed)][1.30215 (0.0294152s)][1.669 (0.0443606s)][1.72395 (0.0616701s)][1.88315 (0.095202s)]]
5470 [[gmp_int][[*1] (0.0225897s)][[*1] (0.0265791s)][[*1] (0.0357725s)][[*1] (0.0505547s)]]
5471 [[tommath_int][10.8281 (0.244603s)][10.1516 (0.26982s)][8.76424 (0.313519s)][8.04364 (0.406644s)]]
5473 [table Operator *(unsigned long long)
5474 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5475 [[cpp_int][[*1] (0.0570721s)][[*1] (0.0856141s)][[*1] (0.143279s)][[*1] (0.252785s)]]
5476 [[cpp_int(fixed)][1.10857 (0.0632686s)][1.2951 (0.110878s)][1.20827 (0.173121s)][1.18463 (0.299456s)]]
5477 [[gmp_int][12.0605 (0.68832s)][8.13434 (0.696415s)][5.21762 (0.747577s)][3.11601 (0.787681s)]]
5478 [[tommath_int][10.0524 (0.57371s)][7.33116 (0.627651s)][4.85202 (0.695193s)][3.35808 (0.848871s)]]
5480 [table Operator *=(unsigned long long)
5481 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5482 [[cpp_int][111.27 (7.43118s)][67.7078 (7.34138s)][43.3851 (7.4075s)][25.3089 (7.55455s)]]
5483 [[cpp_int(fixed)][[*1] (0.0667848s)][[*1] (0.108427s)][[*1] (0.170738s)][[*1] (0.298493s)]]
5484 [[gmp_int][46.3718 (3.09693s)][28.4639 (3.08626s)][18.1719 (3.10264s)][10.5223 (3.14083s)]]
5485 [[tommath_int][276.674 (18.4776s)][169.146 (18.34s)][108.491 (18.5236s)][63.3261 (18.9024s)]]
5488 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5489 [[cpp_int][2.68035 (0.595251s)][2.04702 (0.707471s)][1.62314 (0.921536s)][1.43112 (1.38811s)]]
5490 [[cpp_int(fixed)][[*1] (0.222079s)][[*1] (0.34561s)][[*1] (0.567748s)][[*1] (0.969945s)]]
5491 [[gmp_int][3.79283 (0.842308s)][2.73668 (0.945824s)][1.86649 (1.05969s)][1.32141 (1.2817s)]]
5492 [[tommath_int][13.2531 (2.94324s)][11.2054 (3.87271s)][9.83293 (5.58262s)][13.0164 (12.6252s)]]
5494 [table Operator /(int)
5495 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5496 [[cpp_int][4.06026 (0.225473s)][3.45732 (0.340049s)][3.00195 (0.547957s)][2.80587 (0.978029s)]]
5497 [[cpp_int(fixed)][2.43766 (0.135367s)][2.56264 (0.252052s)][2.44011 (0.445402s)][2.38009 (0.829617s)]]
5498 [[gmp_int][[*1] (0.0555316s)][[*1] (0.0983563s)][[*1] (0.182534s)][[*1] (0.348566s)]]
5499 [[tommath_int][35.9988 (1.99907s)][27.1024 (2.66569s)][21.8333 (3.98531s)][25.8066 (8.99528s)]]
5501 [table Operator /(unsigned long long)
5502 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5503 [[cpp_int][1.50505 (0.705756s)][1.39347 (1.58556s)][2.63348 (3.57438s)][4.75451 (8.52733s)]]
5504 [[cpp_int(fixed)][[*1] (0.468925s)][1.12378 (1.27869s)][2.29966 (3.12128s)][4.4844 (8.04288s)]]
5505 [[gmp_int][2.17234 (1.01866s)][[*1] (1.13785s)][[*1] (1.35728s)][[*1] (1.79352s)]]
5506 [[tommath_int][4.74612 (2.22557s)][2.70088 (3.07319s)][3.65634 (4.96268s)][6.79408 (12.1853s)]]
5508 [table Operator /=(unsigned long long)
5509 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5510 [[cpp_int][1.76281 (0.0574966s)][1.76471 (0.0604224s)][1.56085 (0.0716403s)][1.31422 (0.124043s)]]
5511 [[cpp_int(fixed)][[*1] (0.0326164s)][[*1] (0.0342393s)][[*1] (0.0458981s)][[*1] (0.0943852s)]]
5512 [[gmp_int][20.2862 (0.661664s)][19.4043 (0.664389s)][14.4881 (0.664976s)][7.14238 (0.674135s)]]
5513 [[tommath_int][32.9555 (1.07489s)][30.1525 (1.0324s)][22.8324 (1.04796s)][11.7456 (1.10861s)]]
5516 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5517 [[cpp_int][1.8501 (0.364131s)][1.46527 (0.476653s)][1.27509 (0.689738s)][1.20064 (1.11769s)]]
5518 [[cpp_int(fixed)][[*1] (0.196817s)][[*1] (0.325301s)][[*1] (0.540932s)][[*1] (0.930916s)]]
5519 [[gmp_int][3.2533 (0.640305s)][2.15441 (0.700832s)][1.47898 (0.800029s)][1.07439 (1.00016s)]]
5520 [[tommath_int][15.3501 (3.02116s)][12.1106 (3.9396s)][11.0689 (5.98752s)][13.5535 (12.6172s)]]
5522 [table Operator %(int)
5523 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5524 [[cpp_int][1.82761 (0.104331s)][2.01496 (0.202512s)][2.10004 (0.389523s)][2.17252 (0.768097s)]]
5525 [[cpp_int(fixed)][1.78851 (0.102099s)][1.96844 (0.197838s)][2.02956 (0.376451s)][2.07257 (0.73276s)]]
5526 [[gmp_int][[*1] (0.057086s)][[*1] (0.100505s)][[*1] (0.185483s)][[*1] (0.353552s)]]
5527 [[tommath_int][36.3018 (2.07233s)][26.3075 (2.64402s)][21.9525 (4.07183s)][25.6759 (9.07775s)]]
5529 [table Operator construct
5530 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5531 [[cpp_int][1.40211 (0.0026854s)][[*1] (0.00278639s)][[*1] (0.00322813s)][[*1] (0.0027185s)]]
5532 [[cpp_int(fixed)][[*1] (0.00191526s)][1.40721 (0.00392103s)][1.90346 (0.00614463s)][2.14621 (0.00583447s)]]
5533 [[gmp_int][98.705 (0.189046s)][68.9726 (0.192184s)][58.8994 (0.190135s)][70.0525 (0.190438s)]]
5534 [[tommath_int][105.602 (0.202255s)][74.1994 (0.206748s)][63.6455 (0.205456s)][76.8935 (0.209035s)]]
5536 [table Operator construct(unsigned)
5537 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5538 [[cpp_int][1.73436 (0.00348927s)][[*1] (0.00263476s)][[*1] (0.0027009s)][[*1] (0.00318651s)]]
5539 [[cpp_int(fixed)][[*1] (0.00201185s)][1.36851 (0.0036057s)][2.07362 (0.00560064s)][1.66856 (0.00531688s)]]
5540 [[gmp_int][97.2414 (0.195635s)][76.3759 (0.201232s)][72.7396 (0.196462s)][63.8129 (0.20334s)]]
5541 [[tommath_int][210.112 (0.422713s)][162.652 (0.42855s)][158.33 (0.427634s)][134.626 (0.428987s)]]
5543 [table Operator construct(unsigned long long)
5544 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5545 [[cpp_int][2.34403 (0.00739542s)][1.66376 (0.00713834s)][1.22989 (0.0074969s)][1.23708 (0.00711417s)]]
5546 [[cpp_int(fixed)][[*1] (0.00315501s)][[*1] (0.00429049s)][[*1] (0.00609561s)][[*1] (0.0057508s)]]
5547 [[gmp_int][222.866 (0.703144s)][164.331 (0.705059s)][115.363 (0.70321s)][122.347 (0.703596s)]]
5548 [[tommath_int][218.681 (0.689941s)][163.796 (0.702765s)][114.57 (0.698376s)][122.422 (0.704027s)]]
5551 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5552 [[cpp_int][1.16358 (2.74442s)][1.39847 (8.11559s)][1.64677 (22.2518s)][1.95096 (64.4961s)]]
5553 [[cpp_int(fixed)][[*1] (2.35859s)][1.30986 (7.60133s)][1.67681 (22.6577s)][2.0895 (69.0758s)]]
5554 [[gmp_int][1.03392 (2.4386s)][[*1] (5.80319s)][[*1] (13.5124s)][[*1] (33.0586s)]]
5555 [[tommath_int][5.25978 (12.4057s)][4.4619 (25.8932s)][4.15577 (56.1542s)][3.91192 (129.323s)]]
5557 [table Operator powm
5558 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5559 [[cpp_int][2.50722 (2.91621s)][3.5561 (13.406s)][4.37066 (73.483s)][4.88831 (473.91s)]]
5560 [[cpp_int(fixed)][1.93385 (2.24931s)][3.18107 (11.9922s)][4.20753 (70.7403s)][4.8158 (466.88s)]]
5561 [[gmp_int][[*1] (1.16313s)][[*1] (3.76986s)][[*1] (16.8128s)][[*1] (96.9476s)]]
5562 [[tommath_int][1.44081 (1.67584s)][1.8794 (7.08507s)][2.19115 (36.8394s)][2.17186 (210.557s)]]
5565 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5566 [[cpp_int][1.17175 (0.00160006s)][1.41999 (0.00329476s)][1.40856 (0.00813784s)][1.52964 (0.0229767s)]]
5567 [[cpp_int(fixed)][[*1] (0.00136554s)][[*1] (0.00232027s)][[*1] (0.00577741s)][1.14754 (0.0172372s)]]
5568 [[gmp_int][1.50501 (0.00205515s)][1.52968 (0.00354926s)][1.01989 (0.0058923s)][[*1] (0.015021s)]]
5569 [[tommath_int][12.2161 (0.0166816s)][16.9577 (0.0393463s)][18.7474 (0.108311s)][22.7368 (0.341528s)]]
5572 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5573 [[cpp_int][[*1] (0.0301617s)][[*1] (0.0423404s)][[*1] (0.0522358s)][[*1] (0.0813156s)]]
5574 [[cpp_int(fixed)][1.0638 (0.0320861s)][1.22566 (0.0518951s)][1.28515 (0.0671305s)][1.16118 (0.094422s)]]
5575 [[gmp_int][1.76553 (0.0532514s)][1.51489 (0.0641408s)][1.70708 (0.0891706s)][1.77346 (0.14421s)]]
5576 [[tommath_int][4.37637 (0.131999s)][3.46212 (0.146587s)][2.91875 (0.152463s)][4.19621 (0.341217s)]]
5578 [table Operator |(int)
5579 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5580 [[cpp_int][[*1] (0.0289129s)][[*1] (0.0351119s)][[*1] (0.0406779s)][[*1] (0.0525891s)]]
5581 [[cpp_int(fixed)][1.06091 (0.030674s)][1.25979 (0.0442336s)][1.36194 (0.0554009s)][1.37438 (0.0722772s)]]
5582 [[gmp_int][4.92854 (0.142498s)][4.34687 (0.152627s)][3.71442 (0.151095s)][2.981 (0.156768s)]]
5583 [[tommath_int][10.9847 (0.317598s)][9.37065 (0.329021s)][8.53651 (0.347248s)][11.2155 (0.589813s)]]
5586 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5587 [[cpp_int][[*1] (0.0305149s)][[*1] (0.04217s)][[*1] (0.0525977s)][[*1] (0.0816632s)]]
5588 [[cpp_int(fixed)][1.01544 (0.0309861s)][1.24872 (0.0526585s)][1.26661 (0.066621s)][1.15965 (0.0947007s)]]
5589 [[gmp_int][1.64675 (0.0502505s)][1.47181 (0.0620663s)][1.66038 (0.0873322s)][1.67895 (0.137108s)]]
5590 [[tommath_int][4.30668 (0.131418s)][3.45859 (0.145849s)][2.91462 (0.153303s)][4.15538 (0.339342s)]]
5592 [table Operator ^(int)
5593 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5594 [[cpp_int][1.01566 (0.0296088s)][[*1] (0.0356634s)][[*1] (0.0401898s)][[*1] (0.0514097s)]]
5595 [[cpp_int(fixed)][[*1] (0.0291524s)][1.2393 (0.0441976s)][1.38556 (0.0556856s)][1.38899 (0.0714075s)]]
5596 [[gmp_int][4.68027 (0.136441s)][4.15243 (0.14809s)][3.74237 (0.150405s)][3.0483 (0.156712s)]]
5597 [[tommath_int][10.919 (0.318314s)][9.16311 (0.326788s)][8.62554 (0.346659s)][11.6212 (0.597442s)]]
5600 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5601 [[cpp_int][1.0346 (0.0303431s)][[*1] (0.0427309s)][[*1] (0.0535587s)][1.06945 (0.0828084s)]]
5602 [[cpp_int(fixed)][[*1] (0.0293284s)][1.10435 (0.04719s)][1.05262 (0.0563769s)][[*1] (0.0774309s)]]
5603 [[gmp_int][1.86057 (0.0545675s)][1.58432 (0.0676995s)][1.69164 (0.0906018s)][1.86625 (0.144505s)]]
5604 [[tommath_int][4.4157 (0.129506s)][3.60396 (0.154s)][2.95985 (0.158525s)][4.4032 (0.340944s)]]
5606 [table Operator &(int)
5607 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5608 [[cpp_int][1.05874 (0.038946s)][[*1] (0.0483903s)][[*1] (0.063842s)][[*1] (0.100361s)]]
5609 [[cpp_int(fixed)][[*1] (0.0367853s)][1.05827 (0.0512099s)][1.09114 (0.0696605s)][1.09432 (0.109826s)]]
5610 [[gmp_int][3.92298 (0.144308s)][2.99447 (0.144903s)][2.228 (0.14224s)][1.42296 (0.142809s)]]
5611 [[tommath_int][8.79208 (0.323419s)][7.02288 (0.339839s)][5.65271 (0.36088s)][6.27104 (0.629365s)]]
5614 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5615 [[cpp_int][[*1] (0.0248801s)][1.23196 (0.04s)][[*1] (0.0424149s)][[*1] (0.060157s)]]
5616 [[cpp_int(fixed)][1.08931 (0.027102s)][1.40572 (0.0456418s)][1.3475 (0.0571542s)][1.24573 (0.0749397s)]]
5617 [[gmp_int][1.05561 (0.0262636s)][[*1] (0.0324686s)][1.09914 (0.0466199s)][1.16315 (0.0699719s)]]
5618 [[tommath_int][1.60497 (0.0399319s)][2.13048 (0.0691737s)][2.31219 (0.0980712s)][2.74695 (0.165248s)]]
5621 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5622 [[cpp_int][[*1] (0.0213349s)][1.02127 (0.0295019s)][[*1] (0.0327116s)][1.13168 (0.0433804s)]]
5623 [[cpp_int(fixed)][1.13514 (0.0242181s)][1.16938 (0.0337803s)][1.46999 (0.0480859s)][1.60077 (0.061362s)]]
5624 [[gmp_int][1.26614 (0.0270129s)][[*1] (0.0288873s)][1.42219 (0.0465221s)][[*1] (0.0383329s)]]
5625 [[tommath_int][12.0066 (0.25616s)][10.2837 (0.297067s)][9.99696 (0.327017s)][16.0943 (0.616942s)]]
5628 Test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5629 turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit
5630 Windows Vista machine.
5632 Linux x86_64 results are broadly similar, except that libtommath performs much better there.
5636 [section:rational_performance Rational Type Performance]
5638 Note that these tests are carefully designed to test performance of the underlying algorithms
5639 and not memory allocation or variable copying. As usual, performance results should be taken
5640 with a healthy dose of scepticism, and real-world performance may vary widely depending upon the
5641 specifics of the program. In each table relative times are given first, with the best performer
5642 given a score of 1. Total actual times are given in brackets, measured in seconds for 500000
5646 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5647 [[cpp_rational][5.89417 (18.4116s)][6.87256 (47.4698s)][6.65008 (107.715s)][6.53801 (256.244s)]]
5648 [[mpq_rational][[*1] (3.1237s)][[*1] (6.90715s)][[*1] (16.1975s)][[*1] (39.1929s)]]
5650 [table Operator +(int)
5651 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5652 [[cpp_rational][3.62367 (2.46488s)][4.18291 (2.94603s)][4.726 (3.74866s)][6.1388 (5.56817s)]]
5653 [[mpq_rational][[*1] (0.680215s)][[*1] (0.704303s)][[*1] (0.7932s)][[*1] (0.907046s)]]
5655 [table Operator +(unsigned long long)
5656 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5657 [[cpp_rational][1.1527 (2.6378s)][1.31751 (3.09863s)][1.58996 (4.00714s)][2.15642 (5.75702s)]]
5658 [[mpq_rational][[*1] (2.28837s)][[*1] (2.35189s)][[*1] (2.52028s)][[*1] (2.66971s)]]
5660 [table Operator +=(unsigned long long)
5661 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5662 [[cpp_rational][1.18436 (2.7059s)][1.32279 (3.11099s)][1.61398 (4.05389s)][2.20048 (5.84623s)]]
5663 [[mpq_rational][[*1] (2.2847s)][[*1] (2.35183s)][[*1] (2.51174s)][[*1] (2.6568s)]]
5666 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5667 [[cpp_rational][5.81893 (18.3457s)][6.82209 (47.1928s)][6.64143 (107.498s)][6.51362 (255.137s)]]
5668 [[mpq_rational][[*1] (3.15277s)][[*1] (6.91765s)][[*1] (16.1859s)][[*1] (39.1698s)]]
5670 [table Operator -(int)
5671 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5672 [[cpp_rational][3.72441 (2.48756s)][4.27663 (2.98713s)][4.62109 (3.72114s)][6.17605 (5.56503s)]]
5673 [[mpq_rational][[*1] (0.667908s)][[*1] (0.698479s)][[*1] (0.805252s)][[*1] (0.901066s)]]
5675 [table Operator -(unsigned long long)
5676 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5677 [[cpp_rational][1.15627 (2.63239s)][1.32096 (3.12092s)][1.61044 (4.00106s)][2.19378 (5.7644s)]]
5678 [[mpq_rational][[*1] (2.27663s)][[*1] (2.36262s)][[*1] (2.48445s)][[*1] (2.62761s)]]
5680 [table Operator -=(unsigned long long)
5681 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5682 [[cpp_rational][1.1984 (2.73444s)][1.34141 (3.15698s)][1.64159 (4.06997s)][2.23017 (5.88108s)]]
5683 [[mpq_rational][[*1] (2.28174s)][[*1] (2.35348s)][[*1] (2.47929s)][[*1] (2.63706s)]]
5686 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5687 [[cpp_rational][5.4306 (32.5882s)][6.91805 (89.9436s)][6.94556 (207.307s)][6.88704 (492.151s)]]
5688 [[mpq_rational][[*1] (6.00084s)][[*1] (13.0013s)][[*1] (29.8475s)][[*1] (71.4604s)]]
5690 [table Operator *(int)
5691 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5692 [[cpp_rational][2.12892 (2.51376s)][2.47245 (3.07841s)][2.86832 (3.93619s)][3.94086 (6.02565s)]]
5693 [[mpq_rational][[*1] (1.18077s)][[*1] (1.24508s)][[*1] (1.3723s)][[*1] (1.52902s)]]
5695 [table Operator *(unsigned long long)
5696 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5697 [[cpp_rational][1.32254 (5.43565s)][1.56078 (6.73163s)][1.97701 (9.32522s)][2.85404 (15.1573s)]]
5698 [[mpq_rational][[*1] (4.11002s)][[*1] (4.313s)][[*1] (4.71682s)][[*1] (5.31082s)]]
5700 [table Operator *=(unsigned long long)
5701 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5702 [[cpp_rational][6.29806 (58.1188s)][6.30556 (59.5076s)][6.3385 (62.1007s)][6.55345 (67.6905s)]]
5703 [[mpq_rational][[*1] (9.22804s)][[*1] (9.43733s)][[*1] (9.79739s)][[*1] (10.329s)]]
5706 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5707 [[cpp_rational][4.4269 (66.8031s)][6.40103 (173.527s)][6.32347 (348.193s)][6.61148 (824.063s)]]
5708 [[mpq_rational][[*1] (15.0903s)][[*1] (27.1093s)][[*1] (55.0637s)][[*1] (124.641s)]]
5710 [table Operator /(int)
5711 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5712 [[cpp_rational][1.78772 (2.50984s)][2.10623 (3.10606s)][2.46986 (3.99358s)][3.37428 (5.96678s)]]
5713 [[mpq_rational][[*1] (1.40393s)][[*1] (1.4747s)][[*1] (1.61693s)][[*1] (1.76831s)]]
5715 [table Operator /(unsigned long long)
5716 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5717 [[cpp_rational][1.29695 (5.45454s)][1.55248 (6.85353s)][1.93237 (9.28765s)][2.75211 (14.8541s)]]
5718 [[mpq_rational][[*1] (4.20568s)][[*1] (4.41458s)][[*1] (4.80635s)][[*1] (5.39734s)]]
5720 [table Operator /=(unsigned long long)
5721 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5722 [[cpp_rational][6.19401 (58.4278s)][6.20135 (59.643s)][6.21327 (62.0338s)][6.40576 (67.6778s)]]
5723 [[mpq_rational][[*1] (9.43295s)][[*1] (9.61774s)][[*1] (9.98407s)][[*1] (10.5652s)]]
5725 [table Operator construct
5726 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5727 [[cpp_rational][[*1] (0.00978288s)][[*1] (0.0100574s)][[*1] (0.0101393s)][[*1] (0.0101847s)]]
5728 [[mpq_rational][39.1516 (0.383015s)][38.3523 (0.385725s)][37.5812 (0.381048s)][37.6007 (0.382953s)]]
5730 [table Operator construct(unsigned)
5731 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5732 [[cpp_rational][[*1] (0.0548151s)][[*1] (0.0557542s)][[*1] (0.055825s)][[*1] (0.0552808s)]]
5733 [[mpq_rational][7.21073 (0.395257s)][7.1016 (0.395944s)][7.02046 (0.391917s)][7.16881 (0.396297s)]]
5735 [table Operator construct(unsigned long long)
5736 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5737 [[cpp_rational][[*1] (0.0605156s)][[*1] (0.0616657s)][[*1] (0.0592056s)][[*1] (0.0603081s)]]
5738 [[mpq_rational][35.1604 (2.12775s)][34.7575 (2.14335s)][35.7232 (2.11502s)][35.0437 (2.11342s)]]
5741 [[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]]
5742 [[cpp_rational][5.48898 (0.0208949s)][8.49668 (0.0546688s)][10.107 (0.121897s)][10.5339 (0.310584s)]]
5743 [[mpq_rational][[*1] (0.0038067s)][[*1] (0.00643413s)][[*1] (0.0120606s)][[*1] (0.0294843s)]]
5746 Test code was compiled with Microsoft Visual Studio 2010 with all optimisations
5747 turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit
5748 Windows Vista machine.
5754 [section:map Roadmap]
5756 * Support for atomic loads and stores is not currently supported, but will become more important as a larger number of floating point algorithms become parallelized.
5758 [section:hist History]
5760 [h4 Multiprecision-3.2.3 (Boost-1.72)]
5762 * Big `constexpr` update allows __cpp_int and __float128 arithmetic to be fully `constexpr` with gcc and clang 9 or later,
5763 or any compiler supporting `std::is_constant_evaluated()`.
5765 [h4 Multiprecision-3.1.3 (Boost-1.71)]
5767 * Support hexfloat io-formatting for float128.
5768 * Fix various bugs in variable precision interconversions.
5769 * Respect uppercase for '0x' prefix outputs.
5770 * Incorporate some unit tests from the Etherium project.
5771 * Fix some gcc warnings.
5773 [h4 Multiprecision-3.1.2 (Boost-1.70)]
5775 * Fix various conversion issues in the traits classes, check for compatibility with Boost.Optional.
5776 * Prevent instantiation of `std::numeric_limits` on any old type when checking for convertibility. See [@https://github.com/boostorg/multiprecision/issues/98 #98].
5777 * Update variable precision code to accound for arbitrary precision integers. See [@https://github.com/boostorg/multiprecision/issues/103 #103].
5778 * Add support for XML serialization archives.
5779 * Fix bug in fixed precision iostream formatting in `mpf_float` and `mpfr_float`. See [@https://github.com/boostorg/multiprecision/issues/113 #113].
5780 * Add more overloads for special functions which are better handled natively by MPFR.
5781 * Fixed bug in generic `exp` implementation which could cause invariant failure.
5782 * Fixed generic conversion from float to integer to avoid undefined behaviour. See [@https://github.com/boostorg/multiprecision/issues/110 #110].
5784 [h4 Multiprecision-3.1.1 (Boost-1.69)]
5786 * Big update to better support variable precision types so that the precision of the result
5787 is always the largest of all the arguments.
5788 * Add support for allocators that are `final` in __cpp_int.
5789 * Removed use of deprecated Boost.Endian in favour of Predef.
5790 * Add support for `std::string_view`.
5791 * Fixed minor bug in constant initialization. See [@https://github.com/boostorg/multiprecision/issues/67 #67].
5792 * Make assignment of non-finite value to `cpp_int` a runtime errors. See [@https://github.com/boostorg/multiprecision/issues/58 #58].
5793 * Added typedefs for `cpp_bin_float_oct` and `cpp_complex_oct`.
5795 [h4 Multiprecision-3.1.0 (Boost-1.68)]
5797 * Support added for complex multiprecision numbers.
5798 * Changed conversion to unsigned integer types to be truncating to match standard defined behaviour.
5799 * Correct bug in MPFR string formatting.
5800 * Fix undefined behaviour in cpp_dec_float conversion from long long.
5801 * Add support for Eigen interoperability.
5802 * float128.hpp: Fix Intel on Windows build.
5803 * Fix type used in temporaries when expanding expression templates containing mixed expressions.
5804 * Fix infinite loop in gmp_float to fixed-point string conversion.
5805 * Update the expression templates to issue static_asserts with better error messages when you try and do something unsupported.
5806 * Fix bug in cpp_int where incrementing to zero doesn't set the sign correctly.
5807 * Remove erroneous use of std::move, and rely on NVRO instead.
5808 * Fix up support for changes to MPIR-3.0.
5809 * Fix various conversion errors in cpp_bin_float when the exponent type is a `long long`, or else we're converting to
5810 an integer that is wider than we are.
5811 * Fix compatibility issue with GCC-8 caused by the introduction of `std::byte`.
5813 [h4 Multiprecision-3.0.0 (Boost-1.67)]
5815 * [*Breaking Change:] When converting a multiprecision integer to a narrower type, if the value is too large (or negative) to
5816 fit in the smaller type, then the result is either the maximum (or minimum) value of the target type. This was always the intended
5817 behaviour, but was somewhat haphazardly enforced before. If you really do want just the low order N bits of a value, then you will
5818 need to mask these out prior to the case, for example: `static_cast<unsigned>(~static_cast<unsigned>(0) & my_value)`. Note that
5819 technically (to avoid undefined behaviour) you should do the same thing with built in integer types too.
5820 See [@https://svn.boost.org/trac/boost/ticket/13109 #13109].
5821 * Fix bug in conversion of decimal to rational types (zero needs special handling), see [@https://svn.boost.org/trac/boost/ticket/13148 #13148].
5822 * Fix conversion from cpp_bin_float to a wider built in integer type, see [@https://svn.boost.org/trac/boost/ticket/13301 #13301].
5823 * Improve performance heurists used in cpp_bin_float exp function.
5824 * Fix bug in floor/ceil and cpp_bin_float when the exponent type is wider than an int, see [@https://svn.boost.org/trac/boost/ticket/13264 #13264].
5825 * Disable explicit conversion operator when the target type is already constructible from this type, see [@https://github.com/boostorg/multiprecision/issues/30 #30].
5826 * Fix support for changes new to MPIR-3.0, see [@https://svn.boost.org/trac/boost/ticket/13124 #13124].
5828 [h4 Multiprecision-2.3.2 (Boost-1.65)]
5830 * Updated expression templates to store arithmetic literals directly in the expression template to prevent dangling references, see [@https://github.com/boostorg/multiprecision/issues/19 #19].
5831 * Fix various issues with huge values and overflow in the trig, pow and exp functions, see [@https://github.com/boostorg/multiprecision/issues/24 #24].
5832 * Fix error handling of checked cpp_int multiply that could cause some overflows to be missed.
5834 [h4 Multiprecision-2.3.1 (Boost-1.64)]
5836 * In `cpp_bin_float` prevent double rounding when converting to a denormalized float. See [@https://svn.boost.org/trac/boost/ticket/12527 #12527].
5837 * Fix bug in integer sqrt for very small integers. See [@https://svn.boost.org/trac/boost/ticket/12559 #12559].
5838 * Fix conversion to signed-zero in `cpp_bin_float`.
5839 * Change `cpp_bin_float` rounding code to round at arbitrary location so we can use it for conversions, see [@https://svn.boost.org/trac/boost/ticket/12527 #12527].
5840 * Improve performance of 128-bit bit-scan operations.
5841 * Fix subtraction of very small quantities in `cpp_bin_float`. See: [@https://svn.boost.org/trac/boost/ticket/12580 #12580].
5842 * Bring error handling into line with C99 Annex F. See [@https://svn.boost.org/trac/boost/ticket/12581 #12581].
5843 * Fix bitwise export of trivial `cpp_int`'s, see [@https://svn.boost.org/trac/boost/ticket/12627 #12627].
5844 * Fix `ilogb` (and code that uses it) to consistently return the smallest value of the exponent type when the argument is zero, see [@https://svn.boost.org/trac/boost/ticket/12625 #12625].
5845 * Allow conversion from `__float128` to `cpp_bin_float`.
5846 * Fix bug in left shift of `cpp_int` which would result in bit-loss, see [@https://svn.boost.org/trac/boost/ticket/12790 #12790].
5847 * Fixed bugs in bounded but variable precision `cpp_int`'s caused by over-aggressive constexpr optimization, see [@https://svn.boost.org/trac/boost/ticket/12798 #12798].
5850 [h4 Multiprecision-2.3.0 (Boost-1.63)]
5852 * Added support for all the C99 math functions.
5853 * Extended generic-interconversions to handle narrowing cases as well, changed convert_to member function and hence explicit
5854 conversion operators to use the same conversion code as the explicit constructors.
5855 * Fix IO stream parsing error, see [@https://svn.boost.org/trac/boost/ticket/12488 #12488].
5856 * Make default constructed floating point types all zero for consistency, see [@https://svn.boost.org/trac/boost/ticket/12500 #12500].
5857 * Fix conversion of cpp_bin_float to float/double/long double when the exponent value would overflow an int, see [@https://svn.boost.org/trac/boost/ticket/12512 #12512].
5858 * Fix cpp_bin_float subtractions that yield signed-zeros, see [@https://svn.boost.org/trac/boost/ticket/12524 #12524].
5859 * Fix ceil/trunc/round applied to cpp_bin_float and yielding a signed zero, see [@https://svn.boost.org/trac/boost/ticket/12525 #12525].
5861 [h4 Multiprecision-2.2.8 (Boost-1.62)]
5863 * Added support for hashing via `Boost.Hash` or `std::hash`.
5864 * Fixed some arithmetic operations in cpp_bin_float and cpp_dec_float that should generate a NaN, see [@https://svn.boost.org/trac/boost/ticket/12157 #12157].
5865 * Prevent inadvertant instantiation of variable-precision `mpfr_float_backend` with fixed allocation.
5866 * Fixed division over/underflow in cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12167 #12167].
5867 * Added support for signed-zeros throughout the library, including support for `signbit` and `copysign`, mpfr, float128, and cpp_bin_float types
5868 should now respect signed-zeros correctly.
5869 * Fixed bug in conversion of cpp_bin_float infinities to double etc, see [@https://svn.boost.org/trac/boost/ticket/12196 #12196].
5870 * Fix add and subtract of cpp_bin_float when the exponents would overflow., see [@https://svn.boost.org/trac/boost/ticket/12198 #12198].
5871 * Improve variable-precision support in mpfr and mpf backends, allow these types to be used with Boost.Math.
5872 * Fixed bug in subtraction of signed infinities in cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12209 #12209].
5873 * Fix result of sqrt(infinity) in cpp_bin_float (result should be infinity), see [@https://svn.boost.org/trac/boost/ticket/12227 #12227].
5874 * Added workaround in gmp.hpp for recent MPIR releases which are not quite source-compatible with GMP on Windows x64.
5875 * Allow `cpp_int` code to be used with /RTCc with MSVC.
5876 * Fix conversion of `cpp_int` to signed integer when the result is INT_MIN, see [@https://svn.boost.org/trac/boost/ticket/12343 #12343].
5877 * Update uBlas support to match latest uBlas code.
5878 * Fix some errors present when building on big-endian machines (not all `cpp_int` constructors are available on non-little-endian machines).
5879 * Fix fencepost error in rational to float conversion routines, see [@https://svn.boost.org/trac/boost/ticket/12327 #12327].
5880 * Fix some Oracle C++ compiler compatibility issues.
5881 * Add modf support to complete C90 compatibility.
5882 * Fix self assignment bug in expression template code for expressions such as `a = a * a * a`, see [@https://svn.boost.org/trac/boost/ticket/12408 #12408].
5883 * Fixed some compiler errors that occur when converting from `cpp_int` to `cpp_bin_float`.
5885 [h4 Multiprecision-2.2.7 (Boost-1.61)]
5887 * Fixed bug in stream input for integer types, see [@https://svn.boost.org/trac/boost/ticket/11857 #11857].
5888 * Fixed some ambiguous conversions involving expression templates see [@https://svn.boost.org/trac/boost/ticket/11922 #11922].
5889 * Add expression template aware min/max overloads see [@https://svn.boost.org/trac/boost/ticket/11149 #11149].
5890 * Fix bug in right shifting negative small integers in cpp_int see [@https://svn.boost.org/trac/boost/ticket/11999 #11999].
5891 * Use memmove for bitshifts in cpp_int when possible see [@https://svn.boost.org/trac/boost/ticket/9233 #9233].
5892 * Use memcpy for data import into cpp_int where possible, see [@https://svn.boost.org/trac/boost/ticket/9235 #9235].
5893 * Changed `cpp_bin_float.convert_to<double>()` to a function template rather than proceding via `long double` to avoid
5894 double-rounding bug, see [@https://svn.boost.org/trac/boost/ticket/12039 #12039].
5895 * Fixed conversions from NaN's and Infinities, see [@https://svn.boost.org/trac/boost/ticket/12112 #12112].
5896 * Enabled better support for Clang on Windows.
5897 * Fixed handling of NaN's and Infinities in basic arithmetic for cpp_dec_float and cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12090 #12090].
5898 * Fixed fencepost error in cpp_bin_float subtraction.
5899 * Fixed double-rounding in conversion to float routines for cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12039 #12039].
5900 * Make float128 denorm aware, see [@https://svn.boost.org/trac/boost/ticket/12075 #12075].
5901 * Allow the library and tests to be used without exception handling support, see [@https://svn.boost.org/trac/boost/ticket/12070 #12070].
5902 * Fixed buggy comparison operator overloads for boost::rational.
5903 * Added some workarounds for Oracle C++.
5904 * Fixed some missing typecasts for cases where cpp_int's limb_type is wider than unsigned.
5907 [h4 Multiprecision-2.2.6 (Boost-1.60)]
5909 * Fixed result of Miller Rabin primality test for value 2, see [@https://svn.boost.org/trac/boost/ticket/11495 #11495].
5910 * Improved initialization of cpp_int from very large strings of hex or octal digits, see [@https://svn.boost.org/trac/boost/ticket/11590 #11590].
5911 * Fixed fmod behaviour for negative divisors, see [@https://svn.boost.org/trac/boost/ticket/11641 #11641].
5912 * Fixed infinite division loop in cpp_int special case, see [@https://svn.boost.org/trac/boost/ticket/11648 #11648].
5913 * Patched missing return statement in [@https://svn.boost.org/trac/boost/ticket/11762 #11762].
5914 * Fixed mixed mode arithmetic compiler error in [@https://svn.boost.org/trac/boost/ticket/11764 #11764].
5915 * Fixed over-aggressive use of noexcept in [@https://svn.boost.org/trac/boost/ticket/11826 #11826].
5918 [h4 Multiprecision-2.2.5 (Boost-1.59)]
5920 * Depricated boost/multiprecision/random.hpp as it's no longer needed, updated random examples to match.
5921 * Fixed a bug in cpp_int's right shift operator when shifting negative values - semantics now gives the
5922 same values as shifting 2's compliment integers, though not the same bit pattern.
5923 * Fixed support for GCC-4.6.4 in C++0x mode by disabling conditional noexcept suppoprt for that compiler
5924 see [@https://svn.boost.org/trac/boost/ticket/11402 #11402].
5925 * Suppressed numerous compiler warnings.
5927 [h4 Multiprecision-2.2.4 (Boost-1.58)]
5929 * Changed `frexp` to always be non-expression template generating, see: [@https://svn.boost.org/trac/boost/ticket/10993 10993].
5930 * Improved support of cpp_dec_float on Cygwin and other platforms with missing long double support, see [@https://svn.boost.org/trac/boost/ticket/10924 10924].
5931 * Improved noexcept support and added some more tests, see [@https://svn.boost.org/trac/boost/ticket/10990 10990].
5932 * Various workarounds applied for Intel-15.0 and Solaris-12.4 compilers.
5934 [h4 Multiprecision-2.2.3 (Boost-1.57)]
5936 * Changed rational to float conversions to exactly round to nearest, see [@https://svn.boost.org/trac/boost/ticket/10085 10085].
5937 * Added improved generic float to rational conversions.
5938 * Fixed rare bug in exponent function for __cpp_bin_float.
5939 * Fixed various minor documentation issues.
5941 [h4 Multiprecision-2.2.2 (Boost-1.56)]
5943 * Change floating-point to rational conversions to be implicit, see [@https://svn.boost.org/trac/boost/ticket/10082 10082].
5944 * Fix definition of checked_cpp_rational typedef.
5946 [h4 Multiprecision-2.2.1]
5948 * Fix bug in assignment from string in cpp_int, see [@https://svn.boost.org/trac/boost/ticket/9936 9936].
5950 [h4 Multiprecision-2.2.0]
5952 * Moved to Boost.Multiprecision specific version number - we have one breaking change in Boost-1.54
5953 which makes this major version 2, plus two releases with new features since then.
5954 * Added new __cpp_bin_float backend for binary floating-point.
5955 * Added MSVC-specific #include for compiler intrinsics, see [@https://svn.boost.org/trac/boost/ticket/9336 9336].
5956 * Fixed various typos in docs, see [@https://svn.boost.org/trac/boost/ticket/9432 9432].
5957 * Fixed __gmp_rational to allow move-copy from an already copied-from object, see [@https://svn.boost.org/trac/boost/ticket/9497 9497].
5958 * Added list of values for numeric_limits.
5962 * Added support for Boost.Serialization.
5963 * Suppressed some GCC warnings. See [@https://svn.boost.org/trac/boost/ticket/8872 8872].
5964 * Fixed bug in pow for large integer arguments. See [@https://svn.boost.org/trac/boost/ticket/8809 8809].
5965 * Fixed bug in pow for calculation of 0[super N]. See [@https://svn.boost.org/trac/boost/ticket/8798 8798].
5966 * Fixed bug in fixed precision cpp_int IO code that causes conversion to string to fail when the
5967 bit count is very small (less than CHAR_BIT). See [@https://svn.boost.org/trac/boost/ticket/8745 8745].
5968 * Fixed bug in cpp_int that causes left shift to fail when a fixed precision type would overflow.
5969 See [@https://svn.boost.org/trac/boost/ticket/8741 8741].
5970 * Fixed some cosmetic warnings from cpp_int. See [@https://svn.boost.org/trac/boost/ticket/8748 8748].
5971 * Fixed calls to functions which are required to be macros in C99. See [@https://svn.boost.org/trac/boost/ticket/8732 8732].
5972 * Fixed bug that causes construction from INT_MIN, LONG_MIN etc to fail in cpp_int. See [@https://svn.boost.org/trac/boost/ticket/8711 8711].
5976 * [*Breaking change] renamed `rational_adapter` to `rational_adaptor`.
5977 * Add support for [mpfi].
5978 * Add logged_adaptor.
5979 * Add support for 128-bit floats via GCC's `__float128` or Intel's `_Quad` data types.
5980 * Add support for user-defined literals in cpp_int, improve `constexpr` support.
5981 * Fixed bug in integer division of `cpp_int` that results in incorrect sign of `cpp_int` when both arguments are small enough
5982 to fit in a `double_limb_type`. See [@https://svn.boost.org/trac/boost/ticket/8126 8126].
5983 * Fixed bug in subtraction of a single limb in `cpp_int` that results in incorrect value when the result should have a 0
5984 in the last limb: [@https://svn.boost.org/trac/boost/ticket/8133 8133].
5985 * Fixed bug in `cpp_int` where division of 0 by something doesn't get zero in the result: [@https://svn.boost.org/trac/boost/ticket/8160 8160].
5986 * Fixed bug in some transcendental functions that caused incorrect return values when variables are reused, for example with
5987 `a = pow(a, b)`. See [@https://svn.boost.org/trac/boost/ticket/8326 8326].
5988 * Fixed some assignment operations in the mpfr and gmp backends to be safe if the target has been moved from: [@https://svn.boost.org/trac/boost/ticket/8326 8667].
5989 * Fixed bug in `cpp_int` that gives incorrect answer for 0%N for large N: [@https://svn.boost.org/trac/boost/ticket/8670 8670].
5990 * Fixed set_precision in mpfr backend so it doesn't trample over an existing value: [@https://svn.boost.org/trac/boost/ticket/8692 8692].
5995 * Fix bug in [@https://svn.boost.org/trac/boost/ticket/7878 cpp_int division].
5996 * Fix issue [@https://svn.boost.org/trac/boost/ticket/7806 #7806].
5998 [h4 Post review changes]
6000 * Non-expression template operators further optimised with rvalue reference support.
6001 * Many functions made `constexp`.
6002 * Differentiate between explicit and implicit conversions in the number constructor.
6003 * Removed "mp_" prefix from types.
6004 * Allowed mixed precision arithmetic.
6005 * Changed ExpressionTemplates parameter to class `number` to use enumerated values rather than true/false.
6006 * Changed ExpressionTemplate parameter default value to use a traits class so that the default value depends on the backend used.
6007 * Added support for fused-multiply-add/subtract with GMP support.
6008 * Tweaked expression template unpacking to use fewer temporaries when the LHS also appears in the RHS.
6009 * Refactored `cpp_int_backend` based on review comments with new template parameter structure.
6010 * Added additional template parameter to `mpfr_float_backend` to allow stack-based allocation.
6011 * Added section on mixed precision arithmetic, and added support for operations yielding a higher precision result
6012 than either of the arguments.
6013 * Added overloads of integer-specific functions for built in integer types.
6015 [h4 Pre-review history]
6017 *2011-2012, John Maddock adds an expression template enabled front end to Christopher's code,
6018 and adds support for other backends.
6019 * 2011, Christopher Kormanyos publishes the decimal floating-point code under the Boost
6020 Software Licence. The code is published as: [@http://doi.acm.org/10.1145/1916461.1916469
6021 "Algorithm 910: A Portable C++ Multiple-Precision
6022 System for Special-Function Calculations"], in ACM TOMS, {VOL 37, ISSUE 4, (February 2011)} (C) ACM,
6024 * 2002-2011, Christopher Kormanyos develops the all C++ decimal arithmetic floating-point
6033 More a list of what ['could] be done, rather than what ['should] be done (which may be a much smaller list!).
6035 * Add back-end support for libdecNumber.
6036 * Add an adaptor back-end for complex number types.
6037 * Add better multiplication routines (Karatsuba, FFT etc) to cpp_int_backend.
6038 * Add assembly level routines to cpp_int_backend.
6039 * Can ring types (exact floating-point types) be supported? The answer should be yes, but someone needs to write it,
6040 the hard part is IO and binary-decimal conversion.
6041 * Should there be a choice of rounding mode (probably MPFR specific)?
6042 * We can reuse temporaries in multiple subtrees (temporary caching).
6043 * cpp_dec_float should round to nearest.
6044 * A 2's complement fixed precision int that uses exactly N bits and no more.
6046 Things requested in review:
6048 * The performances of mp_number<a_trivial_adaptor<float>, false>respect to
6049 float and mp_number<a_trivial_adaptor<int>, false> and int should be
6050 given to show the cost of using the generic interface (Mostly done, just need to update docs to the latest results).
6051 * Should we provide min/max overloads for expression templates? (Not done - we can't overload functions declared in the std namespace :-( ).
6052 * The rounding applied when converting must be documented (Done).
6053 * Document why we don't abstract out addition/multiplication algorithms etc. (done - FAQ)
6054 * Document why we don't use proto (compile times) (Done).
6055 * We can reuse temporaries in multiple subtrees (temporary caching) Moved to TODO list.
6056 * Emphasise in the docs that ET's may reorder operations (done 2012/10/31).
6057 * Document what happens to small fixed precision cpp_int's (done 2012/10/31).
6058 * The use of bool in template parameters could be improved by the use of
6059 an enum class which will be more explicit. E.g `enum class expression_template {disabled, enabled};
6060 enum class sign {unsigned, signed};` (Partly done 2012/09/15, done 2012/10/31).
6061 * Each back-end should document the requirements it satisfies (not currently scheduled for inclusion: it's
6062 deliberately an implementation detail, and "optional" requirements are optimisations which can't be detected
6063 by the user). Not done: this is an implementation detail, the exact list of requirements satisfied is purely
6064 an optimization, not something the user can detect.
6065 * A backend for an overflow aware integers (done 2012/10/31).
6066 * IIUC convert_to is used to emulate in c++98 compilers C++11 explicit
6067 conversions. Could the explicit conversion operator be added on
6068 compilers supporting it? (Done 2012/09/15).
6069 * The front-end should make the differences between implicit and explicit
6070 construction (Done 2012/09/15).
6071 * The tutorial should add more examples concerning implicit or explicit
6072 conversions. (Done 2012/09/15).
6073 * The documentation must explain how move semantics helps in this domain
6074 and what the backend needs to do to profit from this optimization. (Done 2012/09/15).
6075 * The documentation should contain Throws specification on the mp_number
6076 and backend requirements operations. (Done 2012/09/15).
6077 * The library interface should use the noexcept (BOOST_NOEXCEPT, ...)
6078 facilities (Done 2012/09/15).
6079 * It is unfortunate that the generic mp_number front end can not make use
6080 constexpr as not all the backends can ensure this (done - we can go quite a way).
6081 * literals: The library doesn't provide some kind of literals. I think that the
6082 mp_number class should provide a way to create literals if the backend
6083 is able to. (Done 2012/09/15).
6084 * The ExpresionTemplate parameter could be defaulted to a traits class for more sensible defaults (done 2012/09/20).
6085 * In a = exp1 op exp2 where a occurs inside one of exp1 or exp2 then we can optimise and eliminate one more temporary (done 2012/09/20).
6089 [h4 Pre-Review Comments]
6091 * Make fixed precision orthogonal to Allocator type in cpp_int. Possible solution - add an additional MaxBits
6092 template argument that defaults to 0 (meaning keep going till no more space/memory). Done.
6093 * Can ring types (exact floating-point types) be supported? The answer should be yes, but someone needs to write it (Moved to TODO list).
6094 * Should there be a choice of rounding mode (probably MPFR specific)? Moved to TODO list.
6095 * Make the exponent type for cpp_dec_float a template parameter, maybe include support for big-integer exponents.
6096 Open question - what should be the default - int32_t or int64_t? (done 2012/09/06)
6097 * Document the size requirements of fixed precision ints (done 2012/09/15).
6098 * Document std lib function accuracy (done 2012/09/15).
6099 * Be a bit clearer on the effects of sign-magnitude representation of cpp_int - min == -max etc - done.
6100 * Document cpp_dec_float precision, rounding, and exponent size (done 2012/09/06).
6101 * Can we be clearer in the docs that mixed arithmetic doesn't work (no longer applicable as of 2012/09/06)?
6102 * Document round functions behaviour better (they behave as in C++11) (added note 2012/09/06).
6103 * Document limits on size of cpp_dec_float (done 2012/09/06).
6104 * Add support for fused multiply add (and subtract). GMP mpz_t could use this (done 2012/09/20).
6111 [[Why do I get compiler errors when passing a `number` to a template function?]
6112 [Most likely you are actually passing an expression template type to the function and
6113 template-argument-deduction deduces the "wrong" type. Try casting the arguments
6114 involving expressions to the actual number type, or as a last resort turning off
6115 expression template support in the number type you are using.]]
6116 [[When is expression template support a performance gain?]
6117 [As a general rule, expression template support adds a small runtime overhead
6118 creating and unpacking the expression templates, but greatly reduces the number of
6119 temporaries created. So it's most effective in improving performance when the cost
6120 of creating a temporary is high: for example when creating a temporary involves a memory
6121 allocation. It is least effective (and may even be a dis-optimisation) when temporaries
6122 are cheap: for example if the number type is basically a thin wrapper around a native
6123 arithmetic type. In addition, since the library makes extensive use of thin inline wrapper
6124 functions, turning on compiler optimization is essential to achieving high performance.]]
6125 [[Do expression templates reorder operations?]
6126 [Yes they do, sometimes quite radically so, if this is a concern then they should be turned
6127 off for the number type you are using.]]
6128 [[I can't construct my number type from ['some other type], but the docs indicate that the conversion should be allowed, what's up?]
6129 [Some conversions are ['explicit], that includes construction from a string, or constructing from any type
6130 that may result in loss of precision (for example constructing an integer type from a float).]]
6131 [[Why do I get an exception thrown (or the program crash due to an uncaught exception) when using the bitwise operators on a checked `cpp_int`?]
6132 [Bitwise operations on negative values (or indeed any signed integer type) are unspecified by the standard. As a result
6133 any attempt to carry out a bitwise operation on a negative checked-integer will result in a `std::range_error` being thrown.]]
6134 [[Why do I get compiler errors when trying to use the complement operator?]
6135 [Use of the complement operator on signed types is problematic as the result is unspecified by the standard, and is further
6136 complicated by the fact that most extended precision integer types use a sign-magnitude representation rather than the 2's
6137 complement one favored by most native integer types. As a result the complement operator is deliberately disabled for
6138 checked `cpp_int`'s. Unchecked `cpp_int`'s give the same valued result as a 2's complement type would, but not the same bit-pattern.]]
6139 [[Why can't I negate an unsigned type?]
6140 [The unary negation operator is deliberately disabled for unsigned integer types as its use would almost always be a programming error.]]
6141 [[Why doesn't the library use proto?]
6142 [A very early version of the library did use proto, but compile times became too slow
6143 for the library to be usable. Since the library only required a tiny fraction of what
6144 proto has to offer anyway, a lightweight expression template mechanism was used instead.
6145 Compile times are still too slow...]]
6146 [[Why not abstract out addition/multiplication algorithms?]
6147 [This was deemed not to be practical: these algorithms are intimately
6148 tied to the actual data representation used.]]
6149 [[How do I choose between Boost.Multiprecision `cpp_bin_50` and `cpp_dec_50`?]
6150 [Unless you have a specific reason to choose `cpp_dec_`, then the default choice should be `cpp_bin_`,
6151 for example using the convenience `typedefs` like `boost::multiprecision::cpp_bin_50` or `boost::multiprecision::cpp_bin_100`.
6153 In general, both work well and give the same results and at roughly the same speed with `cpp_dec_50` sometimes faster.
6155 `cpp_dec_` was developed first paving the way for `cpp_bin_`.
6156 `cpp_dec_` has several guard digits and is not rounded at all, using 'brute force' to get the promised number of decimal digits correct,
6157 but making it difficult to reason about precision and computational uncertainty, for example see [*https://svn.boost.org/trac10/ticket/12133].
6158 It also has a fast but imprecise division operator giving surprising results sometimes, see [*https://svn.boost.org/trac10/ticket/11178].
6160 `cpp_bin_` is correctly/exactly rounded making it possible to reason about both the precision and rounding of the results.]]
6165 [section:ack Acknowledgements]
6167 This library would not have happened without:
6169 * Christopher Kormanyos' C++ decimal number code.
6170 * Paul Bristow for patiently testing, and commenting on the library.
6171 * All the folks at GMP, MPFR and libtommath, for providing the "guts" that makes this library work.
6172 * [@http://www-cs-faculty.stanford.edu/~uno/taocp.html "The Art Of Computer Programming"],
6173 Donald E. Knuth, Volume 2: Seminumerical Algorithms, Third Edition
6174 (Reading, Massachusetts: Addison-Wesley, 1997), xiv+762pp. ISBN 0-201-89684-2
6180 [section:indexes Indexes]
6183 <index type="function_name">
6184 <title>Function Index</title>
6187 <index type="class_name">
6188 <title>Class Index</title>
6191 <index type="typedef_name">
6192 <title>Typedef Index</title>