1[/ 2 Copyright 2011, 2013 John Maddock. 3 Copyright 2013 - 2019 Paul A. Bristow. 4 Copyright 2013 Christopher Kormanyos. 5 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). 9] 10 11[library Boost.Multiprecision 12 [quickbook 1.7] 13 [copyright 2002-2019 John Maddock and Christopher Kormanyos] 14 [purpose Multiprecision Number library] 15 [license 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]) 19 ] 20 [authors [Maddock, John], [Kormanyos, Christopher]] 21 [/last-revision $Date: 2011-07-08 18:51:46 +0100 (Fri, 08 Jul 2011) $] 22] 23 24[import html4_symbols.qbk] [/Ideally this should be the same as Boost.Math I:\boost\libs\math\doc] 25 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] 49 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]] 61 62[template super[x]'''<superscript>'''[x]'''</superscript>'''] 63[template sub[x]'''<subscript>'''[x]'''</subscript>'''] 64 65 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.] 68 69[template equation[name] '''<inlinemediaobject> 70<imageobject role="html"> 71<imagedata fileref="../'''[name]'''.png"></imagedata> 72</imageobject> 73<imageobject role="print"> 74<imagedata fileref="../'''[name]'''.svg"></imagedata> 75</imageobject> 76</inlinemediaobject>'''] 77 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] 81[: 82[role serif_italic [equation]] 83] 84[/ Hint you may need to enclose equation in brackets if it contains comma(s) to avoid "error invalid number of arguments"] 85] 86 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 ] 90 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]] 114 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]] 120 121[section:intro Introduction] 122 123The Multiprecision Library provides [link boost_multiprecision.tut.ints integer], 124[link boost_multiprecision.tut.rational rational], 125[link boost_multiprecision.tut.floats floating-point], 126and [link boost_multiprecision.tut.complex complex] types in C++ that have more 127range and precision than C++'s ordinary built-in types. 128The big number types in Multiprecision can be used with a wide 129selection of basic mathematical operations, elementary transcendental 130functions as well as the functions in Boost.Math. 131The Multiprecision types can also interoperate with any 132__fundamental_type in C++ using clearly defined conversion rules. 133This allows Boost.Multiprecision to be used for all 134kinds of mathematical calculations involving integer, 135rational and floating-point types requiring extended 136range and precision. 137 138Multiprecision consists of a generic interface to the 139mathematics of large numbers as well as a selection of 140big number back-ends, with support for integer, rational, 141floating-point, and complex types. Boost.Multiprecision provides a selection 142of back-ends provided off-the-rack in including 143interfaces to GMP, MPFR, MPIR, MPC, TomMath as well as 144its own collection of Boost-licensed, header-only back-ends for 145integers, rationals and floats. In addition, user-defined back-ends 146can be created and used with the interface of Multiprecision, 147provided the class implementation adheres to the necessary 148[link boost_multiprecision.ref.backendconc concepts]. 149 150Depending 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 153by member functions. The types are __expression_templates - enabled for 154better performance than naive user-defined types. 155 156The Multiprecision library comes in two distinct parts: 157 158* An expression-template-enabled front-end `number` 159that 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 161reduced interface requirements of the front-end. 162 163Separation of front-end and back-end allows use of highly refined, but restricted license libraries 164where possible, but provides Boost license alternatives for users who must have a portable 165unconstrained license. 166Which is to say some back-ends rely on 3rd party libraries, 167but a header-only Boost license version is always available (if somewhat slower). 168 169[h5:getting_started Getting started with Boost.Multiprecision] 170 171Should 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, 172close to 'drop-in' replacements for the __fundamental_type analogs, 173then use a fully Boost-licensed number type, and skip to one of more of : 174 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. 179 180The library is very often used via one of the predefined convenience `typedef`s 181like `boost::multiprecision::int128_t` or `boost::multiprecision::cpp_bin_float_quad`. 182 183For example, if you want a signed, 128-bit fixed size integer: 184 185 #include <boost/multiprecision/cpp_int.hpp> // Integer types. 186 187 boost::multiprecision::int128_t my_128_bit_int; 188 189Alternatively, and more adventurously, if you wanted an 190[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] 191integer type using [gmp] as the underlying implementation then you could use: 192 193 #include <boost/multiprecision/gmp.hpp> // Defines the wrappers around the GMP library's types 194 195 boost::multiprecision::mpz_int myint; // Arbitrary precision integer type. 196 197Or for a simple, portable 128-bit floating-point close to a drop-in for a __fundamental_type like `double`, usually 64-bit 198 199 #include <boost/multiprecision/cpp_bin_float.hpp> 200 201 boost::multiprecision::cpp_bin_float_quad my_quad_real; 202 203Alternatively, you can compose your own 'custom' multiprecision type, by combining `number` with one of the 204predefined back-end types. For example, suppose you wanted a 300 decimal digit floating-point type 205based on the [mpfr] library. In this case, there's no predefined `typedef` with that level of precision, 206so instead we compose our own: 207 208 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR. 209 210 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 211 212 typedef mp::number<mp::mpfr_float_backend<300> > my_float; 213 214 my_float a, b, c; // These variables have 300 decimal digits precision. 215 216We can repeat the above example, but with the expression templates disabled (for faster compile times, but slower runtimes) 217by passing a second template argument to `number`: 218 219 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR. 220 221 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 222 223 typedef mp::number<mp::mpfr_float_backend<300>, et_off> my_float; 224 225 my_float a, b, c; // These variables have 300 decimal digits precision 226 227We can also mix arithmetic operations between different types, provided there is an unambiguous implicit conversion from one 228type to the other: 229 230 #include <boost/multiprecision/cpp_int.hpp> 231 232 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 233 234 mp::int128_t a(3), b(4); 235 mp::int512_t c(50), d; 236 237 d = c * a; // OK, result of mixed arithmetic is an int512_t 238 239Conversions are also allowed: 240 241 d = a; // OK, widening conversion. 242 d = a * b; // OK, can convert from an expression template too. 243 244However conversions that are inherently lossy are either declared explicit or else forbidden altogether: 245 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 248 249Mixed arithmetic will fail if the conversion is either ambiguous or explicit: 250 251 number<cpp_int_backend<>, et_off> a(2); 252 number<cpp_int_backend<>, et_on> b(3); 253 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. 256 257[h4 Move Semantics] 258 259On compilers that support rvalue-references, class `number` is move-enabled if the underlying backend is. 260 261In addition the non-expression template operator overloads (see below) are move aware and have overloads 262that look something like: 263 264 template <class B> 265 number<B, et_off> operator + (number<B, et_off>&& a, const number<B, et_off>& b) 266 { 267 return std::move(a += b); 268 } 269 270These operator overloads ensure that many expressions can be evaluated without actually generating any temporaries. 271However, there are still many simple expressions such as 272 273 a = b * c; 274 275which don't noticeably benefit from move support. Therefore, optimal performance comes from having both 276move-support, and expression templates enabled. 277 278Note that while "moved-from" objects are left in a sane state, they have an unspecified value, and the only permitted 279operations on them are destruction or the assignment of a new value. Any other operation should be considered 280a programming error and all of our backends will trigger an assertion if any other operation is attempted. This behavior 281allows for optimal performance on move-construction (i.e. no allocation required, we just take ownership of the existing 282object's internal state), while maintaining usability in the standard library containers. 283 284[h4:expression_templates Expression Templates] 285 286Class `number` is expression-template-enabled: that means that rather than having a multiplication 287operator that looks like this: 288 289 template <class Backend> 290 number<Backend> operator * (const number<Backend>& a, const number<Backend>& b) 291 { 292 number<Backend> result(a); 293 result *= b; 294 return result; 295 } 296 297Instead the operator looks more like this: 298 299 template <class Backend> 300 ``['unmentionable-type]`` operator * (const number<Backend>& a, const number<Backend>& b); 301 302Where the '['unmentionable]' return type is an implementation detail that, rather than containing the result 303of the multiplication, contains instructions on how to compute the result. In effect it's just a pair 304of references to the arguments of the function, plus some compile-time information that stores what the operation 305is. 306 307The great advantage of this method is the ['elimination of temporaries]: for example, the "naive" implementation 308of `operator*` above, requires one temporary for computing the result, and at least another one to return it. It's true 309that sometimes this overhead can be reduced by using move-semantics, but it can't be eliminated completely. For example, 310lets suppose we're evaluating a polynomial via Horner's method, something like this: 311 312 T a[7] = { /* some values */ }; 313 //.... 314 y = (((((a[6] * x + a[5]) * x + a[4]) * x + a[3]) * x + a[2]) * x + a[1]) * x + a[0]; 315 316If type `T` is a `number`, then this expression is evaluated ['without creating a single temporary value]. In contrast, 317if we were using the [mpfr_class] C++ wrapper for [mpfr] - then this expression would result in no less than 11 318temporaries (this is true even though [mpfr_class] does use expression templates to reduce the number of temporaries somewhat). Had 319we used an even simpler wrapper around [mpfr] like [mpreal] things would have been even worse and no less that 24 temporaries 320are created for this simple expression (note - we actually measure the number of memory allocations performed rather than 321the number of temporaries directly, note also that the [mpf_class] wrapper that will be supplied with GMP-5.1 reduces the number of 322temporaries to pretty much zero). Note that if we compile with expression templates disabled and rvalue-reference support 323on, then actually still have no wasted memory allocations as even though temporaries are created, their contents are moved 324rather than copied. 325[footnote The actual number generated will depend on the compiler, how well it optimizes the code, and whether it supports 326rvalue references. The number of 11 temporaries was generated with Visual C++ 2010.] 327 328[important 329Expression templates can radically reorder the operations in an expression, for example: 330 331 a = (b * c) * a; 332 333Will get transformed into: 334 335 a *= c; 336 a *= b; 337 338If this is likely to be an issue for a particular application, then they should be disabled. 339] 340 341This library also extends expression template support to standard library functions like `abs` or `sin` with `number` 342arguments. This means that an expression such as: 343 344 y = abs(x); 345 346can be evaluated without a single temporary being calculated. Even expressions like: 347 348 y = sin(x); 349 350get this treatment, so that variable 'y' is used as "working storage" within the implementation of `sin`, 351thus reducing the number of temporaries used by one. Of course, should you write: 352 353 x = sin(x); 354 355Then we clearly can't use `x` as working storage during the calculation, so then a temporary variable 356is created in this case. 357 358Given the comments above, you might be forgiven for thinking that expression-templates are some kind of universal-panacea: 359sadly though, all tricks like this have their downsides. For one thing, expression template libraries 360like 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 362on to give really good performance. Also, since the return type from expressions involving `number`s 363is an "unmentionable implementation detail", you have to be careful to cast the result of an expression 364to the actual number type when passing an expression to a template function. For example, given: 365 366 template <class T> 367 void my_proc(const T&); 368 369Then calling: 370 371 my_proc(a+b); 372 373Will very likely result in obscure error messages inside the body of `my_proc` - since we've passed it 374an expression template type, and not a number type. Instead we probably need: 375 376 my_proc(my_number_type(a+b)); 377 378Having said that, these situations don't occur that often - or indeed not at all for non-template functions. 379In addition, all the functions in the Boost.Math library will automatically convert expression-template arguments 380to the underlying number type without you having to do anything, so: 381 382 mpfr_float_100 a(20), delta(0.125); 383 boost::math::gamma_p(a, a + delta); 384 385Will work just fine, with the `a + delta` expression template argument getting converted to an `mpfr_float_100` 386internally by the Boost.Math library. 387 388[caution In C++11 you should never store an expression template using: 389 390`auto my_expression = a + b - c;` 391 392unless you're absolutely sure that the lifetimes of `a`, `b` and `c` will outlive that of `my_expression`. 393 394In fact, it is particularly easy to create dangling references by mixing expression templates with the `auto` 395keyword, for example: 396 397`auto val = cpp_dec_float_50("23.1") * 100;` 398 399In this situation, the integer literal is stored directly in the expression template - so its use is OK here - 400but the `cpp_dec_float_50` temporary is stored by reference and then destructed when the statement completes, 401leaving a dangling reference. 402 403[*['If in doubt, do not ever mix expression templates with the `auto` keyword.]] 404] 405 406And finally... the performance improvements from an expression template library like this are often not as 407dramatic 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 409we see the following typical results for polynomial execution: 410 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)]] 416] 417 418As you can see, the execution time increases a lot more slowly than the number of memory allocations. There are 419a number of reasons for this: 420 421* The cost of extended-precision multiplication and division is so great, that the times taken for these tend to 422swamp 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 425as `operator*` can use the target variable as workspace). Since the expression templates carry out their 426magic by converting out-of-place operators to in-place ones, we necessarily take this hit. Even so the 427transformation is more efficient than creating the extra temporary variable, just not by as much as 428one would hope. 429 430Finally, note that `number` takes a second template argument, which, when set to `et_off` disables all 431the expression template machinery. The result is much faster to compile, but slower at runtime. 432 433We'll conclude this section by providing some more performance comparisons between these three libraries, 434again, all are using [mpfr] to carry out the underlying arithmetic, and all are operating at the same precision 435(50 decimal digits): 436 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)]] 444] 445 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)]] 453] 454 455The above results were generated on Win32 compiling with Visual C++ 2010, all optimizations on (/Ox), 456with MPFR 3.0 and MPIR 2.3.0. 457 458[endsect] [/section:intro Introduction] 459 460[section:tut Tutorial] 461 462In order to use this library you need to make two choices: 463 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)? 467 468[section:ints Integer Types] 469 470The following back-ends provide integer arithmetic: 471 472[table 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].]] 478] 479 480[section:cpp_int cpp_int] 481 482`#include <boost/multiprecision/cpp_int.hpp>` 483 484 namespace boost{ namespace multiprecision{ 485 486 typedef unspecified-type limb_type; 487 488 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 489 enum cpp_int_check_type { checked, unchecked }; 490 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; 497 // 498 // Expression templates default to et_off if there is no allocator: 499 // 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; }; 503 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 507 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; 513 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; 519 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; 524 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; 530 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; 536 537 }} // namespaces 538 539The `cpp_int_backend` type is normally used via one of the convenience typedefs given above. 540 541This 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] 543integer types, and both signed and unsigned types. There are five template arguments: 544 545[variablelist 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.]] 562] 563 564When the template parameter Checked is set to `checked` then the result is a ['checked-integer], checked 565and unchecked integers have the following properties: 566 567[table 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 5722's complement representation of the input value.]] 573[[Unsigned subtraction yielding a negative value.][Throws a `std::range_error`.][Yields the value that would 574result 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, 576that would result from performing the operation on a 2's complement integer type.]] 577] 578 579Things you should know when using this type: 580 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, 585care should be taken to avoid numeric overflow when using this type 586unless 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. 588In this respect the behaviour of these types differs from built-in 2's complement types. In might be tempting to use a 589127-bit type instead, and indeed this does work, but behaviour is still slightly different from a 2's complement built-in type 590as the min and max values are identical (apart from the sign), where as they differ by one for a true 2's complement type. 591That 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 592is 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, 594this 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 596difference to the performance of these types either way - so we may as well have the faster compile times by turning 597the feature off. 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 603 been thrown. 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) 607larger than you would expect for an N-bit integer: 608the extra word stores both the sign, and how many machine words in the integer are actually in use. 609The latter is an optimisation for larger fixed precision integers, so that a 1024-bit integer has almost the same performance 610characteristics 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). 612Typically this means you can use 613an integer type wide enough for the "worst case scenario" with only minor performance degradation even if most of the time 614the arithmetic could in fact be done with a narrower type. 615Also note that unsigned fixed precision types small enough to fit inside the largest native integer become a simple wrapper around that type, 616this 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 618internally `cpp_int_backend` switches to a "trivial" implementation where it is just a thin wrapper around a single 619integer. Note that it will still be slightly slower than a bare native integer, as it emulates a 620signed-magnitude representation rather than simply using the platforms native sign representation: this ensures 621there 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` 624specifies a 1024-bit integer with the value 0xffff. This can be used to generate compile time constants that are 625too 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 627be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition 628the 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 630requires either a C++2a compiler (one which supports `std::is_constant_evaluated()`), or GCC-6 or later in C++14 mode. 631Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations: 632expect 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` 634functions. More information is in the [link boost_multiprecision.tut.import_export section on import/export]. 635 636[h5:cpp_int_eg Example:] 637 638[cpp_int_eg] 639 640[endsect] [/section:cpp_int cpp_int] 641 642[section:gmp_int gmp_int] 643 644`#include <boost/multiprecision/gmp.hpp>` 645 646 namespace boost{ namespace multiprecision{ 647 648 class gmp_int; 649 650 typedef number<gmp_int > mpz_int; 651 652 }} // namespaces 653 654The `gmp_int` back-end is used via the typedef `boost::multiprecision::mpz_int`. It acts as a thin wrapper around the [gmp] `mpz_t` 655to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 656 657As well as the usual conversions from arithmetic and string types, type `mpz_int` is copy constructible and assignable from: 658 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>`. 661 662It's also possible to access the underlying `mpz_t` via the `data()` member function of `gmp_int`. 663 664Things you should know when using this type: 665 666* No changes are made to the GMP library's global settings - so you can safely mix this type with 667existing 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, 670as 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 673as a valid integer. 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] 676is recommended on Win32. 677* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 678 679[h5 Example:] 680 681[mpz_eg] 682 683[endsect] [/section:gmp_int gmp_int] 684 685[section:tom_int tom_int] 686 687`#include <boost/multiprecision/tommath.hpp>` 688 689 namespace boost{ namespace multiprecision{ 690 691 class tommath_int; 692 693 typedef number<tommath_int > tom_int; 694 695 }} // namespaces 696 697The `tommath_int` back-end is used via the typedef `boost::multiprecision::tom_int`. It acts as a thin wrapper around the [tommath] `tom_int` 698to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 699 700Things you should know when using this type: 701 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 704rather 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 706operator`~` is deliberately not implemented for this type. 707* Formatted IO for this type does not support octal or hexadecimal notation for negative values, 708as 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 711as a valid integer. 712* Division by zero results in a `std::overflow_error` being thrown. 713 714[h5 Example:] 715 716[tommath_eg] 717 718[endsect] [/section:tom_int tom_int] 719 720[section:egs Examples] 721 722[import ../example/integer_examples.cpp] 723 724[section:factorials Factorials] 725[FAC1] 726[endsect] [/section:factorials Factorials] 727 728 729[section:bitops Bit Operations] 730[BITOPS] 731[endsect] [/section:bitops Bit Operations] 732 733 734[endsect] 735 736[endsect] 737 738[section:floats floating-point Numbers] 739 740The following back-ends provide floating-point arithmetic: 741 742[table 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.]] 749] 750 751[section:cpp_bin_float cpp_bin_float] 752 753`#include <boost/multiprecision/cpp_bin_float.hpp>` 754 755 namespace boost{ namespace multiprecision{ 756 757 enum digit_base_type 758 { 759 digit_base_2 = 2, 760 digit_base_10 = 10 761 }; 762 763 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0> 764 class cpp_bin_float; 765 766 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 767 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 768 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; 774 775 }} // namespaces 776 777The `cpp_bin_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 778floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 779much greater precision. 780 781Type `cpp_bin_float` can be used at fixed precision by specifying a non-zero `Digits` template parameter. 782The typedefs `cpp_bin_float_50` and `cpp_bin_float_100` provide arithmetic types at 50 and 100 decimal digits precision 783respectively. 784 785Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example 786to 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 789software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively. 790Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size 791or bit-layout as true IEEE compatible types. 792 793Normally `cpp_bin_float` allocates no memory: all of the space required for its digits are allocated 794directly within the class. As a result care should be taken not to use the class with too high a digit count 795as stack space requirements can grow out of control. If that represents a problem then providing an allocator 796as a template parameter causes `cpp_bin_float` to dynamically allocate the memory it needs: this 797significantly reduces the size of `cpp_bin_float` and increases the viable upper limit on the number of digits 798at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 799as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 800Note that since the actual type of the objects allocated 801is 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> > >`. 803 804The final template parameters determine the type and range of the exponent: parameter `Exponent` can be 805any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits 806of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will 807get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then 808the library will choose suitable values that are as large as possible given the constraints of the type 809and need for extra headroom for internal calculations. 810 811There is full standard library and `numeric_limits` support available for this type. 812 813Things you should know when using this type: 814 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, 818and 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 - 821for example you can convert from `number<cpp_bin_float<50> >` to `number<cpp_bin_float<SomeOtherValue> >`. 822Narrowing 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 824as a valid floating-point number. 825* All arithmetic operations are correctly rounded to nearest. String conversions and the `sqrt` function 826are also correctly rounded, but transcendental functions (sin, cos, pow, exp etc) are not. 827 828[h5 cpp_bin_float example:] 829 830[cpp_bin_float_eg] 831 832[endsect] 833 834[section:cpp_dec_float cpp_dec_float] 835 836`#include <boost/multiprecision/cpp_dec_float.hpp>` 837 838 namespace boost{ namespace multiprecision{ 839 840 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 841 class cpp_dec_float; 842 843 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 844 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 845 846 }} // namespaces 847 848The `cpp_dec_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 849floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 850much greater precision. 851 852Type `cpp_dec_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter. 853The typedefs `cpp_dec_float_50` and `cpp_dec_float_100` provide arithmetic types at 50 and 100 decimal digits precision 854respectively. Optionally, you can specify an integer type to use for the exponent, this defaults to a 32-bit integer type 855which is more than large enough for the vast majority of use cases, but larger types such as `long long` can also be specified 856if you need a truly huge exponent range. In any case the ExponentType must be a built in signed integer type at least 2 bytes 857and 16-bits wide. 858 859Normally `cpp_dec_float` allocates no memory: all of the space required for its digits are allocated 860directly within the class. As a result care should be taken not to use the class with too high a digit count 861as stack space requirements can grow out of control. If that represents a problem then providing an allocator 862as the final template parameter causes `cpp_dec_float` to dynamically allocate the memory it needs: this 863significantly reduces the size of `cpp_dec_float` and increases the viable upper limit on the number of digits 864at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 865as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 866 867There is full standard library and `numeric_limits` support available for this type. 868 869Things you should know when using this type: 870 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. 874Normally 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, 876and 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 - 879for example you can convert from `number<cpp_dec_float<50> >` to `number<cpp_dec_float<SomeOtherValue> >`. 880Narrowing 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 882as 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 884the template parameter, actually how much higher is an implementation detail but is always at least 8 decimal 885digits. 886* Operations involving `cpp_dec_float` are always truncating. However, note that since their are guard digits 887in effect, in practice this has no real impact on accuracy for most use cases. 888 889[h5 cpp_dec_float example:] 890 891[cpp_dec_float_eg] 892 893[endsect] 894 895[section:gmp_float gmp_float] 896 897`#include <boost/multiprecision/gmp.hpp>` 898 899 namespace boost{ namespace multiprecision{ 900 901 template <unsigned Digits10> 902 class gmp_float; 903 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; 909 910 }} // namespaces 911 912The `gmp_float` back-end is used in conjunction with `number` : it acts as a thin wrapper around the [gmp] `mpf_t` 913to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 914much greater precision. 915 916Type `gmp_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 917at variable precision by setting the template argument to zero. The typedefs mpf_float_50, mpf_float_100, 918mpf_float_500, mpf_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 919respectively. The typedef mpf_float provides a variable precision type whose precision can be controlled via the 920`number`s member functions. 921 922[note This type only provides standard library and `numeric_limits` support when the precision is fixed at compile time.] 923 924As well as the usual conversions from arithmetic and string types, instances of `number<mpf_float<N> >` are 925copy constructible and assignable from: 926 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>`. 929 930It's also possible to access the underlying `mpf_t` via the `data()` member function of `gmp_float`. 931 932Things you should know when using this type: 933 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 936existing [gmp] code. 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 939exactly 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 941to avoid numeric overflow or division by zero. That latter will result in a std::overflow_error being thrown, 942while generating excessively large exponents may result in instability of the underlying [gmp] 943library (in testing, converting a number with an excessively large or small exponent 944to a string caused [gmp] to segfault). 945* This type can equally be used with [mpir] as the underlying implementation - indeed that is 946the recommended option on Win32. 947* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 948as a valid floating-point number. 949* Division by zero results in a `std::overflow_error` being thrown. 950 951[h5 [gmp] example:] 952 953[mpf_eg] 954 955[endsect] 956 957[section:mpfr_float mpfr_float] 958 959`#include <boost/multiprecision/mpfr.hpp>` 960 961 namespace boost{ namespace multiprecision{ 962 963 enum mpfr_allocation_type 964 { 965 allocate_stack, 966 allocate_dynamic 967 }; 968 969 template <unsigned Digits10, mpfr_allocation_type AllocateType = allocate_dynamic> 970 class mpfr_float_backend; 971 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; 977 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; 980 981 }} // namespaces 982 983The `mpfr_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfr] `mpfr_t` 984to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 985much greater precision. 986 987Type `mpfr_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 988at variable precision by setting the template argument to zero. The typedefs mpfr_float_50, mpfr_float_100, 989mpfr_float_500, mpfr_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 990respectively. The typedef mpfr_float provides a variable precision type whose precision can be controlled via the 991`number`s member functions. 992 993In addition the second template parameter lets you choose between dynamic allocation (the default, 994and uses MPFR's normal allocation routines), 995or stack allocation (where all the memory required for the underlying data types is stored 996within `mpfr_float_backend`). The latter option can result in significantly faster code, at the 997expense of growing the size of `mpfr_float_backend`. It can only be used at fixed precision, and 998should only be used for lower digit counts. Note that we can not guarantee that using `allocate_stack` 999won't cause any calls to mpfr's allocation routines, as mpfr may call these inside it's own code. 1000The following table gives an idea of the performance tradeoff's at 50 decimal digits 1001precision[footnote Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0]: 1002 1003[table 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)]] 1009] 1010 1011[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 1012 1013As well as the usual conversions from arithmetic and string types, instances of `number<mpfr_float_backend<N> >` are 1014copy constructible and assignable from: 1015 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>`. 1019 1020It's also possible to access the underlying `mpfr_t` via the data() member function of `mpfr_float_backend`. 1021 1022Things you should know when using this type: 1023 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 1031as 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 1034of 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 1036is 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 1038to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a` 1039but preserves the precision of `a`. 1040 1041[h5 [mpfr] example:] 1042 1043[mpfr_eg] 1044 1045[endsect] 1046 1047[section:float128 float128] 1048 1049`#include <boost/multiprecision/float128.hpp>` 1050 1051 namespace boost{ namespace multiprecision{ 1052 1053 class float128_backend; 1054 1055 typedef number<float128_backend, et_off> float128; 1056 1057 }} // namespaces 1058 1059The `float128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types 1060and provides an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1061a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real. 1062 1063All the usual standard library and `numeric_limits` support are available, performance should be equivalent 1064to 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.]. 1066 1067As well as the usual conversions from arithmetic and string types, instances of `float128` are 1068copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types. 1069 1070It's also possible to access the underlying `__float128` or `_Quad` type via the `data()` member 1071function of `float128_backend`. 1072 1073Things you should know when using this type: 1074 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, 1078plus the functions `fabs`, `abs`, `fpclassify`, `isnormal`, `isfinite`, `isinf` and `isnan` are also supported if either 1079the 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 1081exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of 1082our 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 1084as 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 1090the 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` 1093unless you also use `-fext-numeric-literals`. 1094 1095[h5 float128 example:] 1096 1097[float128_eg] 1098 1099[endsect] 1100 1101[section:fp_eg Examples] 1102 1103[import ../example/floating_point_examples.cpp] 1104 1105[section:aos Area of Circle] 1106 1107[AOS1] 1108[AOS2] 1109[AOS3] 1110 1111[endsect] 1112 1113[section:jel Defining a Special Function.] 1114 1115[JEL] 1116 1117[endsect] 1118 1119[section:nd Calculating a Derivative] 1120 1121[ND1] 1122[ND2] 1123[ND3] 1124 1125[endsect] 1126 1127[section:gi Calculating an Integral] 1128 1129[GI1] 1130[GI2] 1131 1132[endsect] 1133 1134[section:poly_eg Polynomial Evaluation] 1135 1136[POLY] 1137 1138[endsect] [/section:poly_eg Polynomial Evaluation] 1139 1140[section:variable_precision Variable Precision Newton Evaluation] 1141 1142[mpfr_variable] 1143 1144[endsect] 1145 1146[endsect] [/section:fp_eg Examples] 1147 1148[endsect] [/section:floats floating-point Numbers] 1149 1150[section:interval Interval Number Types] 1151 1152There is one currently only one interval number type supported - [mpfi]. 1153 1154[section:mpfi mpfi_float] 1155 1156`#include <boost/multiprecision/mpfi.hpp>` 1157 1158 namespace boost{ namespace multiprecision{ 1159 1160 template <unsigned Digits10> 1161 class mpfi_float_backend; 1162 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; 1168 1169 }} // namespaces 1170 1171The `mpfi_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfi] `mpfi_t` 1172to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1173much greater precision and implementing interval arithmetic. 1174 1175Type `mpfi_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1176at 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 1178respectively. The `typedef mpfi_float` provides a variable precision type whose precision can be controlled via the 1179`number`s member functions. 1180 1181[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 1182 1183As well as the usual conversions from arithmetic and string types, instances of `number<mpfi_float_backend<N> >` are 1184copy constructible and assignable from: 1185 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. 1189 1190It's also possible to access the underlying `mpfi_t` via the data() member function of `mpfi_float_backend`. 1191 1192Things you should know when using this type: 1193 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 1200as a valid floating-point number. 1201* Division by zero results in an infinity. 1202 1203There are some additional non member functions for working on intervals: 1204 1205 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1206 number<mpfr_float_backend<Digits10>, ExpressionTemplates> lower(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1207 1208Returns the lower end of the interval. 1209 1210 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1211 number<mpfr_float_backend<Digits10>, ExpressionTemplates> upper(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1212 1213Returns the upper end of the interval. 1214 1215 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1216 number<mpfr_float_backend<Digits10>, ExpressionTemplates> median(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1217 1218Returns the mid point of the interval. 1219 1220 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1221 number<mpfr_float_backend<Digits10>, ExpressionTemplates> width(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1222 1223Returns the absolute width of the interval. 1224 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); 1229 1230Returns the interval which is the intersection of the ['a] and ['b]. Returns an 1231unspecified empty interval if there is no such intersection. 1232 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); 1237 1238Returns the interval which is the union of ['a] and ['b]. 1239 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); 1243 1244Returns `true` only if the intervals ['a] and ['b] overlap. 1245 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); 1249 1250Returns `true` only if point ['a] is contained within the interval ['b]. 1251 1252 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1253 bool zero_in(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1254 1255Returns `true` only if the interval ['a] contains the value zero. 1256 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); 1260 1261Returns `true` only if ['a] is a subset of ['b]. 1262 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); 1266 1267Returns `true` only if ['a] is a proper subset of ['b]. 1268 1269 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1270 bool empty(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1271 1272Returns `true` only if ['a] is an empty interval, equivalent to `upper(a) < lower(a)`. 1273 1274 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1275 bool singleton(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1276 1277Returns `true` if `lower(a) == upper(a)`. 1278 1279[h5 [mpfi] example:] 1280 1281[mpfi_eg] 1282 1283[endsect] 1284 1285[endsect] 1286 1287[section:complex Complex Number Types] 1288 1289The following backends provide complex number arithmetic: 1290 1291[table 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.]] 1297] 1298 1299[section:cpp_complex cpp_complex] 1300 1301`#include <boost/multiprecision/cpp_complex.hpp>` 1302 1303 namespace boost{ namespace multiprecision{ 1304 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> >; 1307 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>; 1310 1311 typedef cpp_complex<50> cpp_complex_50; 1312 typedef cpp_complex<100> cpp_complex_100; 1313 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; 1319 1320 1321 }} // namespaces 1322 1323The `cpp_complex_backend` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 1324complex number type that is a drop-in replacement for `std::complex`, but with much greater precision. 1325 1326The template alias `cpp_complex` avoids the need to use class `number` directly. 1327 1328Type `cpp_complex` can be used at fixed precision by specifying a non-zero `Digits` template parameter. 1329The typedefs `cpp_complex_50` and `cpp_complex_100` provide complex number types at 50 and 100 decimal digits precision 1330respectively. 1331 1332Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example 1333to 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 1336software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively. 1337Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size 1338or bit-layout as true IEEE compatible types. 1339 1340Normally `cpp_complex` allocates no memory: all of the space required for its digits are allocated 1341directly within the class. As a result care should be taken not to use the class with too high a digit count 1342as stack space requirements can grow out of control. If that represents a problem then providing an allocator 1343as a template parameter causes `cpp_complex` to dynamically allocate the memory it needs: this 1344significantly reduces the size of `cpp_complex` and increases the viable upper limit on the number of digits 1345at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 1346as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 1347Note that since the actual type of the objects allocated 1348is 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> >`. 1350 1351The next template parameters determine the type and range of the exponent: parameter `Exponent` can be 1352any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits 1353of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will 1354get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then 1355the library will choose suitable values that are as large as possible given the constraints of the type 1356and need for extra headroom for internal calculations. 1357 1358Finally, as with class `number`, the final template parameter determines whether expression templates are turn 1359on or not. Since by default this type allocates no memory, expression template support is off by default. 1360However, you should probably turn it on if you specify an allocator. 1361 1362There is full standard library support available for this type, comparable with what `std::complex` provides. 1363 1364Things you should know when using this type: 1365 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, 1369and 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 - 1373for example you can convert from `number<cpp_complex<50> >` to `number<cpp_bin_float<SomeOtherValue> >`. 1374Narrowing 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 1376as a valid complex number. 1377 1378[h5 example:] 1379 1380[cpp_complex_eg] 1381 1382Which produces the output (for the multiprecision type): 1383 1384[cpp_complex_out] 1385 1386[endsect] 1387 1388[section:mpc_complex mpc_complex] 1389 1390`#include <boost/multiprecision/mpc.hpp>` 1391 1392 namespace boost{ namespace multiprecision{ 1393 1394 template <unsigned Digits10> 1395 class mpc_complex_backend; 1396 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; 1402 1403 }} // namespaces 1404 1405The `mpc_complex_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpc] `mpc_t` 1406to provide an real-number type that is a drop-in replacement for `std::complex`, but with 1407much greater precision. 1408 1409Type `mpc_complex_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1410at variable precision by setting the template argument to zero. The typedefs mpc_complex_50, mpc_complex_100, 1411mpc_complex_500, mpc_complex_1000 provide complex types at 50, 100, 500 and 1000 decimal digits precision 1412respectively. The typedef mpc_complex provides a variable precision type whose precision can be controlled via the 1413`number`s member functions. 1414 1415The `mpc` backend should allow use of the same syntax as the C++ standard library complex type. 1416When using this backend, remember to link with the flags `-lmpc -lmpfr -lgmp`. 1417 1418As well as the usual conversions from arithmetic and string types, instances of `number<mpc_complex_backend<N> >` are 1419copy constructible and assignable from: 1420 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>`. 1425 1426It's also possible to access the underlying `mpc_t` via the data() member function of `mpfr_float_backend`. 1427 1428Things you should know when using this type: 1429 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 1437as 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 1442of 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 1444is 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 1446to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a` 1447but preserves the precision of `a`. 1448 1449[h5 [mpc] example:] 1450 1451[mpc_eg] 1452 1453Which produces the output (for the multiprecision type): 1454 1455[mpc_out] 1456 1457[endsect] 1458 1459[section:complex128 complex128] 1460 1461`#include <boost/multiprecision/complex128.hpp>` 1462 1463 namespace boost{ namespace multiprecision{ 1464 1465 class complex128_backend; 1466 1467 typedef number<complex128_backend, et_off> complex128; 1468 1469 }} // namespaces 1470 1471The `complex128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types 1472and provides a complex-number type that is a drop-in replacement for the native C++ floating-point types, but with 1473a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real. 1474 1475All the usual standard library functions are available, performance should be equivalent 1476to the underlying native types. 1477 1478As well as the usual conversions from arithmetic and string types, instances of `float128` are 1479copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types. 1480 1481Things you should know when using this type: 1482 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 1486exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of 1487our 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 1489as 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 1492the 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`. 1494 1495[h5 complex128 example:] 1496 1497[complex128_eg] 1498 1499Which results in the output: 1500 1501[complex128_out] 1502 1503[endsect] 1504 1505[section:complex_adaptor complex_adaptor] 1506 1507 namespace boost{ namespace multiprecision{ 1508 1509 template <class Backend> 1510 struct complex_adaptor; 1511 1512 }} 1513 1514Class template `complex_adaptor` is designed to sit inbetween class `number` and an actual floating point backend, 1515in order to create a new complex number type. 1516 1517It is the means by which we implement __cpp_complex and __complex128. 1518 1519[endsect] 1520 1521[endsect] 1522 1523[section:rational Rational Number Types] 1524 1525The following back-ends provide rational number arithmetic: 1526 1527[table 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.]] 1534] 1535 1536[section:cpp_rational cpp_rational] 1537 1538`#include <boost/multiprecision/cpp_int.hpp>` 1539 1540 namespace boost{ namespace multiprecision{ 1541 1542 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 1543 1544 typedef number<cpp_rational_backend> cpp_rational; 1545 1546 }} // namespaces 1547 1548The `cpp_rational_backend` type is used via the typedef `boost::multiprecision::cpp_rational`. It provides 1549a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1550 1551As well as the usual conversions from arithmetic and string types, instances of `cpp_rational` are copy constructible 1552and assignable from type `cpp_int`. 1553 1554There is also a two argument constructor that accepts a numerator and denominator: both of type `cpp_int`. 1555 1556There are also non-member functions: 1557 1558 cpp_int numerator(const cpp_rational&); 1559 cpp_int denominator(const cpp_rational&); 1560 1561which return the numerator and denominator of the number. 1562 1563Things you should know when using this type: 1564 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 1568interpreted as a valid rational number. 1569 1570[h5 Example:] 1571 1572[cpp_rational_eg] 1573 1574[endsect] 1575 1576[section:gmp_rational gmp_rational] 1577 1578`#include <boost/multiprecision/gmp.hpp>` 1579 1580 namespace boost{ namespace multiprecision{ 1581 1582 class gmp_rational; 1583 1584 typedef number<gmp_rational > mpq_rational; 1585 1586 }} // namespaces 1587 1588The `gmp_rational` back-end is used via the typedef `boost::multiprecision::mpq_rational`. It acts as a thin wrapper around the [gmp] `mpq_t` 1589to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1590 1591As well as the usual conversions from arithmetic and string types, instances of `number<gmp_rational>` are copy constructible 1592and assignable from: 1593 1594* The [gmp] native types: `mpz_t`, `mpq_t`. 1595* `number<gmp_int>`. 1596 1597There is also a two-argument constructor that accepts a numerator and denominator (both of type `number<gmp_int>`). 1598 1599There are also non-member functions: 1600 1601 mpz_int numerator(const mpq_rational&); 1602 mpz_int denominator(const mpq_rational&); 1603 1604which return the numerator and denominator of the number. 1605 1606It's also possible to access the underlying `mpq_t` via the `data()` member function of `mpq_rational`. 1607 1608Things you should know when using this type: 1609 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 1613interpreted as a valid rational number. 1614* No changes are made to the [gmp] library's global settings, so this type can coexist with existing 1615[gmp] code. 1616* The code can equally be used with [mpir] as the underlying library - indeed that is the preferred option on Win32. 1617 1618[h5 Example:] 1619 1620[mpq_eg] 1621 1622[endsect] 1623 1624[section:tommath_rational tommath_rational] 1625 1626`#include <boost/multiprecision/tommath.hpp>` 1627 1628 namespace boost{ namespace multiprecision{ 1629 1630 typedef rational_adpater<tommath_int> tommath_rational; 1631 typedef number<tommath_rational > tom_rational; 1632 1633 }} // namespaces 1634 1635The `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>` 1637to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1638 1639The advantage of using this type rather than `boost::rational<tom_int>` directly, is that it is expression-template enabled, 1640greatly reducing the number of temporaries created in complex expressions. 1641 1642There are also non-member functions: 1643 1644 tom_int numerator(const tom_rational&); 1645 tom_int denominator(const tom_rational&); 1646 1647which return the numerator and denominator of the number. 1648 1649Things you should know when using this type: 1650 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 1654interpreted 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 1657needs some improvement in this area. 1658 1659[h5 Example:] 1660 1661[mp_rat_eg] 1662 1663[endsect] 1664 1665[section:br Use With Boost.Rational] 1666 1667All of the integer types in this library can be used as template arguments to `boost::rational<IntType>`. 1668 1669Note that using the library in this way largely negates the effect of the expression templates in `number`. 1670 1671[endsect] 1672 1673[section:rational_adaptor rational_adaptor] 1674 1675 namespace boost{ namespace multiprecision{ 1676 1677 template <class IntBackend> 1678 class rational_adpater; 1679 1680 }} 1681 1682The class template `rational_adaptor` is a back-end for `number` which converts any existing integer back-end 1683into a rational-number back-end. 1684 1685So for example, given an integer back-end type `MyIntegerBackend`, the use would be something like: 1686 1687 typedef number<MyIntegerBackend> MyInt; 1688 typedef number<rational_adaptor<MyIntegerBackend> > MyRational; 1689 1690 MyRational r = 2; 1691 r /= 3; 1692 MyInt i = numerator(r); 1693 assert(i == 2); 1694 1695[endsect] 1696 1697[endsect] 1698 1699[section:misc Miscellaneous Number Types.] 1700 1701Backend types listed in this section are predominantly designed to aid debugging. 1702 1703[section:logged_adaptor logged_adaptor] 1704 1705`#include <boost/multiprecision/logged_adaptor.hpp>` 1706 1707 namespace boost{ namespace multiprecision{ 1708 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); 1713 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); 1722 1723 template <Backend> 1724 class logged_adaptor; 1725 1726 }} // namespaces 1727 1728The `logged_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1729some other backend to class `number` and logs all the events that take place on that object. Before any number operation takes 1730place, it calls `log_prefix_event` with the arguments to the operation (up to 4), plus a string describing the operation. 1731Then after the operation it calls `log_postfix_event` with the result of the operation, plus a string describing the operation. 1732Optionally, `log_postfix_event` takes a second result argument: this occurs when the result of the operation is not a `number`, 1733for 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`. 1735 1736The default versions of `log_prefix_event` and `log_postfix_event` do nothing, it is therefore up to the user to overload these 1737for the particular backend being observed. 1738 1739This type provides `numeric_limits` support whenever the template argument Backend does so. 1740 1741This type is particularly useful when combined with an interval number type - in this case we can use `log_postfix_event` 1742to monitor the error accumulated after each operation. We could either set some kind of trap whenever the accumulated error 1743exceeds some threshold, or simply print out diagnostic information. Using this technique we can quickly locate the cause of 1744numerical instability in a particular routine. The following example demonstrates this technique in a trivial algorithm 1745that deliberately introduces cancellation error: 1746 1747[logged_adaptor] 1748 1749When we examine program output we can clearly see that the diameter of the interval increases after each subtraction: 1750 1751[logged_adaptor_output] 1752 1753[endsect] 1754 1755[section:debug_adaptor debug_adaptor] 1756 1757`#include <boost/multiprecision/debug_adaptor.hpp>` 1758 1759 namespace boost{ namespace multiprecision{ 1760 1761 template <Backend> 1762 class debug_adaptor; 1763 1764 }} // namespaces 1765 1766The `debug_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1767some other backend to class `number` and intercepts all operations on that object storing the result as a string within itself. 1768 1769This type provides `numeric_limits` support whenever the template argument Backend does so. 1770 1771This type is particularly useful when your debugger provides a good view of `std::string`: when this is the case 1772multiprecision values can easily be inspected in the debugger by looking at the `debug_value` member of `debug_adaptor`. 1773The down side of this approach is that runtimes are much slower when using this type. Set against that it can make 1774debugging very much easier, certainly much easier than sprinkling code with `printf` statements. 1775 1776When used in conjunction with the Visual C++ debugger visualisers, the value of a multiprecision type that uses this 1777backend 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> > >`: 1779 1780[$../debugger1.png] 1781 1782Otherwise you will need to expand out the view and look at the "debug_value" member: 1783 1784[$../debugger2.png] 1785 1786It works for all the backend types equally too, here it is inspecting a `number<debug_adaptor<gmp_rational> >`: 1787 1788[$../debugger3.png] 1789 1790 1791[endsect] 1792 1793[section:visualizers Visual C++ Debugger Visualizers] 1794 1795Let's face it debugger multiprecision numbers is hard - simply because we can't easily inspect the value of the numbers. 1796Visual C++ provides a partial solution in the shape of "visualizers" which provide improved views of complex data structures, 1797these visualizers need to be added to the `[Visualizer]` section of `autoexp.dat` located in the `Common7/Packages/Debugger` 1798directory 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 1800into your `autoexp.dat` file. 1801 1802[note These visualizers have only been tested with VC10, also given the ability of buggy visualizers to crash your Visual C++ 1803debugger, make sure you back up `autoexp.dat` file before using these!!] 1804 1805The first visualizer provides improved views of `debug_adaptor`: 1806 1807[$../debugger1.png] 1808 1809The next visualizer provides improved views of cpp_int: small numbers are displayed as actual values, while larger numbers are 1810displayed as an array of hexadecimal parts, with the most significant part first. 1811 1812Here's what it looks like for small values: 1813 1814[$../debugger4.png] 1815 1816And for larger values: 1817 1818[$../debugger5.png] 1819 1820There is also a `~raw` child member that 1821lets you see the actual members of the class: 1822 1823[$../debugger6.png] 1824 1825The visualizer for `cpp_dec_float` shows the first few digits of the value in the preview field, and the full array of digits 1826when you expand the view. As before the `~raw` child gives you access to the actual data members: 1827 1828[$../debugger7.png] 1829 1830[endsect] 1831 1832[endsect] 1833 1834[section:conversions Constructing and Interconverting Between Number Types] 1835 1836All of the number types that are based on `number` have certain conversion rules in common. 1837In particular: 1838 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): 1841 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. 1845 1846* A number can be explicitly constructed from an arithmetic type, even when the conversion is lossy: 1847 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. 1853 1854* A `number` can be converted to any built in type, via the `convert_to` member function: 1855 1856 mpz_int z(2); 1857 int i = z.convert_to<int>(); // sets i to 2 1858 1859* Conversions to rational numbers from floating-point ones are always allowed, and are exact and implicit 1860as long as the rational number uses an unbounded integer type. Please be aware that constructing a rational 1861number from an extended precision floating-point type with a large exponent range can effectively run the system 1862out of memory, as in the extreme case ['2[super max_exponent] / CHAR_BITS] bytes of storage may be required. This 1863does not represent a problem for built in floating-point types however, as the exponent range for these is rather 1864limited. 1865 1866* Conversions to floating-point numbers from rational ones are rounded to nearest (less than 0.5ulp error) 1867as long as the floating-point number is binary, and the integer type used by the rational number is unbounded. 1868 1869Additional conversions may be supported by particular backends. 1870 1871* A `number` can be converted to any built in type, via an explicit conversion operator: 1872this functionality is only available on compilers supporting C++11's explicit conversion syntax. 1873 1874 mpz_int z(2); 1875 int i = z; // Error, implicit conversion not allowed. 1876 int j = static_cast<int>(z); // OK explicit conversion. 1877 1878* Any number type can be ['explicitly] constructed (or assigned) from a `const char*` or a `std::string`: 1879 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 1890 1891* Any number type will interoperate with the builtin types in arithmetic expressions as long as the conversions 1892are not lossy: 1893 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: 1898 df *= 2; 1899 1900 // You can't mix integer types with floats though: 1901 cpp_int i = 2; 1902 i *= 3.14; // Error, no *= operator will be found. 1903 1904* Any number type can be streamed to and from the C++ iostreams: 1905 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) 1909 << df << std::endl 1910 cpp_int i = 1; 1911 i <<= 256; 1912 // Now print in hex format with prefix: 1913 std::cout << std::hex << std::showbase << i << std::endl; 1914 1915* Interconversions between number types of the same family are allowed and are implicit conversions if no 1916loss of precision is involved, and explicit if it is: 1917 1918 int128_t i128 = 0; 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. 1922 1923 mpz_int z = 0; 1924 mpf_float f = z; // OK, GMP handles this conversion natively, and it's not lossy and therefore implicit. 1925 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. 1929 1930* Some interconversions between number types are completely generic, and are always available, albeit the conversions are always ['explicit]: 1931 1932 cpp_int cppi(2); 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: 1936 mpz_int z(cppi); 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 1943 1944* Other interconversions may be allowed as special cases, whenever the backend allows it: 1945 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. 1949 1950More information on what additional types a backend supports conversions from are given in the tutorial for each backend. 1951The converting constructor will be implicit if the backend's converting constructor is also implicit, and explicit if the 1952backends converting constructor is also explicit. 1953 1954[endsect] 1955 1956[section:random Generating Random Numbers] 1957 1958Random numbers are generated in conjunction with Boost.Random. 1959 1960There 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`]. 1962This type can be used with either ['unbounded] integer types, or with ['bounded] (ie fixed precision) unsigned integers: 1963 1964[random_eg1] 1965 1966Program output is: 1967 1968[random_eg1_out] 1969 1970In 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 1973with multiprecision types. Note that if you seed an `independent_bits_engine`, then you are actually seeding 1974the underlying generator, and should therefore provide a sequence of unsigned 32-bit values as the seed. 1975 1976Alternatively 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 1978invoke the underlying engine multiple times to build up the required number of bits in the result: 1979 1980[random_eg2] 1981 1982[random_eg2_out] 1983 1984It is also possible to use [@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`] 1985with a multiprecision generator such as [@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`]. 1986Or 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. 1988 1989floating-point values in \[0,1) are most easily generated using [@http://www.boost.org/doc/html/boost/random/generate_canonical.html `generate_canonical`], 1990note that `generate_canonical` will call the generator multiple times to produce the requested number of bits, for example we can use 1991it with a regular generator like so: 1992 1993[random_eg3] 1994 1995[random_eg3_out] 1996 1997Note however, the distributions do not invoke the generator multiple times to fill up the mantissa of a multiprecision floating-point type 1998with random bits. For these therefore, we should probably use a multiprecision generator (ie `independent_bits_engine`) in combination 1999with the distribution: 2000 2001[random_eg4] 2002 2003[random_eg4_out] 2004 2005And 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`] 2006and [@http://www.boost.org/doc/html/boost/random/subtract_with_idp144360752.html `subtract_with_carry_01_engine`] directly with multiprecision floating-point types. 2007It'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 2008use with these generators in this situation. For this reason, these should probably be used for research purposes only: 2009 2010[random_eg5] 2011 2012[endsect] 2013 2014[section:primetest Primality Testing] 2015 2016The library implements a Miller-Rabin test for primality: 2017 2018 #include <boost/multiprecision/miller_rabin.hpp> 2019 2020 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 2021 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials, Engine& gen); 2022 2023 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 2024 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials); 2025 2026These functions perform a Miller-Rabin test for primality, if the result is `false` then /n/ is definitely composite, 2027while if the result is true then n is probably prime. The probability to declare a composite n as probable prime is 2028at most 0.25[super trials]. Note that this does not allow a statement about the probability of n being actually 2029prime (for that, the prior probability would have to be known). The algorithm used performs some 2030trial divisions to exclude small prime factors, does one Fermat test to exclude many more composites, and then 2031uses the Miller-Rabin algorithm straight out of 2032Knuth Vol 2, which recommends 25 trials for a pretty strong likelihood that /n/ is prime. 2033 2034The third optional argument is for a Uniform Random Number Generator from Boost.Random. When not provided the `mt19937` 2035generator is used. Note that when producing random primes then you should probably use a different random number generator 2036to produce candidate prime numbers for testing, than is used internally by `miller_rabin_test` for determining 2037whether the value is prime. It also helps of course to seed the generators with some source of randomness. 2038 2039The following example searches for a prime `p` for which `(p-1)/2` is also probably prime: 2040 2041[safe_prime] 2042 2043[endsect] 2044 2045[section:lits Literal Types and `constexpr` Support] 2046 2047There are two kinds of `constexpr` support in this library: 2048 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 2051constexpr support, and for many operations C++2a support 2052 2053[h4 Declaring numeric literals] 2054 2055There are two backend types which are literals: 2056 2057* __float128 (which requires GCC), and 2058* Instantiations of `cpp_int_backend` where the Allocator parameter is type `void`. 2059In addition, prior to C++14 the Checked parameter must be `boost::multiprecision::unchecked`. 2060 2061For example: 2062 2063 using namespace boost::multiprecision; 2064 2065 constexpr float128 f = 0.1Q // OK, float128's are always literals in C++11 2066 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. 2069 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. 2073 2074There is also support for user defined-literals with __cpp_int - these are limited to unchecked, fixed precision `cpp_int`'s 2075which are specified in hexadecimal notation. The suffixes supported are: 2076 2077[table 2078[[Suffix][Meaning]] 2079[[_cppi][Specifies a value of type: `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`, where N is chosen 2080to 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 2082to 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> >`.]] 2085] 2086 2087In each case, use of these suffixes with hexadecimal values produces a `constexpr` result. 2088 2089Examples: 2090 2091 // 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; 2095 // 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; 2098 // 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; 2104 // 2105 // Smaller values can be assigned to larger values: 2106 int256_t c = 0x1234_cppi; // OK 2107 // 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 2110 // 2111 // Constants can be padded out with leading zeros to generate wider types: 2112 constexpr uint256_t e = 0x0000000000000000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFF_cppui; // OK 2113 // 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`. 2116 // 2117 constexpr int128_t f = 0x1234_cppi128; // OK, always produces an int128_t as the result. 2118 constexpr uint1024_t g = 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbccccccccccccccccccccc_cppui1024; 2119 // 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: 2122 // 2123 BOOST_MP_DEFINE_SIZED_CPP_INT_LITERAL(2048); 2124 // 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> > 2127 // 2128 // Finally negative values are handled via the unary minus operator: 2129 // 2130 constexpr int1024_t i = -0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui1024; 2131 // 2132 // Which means this also works: 2133 constexpr int1024_t j = -g; // OK: unary minus operator is constexpr. 2134 2135[h4 constexpr arithmetic] 2136 2137The front end of the library is all `constexpr` from C++14 and later. Currently there are only two 2138back end types that are `constexpr` aware: __float128 and __cpp_int. More backends will follow at a later date. 2139 2140Provided 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. 2142 2143The __cpp_int types support constexpr arithmetic, provided it is a fixed precision type with no allocator. It may also 2144be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition 2145the 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 2147requires either a C++2a compiler (one which supports `std::is_constant_evaluated()` - currently only gcc-9 or clang-9 or later), 2148or GCC-6 or later in C++14 mode. 2149Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations: 2150expect to hit roadblocks rather easily. 2151 2152For example given: 2153 2154[constexpr_circle] 2155 2156We can now calculate areas and circumferences using all constexpr arithmetic: 2157 2158[constexpr_circle_usage] 2159 2160Note that these make use of the numeric constants from the Math library, which also happen to be `constexpr`. 2161 2162For a more interesting example, in [@../../example/constexpr_float_arithmetic_examples.cpp constexpr_float_arithmetic_examples.cpp] 2163we define a simple class for `constexpr` polynomial arithmetic: 2164 2165 template <class T, unsigned Order> 2166 struct const_polynomial; 2167 2168Given this, we can use recurrence relations to calculate the coefficients for various orthogonal 2169polynomials - in the example we use the Hermite polynomials, only the constructor does any work - 2170it uses the recurrence relations to calculate the coefficient array: 2171 2172[hermite_example] 2173 2174Now we just need to define H[sub 0] and H[sub 1] as termination conditions for the recurrence: 2175 2176[hermite_example2] 2177 2178We can now declare H[sub 9] as a constexpr object, access the coefficients, and evaluate 2179at an abscissa value, all using `constexpr` arithmetic: 2180 2181[hermite_example3] 2182 2183Also since the coefficients to the Hermite polynomials are integers, we can also generate the Hermite 2184coefficients using (fixed precision) cpp_int's: see [@../../test/constexpr_test_cpp_int_6.cpp constexpr_test_cpp_int_6.cpp]. 2185 2186We can also generate factorials (and validate the result) like so: 2187 2188[factorial_decl] 2189 2190 constexpr uint1024_t f1 = factorial(uint1024_t(31)); 2191 static_assert(f1 == 0x1956ad0aae33a4560c5cd2c000000_cppi); 2192 2193Another example in [@../../test/constexpr_test_cpp_int_7.cpp constexpr_test_cpp_int_7.cpp] generates 2194a fresh multiprecision random number each time the file is compiled. 2195 2196 2197[endsect] 2198 2199[section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`] 2200 2201Any integer number type that uses `cpp_int_backend` as it's implementation layer can import or export its bits via two non-member functions: 2202 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, 2207 OutputIterator out, 2208 unsigned chunk_size, 2209 bool msv_first = true); 2210 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>& 2214 import_bits( 2215 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2216 Iterator i, 2217 Iterator j, 2218 unsigned chunk_size = 0, 2219 bool msv_first = true); 2220 2221These functions are designed for data-interchange with other storage formats, and since __cpp_bin_float uses __cpp_int internally, 2222by extension they can be used for floating-point numbers based on that backend as well (see example below). 2223Parameters and use are as follows: 2224 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, 2229 OutputIterator out, 2230 unsigned chunk_size, 2231 bool msv_first = true); 2232 2233Exports the absolute value of `val` to OutputIterator `out`. The function will write `chunk_size` bits at a time 2234to the OutputIterator, and if `msv_first` is true, will write the most-significant block first. Byte and bit order 2235within 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`. 2237 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 2240has to be specified manually. It may also result in compiler warnings about the value being narrowed.] 2241 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] 2244to create a custom OutputIterator that reverses the byte order of each chunk prior to actually storing the result.] 2245 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>& 2249 import_bits( 2250 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2251 ForwardIterator i, 2252 ForwardIterator j, 2253 unsigned chunk_size = 0, 2254 bool msv_first = true); 2255 2256Imports bits from the iterator range ['\[i,j)] and stores them in `val` to produce an unsigned result (if the result 2257is to be signed you will need to handle that separately). When `msv_first` is true, takes `*i` as the most significant 2258chunk. Assumes there are `chunk_size` bits in each value read from the iterator range, and that these are in machine native 2259bit/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 2261if dereferencing the iterators leads to a signed-integer type, [*and] the sign bit is significant (be particularly careful 2262if 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). 2263As 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 2264that presents it in native order (see [@http://www.boost.org/doc/libs/release/libs/endian/doc/index.html Boost.Endian]). 2265 2266[note 2267Note 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 2268iterators much be pointers, and everything must be little-endian.] 2269 2270[h4 Examples] 2271 2272[IE1] 2273 2274[IE2] 2275 2276[endsect] [/section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`] 2277 2278[section:rounding Rounding Rules for Conversions] 2279 2280As a general rule, all conversions between unrelated types are performed using basic arithmetic operations, therefore 2281conversions are either exact, or follow the same rounding rules as arithmetic for the type in question. 2282 2283The following table summarises the situation for conversions from native types: 2284 2285[table 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]] 2299] 2300 2301[endsect] [/section:rounding Rounding Rules for Conversions] 2302 2303[section:mixed Mixed Precision Arithmetic] 2304 2305Mixed precision arithmetic is fully supported by the library. 2306 2307There are two different forms: 2308 2309* Where the operands are of different precision. 2310* Where the operands are of the same precision, but yield a higher precision result. 2311 2312[h4 Mixing Operands of Differing Precision] 2313 2314If the arguments to a binary operator are of different precision, then the operation is allowed 2315as long as there is an unambiguous implicit conversion from one argument type to the other. 2316In all cases the arithmetic is performed "as if" the lower precision type is promoted to the 2317higher precision type before applying the operator. However, particular backends may optimise 2318this and avoid actually creating a temporary if they are able to do so. 2319 2320For example: 2321 2322 mpfr_float_50 a(2), b; 2323 mpfr_float_100 c(3), d; 2324 static_mpfr_float_50 e(5), f; 2325 mpz_int i(20); 2326 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 2331 2332[h4 Operands of the Same Precision] 2333 2334Sometimes you want to apply an operator to two arguments of the same precision in 2335such a way as to obtain a result of higher precision. The most common situation 2336occurs with fixed precision integers, where you want to multiply two N-bit numbers 2337to obtain a 2N-bit result. This is supported in this library by the following 2338free functions: 2339 2340 template <class ResultType, class Source1 class Source2> 2341 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 2342 2343 template <class ResultType, class Source1 class Source2> 2344 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 2345 2346 template <class ResultType, class Source1 class Source2> 2347 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 2348 2349These functions apply the named operator to the arguments ['a] and ['b] and store the 2350result in ['result], returning ['result]. In all cases they behave "as if" 2351arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 2352operator, though particular backends may well avoid that step by way of an optimization. 2353 2354The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 2355may be either instances of class `number` or native integer types. The latter is an optimization 2356that allows arithmetic to be performed on native integer types producing an extended precision result. 2357 2358For example: 2359 2360[mixed_eg] 2361 2362Produces the output: 2363 2364[mixed_output] 2365 2366[h4 Backends With Optimized Mixed Precision Arithmetic] 2367 2368The following backends have at least some direct support for mixed precision arithmetic, 2369and therefore avoid creating unnecessary temporaries when using the interfaces above. 2370Therefore when using these types it's more efficient to use mixed precision arithmetic, 2371than it is to explicitly cast the operands to the result type: 2372 2373__mpfr_float_backend, __mpf_float, __cpp_int. 2374 2375[endsect] [/section:mixed Mixed Precision Arithmetic] 2376 2377[section:gen_int Generic Integer Operations] 2378 2379All of the [link boost_multiprecision.ref.number.integer_functions non-member integer operations] are overloaded for the 2380built in integer types in 2381`<boost/multiprecision/integer.hpp>`. 2382Where these operations require a temporary increase in precision (such as for `powm`), then 2383if no built in type is available, a __cpp_int of appropriate precision will be used. 2384 2385Some of these functions are trivial, others use compiler intrinsics (where available) to ensure optimal evaluation. 2386 2387The overloaded functions are: 2388 2389 template <class Integer, class I2> 2390 Integer& multiply(Integer& result, const I2& a, const I2& b); 2391 2392Multiplies two `I2` values, to produce a wider `Integer` result. 2393 2394Returns `result = a * b` without overflow or loss of precision in the multiplication. 2395 2396 template <class Integer, class I2> 2397 Integer& add(Integer& result, const I2& a, const I2& b); 2398 2399Adds two `I2` values, to produce a wider `Integer` result. 2400 2401Returns `result = a + b` without overflow or loss of precision in the addition. 2402 2403 template <class Integer, class I2> 2404 Integer& subtract(Integer& result, const I2& a, const I2& b); 2405 2406Subtracts two `I2` values, to produce a wider `Integer` result. 2407 2408Returns `result = a - b` without overflow or loss of precision in the subtraction. 2409 2410 template <class Integer> 2411 Integer powm(const Integer& b, const Integer& p, const Integer& m); 2412 2413Returns b[super p] % m. 2414 2415 template <class Integer> 2416 void divide_qr(const Integer& x, const Integer& y, Integer& q, Integer& r); 2417 2418Sets `q = x / y` and `r = x % y`. 2419 2420 template <class Integer1, class Integer2> 2421 Integer2 integer_modulus(const Integer1& x, Integer2 val); 2422 2423Returns x % val; 2424 2425 template <class Integer> 2426 unsigned lsb(const Integer& x); 2427 2428Returns the (zero-based) index of the least significant bit of `x`. 2429 2430Throws a `std::domain_error` if `x <= 0`. 2431 2432 template <class Integer> 2433 unsigned msb(const Integer& x); 2434 2435Returns the (zero-based) index of the most significant bit of `x`. 2436 2437Throws a `std::domain_error` if `x <= 0`. 2438 2439 template <class Integer> 2440 bool bit_test(const Integer& val, unsigned index); 2441 2442Returns `true` if bit `index` is set in `val`. 2443 2444 template <class Integer> 2445 Integer& bit_set(Integer& val, unsigned index); 2446 2447Sets the `index` bit in `val`. 2448 2449 template <class Integer> 2450 Integer& bit_unset(Integer& val, unsigned index); 2451 2452Unsets the `index` bit in `val`. 2453 2454 template <class Integer> 2455 Integer& bit_flip(Integer& val, unsigned index); 2456 2457Flips the `index` bit in `val`. 2458 2459 template <class Integer> 2460 Integer sqrt(const Integer& x); 2461 template <class Integer> 2462 Integer sqrt(const Integer& x, Integer& r); 2463 2464Returns the integer square root `s` of x and sets `r` to the remainder ['x - s[super 2]]. 2465 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); 2469 2470The regular Miller-Rabin functions in `<boost/multiprecision/miller_rabin.hpp>` are defined in terms of the above 2471generic operations, and so function equally well for built-in or __fundamental_types and multiprecision types. 2472 2473[endsect] [/section:gen_int Generic Integer Operations] 2474 2475[section:serial Boost.Serialization Support] 2476 2477Support for serialization comes in two forms: 2478 2479* Classes __number, __debug_adaptor, __logged_adaptor and __rational_adaptor have "pass through" serialization 2480support 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. 2482 2483[endsect] [/section:serialization Boost Serialization] 2484 2485[section:limits Numeric Limits] 2486 2487Boost.Multiprecision tries hard to implement `std::numeric_limits` for all types 2488as far as possible and meaningful because experience with Boost.Math has shown that this aids portability. 2489 2490The [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf C++ standard library] 2491defines `std::numeric_limits` in section 18.3.2. 2492 2493This 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 2495 WD 10967-1] 2496Information technology Language independent arithmetic Part 1: Integer and floating-point arithmetic. 2497 2498That C Standard in turn refers to 2499 2500[@https://doi.org/10.1109/IEEESTD.1985.82928 IEEE754 IEEE Standard for Binary 2501Floating-Point Arithmetic] 2502 2503There is a useful summary at 2504[@http://www.cplusplus.com/reference/limits/numeric_limits/ C++ reference]. 2505 2506The chosen backend often determines how completely `std::numeric_limits` is available. 2507 2508Compiler options, processor type, and definition of macros or assembler instructions to control denormal numbers will alter 2509the values in the tables given below. 2510 2511[warning GMP's `mpf_t` does not have a concept of overflow: 2512operations that lead to overflow eventually run of out of resources 2513and terminate with stack overflow (often after several seconds).] 2514 2515[section:constants std::numeric_limits<> constants] 2516 2517[h4 is_specialized] 2518 2519`true` for all arithmetic types (integer, floating and fixed-point) 2520for which `std::numeric_limits<T>::numeric_limits` is specialized. 2521 2522A typical test is 2523 2524 if (std::numeric_limits<T>::is_specialized == false) 2525 { 2526 std::cout << "type " << typeid(T).name() << " is not specialized for std::numeric_limits!" << std::endl; 2527 // ... 2528 } 2529 2530Typically `numeric_limits<T>::is_specialized` is `true` for all `T` where the compile-time constant 2531members of `numeric_limits` are indeed known at compile time, and don't vary at runtime. For example 2532floating-point types with runtime-variable precision such as `mpfr_float` have no `numeric_limits` 2533specialization as it would be impossible to define all the members at compile time. In contrast 2534the precision of a type such as `mpfr_float_50` is known at compile time, and so it ['does] have a 2535`numeric_limits` specialization. 2536 2537Note that not all the `std::numeric_limits` member constants and functions are meaningful for all user-defined types (UDT), 2538such as the decimal and binary multiprecision types provided here. More information on this is given in the sections below. 2539 2540[h4 infinity] 2541 2542For floating-point types, [infin] is defined wherever possible, 2543but clearly infinity is meaningless for __arbitrary_precision arithmetic backends, 2544and there is one floating-point type (GMP's `mpf_t`, see __mpf_float) which has no notion 2545of infinity or NaN at all. 2546 2547A typical test whether infinity is implemented is 2548 2549 if(std::numeric_limits<T>::has_infinity) 2550 { 2551 std::cout << std::numeric_limits<T>::infinity() << std::endl; 2552 } 2553 2554and using tests like this is strongly recommended to improve portability. 2555 2556If the backend is switched to a type that does not support infinity then, 2557without checks like this, there will be trouble. 2558 2559[h4 is_signed] 2560 2561`std::numeric_limits<T>::is_signed == true` if the type `T` is signed. 2562 2563For built-in binary types, the sign is held in a single bit, 2564but for other types (cpp_dec_float and cpp_bin_float) 2565it may be a separate storage element, usually `bool`. 2566 2567[h4 is_exact] 2568 2569`std::numeric_limits<T>::is_exact == true` if type T uses exact representations. 2570 2571This is defined as `true` for all integer types and `false` for floating-point types. 2572 2573[@http://stackoverflow.com/questions/14203654/stdnumeric-limitsis-exact-what-is-a-usable-definition A usable definition] 2574has been discussed. 2575 2576ISO/IEC 10967-1, Language independent arithmetic, noted by the C++ Standard defines 2577 2578 A floating-point type F shall be a finite subset of [real]. 2579 2580The important practical distinction is that all integers (up to `max()`) can be stored exactly. 2581 2582[@http://en.wikipedia.org/wiki/Rational_number Rational] 2583types using two integer types are also exact. 2584 2585Floating-point types [*cannot store all real values] 2586(those in the set of [real]) [*exactly]. 2587For example, 0.5 can be stored exactly in a binary floating-point, but 0.1 cannot. 2588What is stored is the nearest representable real value, that is, rounded to nearest. 2589 2590Fixed-point types (usually decimal) are also defined as exact, in that they only 2591store a [*fixed precision], so half cents or pennies (or less) cannot be stored. 2592The results of computations are rounded up or down, 2593just like the result of integer division stored as an integer result. 2594 2595There are number of proposals to 2596[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html 2597add Decimal floating-point Support to C++]. 2598 2599[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2849.pdf Decimal TR]. 2600 2601And also 2602[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html 2603C++ Binary Fixed-Point Arithmetic]. 2604 2605[h4 is_bounded] 2606 2607`std::numeric_limits<T>::is_bounded == true` if the set of values represented by the type `T` is finite. 2608 2609This is `true` for all built-in integer, fixed and floating-point types, 2610and most multi-precision types. 2611 2612It is only `false` for a few __arbitrary_precision types like `cpp_int`. 2613 2614Rational and fixed-exponent representations are exact but not integer. 2615 2616[h4 is_modulo] 2617 2618`std::numeric_limits<T>::is_modulo` is defined as `true` if adding two positive values of type T 2619can yield a result less than either value. 2620 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. 2623 2624For most built-in integer types, `std::numeric_limits<>::is_modulo` is `true`. 2625 2626`bool` is the only exception. 2627 2628The modulo behaviour is sometimes useful, 2629but also can be unexpected, and sometimes undesired, behaviour. 2630 2631Overflow of signed integers can be especially unexpected, 2632possibly causing change of sign. 2633 2634Boost.Multiprecision integer type `cpp_int` is not modulo 2635because as an __arbitrary_precision types, 2636it expands to hold any value that the machine resources permit. 2637 2638However 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). 2641 2642Built-in and multi-precision floating-point types are normally not modulo. 2643 2644Where possible, overflow is to `std::numeric_limits<>::infinity()`, 2645provided `std::numeric_limits<>::has_infinity == true`. 2646 2647[h4 radix] 2648 2649Constant `std::numeric_limits<T>::radix` returns either 2 (for built-in and binary types) 2650or 10 (for decimal types). 2651 2652[h4 digits] 2653 2654The number of `radix` digits that be represented without change: 2655 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. 2658 2659The 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. 2663The value of `digits` reflects the fact that there is one implicit bit which is always set to 1. 2664 2665The Boost.Multiprecision binary types do not use an implicit bit, so the 2666`digits` member reflects exactly how many bits of precision were requested: 2667 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. 2672 2673For the most common case of `radix == 2`, 2674`std::numeric_limits<T>::digits` is the number of bits in the representation, 2675not counting any sign bit. 2676 2677For a decimal integer type, when `radix == 10`, it is the number of decimal digits. 2678 2679[h4 digits10] 2680 2681Constant `std::numeric_limits<T>::digits10` returns the number of 2682decimal digits that can be represented without change or loss. 2683 2684For example, `numeric_limits<unsigned char>::digits10` is 2. 2685 2686This somewhat inscrutable definition means that an `unsigned char` 2687can hold decimal values `0..99` 2688without loss of precision or accuracy, usually from truncation. 2689 2690Had the definition been 3 then that would imply it could hold 0..999, 2691but as we all know, an 8-bit `unsigned char` can only hold 0..255, 2692and an attempt to store 256 or more will involve loss or change. 2693 2694For bounded integers, it is thus [*one less] than number of decimal digits 2695you need to display the biggest integer `std::numeric_limits<T>::max()`. 2696This value can be used to predict the layout width required for 2697 2698[digits10_1] 2699 2700For example, `unsigned short` is often stored in 16 bits, 2701so the maximum value is 0xFFFF or 65535. 2702 2703[digits10_2] 2704 2705 2706For bounded floating-point types, 2707if we create a `double` with a value with `digits10` (usually 15) decimal digits, 2708`1e15` or `1000000000000000` : 2709 2710[digits10_3] 2711 2712and we can increment this value to `1000000000000001` 2713as expected and show the difference too. 2714 2715But if we try to repeat this with more than `digits10` digits, 2716 2717[digits10_4] 2718 2719then we find that when we add one it has no effect, 2720and display show that there is loss of precision. See 2721[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error]. 2722 2723So `digits10` is the number of decimal digits [*guaranteed] to be correct. 2724 2725For example, 'round-tripping' for `double`: 2726 2727* If a decimal string with at most `digits10`( == 15) significant decimal digits 2728is converted to `double` and then converted back to the 2729same number of significant decimal digits, 2730then the final string will match the original 15 decimal digit string. 2731* If a `double` floating-point number is converted to a decimal string 2732with at least 17 decimal digits 2733and then converted back to `double`, 2734then the result will be binary identical to the original `double` value. 2735 2736For most purposes, you will much more likely want 2737`std::numeric_limits<>::max_digits10`, 2738the number of decimal digits that ensure that a change of one least significant bit (ULP) 2739produces a different decimal digits string. 2740 2741For the most common `double` floating-point type,`max_digits10` is `digits10+2`, 2742but you should use C++11 `max_digits10` 2743where possible (see [link boost_multiprecision.tut.limits.constants.max_digits10 below]). 2744 2745[h4:max_digits10 max_digits10] 2746 2747`std::numeric_limits<T>::max_digits10` was added for floating-point 2748because `digits10` decimal digits are insufficient to show 2749a least significant bit (ULP) change giving puzzling displays like 2750 2751 0.666666666666667 != 0.666666666666667 2752 2753from failure to 'round-trip', for example: 2754 2755[max_digits10_2] 2756 2757If you wish to ensure that a change of one least significant bit (ULP) 2758produces a different decimal digits string, 2759then `max_digits10` is the precision to use. 2760 2761For example: 2762 2763[max_digits10_3] 2764 2765will display [pi] to the maximum possible precision using a `double`. 2766 2767[max_digits10_4] 2768 2769For integer types, `max_digits10` is implementation-dependent, 2770but is usually `digits10 + 2`. 2771This 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]. 2773 2774So this will produce neat columns. 2775 2776 std::cout << std::setw(std::numeric_limits<int>::max_digits10) ... 2777 2778The extra two or three least-significant digits are 'noisy' and may be junk, 2779but 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) 2781you must use `os.precision(std::numeric_limits<T>::max_digits10)`. 2782 2783[note For Microsoft Visual Studio 2010, 2784`std::numeric_limits<float>::max_digits10` is wrongly defined as 8. It should be 9. 2785] 2786 2787[note For Microsoft Visual Studio before 2013 and the default floating-point 2788format, a small range of double-precision floating-point values with a 2789significand of approximately 0.0001 to 0.004 and exponent values of 1010 to 27901014 do not round-trip exactly being off by one least significant bit, 2791for probably every third value of the significand. 2792 2793A workaround is using the scientific or exponential format `std::scientific`. 2794 2795Other 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]. 2797 2798For more details see 2799[@https://www.exploringbinary.com/incorrect-round-trip-conversions-in-visual-c-plus-plus/ Incorrect Round-Trip Conversions in Visual C++], 2800and references therein 2801and 2802[@https://arxiv.org/pdf/1310.8121.pdf Easy Accurate Reading and Writing of Floating-Point Numbers, Aubrey Jaffer (August 2018)]. 2803 2804Microsoft 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] 2806algorithm, claimed to be both exact and fast for 32 and 64-bit floating-point numbers. 2807] [/note] 2808 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. 2811] [/note] 2812 2813[note ['requires cxx11_numeric_limits] is a suitable test for use of `std::numeric_limits<float>::max_digits10` 2814to control if a target in a jamfile used by a Boost B2/bjam program is built, or not. 2815] [/note] 2816 2817 2818If `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]. 2820 2821In C++, the equations for what Kahan (on page 4) describes as 'at least' and 'at most' are: 2822 2823 static long double const log10Two = 0.30102999566398119521373889472449L; // log10(2.) 2824 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'. 2827 2828Unfortunately, these cannot be evaluated (at least by C++03) at [*compile-time]. 2829So the following expression is often used instead. 2830 2831 max_digits10 = 2 + std::numeric_limits<T>::digits * 3010U/10000U; 2832 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. 2835 2836often the actual values are computed for the C limits macros: 2837 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. 2841 2842The factor 3010U/10000U is ['log[sub 10](2) = 0.3010] 2843that can be evaluated at compile-time using only `short unsigned int`s to be a desirable `const` or `constexpr` (and usually also `static`). 2844 2845Boost 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]. 2847 2848(See also 2849[@http://www.loria.fr/~zimmerma/mca/mca-cup-0.5.9.pdf Richard P. Brent and Paul Zimmerman, Modern Computer Arithmetic] 2850Equation 3.8 on page 116). 2851 2852[max_digits10_1] [/ example for using max_digits10] 2853 2854[h4 round_style] 2855 2856The rounding style determines how the result of floating-point operations 2857is treated when the result cannot be [*exactly represented] in the significand. 2858Various rounding modes may be provided: 2859 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. 2866 2867For integer types, `std::numeric_limits<T>::round_style` is always towards zero, so 2868 2869 std::numeric_limits<T>::round_style == std::round_to_zero; 2870 2871A decimal type, `cpp_dec_float` rounds in no particular direction, 2872which is to say it doesn't round at all. 2873And since there are several guard digits, 2874it's not really the same as truncation (round toward zero) either. 2875 2876For floating-point types, it is normal to round to nearest. 2877 2878 std::numeric_limits<T>::round_style == std::round_to_nearest; 2879 2880See function `std::numeric_limits<T>::round_error` for the maximum error (in ULP) 2881that rounding can cause. 2882 2883[h4 has_denorm_loss] 2884 2885`true` if a loss of precision is detected as a 2886[@http://en.wikipedia.org/wiki/Denormalization denormalization] loss, 2887rather than an inexact result. 2888 2889Always `false` for integer types. 2890 2891`false` for all types which do not have `has_denorm` == `std::denorm_present`. 2892 2893[h4 denorm_style] 2894 2895[@http://en.wikipedia.org/wiki/Denormal_number Denormalized values] are 2896representations with a variable number of exponent bits that can permit 2897gradual underflow, so that, if type T is `double`. 2898 2899 std::numeric_limits<T>::denorm_min() < std::numeric_limits<T>::min() 2900 2901A type may have any of the following `enum float_denorm_style` values: 2902 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. 2907 2908[h4 Tinyness before rounding] 2909 2910`bool std::numeric_limits<T>::tinyness_before` 2911 2912`true` if a type can determine that a value is too small 2913to be represent as a normalized value before rounding it. 2914 2915Generally true for `is_iec559` floating-point built-in types, 2916but false for integer types. 2917 2918Standard-compliant IEEE 754 floating-point implementations may detect the floating-point underflow at three predefined moments: 2919 2920# After computation of a result with absolute value smaller than 2921`std::numeric_limits<T>::min()`, 2922such implementation detects ['tinyness before rounding] (e.g. UltraSparc). 2923 2924# After rounding of the result to `std::numeric_limits<T>::digits` bits, 2925if the result is tiny, such implementation detects ['tinyness after rounding] 2926(e.g. SuperSparc). 2927 2928# If the conversion of the rounded tiny result to subnormal form 2929resulted in the loss of precision, such implementation detects ['denorm loss]. 2930 2931[endsect] [/section:constants std::numeric_limits<> Constants] 2932 2933[section:functions `std::numeric_limits<>` functions] 2934 2935[h4:max_function `max` function] 2936 2937Function `(std::numeric_limits<T>::max)()` returns the largest finite value 2938that can be represented by the type T. If there is no such value (and 2939`numeric_limits<T>::bounded` is `false`) then returns `T()`. 2940 2941For built-in types there is usually a corresponding MACRO value TYPE_MAX, 2942where TYPE is CHAR, INT, FLOAT etc. 2943 2944Other types, including those provided by a typedef, 2945for example `INT64_T_MAX` for `int64_t`, may provide a macro definition. 2946 2947To cater for situations where no `numeric_limits` specialization is available 2948(for example because the precision of the type varies at runtime), 2949packaged versions of this (and other functions) are provided using 2950 2951 #include <boost/math/tools/precision.hpp> 2952 2953 T = boost::math::tools::max_value<T>(); 2954 2955Of course, these simply use `(std::numeric_limits<T>::max)()` if available, 2956but otherwise 'do something sensible'. 2957 2958[h4 lowest function] 2959 2960Since C++11: `std::numeric_limits<T>::lowest()` is 2961 2962* For integral types, the same as function `min()`. 2963* For floating-point types, generally the negative of `max()` 2964(but implementation-dependent). 2965 2966[digits10_5] 2967 2968[h4:min_function `min` function] 2969 2970Function `(std::numeric_limits<T>::min)()` returns the minimum finite value 2971that can be represented by the type T. 2972 2973For built-in types, there is usually a corresponding MACRO value TYPE_MIN, 2974where TYPE is CHAR, INT, FLOAT etc. 2975 2976Other types, including those provided by a `typedef`, 2977for example, `INT64_T_MIN` for `int64_t`, may provide a macro definition. 2978 2979For floating-point types, 2980it is more fully defined as the ['minimum positive normalized value]. 2981 2982See `std::numeric_limits<T>::denorm_min()` for the smallest denormalized value, provided 2983 2984 std::numeric_limits<T>::has_denorm == std::denorm_present 2985 2986To cater for situations where no `numeric_limits` specialization is available 2987(for example because the precision of the type varies at runtime), 2988packaged versions of this (and other functions) are provided using 2989 2990 #include <boost/math/tools/precision.hpp> 2991 2992 T = boost::math::tools::min_value<T>(); 2993 2994Of course, these simply use `std::numeric_limits<T>::min()` if available. 2995 2996[h4 denorm_min function] 2997 2998Function `std::numeric_limits<T>::denorm_min()` 2999returns the smallest 3000[@http://en.wikipedia.org/wiki/Denormal_number denormalized value], 3001provided 3002 3003 std::numeric_limits<T>::has_denorm == std::denorm_present 3004 3005[denorm_min_1] 3006 3007The exponent is effectively reduced from -308 to -324 3008(though it remains encoded as zero and leading zeros appear in the significand, 3009thereby losing precision until the significand reaches zero). 3010 3011[h4 round_error] 3012 3013Function `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]) 3015that can be caused by any basic arithmetic operation. 3016 3017 round_style == std::round_indeterminate; 3018 3019The rounding style is indeterminable at compile time. 3020 3021For floating-point types, when rounding is to nearest, 3022only half a bit is lost by rounding, and `round_error == 0.5`. 3023In contrast when rounding is towards zero, or plus/minus infinity, 3024we can loose up to one bit from rounding, and `round_error == 1`. 3025 3026For integer types, rounding always to zero, so at worst almost one bit can be rounded, 3027so `round_error == 1`. 3028 3029`round_error()` can be used with `std::numeric_limits<T>::epsilon()` to estimate 3030the maximum potential error caused by rounding. For typical floating-point types, 3031`round_error() = 1/2`, so half epsilon is the maximum potential error. 3032 3033[round_error_1] 3034 3035There are, of course, many occasions when much bigger loss of precision occurs, 3036for example, caused by 3037[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error] 3038or very many iterations. 3039 3040[h4:epsilon epsilon] 3041 3042Function `std::numeric_limits<T>::epsilon()` is meaningful only for non-integral types. 3043 3044It returns the difference between `1.0` and the next value representable 3045by the floating-point type T. 3046So it is a one least-significant-bit change in this floating-point value. 3047 3048For `double` (`float_64t`) it is `2.2204460492503131e-016` 3049showing all possibly significant 17 decimal digits. 3050 3051[epsilon_1] 3052 3053We can explicitly increment by one bit using the function `boost::math::float_next()` 3054and the result is the same as adding `epsilon`. 3055 3056[epsilon_2] 3057 3058Adding any smaller value, like half `epsilon`, will have no effect on this value. 3059 3060[epsilon_3] 3061 3062So this cancellation error leaves the values equal, despite adding half `epsilon`. 3063 3064To achieve greater portability over platform and floating-point type, 3065Boost.Math and Boost.Multiprecision provide a package of functions that 3066'do something sensible' if the standard `numeric_limits` is not available. 3067To use these `#include <boost/math/tools/precision.hpp>`. 3068 3069[epsilon_4] 3070 3071[h5:FP_tolerance Tolerance for Floating-point Comparisons] 3072 3073[@https://en.wikipedia.org/wiki/Machine_epsilon Machine epsilon [epsilon]] 3074is very useful to compute a tolerance when comparing floating-point values, 3075a much more difficult task than is commonly imagined. 3076 3077The C++ standard specifies [@https://en.cppreference.com/w/cpp/types/numeric_limits/epsilon `std::numeric_limits<>::epsilon()`] 3078and Boost.Multiprecision implements this (where possible) for its program-defined types analogous to the 3079__fundamental floating-point types like `double` `float`. 3080 3081For 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] 3083 3084The naive test comparing the absolute difference between two values and a tolerance 3085does not give useful results if the values are too large or too small. 3086 3087So Boost.Test uses an algorithm first devised by Knuth 3088for reliably checking if floating-point values are close enough. 3089 3090See Donald. E. Knuth. The art of computer programming (vol II). 3091Copyright 1998 Addison-Wesley Longman, Inc., 0-201-89684-2. 3092Addison-Wesley Professional; 3rd edition. (The relevant equations are in paragraph 4.2.2, Eq. 36 and 37.) 3093 3094See [@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] 3095for more details. 3096 3097See also: 3098 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] 3100 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] 3102 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] 3104 3105[tolerance_1] 3106 3107used thus: 3108 3109 cd ./test 3110 BOOST_CHECK_CLOSE_FRACTION(expected, calculated, tolerance); 3111 3112(There is also a version BOOST_CHECK_CLOSE using tolerance as a [*percentage] rather than a fraction; 3113usually the fraction version is simpler to use). 3114 3115[tolerance_2] 3116 3117[h4:infinity Infinity - positive and negative] 3118 3119For floating-point types only, for which 3120`std::numeric_limits<T>::has_infinity == true`, 3121function `std::numeric_limits<T>::infinity()` 3122provides an implementation-defined representation for [infin]. 3123 3124The 'representation' is a particular bit pattern reserved for infinity. 3125For 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] 3127are assigned bit patterns for all defined floating-point types. 3128 3129Confusingly, the string resulting from outputting this representation, is also 3130implementation-defined. And the string that can be input to generate the representation is also implementation-defined. 3131 3132For example, the output is `1.#INF` on Microsoft systems, but `inf` on most *nix platforms. 3133 3134This implementation-defined-ness has hampered use of infinity (and NaNs) 3135but Boost.Math and Boost.Multiprecision work hard to provide a sensible representation 3136for [*all] floating-point types, not just the built-in types, 3137which with the use of suitable facets to define the input and output strings, makes it possible 3138to use these useful features portably and including Boost.Serialization. 3139 3140[h4 Not-A-Number NaN] 3141 3142[h5 Quiet_NaN] 3143 3144For floating-point types only, for which 3145`std::numeric_limits<T>::has_quiet_NaN == true`, 3146function `std::numeric_limits<T>::quiet_NaN()` 3147provides an implementation-defined representation for NaN. 3148 3149[@http://en.wikipedia.org/wiki/NaN NaNs] are values to indicate that the 3150result of an assignment or computation is meaningless. 3151A typical example is `0/0` but there are many others. 3152 3153NaNs may also be used, to represent missing values: for example, 3154these could, by convention, be ignored in calculations of statistics like means. 3155 3156Many of the problems with a representation for 3157[@http://en.wikipedia.org/wiki/NaN Not-A-Number] has hampered portable use, 3158similar to those with infinity. 3159 3160[nan_1] 3161 3162But using Boost.Math and suitable facets can permit portable use 3163of both NaNs and positive and negative infinity. 3164 3165[facet_1] 3166 3167[h5 Signaling NaN] 3168 3169For floating-point types only, for which 3170`std::numeric_limits<T>::has_signaling_NaN == true`, 3171function `std::numeric_limits<T>::signaling_NaN()` 3172provides an implementation-defined representation for NaN that causes a hardware trap. 3173It should be noted however, that at least one implementation of this function causes a hardware 3174trap to be triggered simply by calling `std::numeric_limits<T>::signaling_NaN()`, and not only 3175by using the value returned. 3176 3177[endsect] [/section:functions std::numeric_limits<> functions] 3178 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] 3182 3183[section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`] 3184 3185Based on the information above, one can see that different kinds of numbers can be 3186differentiated based on the information stored in `std::numeric_limits`. This is 3187in addition to the traits class [link boost_multiprecision.ref.number.traits_class_support 3188number_category] provided by this library. 3189 3190[h4 Integer Types] 3191 3192For an integer type T, all of the following conditions hold: 3193 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 3201 3202In addition the type is /signed/ if: 3203 3204 std::numeric_limits<T>::is_signed == true 3205 3206If the type is arbitrary precision then: 3207 3208 std::numeric_limits<T>::is_bounded == false 3209 3210Otherwise the type is bounded, and returns a non zero value 3211from: 3212 3213 std::numeric_limits<T>::max() 3214 3215and has: 3216 3217 std::numeric_limits<T>::is_modulo == true 3218 3219if the type implements modulo arithmetic on overflow. 3220 3221[h4 Rational Types] 3222 3223Rational types are just like integers except that: 3224 3225 std::numeric_limits<T>::is_integer == false 3226 3227[h4 Fixed Precision Types] 3228 3229There appears to be no way to tell these apart from rational types, unless they set: 3230 3231 std::numeric_limits<T>::is_exact == false 3232 3233This is because these types are in essence a rational type with a fixed denominator. 3234 3235[h4 floating-point Types] 3236 3237For a floating-point type T, all of the following conditions hold: 3238 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 3246 3247In addition the type is /signed/ if: 3248 3249 std::numeric_limits<T>::is_signed == true 3250 3251And the type may be decimal or binary depending on the value of: 3252 3253 std::numeric_limits<T>::radix 3254 3255In general, there are no arbitrary precision floating-point types, and so: 3256 3257 std::numeric_limits<T>::is_bounded == false 3258 3259[h4 Exact floating-point Types] 3260 3261Exact floating-point types are a [@http://en.wikipedia.org/wiki/Field_%28mathematics%29 field] 3262composed of an arbitrary precision integer scaled by an exponent. Such types 3263have no division operator and are the same as floating-point types except: 3264 3265 std::numeric_limits<T>::is_exact == true 3266 3267[h4 Complex Numbers] 3268 3269For historical reasons, complex numbers do not specialize `std::numeric_limits`, instead you must 3270inspect `std::numeric_limits<typename T::value_type>`. 3271 3272[endsect] [/section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`] 3273 3274[endsect] [/section:limits Numeric Limits] 3275 3276 3277[section:input_output Input Output] 3278 3279[h4 Loopback testing] 3280 3281['Loopback] or ['round-tripping] refers to writing out a value as a decimal digit string using `std::iostream`, 3282usually to a `std::stringstream`, and then reading the string back in to another value, 3283and confirming that the two values are identical. A trivial example using `float` is: 3284 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. 3293 3294and this can be run in a loop for all possible values of a 32-bit float. 3295For other floating-point types `T`, including built-in `double`, 3296it takes far too long to test all values, 3297so a reasonable test strategy is to use a large number of random values. 3298 3299 T write; 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. 3304 3305 T read; 3306 ss >> read; // Get read using operator>> from stringstream. 3307 BOOST_CHECK_EQUAL(read, write); 3308 3309 read = static_cast<T>(ss.str()); // Get read by converting from decimal digits string representation of write. 3310 BOOST_CHECK_EQUAL(read, write); 3311 3312 read = static_cast<T>(write.str(0, f)); // Get read using format specified when written. 3313 BOOST_CHECK_EQUAL(read, write); 3314 3315 3316The test at 3317[@../../test/test_cpp_bin_float_io.cpp test_cpp_bin_float_io.cpp] 3318allows any floating-point type to be ['round_tripped] using a wide range of fairly random values. 3319It also includes tests compared a collection of 3320[@../../test/string_data.ipp stringdata] test cases in a file. 3321 3322[h4 Comparing with output using Built-in types] 3323 3324One can make some comparisons with the output of 3325 3326 <number<cpp_bin_float<53, digit_count_2> > 3327 3328which has the same number of significant bits (53) as 64-bit double precision floating-point. 3329 3330However, although most outputs are identical, there are differences on some platforms 3331caused 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], 3333incorporated by C++. 3334 3335[:['"For e, E, f, F, g, and G conversions, if the number of significant decimal digits 3336is at most DECIMAL_DIG, then the result should be correctly rounded. 3337If the number of significant decimal digits is more than DECIMAL_DIG 3338but the source value is exactly representable with DECIMAL_DIG digits, 3339then the result should be an exact representation with trailing zeros. 3340Otherwise, the source value is bounded by two adjacent decimal strings L < U, 3341both having DECIMAL_DIG significant digits; 3342the value of the resultant decimal string D should satisfy L<= D <= U, 3343with the extra stipulation that the error should have a correct sign 3344for the current rounding direction."]] 3345 3346So not only is correct rounding for the full number of digits not required, 3347but even if the *optional* recommended practice is followed, 3348then the value of these last few digits is unspecified 3349as long as the value is within certain bounds. 3350 3351[note Do not expect the output from different platforms 3352to be [*identical], but `cpp_dec_float`, `cpp_bin_float` (and other backends) outputs should be 3353correctly rounded to the number of digits requested by the set precision and format.] 3354 3355 3356[h4 Macro BOOST_MP_MIN_EXPONENT_DIGITS] 3357 3358[@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 Standard] 3359for [/e and E] format specifiers, 7.19.6 Formatted input/output functions requires: 3360 3361\"The exponent always contains at least two digits, 3362and only as many more digits as necessary to represent the exponent.\" 3363 3364So to conform to the C99 standard (incorporated by C++) 3365 3366 #define BOOST_MP_MIN_EXPONENT_DIGITS 2 3367 3368Confusingly, Microsoft (and MinGW) do not conform to this standard and provide 3369[*at least three digits], for example `1e+001`. 3370So if you want the output to match that from 3371built-in floating-point types on compilers that use Microsofts runtime then use: 3372 3373 #define BOOST_MP_MIN_EXPONENT_DIGITS 3 3374 3375Also useful to get the minimum exponent field width is 3376 3377 #define BOOST_MP_MIN_EXPONENT_DIGITS 1 3378 3379producing a compact output like `2e+4`, 3380useful when conserving space is important. 3381 3382Larger values are also supported, for example, value 4 for `2e+0004` 3383which may be useful to ensure that columns line up. 3384 3385[endsect] [/section:input_output Input Output] 3386 3387[section:hash Hash Function Support] 3388 3389[hash1] 3390 3391[hash2] 3392 3393[hash3] 3394 3395[hash4] 3396 3397[endsect][/hash] 3398 3399[section:eigen Eigen Interoperability] 3400 3401This library provides the header: 3402 3403 #include <boost/multiprecision/eigen.hpp> 3404 3405which defines the traits classes and functions that the Eigen library needs all user-defined number types to provide. 3406 3407For example the following code performs quad-precision matrix solving on complex numbers: 3408 3409[eigen_eg] 3410 3411Which produces the following output: 3412 3413[eigen_out] 3414 3415[endsect] 3416[endsect] 3417 3418[section:ref Reference] 3419 3420[section:number number] 3421 3422[h4 Synopsis] 3423 3424 namespace boost{ namespace multiprecision{ 3425 3426 enum expression_template_option { et_on = 1, et_off = 0 }; 3427 3428 template <class Backend> struct expression_template_default 3429 { static const expression_template_option value = et_on; }; 3430 3431 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 3432 class number 3433 { 3434 public: 3435 typedef Backend backend_type; 3436 typedef typename component_type<self_type>::type value_type; 3437 3438 number(); 3439 number(see-below); 3440 number& operator=(see-below); 3441 number& assign(see-below); 3442 3443 // Member operators 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); 3452 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]``&); 3459 3460 // Use in Boolean context: 3461 operator ``['convertible-to-bool-type]``()const; 3462 // swap: 3463 void swap(number& other); 3464 // Sign: 3465 bool is_zero()const; 3466 int sign()const; 3467 // string conversion: 3468 std::string str()const; 3469 // Generic conversion mechanism 3470 template <class T> 3471 T convert_to()const; 3472 template <class T> 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); 3479 // Comparison: 3480 int compare(const number<Backend>& o)const; 3481 template <class V> 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; 3487 template <class T> 3488 void real(const T& val); 3489 template <class T> 3490 void imag(const T& val); 3491 // Access to the underlying implementation: 3492 Backend& backend(); 3493 const Backend& backend()const; 3494 }; 3495 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]``&); 3517 3518 // Swap: 3519 template <class Backend, expression_template_option ExpressionTemplates> 3520 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 3521 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); 3528 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); 3536 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]``&); 3540 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]``&); 3599 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]``&); 3606 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]``&); 3629 3630 // Traits support: 3631 template <class T> 3632 struct component_type; 3633 template <class T> 3634 struct number_category; 3635 template <class T> 3636 struct is_number; 3637 template <class T> 3638 struct is_number_expression; 3639 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); 3666 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]``&); 3670 3671 }} // namespaces 3672 3673 namespace boost{ namespace math{ 3674 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); 3681 3682 }} // namespaces 3683 3684 // numeric_limits support: 3685 namespace std{ 3686 3687 template <class Backend, expression_template_option ExpressionTemplates> 3688 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 3689 { 3690 /* Usual members here */ 3691 }; 3692 3693 } 3694 3695[h4 Description] 3696 3697 enum expression_template_option { et_on = 1, et_off = 0 }; 3698 3699This enumerated type is used to specify whether expression templates are turned on (et_on) or turned off (et_off). 3700 3701 template <class Backend> struct expression_template_default 3702 { static const expression_template_option value = et_on; }; 3703 3704This traits class specifies the default expression template option to be used with a particular Backend type. 3705It defaults to `et_on`. 3706 3707 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 3708 class number; 3709 3710Class `number` has two template arguments: 3711 3712[variablelist 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.]] 3717] 3718 3719 number(); 3720 number(see-below); 3721 number& operator=(see-below); 3722 number& assign(see-below); 3723 3724Type `number` is default constructible, and both copy constructible and assignable from: 3725 3726* Itself. 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 3731supports rvalue reference construction. In the case of assignment, move semantics are always supported 3732when 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`, 3734or `cpp_dec_float_50` to `cpp_dec_float_100`. 3735 3736Type `number` is explicitly constructible from: 3737 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 3744to rational, integer to float, rational to rational, rational to float, or float to float. 3745 3746The assign member function is available for any type for which an explicit converting constructor exists. 3747It is intended to be used where a temporary generated from an explicit assignment would be expensive, for example: 3748 3749 mpfr_float_50 f50; 3750 mpfr_float_100 f100; 3751 3752 f50 = static_cast<mpfr_float_50>(f100); // explicit cast create a temporary 3753 f50.assign(f100); // explicit call to assign create no temporary 3754 3755In addition, if the type has multiple components (for example rational or complex number types), then there is a 3756two argument constructor: 3757 3758 number(arg1, arg2); 3759 3760Where the two args must either be arithmetic types, or types that are convertible to the two components of `this`. 3761 3762Finally, when the type has a variable precision, then there are constructors: 3763 3764 number(arg1, precision); 3765 number(arg1, arg2, precision); 3766 3767Where `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. 3768 3769Likewise `assign` has a 2-arg overloaded, with the second argument being the precision. 3770 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]``&); 3786 3787These operators all take their usual arithmetic meanings. 3788 3789The arguments to these operators is either: 3790 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`. 3794 3795For the left and right shift operations, the argument must be a builtin 3796integer type with a positive value (negative values result in a `std::runtime_error` being thrown). 3797 3798 operator ``['convertible-to-bool-type]``()const; 3799 3800Returns an ['unmentionable-type] that is usable in Boolean contexts (this allows `number` to be used in any 3801Boolean context - if statements, conditional statements, or as an argument to a logical operator - without 3802type `number` being convertible to type `bool`. 3803 3804This operator also enables the use of `number` with any of the following operators: 3805`!`, `||`, `&&` and `?:`. 3806 3807 void swap(number& other); 3808 3809Swaps `*this` with `other`. 3810 3811 bool is_zero()const; 3812 3813Returns `true` is `*this` is zero, otherwise `false`. 3814 3815 int sign()const; 3816 3817Returns a value less than zero if `*this` is negative, a value greater than zero if `*this` is positive, and zero 3818if `*this` is zero. 3819 3820 std::string str(unsigned precision, bool scientific = true)const; 3821 3822Returns the number formatted as a string, with at least /precision/ digits, and in scientific format 3823if /scientific/ is true. 3824 3825 template <class T> 3826 T convert_to()const; 3827 3828 template <class T> 3829 explicit operator T ()const; 3830 3831Provides a generic conversion mechanism to convert `*this` to type `T`. Type `T` may be any arithmetic type. 3832Optionally other types may also be supported by specific `Backend` types. 3833 3834 3835 static unsigned default_precision(); 3836 static void default_precision(unsigned digits10); 3837 unsigned precision()const; 3838 void precision(unsigned digits10); 3839 3840These functions are only available if the Backend template parameter supports runtime changes to precision. They get and set 3841the default precision and the precision of `*this` respectively. 3842 3843 int compare(const number<Backend, ExpressionTemplates>& o)const; 3844 template <class V> 3845 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type 3846 compare(const V& other)const; 3847 3848Returns: 3849 3850* A value less that 0 for `*this < other` 3851* A value greater that 0 for `*this > other` 3852* Zero for `*this == other` 3853 3854 value_type real()const; 3855 value_type imag()const; 3856 3857These return the real and imaginary parts respectively. If the number is not a complex type, then the imaginary part is always zero. 3858 3859 template <class T> 3860 void real(const T& val); 3861 template <class T> 3862 void imag(const T& val); 3863 3864These set the real and imaginary parts respectively of the number. If the number is not a complex type, then setting the real part 3865is equivalent to assignment, and attempting to set the imaginary part will result in a compile time error. 3866 3867 Backend& backend(); 3868 const Backend& backend()const; 3869 3870Returns the underlying back-end instance used by `*this`. 3871 3872[h4 Non-member operators] 3873 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]``&); 3895 3896These operators all take their usual arithmetic meanings. 3897 3898The arguments to these functions must contain at least one of the following: 3899 3900* A `number`. 3901* An expression template type derived from `number`. 3902* Any type for which `number` has an implicit constructor - for example a builtin arithmetic type. 3903 3904The return type of these operators is either: 3905 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. 3909 3910Finally note that the second argument to the left and right shift operations must be a builtin integer type, 3911and that the argument must be positive (negative arguments result in a `std::runtime_error` being thrown). 3912 3913[h4 swap] 3914 3915 template <class Backend, ExpressionTemplates> 3916 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 3917 3918Swaps `a` and `b`. 3919 3920[h4 Iostream Support] 3921 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) 3928 3929These operators provided formatted input-output operations on `number` types, and expression templates derived from them. 3930 3931It's down to the back-end type to actually implement string conversion. However, the back-ends provided with 3932this library support all of the iostream formatting flags, field width and precision settings. 3933 3934[h4 Arithmetic with a higher precision result] 3935 3936 template <class ResultType, class Source1 class Source2> 3937 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 3938 3939 template <class ResultType, class Source1 class Source2> 3940 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 3941 3942 template <class ResultType, class Source1 class Source2> 3943 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 3944 3945These functions apply the named operator to the arguments ['a] and ['b] and store the 3946result in ['result], returning ['result]. In all cases they behave "as if" 3947arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 3948operator, though particular backends may well avoid that step by way of an optimization. 3949 3950The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 3951may be either instances of class `number` or native integer types. The latter is an optimization 3952that allows arithmetic to be performed on native integer types producing an extended precision result. 3953 3954[h4 Non-member standard library function support] 3955 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]``&); 4013 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]``&); 4020 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]``&); 4027 4028These functions all behave exactly as their standard library C++11 counterparts do: their argument is either an instance of `number` or 4029an expression template derived from it; If the argument is of type `number<Backend, et_off>` then that is also the return type, 4030otherwise the return type is an expression template unless otherwise stated. 4031 4032The integer type arguments to `ldexp`, `frexp`, `scalbn` and `ilogb` may be either type `int`, or the actual 4033type of the exponent of the number type. 4034 4035Complex number types support the following functions: 4036 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]``&); 4046 4047In addition the functions `real`, `imag`, `arg`, `norm`, `conj` and `proj` are overloaded for scalar (ie non-complex) types in the same 4048manner as `<complex>` and treat the argument as a value whose imaginary part is zero. 4049 4050There are also some functions implemented for compatibility with the Boost.Math functions of the same name: 4051 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]``&); 4058 4059All these functions are normally implemented by the Backend type. However, default versions are provided for Backend types that 4060don't have native support for these functions. Please note however, that this default support requires the precision of the type 4061to be a compile time constant - this means for example that the [gmp] MPF Backend will not work with these functions when that type is 4062used at variable precision. 4063 4064Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types (if any other types 4065such as fixed precision or complex types are added to the library later, then these functions may be extended to support those number types). 4066 4067The precision of these functions is generally determined by the backend implementation. For example the precision 4068of these functions when used with __mpfr_float_backend is determined entirely by [mpfr]. When these functions use our own 4069implementations, the accuracy of the transcendental functions is generally a few epsilon. Note however, that the trigonometrical 4070functions incur the usual accuracy loss when reducing arguments by large multiples of [pi]. Also note that both __mpf_float 4071and __cpp_dec_float have a number of guard digits beyond their stated precision, so the error rates listed for these 4072are in some sense artificially low. 4073 4074The following table shows the error rates we observe for these functions with various backend types, functions not listed 4075here are exact (tested on Win32 with VC++10, MPFR-3.0.0, MPIR-2.1.1): 4076 4077[table 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]] 4094] 4095[h4 Traits Class Support] 4096 4097 template <class T> 4098 struct component_type; 4099 4100If 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. 4102 4103 template <class T> 4104 struct number_category; 4105 4106A 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 4109with built in arithmetic types as well as multiprecision ones. 4110 4111 template <class T> 4112 struct is_number; 4113 4114A traits class that inherits from `mpl::true_` if T is an instance of `number<>`, otherwise from `mpl::false_`. 4115 4116 template <class T> 4117 struct is_number_expression; 4118 4119A traits class that inherits from `mpl::true_` if T is an expression template type derived from `number<>`, otherwise from `mpl::false_`. 4120 4121 4122 4123[h4 Integer functions] 4124 4125In addition to functioning with types from this library, these functions are also overloaded for built in integer 4126types if you include `<boost/multiprecision/integer.hpp>`. Further, when used with fixed precision types (whether 4127built in integers or multiprecision ones), the functions will promote to a wider type internally when the algorithm 4128requires it. Versions overloaded for built in integer types return that integer type rather than an expression 4129template. 4130 4131 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 4132 4133Returns the largest integer `x` that divides both `a` and `b`. 4134 4135 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 4136 4137Returns the smallest integer `x` that is divisible by both `a` and `b`. 4138 4139 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``& b, unsigned p); 4140 4141Returns ['b[super p]] as an expression template. Note that this function should be used with extreme care as the result can grow so 4142large as to take "effectively forever" to compute, or else simply run the host machine out of memory. This is the one function in 4143this category that is not overloaded for built in integer types, further, it's probably not a good idea to use it with 4144fixed precision `cpp_int`'s either. 4145 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); 4147 4148Returns ['b[super p] mod m] as an expression template. Fixed precision types are promoted internally to ensure accuracy. 4149 4150 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``& a); 4151 4152Returns the largest integer `x` such that `x * x < a`. 4153 4154 template <class Backend, expression_template_option ExpressionTemplates> 4155 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``& a, number<Backend, EXpressionTemplates>& r); 4156 4157Returns the largest integer `x` such that `x * x < a`, and sets the remainder `r` such that `r = a - x * x`. 4158 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); 4162 4163Divides x by y and returns both the quotient and remainder. After the call `q = x / y` and `r = x % y`. 4164 4165 template <class Integer> 4166 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val); 4167 4168Returns the absolute value of `x % val`. 4169 4170 unsigned lsb(const ``['number-or-expression-template-type]``& x); 4171 4172Returns the (zero-based) index of the least significant bit that is set to 1. 4173 4174Throws a `std::range_error` if the argument is <= 0. 4175 4176 unsigned msb(const ``['number-or-expression-template-type]``& x); 4177 4178Returns the (zero-based) index of the most significant bit. 4179 4180Throws a `std::range_error` if the argument is <= 0. 4181 4182 template <class Backend, class ExpressionTemplates> 4183 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index); 4184 4185Returns `true` if the bit at /index/ in /val/ is set. 4186 4187 template <class Backend, class ExpressionTemplates> 4188 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index); 4189 4190Sets the bit at /index/ in /val/, and returns /val/. 4191 4192 template <class Backend, class ExpressionTemplates> 4193 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index); 4194 4195Unsets the bit at /index/ in /val/, and returns /val/. 4196 4197 template <class Backend, class ExpressionTemplates> 4198 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index); 4199 4200Flips the bit at /index/ in /val/, and returns /val/. 4201 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); 4205 4206Tests to see if the number /n/ is probably prime - the test excludes the vast majority of composite numbers 4207by excluding small prime factors and performing a single Fermat test. Then performs /trials/ Miller-Rabin 4208tests. Returns `false` if /n/ is definitely composite, or `true` if /n/ is probably prime with the 4209probability of it being composite less than 0.25^trials. Fixed precision types are promoted internally 4210to ensure accuracy. 4211 4212[h4 Rational Number Functions] 4213 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]``&); 4216 4217These functions return the numerator and denominator of a rational number respectively. 4218 4219[h4 Boost.Math Interoperability Support] 4220 4221 namespace boost{ namespace math{ 4222 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); 4228 4229 }} // namespaces 4230 4231These floating-point classification functions behave exactly as their Boost.Math equivalents. 4232 4233Other Boost.Math functions and templates may also be 4234specialized or overloaded to ensure interoperability. 4235 4236[h4 std::numeric_limits support] 4237 4238 namespace std{ 4239 4240 template <class Backend, ExpressionTemplates> 4241 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 4242 { 4243 /* Usual members here */ 4244 }; 4245 4246 } 4247 4248Class template `std::numeric_limits` is specialized for all instantiations of `number` whose precision is known at compile time, plus those 4249types whose precision is unlimited (though it is much less useful in those cases). It is not specialized for types 4250whose precision can vary at compile time (such as `mpf_float`). 4251 4252[endsect] 4253 4254[section:cpp_int_ref cpp_int] 4255 4256 namespace boost{ namespace multiprecision{ 4257 4258 typedef unspecified-type limb_type; 4259 4260 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 4261 enum cpp_int_check_type { checked, unchecked }; 4262 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; 4269 // 4270 // Expression templates default to et_off if there is no allocator: 4271 // 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; }; 4275 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 4279 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; 4285 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; 4291 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; 4296 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; 4302 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; 4308 4309 }} // namespaces 4310 4311Class template `cpp_int_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4312Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4313to change. 4314 4315The template arguments are: 4316 4317[variablelist 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.]] 4334] 4335 4336The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4337 4338More information on this type can be found in the [link boost_multiprecision.tut.ints.cpp_int tutorial]. 4339 4340[endsect] 4341 4342[section:gmp_int_ref gmp_int] 4343 4344 namespace boost{ namespace multiprecision{ 4345 4346 class gmp_int; 4347 4348 typedef number<gmp_int > mpz_int; 4349 4350 }} // namespaces 4351 4352Class template `gmp_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4353Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4354to change. 4355 4356The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4357 4358More information on this type can be found in the [link boost_multiprecision.tut.ints.gmp_int tutorial]. 4359 4360[endsect] 4361 4362[section:tom_int_ref tom_int] 4363 4364 namespace boost{ namespace multiprecision{ 4365 4366 class tommath_int; 4367 4368 typedef number<tommath_int > tom_int; 4369 4370 }} // namespaces 4371 4372Class template `tommath_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4373Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4374to change. 4375 4376The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4377 4378More information on this type can be found in the [link boost_multiprecision.tut.ints.tom_int tutorial]. 4379 4380[endsect] 4381 4382[section:mpf_ref gmp_float] 4383 4384 namespace boost{ namespace multiprecision{ 4385 4386 template <unsigned Digits10> 4387 class gmp_float; 4388 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; 4394 4395 }} // namespaces 4396 4397Class template `gmp_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4398Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4399to change. 4400 4401The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 4402should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 4403and `number::precision`. Note that this type does not in any way change the GMP library's global state (for example 4404it does not change the default precision of the mpf_t data type), therefore you can safely mix this type with existing 4405code that uses GMP, and also mix `gmp_float`s of differing precision. 4406 4407The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4408 4409More information on this type can be found in the [link boost_multiprecision.tut.floats.gmp_float tutorial]. 4410 4411[endsect] 4412 4413[section:mpfr_ref mpfr_float_backend] 4414 4415 namespace boost{ namespace multiprecision{ 4416 4417 template <unsigned Digits10> 4418 class mpfr_float_backend; 4419 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; 4425 4426 }} // namespaces 4427 4428Class template `mpfr_float_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4429Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4430to change. 4431 4432The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 4433should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 4434and `number::precision`. Note that this type does not in any way change the GMP or MPFR library's global state (for example 4435it does not change the default precision of the mpfr_t data type), therefore you can safely mix this type with existing 4436code that uses GMP or MPFR, and also mix `mpfr_float_backend`s of differing precision. 4437 4438The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4439 4440More information on this type can be found in the [link boost_multiprecision.tut.floats.mpfr_float tutorial]. 4441 4442[endsect] 4443 4444[section:cpp_bin_float_ref cpp_bin_float] 4445 4446 namespace boost{ namespace multiprecision{ 4447 4448 enum digit_base_type 4449 { 4450 digit_base_2 = 2, 4451 digit_base_10 = 10 4452 }; 4453 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; 4456 4457 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 4458 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 4459 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; 4465 4466 }} // namespaces 4467 4468Class template `cpp_bin_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4469Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4470to change. 4471 4472The class takes six template parameters: 4473 4474[variablelist 4475[[Digits][The number of digits precision the type 4476should 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 4479allocation 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 4482given 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 4484given the limitations of the type and our internal requirements".]] 4485] 4486 4487The type of `number_category<cpp_bin_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4488 4489More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_bin_float tutorial]. 4490 4491[h4 Implementation Notes] 4492 4493Internally, an N-bit `cpp_bin_float` is represented as an N-bit unsigned integer along with an exponent and a sign. 4494The integer part is normalized so that it's most significant bit is always 1. The decimal point is assumed to be 4495directly after the most significant bit of the integer part. The special values zero, infinity and NaN all have 4496the integer part set to zero, and the exponent to one of 3 special values above the maximum permitted exponent. 4497 4498Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain a 2N-bit number, then round and 4499adjust the sign and exponent. 4500 4501Addition and subtraction proceed similarly - if the exponents are such that there is overlap between the two 4502values, then left shift the larger value to produce a number with between N and 2N bits, then perform integer 4503addition or subtraction, round, and adjust the exponent. 4504 4505Division proceeds as follows: first scale the numerator by some power of 2 so that integer division will 4506produce either an N-bit or N+1 bit result plus a remainder. If we get an N bit result then the size of 4507twice the remainder compared to the denominator gives us the rounding direction. Otherwise we have one extra bit 4508in the result which we can use to determine rounding (in this case ties occur only if the remainder is zero and 4509the extra bit is a 1). 4510 4511Square root uses integer square root in a manner analogous to division. 4512 4513Decimal string to binary conversion proceeds as follows: first parse the digits to 4514produce an integer multiplied by a decimal exponent. Note that we stop parsing digits 4515once we have parsed as many as can possibly effect the result - this stops the integer 4516part growing too large when there are a very large number of input digits provided. 4517At this stage if the decimal exponent is positive then the result is an integer and we 4518can in principle simply multiply by 10^N to get an exact integer result. In practice 4519however, that could produce some very large integers. We also need to be able to divide 4520by 10^N in the event that the exponent is negative. Therefore calculation of the 10^N 4521values plus the multiplication or division are performed using limited precision 4522integer arithmetic, plus an exponent, and a track of the accumulated error. At the end of 4523the calculation we will either be able to round unambiguously, or the error will be such 4524that we can't tell which way to round. In the latter case we simply up the precision and try 4525again until we have an unambiguously rounded result. 4526 4527Binary 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 4529so that the result is an N bit integer assuming we want N digits printed in the result. 4530As before we use limited precision arithmetic to calculate the result and up the 4531precision as necessary until the result is unambiguously correctly rounded. In addition 4532our initial calculation of the decimal exponent may be out by 1, so we have to correct 4533that and loop as well in the that case. 4534 4535[endsect] 4536 4537[section:cpp_dec_ref cpp_dec_float] 4538 4539 namespace boost{ namespace multiprecision{ 4540 4541 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 4542 class cpp_dec_float; 4543 4544 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 4545 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 4546 4547 }} // namespaces 4548 4549Class template `cpp_dec_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4550Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4551to change. 4552 4553The class takes three template parameters: 4554 4555[variablelist 4556[[Digits10][The number of decimal digits precision the type 4557should support. Note that this type does not normally perform any dynamic memory allocation, and as a result the `Digits10` 4558template 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 4561allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]] 4562] 4563 4564The type of `number_category<cpp_dec_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4565 4566More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_dec_float tutorial]. 4567 4568[endsect] 4569 4570[section:internals Internal Support Code] 4571 4572There are some traits classes which authors of new backends should be aware of: 4573 4574 namespace boost{ namespace multiprecision{ namespace detail{ 4575 4576 template<typename From, typename To> 4577 struct is_explicitly_convertible; 4578 4579 }}} 4580 4581Inherits from `boost::integral_constant<bool,true>` if type `From` has an explicit conversion from `To`. 4582 4583For compilers that support C++11 SFINAE-expressions this trait should "just work". Otherwise it inherits 4584from `boost::is_convertible<From, To>::type`, and will need to be specialised for Backends that have 4585constructors marked as `explicit`. 4586 4587 template <class From, class To> 4588 struct is_lossy_conversion 4589 { 4590 static const bool value = see below; 4591 }; 4592 4593Member `value` is true if the conversion from `From` to `To` would result in a loss of precision, and `false` otherwise. 4594 4595The default version of this trait simply checks whether the ['kind] of conversion (for example from a floating-point to an integer type) 4596is inherently lossy. Note that if either of the types `From` or `To` are of an unknown number category (because `number_category` is not 4597specialised for that type) then this trait will be `true`. 4598 4599 template<typename From, typename To> 4600 struct is_restricted_conversion 4601 { 4602 static const bool value = see below; 4603 }; 4604 4605Member `value` is `true` if `From` is only explicitly convertible to `To` and not implicitly convertible, or 4606if `is_lossy_conversion<From, To>::value` is `true`. Otherwise `false`. 4607 4608Note that while this trait is the ultimate arbiter of which constructors are marked as `explicit` in class `number`, 4609authors of backend types should generally specialise one of the traits above, rather than this one directly. 4610 4611 template <class T> 4612 is_signed_number; 4613 template <class T> 4614 is_unsigned_number; 4615 4616These 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. 4618 4619[endsect] 4620 4621[section:backendconc Backend Requirements] 4622 4623The requirements on the `Backend` template argument to `number` are split up into 4624sections: compulsory and optional. 4625 4626Compulsory requirements have no default implementation in the library, therefore if the feature 4627they implement is to be supported at all, then they must be implemented by the backend. 4628 4629Optional requirements have default implementations that are called if the backend doesn't provide 4630it's own. Typically the backend will implement these to improve performance. 4631 4632In the following tables, type B is the `Backend` template argument to `number`, `b` and `b2` are 4633a 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`, 4638B2 is another type that meets these requirements, b2 is a variable of type B2, `ss` is variable of type `std::streamsize` 4639and `ff` is a variable of type `std::ios_base::fmtflags`. 4640 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]]] 4698] 4699 4700[table Optional Requirements on the Backend Type 4701[[Expression][Returns][Comments][Throws]] 4702 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]]] 4720 4721[[['Comparisons:]]] 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]]] 4759 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 4820 `eval_add(b, cb3)`. 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]]] 4851 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]]] 4960 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]]] 4968 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.]] 5022 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.]] 5026 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`.]] 5033 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.]] 5037 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`.]] 5043 5044[[['hashing:]]] 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.]] 5047] 5048 5049When the tables above place no ['throws] requirements on an operation, then it is up to each type modelling this concept to 5050decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or 5051inherit from the type `std::runtime_error`. For example, a floating-point type might choose to throw `std::overflow_error` 5052whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero. 5053 5054[note 5055The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name - 5056in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.] 5057 5058[h4 Overloadable Functions] 5059 5060Some of the C99 math functions do not have `eval_` functions but must be overloaded directly: these functions 5061are either trivial or are forwarded to the Boost.Math implementations by default. 5062The full list of these functions is: 5063 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]``&); 5082 5083[endsect] 5084 5085[section:headers Header File Structure] 5086 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.]] 5099] 5100 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.]] 5120] 5121 5122[endsect] 5123 5124[endsect] 5125 5126[section:perf Performance Comparison] 5127 5128[section:overhead The Overhead in the Number Class Wrapper] 5129 5130Using a simple [@../../performance/arithmetic_backend.hpp backend class] that wraps any built in arithmetic type 5131we can measure the overhead involved in wrapping a type inside the `number` frontend, and the effect that turning 5132on expression templates has. The following table compares the performance between `double` and a `double` wrapped 5133inside class `number`: 5134 5135[table 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)]] 5140] 5141 5142As you can see whether or not there is an overhead, and how large it is depends on the actual situation, 5143but the overhead is in any cases small. Expression templates generally add a greater overhead the 5144more complex the expression becomes due to the logic of figuring out how to best unpack and evaluate 5145the 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 5147a bigger win. 5148 5149The following table compares arithmetic using either `long long` or `number<arithmetic_backend<long long> >` 5150for the [@../../performance/voronoi_performance.cpp voronoi-diagram builder test]: 5151 5152[table 5153[[Type][Relative time]] 5154[[`long long`][[*1.0](0.0823s)]] 5155[[`number<arithmetic_backend<long long>, et_off>`][1.05 (0.0875s)]] 5156] 5157 5158This test involves mainly creating a lot of temporaries and performing a small amount of arithmetic on them, 5159with very little difference in performance between the native and "wrapped" types. 5160 5161The test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5162turned on (/Ox), and used MPIR-2.3.0 and [tommath]-0.42.0. The tests were run on 32-bit 5163Windows Vista machine. 5164 5165[endsect] 5166 5167[section:realworld Floating-Point Real World Tests] 5168 5169These tests test the total time taken to execute all of Boost.Math's test cases for these functions. 5170In each case the best performing library gets a relative score of 1, with the total execution time 5171given in brackets. The first three libraries listed are the various floating-point types provided 5172by this library, while for comparison, two popular C++ front-ends to [mpfr] ([mpfr_class] and [mpreal]) 5173are also shown. 5174 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)]] 5183] 5184 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)]] 5193] 5194 5195Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5196turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 5197Windows Vista machine. 5198 5199[endsect] 5200 5201[section:int_real_world Integer Real World Tests] 5202 5203The first set of [@../../performance/voronoi_performance.cpp tests] measure the times taken to 5204execute the multiprecision part of the Voronoi-diagram builder from Boost.Polygon. The tests 5205mainly create a large number of temporaries "just in case" multiprecision arithmetic is required, 5206for comparison, also included in the tests is Boost.Polygon's own partial-multiprecision integer 5207type which was custom written for this specific task: 5208 5209[table 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)]] 5221] 5222 5223Note how for this use case, any dynamic allocation is a performance killer. 5224 5225The next [@../../performance/miller_rabin_performance.cpp tests] measure the time taken to generate 1000 128-bit 5226random numbers and test for primality using the Miller Rabin test. This is primarily a test of modular-exponentiation 5227since that is the rate limiting step: 5228 5229[table 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)]] 5243] 5244 5245It's interesting to note that expression templates have little effect here - perhaps because the actual expressions involved 5246are relatively trivial in this case - so the time taken for multiplication and division tends to dominate. Also note 5247how increasing the internal cache size used by `cpp_int` is quite effective in this case in cutting out memory allocations 5248altogether - cutting about a third off the total runtime. Finally the much quicker times from GMP and tommath are down to their 5249much better modular-exponentiation algorithms (GMP's is about 5x faster). That's an issue which needs to be addressed 5250in a future release for __cpp_int. 5251 5252Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5253turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 5254Windows Vista machine. 5255 5256[endsect] 5257 5258[section:float_performance Float Algorithm Performance] 5259 5260Note that these tests are carefully designed to test performance of the underlying algorithms 5261and not memory allocation or variable copying. As usual, performance results should be taken 5262with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5263specifics of the program. In each table relative times are given first, with the best performer 5264given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5265operations. 5266 5267[table Operator + 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)]] 5272] 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)]] 5278] 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)]] 5284] 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)]] 5290] 5291[table Operator - 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)]] 5296] 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)]] 5302] 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)]] 5308] 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)]] 5314] 5315[table Operator * 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)]] 5320] 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)]] 5326] 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)]] 5332] 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)]] 5338] 5339[table Operator / 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)]] 5344] 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)]] 5350] 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)]] 5356] 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)]] 5362] 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)]] 5368] 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)]] 5374] 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)]] 5380] 5381[table Operator str 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)]] 5386] 5387 5388Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5389turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 5390Windows Vista machine. 5391 5392[endsect] 5393 5394[section:integer_performance Integer Algorithm Performance] 5395 5396Note that these tests are carefully designed to test performance of the underlying algorithms 5397and not memory allocation or variable copying. As usual, performance results should be taken 5398with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5399specifics of the program. In each table relative times are given first, with the best performer 5400given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5401operations. 5402 5403[table Operator + 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)]] 5409] 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)]] 5416] 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)]] 5423] 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)]] 5430] 5431[table Operator - 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)]] 5437] 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)]] 5444] 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)]] 5451] 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)]] 5458] 5459[table Operator * 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)]] 5465] 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)]] 5472] 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)]] 5479] 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)]] 5486] 5487[table Operator / 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)]] 5493] 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)]] 5500] 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)]] 5507] 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)]] 5514] 5515[table Operator % 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)]] 5521] 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)]] 5528] 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)]] 5535] 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)]] 5542] 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)]] 5549] 5550[table Operator gcd 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)]] 5556] 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)]] 5563] 5564[table Operator str 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)]] 5570] 5571[table Operator | 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)]] 5577] 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)]] 5584] 5585[table Operator ^ 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)]] 5591] 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)]] 5598] 5599[table Operator & 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)]] 5605] 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)]] 5612] 5613[table Operator << 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)]] 5619] 5620[table Operator >> 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)]] 5626] 5627 5628Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5629turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 5630Windows Vista machine. 5631 5632Linux x86_64 results are broadly similar, except that libtommath performs much better there. 5633 5634[endsect] 5635 5636[section:rational_performance Rational Type Performance] 5637 5638Note that these tests are carefully designed to test performance of the underlying algorithms 5639and not memory allocation or variable copying. As usual, performance results should be taken 5640with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5641specifics of the program. In each table relative times are given first, with the best performer 5642given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5643operations. 5644 5645[table Operator + 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)]] 5649] 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)]] 5654] 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)]] 5659] 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)]] 5664] 5665[table Operator - 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)]] 5669] 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)]] 5674] 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)]] 5679] 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)]] 5684] 5685[table Operator * 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)]] 5689] 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)]] 5694] 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)]] 5699] 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)]] 5704] 5705[table Operator / 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)]] 5709] 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)]] 5714] 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)]] 5719] 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)]] 5724] 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)]] 5729] 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)]] 5734] 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)]] 5739] 5740[table Operator str 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)]] 5744] 5745 5746Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 5747turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 5748Windows Vista machine. 5749 5750[endsect] 5751 5752[endsect] 5753 5754[section:map Roadmap] 5755 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. 5757 5758[section:hist History] 5759 5760[h4 Multiprecision-3.2.3 (Boost-1.72)] 5761 5762* Big `constexpr` update allows __cpp_int and __float128 arithmetic to be fully `constexpr` with gcc and clang 9 or later, 5763or any compiler supporting `std::is_constant_evaluated()`. 5764 5765[h4 Multiprecision-3.1.3 (Boost-1.71)] 5766 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. 5772 5773[h4 Multiprecision-3.1.2 (Boost-1.70)] 5774 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]. 5783 5784[h4 Multiprecision-3.1.1 (Boost-1.69)] 5785 5786* Big update to better support variable precision types so that the precision of the result 5787is 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`. 5794 5795[h4 Multiprecision-3.1.0 (Boost-1.68)] 5796 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 5810an integer that is wider than we are. 5811* Fix compatibility issue with GCC-8 caused by the introduction of `std::byte`. 5812 5813[h4 Multiprecision-3.0.0 (Boost-1.67)] 5814 5815* [*Breaking Change:] When converting a multiprecision integer to a narrower type, if the value is too large (or negative) to 5816fit in the smaller type, then the result is either the maximum (or minimum) value of the target type. This was always the intended 5817behaviour, but was somewhat haphazardly enforced before. If you really do want just the low order N bits of a value, then you will 5818need to mask these out prior to the case, for example: `static_cast<unsigned>(~static_cast<unsigned>(0) & my_value)`. Note that 5819technically (to avoid undefined behaviour) you should do the same thing with built in integer types too. 5820See [@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]. 5827 5828[h4 Multiprecision-2.3.2 (Boost-1.65)] 5829 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. 5833 5834[h4 Multiprecision-2.3.1 (Boost-1.64)] 5835 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]. 5848 5849 5850[h4 Multiprecision-2.3.0 (Boost-1.63)] 5851 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 5854conversion 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]. 5860 5861[h4 Multiprecision-2.2.8 (Boost-1.62)] 5862 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 5868should 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`. 5884 5885[h4 Multiprecision-2.2.7 (Boost-1.61)] 5886 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 5894double-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. 5905 5906 5907[h4 Multiprecision-2.2.6 (Boost-1.60)] 5908 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]. 5916 5917 5918[h4 Multiprecision-2.2.5 (Boost-1.59)] 5919 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 5922same 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 5924see [@https://svn.boost.org/trac/boost/ticket/11402 #11402]. 5925* Suppressed numerous compiler warnings. 5926 5927[h4 Multiprecision-2.2.4 (Boost-1.58)] 5928 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. 5933 5934[h4 Multiprecision-2.2.3 (Boost-1.57)] 5935 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. 5940 5941[h4 Multiprecision-2.2.2 (Boost-1.56)] 5942 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. 5945 5946[h4 Multiprecision-2.2.1] 5947 5948* Fix bug in assignment from string in cpp_int, see [@https://svn.boost.org/trac/boost/ticket/9936 9936]. 5949 5950[h4 Multiprecision-2.2.0] 5951 5952* Moved to Boost.Multiprecision specific version number - we have one breaking change in Boost-1.54 5953which 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. 5959 5960[h4 Boost-1.55] 5961 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 5967bit 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. 5969See [@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]. 5973 5974[h4 1.54] 5975 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 5982to 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 5984in 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]. 5991 5992[h4 1.53] 5993 5994* First Release. 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]. 5997 5998[h4 Post review changes] 5999 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 6012than either of the arguments. 6013* Added overloads of integer-specific functions for built in integer types. 6014 6015[h4 Pre-review history] 6016 6017*2011-2012, John Maddock adds an expression template enabled front end to Christopher's code, 6018and adds support for other backends. 6019* 2011, Christopher Kormanyos publishes the decimal floating-point code under the Boost 6020Software Licence. The code is published as: [@http://doi.acm.org/10.1145/1916461.1916469 6021"Algorithm 910: A Portable C++ Multiple-Precision 6022System for Special-Function Calculations"], in ACM TOMS, {VOL 37, ISSUE 4, (February 2011)} (C) ACM, 60232011. 6024* 2002-2011, Christopher Kormanyos develops the all C++ decimal arithmetic floating-point 6025code. 6026 6027[endsect] 6028 6029[section:todo TODO] 6030 6031 6032 6033More a list of what ['could] be done, rather than what ['should] be done (which may be a much smaller list!). 6034 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, 6040the 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. 6045 6046Things requested in review: 6047 6048* The performances of mp_number<a_trivial_adaptor<float>, false>respect to 6049float and mp_number<a_trivial_adaptor<int>, false> and int should be 6050given 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 6059an enum class which will be more explicit. E.g `enum class expression_template {disabled, enabled}; 6060enum 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 6062deliberately an implementation detail, and "optional" requirements are optimisations which can't be detected 6063by the user). Not done: this is an implementation detail, the exact list of requirements satisfied is purely 6064an 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 6067conversions. Could the explicit conversion operator be added on 6068compilers supporting it? (Done 2012/09/15). 6069* The front-end should make the differences between implicit and explicit 6070construction (Done 2012/09/15). 6071* The tutorial should add more examples concerning implicit or explicit 6072conversions. (Done 2012/09/15). 6073* The documentation must explain how move semantics helps in this domain 6074and 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 6076and backend requirements operations. (Done 2012/09/15). 6077* The library interface should use the noexcept (BOOST_NOEXCEPT, ...) 6078facilities (Done 2012/09/15). 6079* It is unfortunate that the generic mp_number front end can not make use 6080constexpr 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 6082mp_number class should provide a way to create literals if the backend 6083is 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). 6086 6087 6088 6089[h4 Pre-Review Comments] 6090 6091* Make fixed precision orthogonal to Allocator type in cpp_int. Possible solution - add an additional MaxBits 6092template 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. 6096Open 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). 6105 6106[endsect] 6107 6108[section:faq FAQ] 6109 6110[variablelist 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`. 6152 6153 In general, both work well and give the same results and at roughly the same speed with `cpp_dec_50` sometimes faster. 6154 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]. 6159 6160 `cpp_bin_` is correctly/exactly rounded making it possible to reason about both the precision and rounding of the results.]] 6161] [/variablelist] 6162 6163[endsect] 6164 6165[section:ack Acknowledgements] 6166 6167This library would not have happened without: 6168 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"], 6173Donald E. Knuth, Volume 2: Seminumerical Algorithms, Third Edition 6174(Reading, Massachusetts: Addison-Wesley, 1997), xiv+762pp. ISBN 0-201-89684-2 6175 6176[endsect] 6177 6178[endsect] 6179 6180[section:indexes Indexes] 6181 6182''' 6183<index type="function_name"> 6184<title>Function Index</title> 6185</index> 6186 6187<index type="class_name"> 6188<title>Class Index</title> 6189</index> 6190 6191<index type="typedef_name"> 6192<title>Typedef Index</title> 6193</index> 6194 6195<index/> 6196''' 6197 6198[endsect] 6199