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-2020 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/big_seventh.cpp] 33 34[import ../example/cpp_int_import_export.cpp] 35[import ../example/cpp_bin_float_import_export.cpp] 36[import ../example/tommath_snips.cpp] 37[import ../example/cpp_int_snips.cpp] 38[import ../example/random_snips.cpp] 39[import ../example/safe_prime.cpp] 40[import ../example/mixed_integer_arithmetic.cpp] 41[import ../example/logged_adaptor.cpp] 42[import ../example/numeric_limits_snips.cpp] 43[import ../example/hashing_examples.cpp] 44[import ../example/cpp_complex_examples.cpp] 45[import ../example/mpc_examples.cpp] 46[import ../example/complex128_examples.cpp] 47[import ../example/eigen_example.cpp] 48[import ../example/mpfr_precision.cpp] 49[import ../example/constexpr_float_arithmetic_examples.cpp] 50[import ../test/constexpr_test_cpp_int_5.cpp] 51[import ../test/constexpr_test_cpp_int_7.cpp] 52 53[/External links as templates (see also some defs below)] 54[template mpfr[] [@http://www.mpfr.org MPFR]] 55[template mpc[] [@http://www.multiprecision.org MPC]] 56[template mpfi[] [@http://perso.ens-lyon.fr/nathalie.revol/software.html MPFI]] 57[template gmp[] [@http://gmplib.org GMP]] 58[template mpf_class[] [@http://gmplib.org/manual/C_002b_002b-Interface-Floats.html#C_002b_002b-Interface-Floats mpf_class]] 59[template mpfr_class[] [@http://math.berkeley.edu/~wilken/code/gmpfrxx/ mpfr_class]] 60[template mpreal[] [@http://www.holoborodko.com/pavel/mpfr/ mpreal]] 61[template mpir[] [@http://mpir.org/ MPIR]] 62[template tommath[] [@http://libtom.net libtommath]] 63[template quadmath[] [@http://gcc.gnu.org/onlinedocs/libquadmath/ libquadmath]] 64 65[template super[x]'''<superscript>'''[x]'''</superscript>'''] 66[template sub[x]'''<subscript>'''[x]'''</subscript>'''] 67 68[/insert Equation as a PNG or SVG image, previous generated with an external tool like Latex.] 69[/Used thus [equation ellint6] - without the file type suffix which will chosen automatically.] 70 71[template equation[name] '''<inlinemediaobject> 72<imageobject role="html"> 73<imagedata fileref="../'''[name]'''.png"></imagedata> 74</imageobject> 75<imageobject role="print"> 76<imagedata fileref="../'''[name]'''.svg"></imagedata> 77</imageobject> 78</inlinemediaobject>'''] 79 80[/insert Indented one-line expression italic and serif font probably using Unicode symbols for Greek and symbols.] 81[/Example: [expression [sub 1]F[sub 0](a, z) = (1-z)[super -a]]] 82[template expression[equation] 83[: 84[role serif_italic [equation]] 85] 86[/ Hint you may need to enclose equation in brackets if it contains comma(s) to avoid "error invalid number of arguments"] 87] 88 89[def __tick [role aligncenter [role green \u2714]]] [/ u2714 is a HEAVY CHECK MARK tick (2713 check mark), green] 90[def __cross [role aligncenter [role red \u2718]]] [/ u2718 is a heavy cross, red] 91[def __star [role aligncenter [role red \u2736]]] [/ 6-point star red ] 92 93[/Boost.Multiprecision internals links] 94[def __cpp_int [link boost_multiprecision.tut.ints.cpp_int cpp_int]] 95[def __gmp_int [link boost_multiprecision.tut.ints.gmp_int gmp_int]] 96[def __tom_int [link boost_multiprecision.tut.ints.tom_int tom_int]] 97[def __gmp_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]] 98[def __mpf_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]] 99[def __mpfr_float_backend [link boost_multiprecision.tut.floats.mpfr_float mpfr_float]] 100[def __cpp_bin_float [link boost_multiprecision.tut.floats.cpp_bin_float cpp_bin_float]] 101[def __cpp_dec_float [link boost_multiprecision.tut.floats.cpp_dec_float cpp_dec_float]] 102[def __gmp_rational [link boost_multiprecision.tut.rational.gmp_rational gmp_rational]] 103[def __cpp_rational [link boost_multiprecision.tut.rational.cpp_rational cpp_rational]] 104[def __tommath_rational [link boost_multiprecision.tut.rational.tommath_rational tommath_rational]] 105[def __number [link boost_multiprecision.ref.number number]] 106[def __float128__ [link boost_multiprecision.tut.floats.float128 float128]] 107[def __cpp_complex [link boost_multiprecision.tut.complex.cpp_complex cpp_complex]] 108[def __mpc_complex [link boost_multiprecision.tut.complex.mpc_complex mpc_complex]] 109[def __debug_adaptor [link boost_multiprecision.tut.misc.debug_adaptor debug_adaptor]] 110[def __logged_adaptor [link boost_multiprecision.tut.misc.logged_adaptor logged_adaptor]] 111[def __rational_adaptor [link boost_multiprecision.tut.rational.rational_adaptor rational_adaptor]] 112[def __cpp_complex [link boost_multiprecision.tut.complex.cpp_complex cpp_complex]] 113[def __mpc_complex [link boost_multiprecision.tut.complex.mpc_complex mpc_complex]] 114[def __complex128 [link boost_multiprecision.tut.complex.complex128 complex128]] 115[def __complex_adaptor [link boost_multiprecision.tut.complex.complex_adaptor complex_adaptor]] 116[def __random [link boost_multiprecision.tut.random random number generation]] 117[def __literals [link boost_multiprecision.tut.lits literals]] 118 119[/External references links as macro definitions.] 120[def __expression_template [@https://en.wikipedia.org/wiki/Expression_templates expression template]] 121[def __expression_templates [@https://en.wikipedia.org/wiki/Expression_templates expression templates]] [/plural version] 122[def __UDT [@http://eel.is/c++draft/definitions#defns.prog.def.type program-defined type]] 123[def __fundamental_type [@https://en.cppreference.com/w/cpp/language/types fundamental (built-in) type]] 124[def __fundamental_types [@https://en.cppreference.com/w/cpp/language/types fundamental (built-in) types]] 125[def __fundamental [@https://en.cppreference.com/w/cpp/language/types fundamental (built-in)]] 126[def __math_constants [@https://www.boost.org/doc/libs/release/libs/math/doc/html/math_toolkit/constants.html Boost.Math constants]] 127[def __boost_macros [@https://www.boost.org/doc/libs/release/libs/config/doc/html/boost_config/boost_macro_reference.html Boost macros]] 128[def __boost_config [@https://www.boost.org/doc/libs/release/libs/config/doc/html/index.html Boost.Config]] 129[def __is_constant_evaluated [@https://en.cppreference.com/w/cpp/types/is_constant_evaluated `std::is_constant_evaluated`]] 130[def __compiler_support [@https://en.cppreference.com/w/cpp/compiler_support compiler support]] 131[def __ULP [@http://en.wikipedia.org/wiki/Unit_in_the_last_place Unit in the last place (ULP)]] 132[def __Mathematica [@http://www.wolfram.com/products/mathematica/index.html Wolfram Mathematica]] 133[def __WolframAlpha [@http://www.wolframalpha.com/ Wolfram Alpha]] 134[def __Boost_Serialization [@https://www.boost.org/doc/libs/release/libs/serialization/doc/index.html Boost.Serialization]] 135[def __Boost_Math [@https://www.boost.org/doc/libs/release/libs/math/doc/index.html Boost.Math]] 136[def __Boost_Multiprecision [@https://www.boost.org/doc/libs/release/libs/multiprecision/doc/index.html Boost.Multiprecision]] 137 138[section:intro Introduction] 139 140The Multiprecision Library provides [link boost_multiprecision.tut.ints integer], 141[link boost_multiprecision.tut.rational rational], 142[link boost_multiprecision.tut.floats floating-point], 143and [link boost_multiprecision.tut.complex complex] types in C++ that have more 144range and precision than C++'s ordinary __fundamental types. 145The big number types in Multiprecision can be used with a wide 146selection of basic mathematical operations, elementary transcendental 147functions as well as the functions in Boost.Math. 148The Multiprecision types can also interoperate with any 149__fundamental_type in C++ using clearly defined conversion rules. 150This allows Boost.Multiprecision to be used for all 151kinds of mathematical calculations involving integer, 152rational and floating-point types requiring extended 153range and precision. 154 155Multiprecision consists of a generic interface to the 156mathematics of large numbers as well as a selection of 157big number back-ends, with support for integer, rational, 158floating-point, and complex types. Boost.Multiprecision provides a selection 159of back-ends provided off-the-rack in including 160interfaces to GMP, MPFR, MPIR, MPC, TomMath as well as 161its own collection of Boost-licensed, header-only back-ends for 162integers, rationals and floats. In addition, user-defined back-ends 163can be created and used with the interface of Multiprecision, 164provided the class implementation adheres to the necessary 165[link boost_multiprecision.ref.backendconc concepts]. 166 167Depending upon the number type, precision may be arbitrarily large 168(limited only by available memory), fixed at compile time 169(for example, 50 or 100 decimal digits), or a variable controlled at run-time 170by member functions. The types are __expression_templates - enabled for 171better performance than naive user-defined types. 172 173The Multiprecision library comes in two distinct parts: 174 175* An expression-template-enabled front-end `number` 176that handles all the operator overloading, expression evaluation optimization, and code reduction. 177* A selection of back-ends that implement the actual arithmetic operations, and need conform only to the 178reduced interface requirements of the front-end. 179 180Separation of front-end and back-end allows use of highly refined, but restricted license libraries 181where possible, but provides Boost license alternatives for users who must have a portable 182unconstrained license. 183Which is to say some back-ends rely on 3rd party libraries, 184but a header-only Boost license version is always available (if somewhat slower). 185 186[h5:getting_started Getting started with Boost.Multiprecision] 187 188Should 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, 189close to 'drop-in' replacements for the __fundamental_type analogs, 190then use a fully Boost-licensed number type, and skip to one of more of : 191 192* __cpp_int for multiprecision integers, 193* __cpp_rational for rational types, 194* __cpp_bin_float and __cpp_dec_float for multiprecision floating-point types, 195* __cpp_complex for complex types. 196 197The library is very often used via one of the predefined convenience `typedef`s 198like `boost::multiprecision::int128_t` or `boost::multiprecision::cpp_bin_float_quad`. 199 200For example, if you want a signed, 128-bit fixed size integer: 201 202 #include <boost/multiprecision/cpp_int.hpp> // Integer types. 203 204 boost::multiprecision::int128_t my_128_bit_int; 205 206Alternatively, and more adventurously, if you wanted an 207[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] 208integer type using [gmp] as the underlying implementation then you could use: 209 210 #include <boost/multiprecision/gmp.hpp> // Defines the wrappers around the GMP library's types 211 212 boost::multiprecision::mpz_int myint; // Arbitrary precision integer type. 213 214Or for a simple, portable 128-bit floating-point close to a drop-in for a __fundamental_type like `double`, usually 64-bit 215 216 #include <boost/multiprecision/cpp_bin_float.hpp> 217 218 boost::multiprecision::cpp_bin_float_quad my_quad_real; 219 220Alternatively, you can compose your own 'custom' multiprecision type, by combining `number` with one of the 221predefined back-end types. For example, suppose you wanted a 300 decimal digit floating-point type 222based on the [mpfr] library. In this case, there's no predefined `typedef` with that level of precision, 223so instead we compose our own: 224 225 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR. 226 227 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 228 229 typedef mp::number<mp::mpfr_float_backend<300> > my_float; 230 231 my_float a, b, c; // These variables have 300 decimal digits precision. 232 233We can repeat the above example, but with the expression templates disabled (for faster compile times, but slower runtimes) 234by passing a second template argument to `number`: 235 236 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR. 237 238 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 239 240 typedef mp::number<mp::mpfr_float_backend<300>, et_off> my_float; 241 242 my_float a, b, c; // These variables have 300 decimal digits precision 243 244We can also mix arithmetic operations between different types, provided there is an unambiguous implicit conversion from one 245type to the other: 246 247 #include <boost/multiprecision/cpp_int.hpp> 248 249 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 250 251 mp::int128_t a(3), b(4); 252 mp::int512_t c(50), d; 253 254 d = c * a; // OK, result of mixed arithmetic is an int512_t 255 256Conversions are also allowed: 257 258 d = a; // OK, widening conversion. 259 d = a * b; // OK, can convert from an expression template too. 260 261However conversions that are inherently lossy are either declared explicit or else forbidden altogether: 262 263 d = 3.14; // Error implicit conversion from double not allowed. 264 d = static_cast<mp::int512_t>(3.14); // OK explicit construction is allowed 265 266Mixed arithmetic will fail if the conversion is either ambiguous or explicit: 267 268 number<cpp_int_backend<>, et_off> a(2); 269 number<cpp_int_backend<>, et_on> b(3); 270 271 b = a * b; // Error, implicit conversion could go either way. 272 b = a * 3.14; // Error, no operator overload if the conversion would be explicit. 273 274[h4 Move Semantics] 275 276On compilers that support rvalue-references, class `number` is move-enabled if the underlying backend is. 277 278In addition the non-expression template operator overloads (see below) are move aware and have overloads 279that look something like: 280 281 template <class B> 282 number<B, et_off> operator + (number<B, et_off>&& a, const number<B, et_off>& b) 283 { 284 return std::move(a += b); 285 } 286 287These operator overloads ensure that many expressions can be evaluated without actually generating any temporaries. 288However, there are still many simple expressions such as 289 290 a = b * c; 291 292which don't noticeably benefit from move support. Therefore, optimal performance comes from having both 293move-support, and expression templates enabled. 294 295Note that while "moved-from" objects are left in a sane state, they have an unspecified value, and the only permitted 296operations on them are destruction or the assignment of a new value. Any other operation should be considered 297a programming error and all of our backends will trigger an assertion if any other operation is attempted. This behavior 298allows for optimal performance on move-construction (i.e. no allocation required, we just take ownership of the existing 299object's internal state), while maintaining usability in the standard library containers. 300 301[h4:expression_templates Expression Templates] 302 303Class `number` is expression-template-enabled: that means that rather than having a multiplication 304operator that looks like this: 305 306 template <class Backend> 307 number<Backend> operator * (const number<Backend>& a, const number<Backend>& b) 308 { 309 number<Backend> result(a); 310 result *= b; 311 return result; 312 } 313 314Instead the operator looks more like this: 315 316 template <class Backend> 317 ``['unmentionable-type]`` operator * (const number<Backend>& a, const number<Backend>& b); 318 319Where the '['unmentionable]' return type is an implementation detail that, rather than containing the result 320of the multiplication, contains instructions on how to compute the result. In effect it's just a pair 321of references to the arguments of the function, plus some compile-time information that stores what the operation 322is. 323 324The great advantage of this method is the ['elimination of temporaries]: for example, the "naive" implementation 325of `operator*` above, requires one temporary for computing the result, and at least another one to return it. It's true 326that sometimes this overhead can be reduced by using move-semantics, but it can't be eliminated completely. For example, 327lets suppose we're evaluating a polynomial via Horner's method, something like this: 328 329 T a[7] = { /* some values */ }; 330 //.... 331 y = (((((a[6] * x + a[5]) * x + a[4]) * x + a[3]) * x + a[2]) * x + a[1]) * x + a[0]; 332 333If type `T` is a `number`, then this expression is evaluated ['without creating a single temporary value]. In contrast, 334if we were using the [mpfr_class] C++ wrapper for [mpfr] - then this expression would result in no less than 11 335temporaries (this is true even though [mpfr_class] does use expression templates to reduce the number of temporaries somewhat). Had 336we used an even simpler wrapper around [mpfr] like [mpreal] things would have been even worse and no less that 24 temporaries 337are created for this simple expression (note - we actually measure the number of memory allocations performed rather than 338the number of temporaries directly, note also that the [mpf_class] wrapper that will be supplied with GMP-5.1 reduces the number of 339temporaries to pretty much zero). Note that if we compile with expression templates disabled and rvalue-reference support 340on, then actually still have no wasted memory allocations as even though temporaries are created, their contents are moved 341rather than copied. 342[footnote The actual number generated will depend on the compiler, how well it optimizes the code, and whether it supports 343rvalue references. The number of 11 temporaries was generated with Visual C++ 2010.] 344 345[important 346Expression templates can radically reorder the operations in an expression, for example: 347 348 a = (b * c) * a; 349 350Will get transformed into: 351 352 a *= c; 353 a *= b; 354 355If this is likely to be an issue for a particular application, then they should be disabled. 356] 357 358This library also extends expression template support to standard library functions like `abs` or `sin` with `number` 359arguments. This means that an expression such as: 360 361 y = abs(x); 362 363can be evaluated without a single temporary being calculated. Even expressions like: 364 365 y = sin(x); 366 367get this treatment, so that variable 'y' is used as "working storage" within the implementation of `sin`, 368thus reducing the number of temporaries used by one. Of course, should you write: 369 370 x = sin(x); 371 372Then we clearly can't use `x` as working storage during the calculation, so then a temporary variable 373is created in this case. 374 375Given the comments above, you might be forgiven for thinking that expression-templates are some kind of universal-panacea: 376sadly though, all tricks like this have their downsides. For one thing, expression template libraries 377like this one, tend to be slower to compile than their simpler cousins, they're also harder to debug 378(should you actually want to step through our code!), and rely on compiler optimizations being turned 379on to give really good performance. Also, since the return type from expressions involving `number`s 380is an "unmentionable implementation detail", you have to be careful to cast the result of an expression 381to the actual number type when passing an expression to a template function. For example, given: 382 383 template <class T> 384 void my_proc(const T&); 385 386Then calling: 387 388 my_proc(a+b); 389 390Will very likely result in obscure error messages inside the body of `my_proc` - since we've passed it 391an expression template type, and not a number type. Instead we probably need: 392 393 my_proc(my_number_type(a+b)); 394 395Having said that, these situations don't occur that often - or indeed not at all for non-template functions. 396In addition, all the functions in the Boost.Math library will automatically convert expression-template arguments 397to the underlying number type without you having to do anything, so: 398 399 mpfr_float_100 a(20), delta(0.125); 400 boost::math::gamma_p(a, a + delta); 401 402Will work just fine, with the `a + delta` expression template argument getting converted to an `mpfr_float_100` 403internally by the Boost.Math library. 404 405[caution In C++11 you should never store an expression template using: 406 407`auto my_expression = a + b - c;` 408 409unless you're absolutely sure that the lifetimes of `a`, `b` and `c` will outlive that of `my_expression`. 410 411In fact, it is particularly easy to create dangling references by mixing expression templates with the `auto` 412keyword, for example: 413 414`auto val = cpp_dec_float_50("23.1") * 100;` 415 416In this situation, the integer literal is stored directly in the expression template - so its use is OK here - 417but the `cpp_dec_float_50` temporary is stored by reference and then destructed when the statement completes, 418leaving a dangling reference. 419 420[*['If in doubt, do not ever mix expression templates with the `auto` keyword.]] 421] 422 423And finally... the performance improvements from an expression template library like this are often not as 424dramatic as the reduction in number of temporaries would suggest. For example, if we compare this library with 425[mpfr_class] and [mpreal], with all three using the underlying [mpfr] library at 50 decimal digits precision then 426we see the following typical results for polynomial execution: 427 428[table Evaluation of Order 6 Polynomial. 429[[Library] [Relative Time] [Relative number of memory allocations]] 430[[number] [1.0 (0.00957s)] [1.0 (2996 total)]] 431[[[mpfr_class]] [1.1 (0.0102s)] [4.3 (12976 total)]] 432[[[mpreal]] [1.6 (0.0151s)] [9.3 (27947 total)]] 433] 434 435As you can see, the execution time increases a lot more slowly than the number of memory allocations. There are 436a number of reasons for this: 437 438* The cost of extended-precision multiplication and division is so great, that the times taken for these tend to 439swamp everything else. 440* The cost of an in-place multiplication (using `operator*=`) tends to be more than an out-of-place 441`operator*` (typically `operator *=` has to create a temporary workspace to carry out the multiplication, where 442as `operator*` can use the target variable as workspace). Since the expression templates carry out their 443magic by converting out-of-place operators to in-place ones, we necessarily take this hit. Even so the 444transformation is more efficient than creating the extra temporary variable, just not by as much as 445one would hope. 446 447Finally, note that `number` takes a second template argument, which, when set to `et_off` disables all 448the expression template machinery. The result is much faster to compile, but slower at runtime. 449 450We'll conclude this section by providing some more performance comparisons between these three libraries, 451again, all are using [mpfr] to carry out the underlying arithmetic, and all are operating at the same precision 452(50 decimal digits): 453 454[table Evaluation of Boost.Math's Bessel function test data 455[[Library] [Relative Time] [Relative Number of Memory Allocations]] 456[[mpfr_float_50] [1.0 (5.78s)] [1.0 (1611963)]] 457[[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)] 458 [1.1 (6.29s)] [2.64 (4260868)]] 459[[[mpfr_class]] [1.1 (6.28s)] [2.45 (3948316)]] 460[[[mpreal]] [1.65 (9.54s)] [8.21 (13226029)]] 461] 462 463[table Evaluation of Boost.Math's Non-Central T distribution test data 464[[Library][Relative Time][Relative Number of Memory Allocations]] 465[[number] [1.0 (263s)][1.0 (127710873)]] 466[[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)] 467 [1.0 (260s)][1.2 (156797871)]] 468[[[mpfr_class]] [1.1 (287s)][2.1 (268336640)]] 469[[[mpreal]] [1.5 (389s)][3.6 (466960653)]] 470] 471 472The above results were generated on Win32 compiling with Visual C++ 2010, all optimizations on (/Ox), 473with MPFR 3.0 and MPIR 2.3.0. 474 475[endsect] [/section:intro Introduction] 476 477[section:tut Tutorial] 478 479In order to use this library you need to make two choices: 480 481* What kind of number do I want ([link boost_multiprecision.tut.ints integer], 482[link boost_multiprecision.tut.floats floating-point], [link boost_multiprecision.tut.rational rational], or [link boost_multiprecision.tut.complex complex]). 483* Which back-end do I want to perform the actual arithmetic (Boost-supplied, GMP, MPFR, MPC, Tommath etc)? 484 485[section:ints Integer Types] 486 487The following back-ends provide integer arithmetic: 488 489[table 490[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 491[[`cpp_int`][boost/multiprecision/cpp_int.hpp][2][None] 492 [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]]] 493[[`gmp_int`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 494[[`tom_int`][boost/multiprecision/tommath.hpp][2][[tommath]][Public domain back-end with no licence restrictions.][Slower than [gmp].]] 495] 496 497[section:cpp_int cpp_int] 498 499`#include <boost/multiprecision/cpp_int.hpp>` 500 501 namespace boost{ namespace multiprecision{ 502 503 typedef unspecified-type limb_type; 504 505 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 506 enum cpp_int_check_type { checked, unchecked }; 507 508 template <unsigned MinBits = 0, 509 unsigned MaxBits = 0, 510 cpp_integer_type SignType = signed_magnitude, 511 cpp_int_check_type Checked = unchecked, 512 class Allocator = std::allocator<limb_type> > 513 class cpp_int_backend; 514 // 515 // Expression templates default to et_off if there is no allocator: 516 // 517 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked> 518 struct expression_template_default<cpp_int_backend<MinBits, MaxBits, SignType, Checked, void> > 519 { static const expression_template_option value = et_off; }; 520 521 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer 522 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 523 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number 524 525 // Fixed precision unsigned types: 526 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t; 527 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t; 528 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t; 529 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t; 530 531 // Fixed precision signed types: 532 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t; 533 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t; 534 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t; 535 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t; 536 537 // Over again, but with checking enabled this time: 538 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int; 539 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend; 540 typedef number<cpp_rational_backend> checked_cpp_rational; 541 542 // Checked fixed precision unsigned types: 543 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t; 544 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t; 545 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t; 546 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t; 547 548 // Fixed precision signed types: 549 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t; 550 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t; 551 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t; 552 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t; 553 554 }} // namespaces 555 556The `cpp_int_backend` type is normally used via one of the convenience typedefs given above. 557 558This back-end is the "Swiss Army Knife" of integer types as it can represent both fixed and 559[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] 560integer types, and both signed and unsigned types. There are five template arguments: 561 562[variablelist 563[[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory 564 allocation. When zero, this field is determined automatically based on how many bits can be stored 565 in union with the dynamic storage header: setting a larger value may improve performance as larger integer 566 values will be stored internally before memory allocation is required.]] 567[[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type. 568 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic 569 memory allocation will ever be performed: in this situation the Allocator parameter should be set to 570 type `void`. Note that this parameter should not be used simply to prevent large memory 571 allocations, not only is that role better performed by the allocator, but fixed precision 572 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]] 573[[SignType][Determines whether the resulting type is signed or not. Note that for 574[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types 575 this parameter must be `signed_magnitude`. For fixed precision 576 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]] 577[[Checked][This parameter has two values: `checked` or `unchecked`. See below.]] 578[[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]] 579] 580 581When the template parameter Checked is set to `checked` then the result is a ['checked-integer], checked 582and unchecked integers have the following properties: 583 584[table 585[[Condition][Checked-Integer][Unchecked-Integer]] 586[[Numeric overflow in fixed precision arithmetic][Throws a `std::overflow_error`.][Performs arithmetic modulo 2[super MaxBits]]] 587[[Constructing an integer from a value that can not be represented in the target type][Throws a `std::range_error`.] 588[Converts the value modulo 2[super MaxBits], signed to unsigned conversions extract the last MaxBits bits of the 5892's complement representation of the input value.]] 590[[Unsigned subtraction yielding a negative value.][Throws a `std::range_error`.][Yields the value that would 591result from treating the unsigned type as a 2's complement signed type.]] 592[[Attempting a bitwise operation on a negative value.][Throws a `std::range_error`][Yields the value, but not the bit pattern, 593that would result from performing the operation on a 2's complement integer type.]] 594] 595 596Things you should know when using this type: 597 598* Default constructed `cpp_int_backend`s have the value zero. 599* Division by zero results in a `std::overflow_error` being thrown. 600* Construction from a string that contains invalid non-numeric characters results in a `std::runtime_error` being thrown. 601* Since the precision of `cpp_int_backend` is necessarily limited when the allocator parameter is void, 602care should be taken to avoid numeric overflow when using this type 603unless you actually want modulo-arithmetic behavior. 604* The type uses a sign-magnitude representation internally, so type `int128_t` has 128-bits of precision plus an extra sign bit. 605In this respect the behaviour of these types differs from __fundamental 2's complement types. In might be tempting to use a 606127-bit type instead, and indeed this does work, but behaviour is still slightly different from a 2's complement __fundamental type 607as the minimum and maximum values are identical (apart from the sign), where as they differ by one for a true 2's complement type. 608That said it should be noted that there's no requirement for fundamental_types to be 2's complement either - it's simply that this 609is the most common format by far. 610* Attempting to print negative values as either an Octal or Hexadecimal string results in a `std::runtime_error` being thrown, 611this is a direct consequence of the sign-magnitude representation. 612* The fixed precision types `[checked_][u]intXXX_t` have expression template support turned off - it seems to make little 613difference to the performance of these types either way - so we may as well have the faster compile times by turning 614the feature off. 615* Unsigned types support subtraction - the result is "as if" a 2's complement operation had been performed as long as they are not 616 ['checked-integers] (see above). 617 In other words they behave pretty much as a __fundamental integer type would in this situation. So for example if we were using 618 `uint128_t` then `uint128_t(1)-4` would result in the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD` 619 of type `uint128_t`. However, had this operation been performed on `checked_uint128_t` then a `std::range_error` would have 620 been thrown. 621* Unary negation of unsigned types results in a compiler error (static assertion). 622* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 623* When used at fixed precision, the size of this type is always one machine word (plus any compiler-applied alignment padding) 624larger than you would expect for an N-bit integer: 625the extra word stores both the sign, and how many machine words in the integer are actually in use. 626The latter is an optimisation for larger fixed precision integers, so that a 1024-bit integer has almost the same performance 627characteristics as a 128-bit integer, rather than being 4 times slower for addition and 16 times slower for multiplication 628 (assuming the values involved would always fit in 128 bits). 629Typically this means you can use 630an integer type wide enough for the "worst case scenario" with only minor performance degradation even if most of the time 631the arithmetic could in fact be done with a narrower type. 632Also note that unsigned fixed precision types small enough to fit inside the largest native integer become a simple wrapper around that type, 633this includes the "checked" variants. Small signed types will always have an extra sign word and so be larger than their native equivalent. 634* When used at fixed precision and MaxBits is smaller than the number of bits in the largest native integer type, then 635internally `cpp_int_backend` switches to a "trivial" implementation where it is just a thin wrapper around a single 636integer. Note that it will still be slightly slower than a bare native integer, as it emulates a 637signed-magnitude representation rather than simply using the platforms native sign representation: this ensures 638there is no step change in behavior as a cpp_int grows in size. 639* Fixed precision `cpp_int`'s have some support for `constexpr` values and user-defined literals, see 640[link boost_multiprecision.tut.lits here] for the full description. For example `0xfffff_cppi1024` 641specifies a 1024-bit integer with the value 0xffff. This can be used to generate compile-time constants that are 642too large to fit into any __fundamental number type. 643* The __cpp_int types support constexpr arithmetic, provided it is a fixed-precision type with no allocator. It may also 644be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition 645the free functions `abs`, `swap`, `multiply`, `add`, `subtract`, `divide_qr`, `integer_modulus`, `powm`, `lsb`, `msb`, 646`bit_test`, `bit_set`, `bit_unset`, `bit_flip`, `sqrt`, `gcd`, `lcm` are all supported. Use of __cpp_int in this way 647requires either a C++2a compiler (one which supports `std::is_constant_evaluated()`), or GCC-6 or later in C++14 mode. 648Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations: 649expect to hit roadblocks rather easily. 650* You can import/export the raw bits of a __cpp_int to and from external storage via the `import_bits` and `export_bits` 651functions. More information is in the [link boost_multiprecision.tut.import_export section on import/export]. 652 653[h5:cpp_int_eg Example:] 654 655[cpp_int_eg] 656 657[endsect] [/section:cpp_int cpp_int] 658 659[section:gmp_int gmp_int] 660 661`#include <boost/multiprecision/gmp.hpp>` 662 663 namespace boost{ namespace multiprecision{ 664 665 class gmp_int; 666 667 typedef number<gmp_int > mpz_int; 668 669 }} // namespaces 670 671The `gmp_int` back-end is used via the typedef `boost::multiprecision::mpz_int`. It acts as a thin wrapper around the [gmp] `mpz_t` 672to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 673 674As well as the usual conversions from arithmetic and string types, type `mpz_int` is copy constructible and assignable from: 675 676* The [gmp] native types: `mpf_t`, `mpz_t`, `mpq_t`. 677* Instances of `number<T>` that are wrappers around those types: `number<gmp_float<N> >`, `number<gmp_rational>`. 678 679It's also possible to access the underlying `mpz_t` via the `data()` member function of `gmp_int`. 680 681Things you should know when using this type: 682 683* No changes are made to the GMP library's global settings - so you can safely mix this type with 684existing code that uses [gmp]. 685* Default constructed `gmp_int`s have the value zero (this is GMP's default behavior). 686* Formatted IO for this type does not support octal or hexadecimal notation for negative values, 687as a result performing formatted output on this type when the argument is negative and either of the flags 688`std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown. 689* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 690as a valid integer. 691* Division by zero results in a `std::overflow_error` being thrown. 692* Although this type is a wrapper around [gmp] it will work equally well with [mpir]. Indeed use of [mpir] 693is recommended on Win32. 694* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 695 696[h5 Example:] 697 698[mpz_eg] 699 700[endsect] [/section:gmp_int gmp_int] 701 702[section:tom_int tom_int] 703 704`#include <boost/multiprecision/tommath.hpp>` 705 706 namespace boost{ namespace multiprecision{ 707 708 class tommath_int; 709 710 typedef number<tommath_int > tom_int; 711 712 }} // namespaces 713 714The `tommath_int` back-end is used via the typedef `boost::multiprecision::tom_int`. It acts as a thin wrapper around the [tommath] `tom_int` 715to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 716 717Things you should know when using this type: 718 719* Default constructed objects have the value zero (this is [tommath]'s default behavior). 720* Although `tom_int` is mostly a drop in replacement for the integer __fundamental_types, it should be noted that it is a 721rather strange beast as it's a signed type that is not a 2's complement type. As a result the bitwise operations 722`| & ^` will throw a `std::runtime_error` exception if either of the arguments is negative. Similarly the complement 723operator`~` is deliberately not implemented for this type. 724* Formatted IO for this type does not support octal or hexadecimal notation for negative values, 725as a result performing formatted output on this type when the argument is negative and either of the flags 726`std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown. 727* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 728as a valid integer. 729* Division by zero results in a `std::overflow_error` being thrown. 730 731[h5 Example:] 732 733[tommath_eg] 734 735[endsect] [/section:tom_int tom_int] 736 737[section:egs Examples] 738 739[import ../example/integer_examples.cpp] 740 741[section:factorials Factorials] 742[FAC1] 743[endsect] [/section:factorials Factorials] 744 745 746[section:bitops Bit Operations] 747[BITOPS] 748[endsect] [/section:bitops Bit Operations] 749 750 751[endsect] 752 753[endsect] 754 755[section:floats Floating-point Types] 756 757The following back-ends provide floating-point arithmetic: 758 759[table 760[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 761[[`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.]] 762[[`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.]] 763[[`mpf_float<N>`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 764[[`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.]] 765[[`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.]] 766] 767 768[section:cpp_bin_float cpp_bin_float] 769 770`#include <boost/multiprecision/cpp_bin_float.hpp>` 771 772 namespace boost{ namespace multiprecision{ 773 774 enum digit_base_type 775 { 776 digit_base_2 = 2, 777 digit_base_10 = 10 778 }; 779 780 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0> 781 class cpp_bin_float; 782 783 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 784 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 785 786 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single; 787 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double; 788 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended; 789 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad; 790 typedef number<backends::cpp_bin_float<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143>, et_off> cpp_bin_float_oct; 791 792 }} // namespaces 793 794The `cpp_bin_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 795floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 796much greater precision. 797 798Type `cpp_bin_float` can be used at fixed precision by specifying a non-zero `Digits` template parameter. 799The typedefs `cpp_bin_float_50` and `cpp_bin_float_100` provide arithmetic types at 50 and 100 decimal digits precision 800respectively. 801 802Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example 803to declare a `cpp_bin_float` with exactly the same precision as `double` one would use 804`number<cpp_bin_float<53, digit_base_2> >`. The typedefs `cpp_bin_float_single`, `cpp_bin_float_double`, 805`cpp_bin_float_quad`, `cpp_bin_float_oct` and `cpp_bin_float_double_extended` provide 806software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively. 807Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size 808or bit-layout as true IEEE compatible types. 809 810Normally `cpp_bin_float` allocates no memory: all of the space required for its digits are allocated 811directly within the class. As a result care should be taken not to use the class with too high a digit count 812as stack space requirements can grow out of control. If that represents a problem then providing an allocator 813as a template parameter causes `cpp_bin_float` to dynamically allocate the memory it needs: this 814significantly reduces the size of `cpp_bin_float` and increases the viable upper limit on the number of digits 815at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 816as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 817Note that since the actual type of the objects allocated 818is completely opaque, the suggestion would be to use an allocator with `void` `value_type`, for example: 819`number<cpp_bin_float<1000, digit_base_10, std::allocator<void> > >`. 820 821The final template parameters determine the type and range of the exponent: parameter `Exponent` can be 822any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits 823of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will 824get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then 825the library will choose suitable values that are as large as possible given the constraints of the type 826and need for extra headroom for internal calculations. 827 828There is full standard library and `numeric_limits` support available for this type. 829 830Things you should know when using this type: 831 832* Default constructed `cpp_bin_float`s have a value of zero. 833* The radix of this type is 2, even when the precision is specified as decimal digits. 834* The type supports both infinities and NaNs. An infinity is generated whenever the result would overflow, 835and a NaN is generated for any mathematically undefined operation. 836* There is a `std::numeric_limits` specialisation for this type. 837* Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type - 838for example you can convert from `number<cpp_bin_float<50> >` to `number<cpp_bin_float<SomeOtherValue> >`. 839Narrowing conversions round to nearest and are `explicit`. 840* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 841as a valid floating-point number. 842* All arithmetic operations are correctly rounded to nearest. String conversions and the `sqrt` function 843are also correctly rounded, but transcendental functions (sin, cos, pow, exp etc) are not. 844 845[h5 cpp_bin_float example:] 846 847[cpp_bin_float_eg] 848 849[endsect] 850 851[section:cpp_dec_float cpp_dec_float] 852 853`#include <boost/multiprecision/cpp_dec_float.hpp>` 854 855 namespace boost{ namespace multiprecision{ 856 857 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 858 class cpp_dec_float; 859 860 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 861 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 862 863 }} // namespaces 864 865The `cpp_dec_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 866floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 867much greater precision. 868 869Type `cpp_dec_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter. 870The typedefs `cpp_dec_float_50` and `cpp_dec_float_100` provide arithmetic types at 50 and 100 decimal digits precision 871respectively. Optionally, you can specify an integer type to use for the exponent, this defaults to a 32-bit integer type 872which is more than large enough for the vast majority of use cases, but larger types such as `long long` can also be specified 873if you need a truly huge exponent range. In any case the ExponentType must be a __fundamental signed integer type at least 2 bytes 874and 16-bits wide. 875 876Normally `cpp_dec_float` allocates no memory: all of the space required for its digits are allocated 877directly within the class. As a result care should be taken not to use the class with too high a digit count 878as stack space requirements can grow out of control. If that represents a problem then providing an allocator 879as the final template parameter causes `cpp_dec_float` to dynamically allocate the memory it needs: this 880significantly reduces the size of `cpp_dec_float` and increases the viable upper limit on the number of digits 881at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 882as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 883 884There is full standard library and `std::numeric_limits` support available for this type. 885 886Things you should know when using this type: 887 888* Default constructed `cpp_dec_float`s have a value of zero. 889* The radix of this type is 10. As a result it can behave subtly differently from base-2 types. 890* The type has a number of internal guard digits over and above those specified in the template argument. 891Normally these should not be visible to the user. 892* The type supports both infinities and NaNs. An infinity is generated whenever the result would overflow, 893and a NaN is generated for any mathematically undefined operation. 894* There is a `std::numeric_limits` specialisation for this type. 895* Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type - 896for example you can convert from `number<cpp_dec_float<50> >` to `number<cpp_dec_float<SomeOtherValue> >`. 897Narrowing conversions are truncating and `explicit`. 898* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 899as a valid floating-point number. 900* The actual precision of a `cpp_dec_float` is always slightly higher than the number of digits specified in 901the template parameter, actually how much higher is an implementation detail but is always at least 8 decimal 902digits. 903* Operations involving `cpp_dec_float` are always truncating. However, note that since there are guard digits 904in effect, in practice this has no real impact on accuracy for most use cases. 905 906[h5 cpp_dec_float example:] 907 908[cpp_dec_float_eg] 909 910[endsect] 911 912[section:gmp_float gmp_float] 913 914`#include <boost/multiprecision/gmp.hpp>` 915 916 namespace boost{ namespace multiprecision{ 917 918 template <unsigned Digits10> 919 class gmp_float; 920 921 typedef number<gmp_float<50> > mpf_float_50; 922 typedef number<gmp_float<100> > mpf_float_100; 923 typedef number<gmp_float<500> > mpf_float_500; 924 typedef number<gmp_float<1000> > mpf_float_1000; 925 typedef number<gmp_float<0> > mpf_float; 926 927 }} // namespaces 928 929The `gmp_float` back-end is used in conjunction with `number` : it acts as a thin wrapper around the [gmp] `mpf_t` 930to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 931much greater precision. 932 933Type `gmp_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 934at variable precision by setting the template argument to zero. The typedefs mpf_float_50, mpf_float_100, 935mpf_float_500, mpf_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 936respectively. The typedef mpf_float provides a variable precision type whose precision can be controlled via the 937`number`s member functions. 938 939[note This type only provides standard library and `numeric_limits` support when the precision is fixed at compile time.] 940 941As well as the usual conversions from arithmetic and string types, instances of `number<mpf_float<N> >` are 942copy constructible and assignable from: 943 944* The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`. 945* The `number` wrappers around those types: `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`. 946 947It's also possible to access the underlying `mpf_t` via the `data()` member function of `gmp_float`. 948 949Things you should know when using this type: 950 951* Default constructed `gmp_float`s have the value zero (this is the [gmp] library's default behavior). 952* No changes are made to the [gmp] library's global settings, so this type can be safely mixed with 953existing [gmp] code. 954* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 955* It is not possible to round-trip objects of this type to and from a string and get back 956exactly the same value. This appears to be a limitation of [gmp]. 957* Since the underlying [gmp] types have no notion of infinities or NaNs, care should be taken 958to avoid numeric overflow or division by zero. That latter will result in a std::overflow_error being thrown, 959while generating excessively large exponents may result in instability of the underlying [gmp] 960library (in testing, converting a number with an excessively large or small exponent 961to a string caused [gmp] to segfault). 962* This type can equally be used with [mpir] as the underlying implementation - indeed that is 963the recommended option on Win32. 964* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 965as a valid floating-point number. 966* Division by zero results in a `std::overflow_error` being thrown. 967 968[h5 [gmp] example:] 969 970[mpf_eg] 971 972[endsect] 973 974[section:mpfr_float mpfr_float] 975 976`#include <boost/multiprecision/mpfr.hpp>` 977 978 namespace boost{ namespace multiprecision{ 979 980 enum mpfr_allocation_type 981 { 982 allocate_stack, 983 allocate_dynamic 984 }; 985 986 template <unsigned Digits10, mpfr_allocation_type AllocateType = allocate_dynamic> 987 class mpfr_float_backend; 988 989 typedef number<mpfr_float_backend<50> > mpfr_float_50; 990 typedef number<mpfr_float_backend<100> > mpfr_float_100; 991 typedef number<mpfr_float_backend<500> > mpfr_float_500; 992 typedef number<mpfr_float_backend<1000> > mpfr_float_1000; 993 typedef number<mpfr_float_backend<0> > mpfr_float; 994 995 typedef number<mpfr_float_backend<50, allocate_stack> > static_mpfr_float_50; 996 typedef number<mpfr_float_backend<100, allocate_stack> > static_mpfr_float_100; 997 998 }} // namespaces 999 1000The `mpfr_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfr] `mpfr_t` 1001to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1002much greater precision. 1003 1004Type `mpfr_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1005at variable precision by setting the template argument to zero. The typedefs mpfr_float_50, mpfr_float_100, 1006mpfr_float_500, mpfr_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 1007respectively. The typedef mpfr_float provides a variable precision type whose precision can be controlled via the 1008`number`s member functions. 1009 1010In addition the second template parameter lets you choose between dynamic allocation (the default, 1011and uses MPFR's normal allocation routines), 1012or stack allocation (where all the memory required for the underlying data types is stored 1013within `mpfr_float_backend`). The latter option can result in significantly faster code, at the 1014expense of growing the size of `mpfr_float_backend`. It can only be used at ['fixed precision], and 1015should only be used for lower digit counts. Note that we can not guarantee that using `allocate_stack` 1016won't cause any calls to `mpfr`'s allocation routines, as `mpfr` may call these inside its own code. 1017The following table gives an idea of the performance tradeoff's at 50 decimal digits 1018precision[footnote Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0]: 1019 1020[table 1021[[Type][Bessel function evaluation, relative times]] 1022[[`number<mpfr_float_backend<50, allocate_static>, et_on>`][1.0 (5.5s)]] 1023[[`number<mpfr_float_backend<50, allocate_static>, et_off>`][1.05 (5.8s)]] 1024[[`number<mpfr_float_backend<50, allocate_dynamic>, et_on>`][1.05 (5.8s)]] 1025[[`number<mpfr_float_backend<50, allocate_dynamic>, et_off>`][1.16 (6.4s)]] 1026] 1027 1028[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 1029 1030As well as the usual conversions from arithmetic and string types, instances of `number<mpfr_float_backend<N> >` are 1031copy constructible and assignable from: 1032 1033* The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`. 1034* The [mpfr] native type `mpfr_t`. 1035* The `number` wrappers around those types: `number<mpfr_float_backend<M> >`, `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`. 1036 1037It's also possible to access the underlying `mpfr_t` via the data() member function of `mpfr_float_backend`. 1038 1039Things you should know when using this type: 1040 1041* A default constructed `mpfr_float_backend` is set to zero (['Note that this is [*not] the default [mpfr] behavior]). 1042* All operations use round to nearest. 1043* No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing 1044[mpfr] or [gmp] code. 1045* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. 1046* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1047* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1048as a valid floating-point number. 1049* Division by zero results in an infinity. 1050* When using the variable precision type `mpfr_float`, then copy construction and assignment ['copies the precision 1051of the source variable]. Likewise move construction and assignment. 1052* When constructing the variable precision type `mpfr_float` you can specify two arguments to the constructor - the first 1053is the value to assign to the variable, the second is an unsigned integer specifying the precision in decimal places. The 1054`assign` member function similarly has a 2-argument overload taking the value to assign and the precision. You can use this 1055to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a` 1056but preserves the precision of `a`. 1057 1058[h5 [mpfr] example:] 1059 1060[mpfr_eg] 1061 1062[endsect] [/section:mpfr_float mpfr_float] 1063 1064[section:float128 float128] 1065 1066`#include <boost/multiprecision/float128.hpp>` 1067 1068 namespace boost{ namespace multiprecision{ 1069 1070 class float128_backend; 1071 1072 typedef number<float128_backend, et_off> float128; 1073 1074 }} // namespaces 1075 1076The `float128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types 1077and provides an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1078a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real. 1079 1080All the usual standard library and `std::numeric_limits` support are available, performance should be equivalent 1081to the underlying native types: for example the LINPACK benchmarks for GCC's `__float128` and 1082`boost::multiprecision::float128` both achieved 5.6 MFLOPS[footnote On 64-bit Ubuntu 11.10, GCC-4.8.0, Intel Core 2 Duo T5800.]. 1083 1084As well as the usual conversions from arithmetic and string types, instances of `float128` are 1085copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types. 1086 1087It's also possible to access the underlying `__float128` or `_Quad` type via the `data()` member 1088function of `float128_backend`. 1089 1090Things you should know when using this type: 1091 1092* Default constructed `float128`s have the value zero. 1093* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1094* This type is fully `constexpr` aware - basic constexpr arithmetic is supported from C++14 and onwards, comparisons, 1095plus the functions `fabs`, `abs`, `fpclassify`, `isnormal`, `isfinite`, `isinf` and `isnan` are also supported if either 1096the compiler implements C++20's `std::is_constant_evaluated()`, or if the compiler is GCC. 1097* It is not possible to round-trip objects of this type to and from a string and get back 1098exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of 1099our code. Round tripping when using `__float128` as the underlying type is possible (both for GCC and Intel). 1100* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1101as a valid floating-point number. 1102* Division by zero results in an infinity being produced. 1103* Type `float128` can be used as a literal type (constexpr support). 1104* Type `float128` can be used for full `constexpr` arithmetic from C++14 and later with GCC. The functions `abs`, `fabs`, 1105`fpclassify`, `isnan`, `isinf`, `isfinite` and `isnormal` are also `constexpr`, but the transcendental functions are not. 1106* When using the Intel compiler, the underlying type defaults to `__float128` if it's available and `_Quad` if not. You can override 1107the default by defining either `BOOST_MP_USE_FLOAT128` or `BOOST_MP_USE_QUAD`. 1108* When the underlying type is Intel's `_Quad` type, the code must be compiled with the compiler option `-Qoption,cpp,--extended_float_type`. 1109* 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` 1110unless you also use `-fext-numeric-literals`. 1111* You will need to link to `libquadmath.dll` with the link command `-lquadmath` and ensure that the DLL is visible by the linker. 1112If you are using the B2/bjam build system then commands`<linkflags>-lQUADMATH` and `<linkflags>-L"path/to/lib"` will be needed. 1113* The values shown by `std::numeric_limits<float128>` and extremely close ['but not identical] 1114to those from the equivalent precision and range multiprecision types `std::numeric_limits<cpp_bin_float_quad>` and `std::numeric_limits<cpp_dec_float_quad>`. 1115 1116[h5 float128 example:] 1117 1118[float128_eg] 1119 1120Values for `std::numeric_limits<float128>` are: 1121 1122[float128_numeric_limits] 1123 1124[endsect] [/section:float128 float128] 1125 1126[section:fp_eg Examples] 1127 1128[import ../example/floating_point_examples.cpp] 1129 1130[section:aos Area of Circle] 1131 1132[/I:\boost\libs\multiprecision\example\floating_point_examples.cpp] 1133[AOS1] 1134[AOS2] 1135[AOS3] 1136 1137[endsect] [/section:aos Area of Circle] 1138 1139 1140[section:caveats Drop-in Caveats] 1141[import ../example/big_seventh.cpp] 1142 1143[big_seventh_example_1] 1144[big_seventh_example_2] 1145[big_seventh_example_3] 1146[big_seventh_example_constexpr] [/ Hopefully a temporary restriction.] 1147[big_seventh_example_4] 1148 1149Typical output is: 1150[big_seventh_example_output] 1151 1152[endsect] [/section:caveats Caveats] 1153 1154[section:jel Defining a Special Function.] 1155 1156[JEL] 1157 1158[endsect] [/section:jel Defining a Special Function.] 1159 1160 1161[section:nd Calculating a Derivative] 1162 1163[ND1] 1164[ND2] 1165[ND3] 1166 1167[endsect] [/section:nd Calculating a Derivative] 1168 1169 1170[section:gi Calculating an Integral] 1171 1172[GI1] 1173[GI2] 1174 1175[endsect] [/section:gi Calculating an Integral] 1176 1177 1178[section:poly_eg Polynomial Evaluation] 1179 1180[POLY] 1181 1182[endsect] [/section:poly_eg Polynomial Evaluation] 1183 1184[section:variable_precision Variable-Precision Newton Evaluation] 1185 1186[mpfr_variable] 1187 1188[endsect] [/section:variable_precision Variable-Precision Newton Evaluation] 1189 1190[section:gauss_lagerre_quadrature Gauss-Laguerre quadrature] 1191 1192[import ../example/gauss_laguerre_quadrature.cpp] 1193 1194This example uses __Boost_Multiprecision to implement a high-precision Gauss-Laguerre quadrature integration. 1195The quadrature is used to calculate the `airy_ai(x)` function for real-valued `x` on the positive axis with `x >= 1`. 1196 1197In this way, the integral representation could be seen as part of a scheme to calculate 1198real-valued Airy functions on the positive axis for medium to large argument. 1199A Taylor series or hypergeometric function (not part of this example) could be used for smaller arguments. 1200 1201This example has been tested with decimal digits counts ranging from 21...301, by adjusting the parameter 1202`local::my_digits10` at compile time. 1203 1204The quadrature integral representaion of `airy_ai(x)` used in this example can be found in: 1205 1206A. Gil, J. Segura, N.M. Temme, "Numerical Methods for Special Functions" 1207(SIAM Press 2007), ISBN 9780898717822, Sect. 5.3.3, in particular Eq. 5.110, page 145. 1208 1209Subsequently, Gil et al's book cites the another work: 1210W. Gautschi, "Computation of Bessel and Airy functions and of related Gaussian quadrature formulae", 1211BIT, 42 (2002), pp. 110-118, [@https://doi.org/10.1023/A:1021974203359] that is also available as 1212[@https://www.cs.purdue.edu/homes/wxg/selected_works/section_02/169.pdf Gautschi_169.pdf]. 1213 1214This Gauss-Laguerre quadrature is designed for `airy_ai(x)` with real-valued `x >= 1`. 1215 1216The example uses Gauss-Laguerre quadrature integration to compute `airy_ai(x / 7)` 1217with `7 <= x <= 120` and where `x` is incremented in steps of 1. 1218 1219During development of this example, we have empirically found the numbers of Gauss-Laguerre coefficients 1220needed for convergence when using various counts of base-10 digits. 1221 1222Let's calibrate, for instance, the number of coefficients needed at the point `x = 1`. 1223 1224Empirical data were used with __WolframAlpha : 1225`` 1226Fit[{{21.0, 3.5}, {51.0, 11.1}, {101.0, 22.5}, {201.0, 46.8}}, {1, d, d^2}, d]FullSimplify[%] 1227 0.0000178915 d^2 + 0.235487 d - 1.28301 1228 or 1229 -1.28301 + (0.235487 + 0.0000178915 d) d 1230`` 1231 1232We need significantly more coefficients at smaller real values than are needed 1233at larger real values because the slope derivative of `airy_ai(x)` gets more 1234steep as x approaches zero. `laguerre_order` is calculated using this equation. 1235 1236 1237Snippets from (copious) output from a progress bar during calculation of approximate root estimates 1238followed by calculation of accurate abscissa and weights is: 1239 1240[gauss_laguerre_quadrature_output_1] 1241 1242Finally the result using Gauss-Laguerre quadrature is compared with a calculation using `cyl_bessel_k`, 1243and both are listed, finally confirming that none differ more than a small tolerance. 1244[gauss_laguerre_quadrature_output_2] 1245 1246For more detail see comments in the source code for this example at [@../../example/gauss_laguerre_quadrature.cpp gauss_laguerre_quadrature.cpp]. 1247 1248[endsect] [/section:gauss_lagerre_quadrature Gauss-Laguerre quadrature] 1249 1250[endsect] [/section:fp_eg Examples] 1251 1252[endsect] [/section:floats floating-point Numbers] 1253 1254[section:interval Interval Number Types] 1255 1256There is one currently only one interval number type supported - [mpfi]. 1257 1258[section:mpfi mpfi_float] 1259 1260`#include <boost/multiprecision/mpfi.hpp>` 1261 1262 namespace boost{ namespace multiprecision{ 1263 1264 template <unsigned Digits10> 1265 class mpfi_float_backend; 1266 1267 typedef number<mpfi_float_backend<50> > mpfi_float_50; 1268 typedef number<mpfi_float_backend<100> > mpfifloat_100; 1269 typedef number<mpfi_float_backend<500> > mpfifloat_500; 1270 typedef number<mpfi_float_backend<1000> > mpfi_float_1000; 1271 typedef number<mpfi_float_backend<0> > mpfi_float; 1272 1273 }} // namespaces 1274 1275The `mpfi_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfi] `mpfi_t` 1276to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1277much greater precision and implementing interval arithmetic. 1278 1279Type `mpfi_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1280at variable precision by setting the template argument to zero. The `typedef`s `mpfi_float_50`, `mpfi_float_100`, 1281`mpfi_float_500`, `mpfi_float_1000` provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 1282respectively. The `typedef mpfi_float` provides a variable precision type whose precision can be controlled via theF 1283`number`s member functions. 1284 1285[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 1286 1287As well as the usual conversions from arithmetic and string types, instances of `number<mpfi_float_backend<N> >` are 1288copy constructible and assignable from: 1289 1290* The [mpfi] native type `mpfi_t`. 1291* The `number` wrappers around [mpfi] or [mpfr]: `number<mpfi_float_backend<M> >` and `number<mpfr_float<M> >`. 1292* There is a two argument constructor taking two `number<mpfr_float<M> >` arguments specifying the interval. 1293 1294It's also possible to access the underlying `mpfi_t` via the `data()` member function of `mpfi_float_backend`. 1295 1296Things you should know when using this type: 1297 1298* A default constructed `mpfi_float_backend` is set to zero (['Note that this is [*not] the default [mpfi] behavior]). 1299* No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing 1300[mpfr] or [gmp] code. 1301* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. 1302* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1303* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1304as a valid floating-point number. 1305* Division by zero results in an infinity. 1306 1307There are some additional non member functions for working on intervals: 1308 1309 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1310 number<mpfr_float_backend<Digits10>, ExpressionTemplates> lower(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1311 1312Returns the lower end of the interval. 1313 1314 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1315 number<mpfr_float_backend<Digits10>, ExpressionTemplates> upper(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1316 1317Returns the upper end of the interval. 1318 1319 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1320 number<mpfr_float_backend<Digits10>, ExpressionTemplates> median(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1321 1322Returns the mid point of the interval. 1323 1324 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1325 number<mpfr_float_backend<Digits10>, ExpressionTemplates> width(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1326 1327Returns the absolute width of the interval. 1328 1329 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1330 number<mpfi_float_backend<Digits10>, ExpressionTemplates> intersect( 1331 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1332 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1333 1334Returns the interval which is the intersection of the ['a] and ['b]. Returns an 1335unspecified empty interval if there is no such intersection. 1336 1337 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1338 number<mpfi_float_backend<Digits10>, ExpressionTemplates> hull( 1339 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1340 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1341 1342Returns the interval which is the union of ['a] and ['b]. 1343 1344 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1345 bool overlap(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1346 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1347 1348Returns `true` only if the intervals ['a] and ['b] overlap. 1349 1350 template <unsigned Digits10, expression_template_option ExpressionTemplates1, expression_template_option ExpressionTemplates2> 1351 bool in(const number<mpfr_float_backend<Digits10>, ExpressionTemplates1>& a, 1352 const number<mpfi_float_backend<Digits10>, ExpressionTemplates2>& b); 1353 1354Returns `true` only if point ['a] is contained within the interval ['b]. 1355 1356 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1357 bool zero_in(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1358 1359Returns `true` only if the interval ['a] contains the value zero. 1360 1361 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1362 bool subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1363 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1364 1365Returns `true` only if ['a] is a subset of ['b]. 1366 1367 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1368 bool proper_subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1369 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1370 1371Returns `true` only if ['a] is a proper subset of ['b]. 1372 1373 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1374 bool empty(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1375 1376Returns `true` only if ['a] is an empty interval, equivalent to `upper(a) < lower(a)`. 1377 1378 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1379 bool singleton(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1380 1381Returns `true` if `lower(a) == upper(a)`. 1382 1383[h5 [mpfi] example:] 1384 1385[mpfi_eg] 1386 1387[endsect] [ section:mpfi mpfi_float] 1388 1389[endsect] [/section:interval Interval Number Types] 1390 1391[section:complex Complex Number Types] 1392 1393The following backends provide complex number arithmetic: 1394 1395[table 1396[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 1397[[`cpp_complex`][boost/multiprecision/cpp_complex.hpp][2][None][An all C++ Boost-licensed implementation.][Slower than [mpc].]] 1398[[`mpc`][boost/multiprecision/mpc.hpp][2][[mpc]][Very fast and efficient back-end.][Dependency on LGLP-licensed [MPC] library.]] 1399[[`compplex128`][boost/multiprecision/complex128.hpp][2][`__float128` and libquadmath][Very fast and efficient number type.][128-bit precision only, and resticted to GCC.]] 1400[[`complex_adaptor`][boost/multiprecision/complex_adaptor.hpp][-][none][Can convert any backend type into a complex number backend.][Not a number in its own right, and hard to use as a result.]] 1401] 1402 1403[section:cpp_complex cpp_complex] 1404 1405`#include <boost/multiprecision/cpp_complex.hpp>` 1406 1407 namespace boost{ namespace multiprecision{ 1408 1409 template <unsigned Digits, backends::digit_base_type DigitBase = backends::digit_base_10, class Allocator = void, class Exponent = int, Exponent MinExponent = 0, Exponent MaxExponent = 0> 1410 using cpp_complex_backend = complex_adaptor<cpp_bin_float<Digits, DigitBase, Allocator, Exponent, MinExponent, MaxExponent> >; 1411 1412 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> 1413 using cpp_complex = number<complex_adaptor<cpp_bin_float<Digits, DigitBase, Allocator, Exponent, MinExponent, MaxExponent> >, ExpressionTemplates>; 1414 1415 typedef cpp_complex<50> cpp_complex_50; 1416 typedef cpp_complex<100> cpp_complex_100; 1417 1418 typedef cpp_complex<24, backends::digit_base_2, void, boost::int16_t, -126, 127> cpp_complex_single; 1419 typedef cpp_complex<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023> cpp_complex_double; 1420 typedef cpp_complex<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383> cpp_complex_extended; 1421 typedef cpp_complex<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383> cpp_complex_quad; 1422 typedef cpp_complex<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143> cpp_complex_oct; 1423 1424 1425 }} // namespaces 1426 1427The `cpp_complex_backend` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 1428complex number type that is a drop-in replacement for `std::complex`, but with much greater precision. 1429 1430The template alias `cpp_complex` avoids the need to use class `number` directly. 1431 1432Type `cpp_complex` can be used at fixed precision by specifying a non-zero `Digits` template parameter. 1433The typedefs `cpp_complex_50` and `cpp_complex_100` provide complex number types at 50 and 100 decimal digits precision 1434respectively. 1435 1436Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example 1437to declare a `cpp_complex` with exactly the same precision as `std::complex<double>` one would use 1438`cpp_complex<53, digit_base_2>`. The typedefs `cpp_complex_single`, `cpp_complex_double`, 1439`cpp_complex_quad`, `cpp_complex_oct` and `cpp_complex_double_extended` provide 1440software analogues of the IEEE single, double, quad and octuple float data types, plus the Intel-extended-double type respectively. 1441Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size 1442or bit-layout as true IEEE compatible types. 1443 1444Normally `cpp_complex` allocates no memory: all of the space required for its digits are allocated 1445directly within the class. As a result care should be taken not to use the class with too high a digit count 1446as stack space requirements can grow out of control. If that represents a problem then providing an allocator 1447as a template parameter causes `cpp_complex` to dynamically allocate the memory it needs: this 1448significantly reduces the size of `cpp_complex` and increases the viable upper limit on the number of digits 1449at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 1450as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 1451Note that since the actual type of the objects allocated 1452is completely opaque, the suggestion would be to use an allocator with `char` `value_type`, for example: 1453`cpp_complex<1000, digit_base_10, std::allocator<char> >`. 1454 1455The next template parameters determine the type and range of the exponent: parameter `Exponent` can be 1456any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits 1457of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will 1458get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then 1459the library will choose suitable values that are as large as possible given the constraints of the type 1460and need for extra headroom for internal calculations. 1461 1462Finally, as with class `number`, the final template parameter determines whether expression templates are turn 1463on or not. Since by default this type allocates no memory, expression template support is off by default. 1464However, you should probably turn it on if you specify an allocator. 1465 1466There is full standard library support available for this type, comparable with what `std::complex` provides. 1467 1468Things you should know when using this type: 1469 1470* Default constructed `cpp_complex`s have a value of zero. 1471* The radix of this type is 2, even when the precision is specified as decimal digits. 1472* The type supports both infinities and NaNs. An infinity is generated whenever the result would overflow, 1473and a NaN is generated for any mathematically undefined operation. 1474* There is no `std::numeric_limits` specialisation for this type: this is the same behaviour as `std::complex`. If you need 1475`std::numeric_limits` support you need to look at `std::numeric_limits<my_complex_number_type::value_type>`. 1476* Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type - 1477for example you can convert from `number<cpp_complex<50> >` to `number<cpp_bin_float<SomeOtherValue> >`. 1478Narrowing conversions round to nearest and are `explicit`. 1479* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1480as a valid complex number. 1481 1482[h5 example:] 1483 1484[cpp_complex_eg] 1485 1486Which produces the output (for the multiprecision type): 1487 1488[cpp_complex_out] 1489 1490[endsect] [/section:complex Complex Number Types] 1491 1492[section:mpc_complex mpc_complex] 1493 1494`#include <boost/multiprecision/mpc.hpp>` 1495 1496 namespace boost{ namespace multiprecision{ 1497 1498 template <unsigned Digits10> 1499 class mpc_complex_backend; 1500 1501 typedef number<mpc_complex_backend<50> > mpc_complex_50; 1502 typedef number<mpc_complex_backend<100> > mpc_complex_100; 1503 typedef number<mpc_complex_backend<500> > mpc_complex_500; 1504 typedef number<mpc_complex_backend<1000> > mpc_complex_1000; 1505 typedef number<mpc_complex_backend<0> > mpc_complex; 1506 1507 }} // namespaces 1508 1509The `mpc_complex_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpc] `mpc_t` 1510to provide an real-number type that is a drop-in replacement for `std::complex`, but with 1511much greater precision. 1512 1513Type `mpc_complex_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1514at variable precision by setting the template argument to zero. The typedefs mpc_complex_50, mpc_complex_100, 1515mpc_complex_500, mpc_complex_1000 provide complex types at 50, 100, 500 and 1000 decimal digits precision 1516respectively. The typedef mpc_complex provides a variable precision type whose precision can be controlled via the 1517`number`s member functions. 1518 1519The `mpc` backend should allow use of the same syntax as the C++ standard library complex type. 1520When using this backend, remember to link with the flags `-lmpc -lmpfr -lgmp`. 1521 1522As well as the usual conversions from arithmetic and string types, instances of `number<mpc_complex_backend<N> >` are 1523copy constructible and assignable from: 1524 1525* The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`. 1526* The [mpfr] native type `mpfr_t`. 1527* The [mpc] native type `mpc_t`. 1528* The `number` wrappers around those types: `number<mpfr_float_backend<M> >`, `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`. 1529 1530It's also possible to access the underlying `mpc_t` via the `data()` member function of `mpfr_float_backend`. 1531 1532Things you should know when using this type: 1533 1534* A default constructed `mpc_complex_backend` is set to zero (['Note that this is [*not] the default [mpc] behavior]). 1535* All operations use round to nearest. 1536* No changes are made to [mpc], [gmp] or [mpfr] global settings, so this type can coexist with existing 1537[mpc], [mpfr] or [gmp] code. 1538* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. 1539* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1540* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1541as a valid complex number. 1542* Division by zero results in a complex-infinity. 1543* Unlike `std::complex`, you can not use `reinterpret_cast` to treat this type as an array of the underlying floating point type. 1544* Unlike `std::complex`, there are no literals for imaginary values. 1545* When using the variable precision type `mpc_complex`, then copy construction and assignment ['copies the precision 1546of the source variable]. Likewise move construction and assignment. 1547* When constructing the variable precision type `mpc_complex` you can specify two arguments to the constructor - the first 1548is the value to assign to the variable, the second is an unsigned integer specifying the precision in decimal places. The 1549`assign` member function similarly has a 2-argument overload taking the value to assign and the precision. You can use this 1550to preserve the precision of the target variable using the somewhat arcane: `a.assign(b, a.precision())`, which assigns `b` to `a` 1551but preserves the precision of `a`. 1552 1553[h5 [mpc] example:] 1554 1555[mpc_eg] 1556 1557Which produces the output (for the multiprecision type): 1558 1559[mpc_out] 1560 1561[endsect] [/section:mpc_complex mpc_complex] 1562 1563[section:complex128 complex128] 1564 1565`#include <boost/multiprecision/complex128.hpp>` 1566 1567 namespace boost{ namespace multiprecision{ 1568 1569 class complex128_backend; 1570 1571 typedef number<complex128_backend, et_off> complex128; 1572 1573 }} // namespaces 1574 1575The `complex128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types 1576and provides a complex-number type that is a drop-in replacement for the native C++ floating-point types, but with 1577a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real. 1578 1579All the usual standard library functions are available, performance should be equivalent 1580to the underlying native types. 1581 1582As well as the usual conversions from arithmetic and string types, instances of `float128` are 1583copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types. 1584 1585Things you should know when using this type: 1586 1587* Default constructed `complex128`s have the value zero. 1588* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1589* It is not possible to round-trip objects of this type to and from a string and get back 1590exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of 1591our code. Round tripping when using `__float128` as the underlying type is possible (both for GCC and Intel). 1592* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1593as a valid floating-point number. 1594* Division by zero results in an infinity being produced. 1595* When using the Intel compiler, the underlying type defaults to `__float128` if it's available and `_Quad` if not. You can override 1596the default by defining either `BOOST_MP_USE_FLOAT128` or `BOOST_MP_USE_QUAD`. 1597* When the underlying type is Intel's `_Quad` type, the code must be compiled with the compiler option `-Qoption,cpp,--extended_float_type`. 1598 1599[h5 complex128 example:] 1600 1601[complex128_eg] 1602 1603Which results in the output: 1604 1605[complex128_out] 1606 1607[endsect] [/section:complex128 complex128] 1608 1609 1610[section:complex_adaptor complex_adaptor] 1611 1612 namespace boost{ namespace multiprecision{ 1613 1614 template <class Backend> 1615 struct complex_adaptor; 1616 1617 }} 1618 1619Class template `complex_adaptor` is designed to sit inbetween class `number` and an actual floating point backend, 1620in order to create a new complex number type. 1621 1622It is the means by which we implement __cpp_complex and __complex128. 1623 1624[endsect] [/section:complex_adaptor complex_adaptor] 1625 1626[endsect] [/section:complex Complex Number Types] 1627 1628[section:rational Rational Number Types] 1629 1630The following back-ends provide rational number arithmetic: 1631 1632[table 1633[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 1634[[`cpp_rational`][boost/multiprecision/cpp_int.hpp][2][None][An all C++ Boost-licensed implementation.][Slower than [gmp].]] 1635[[`gmp_rational`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 1636[[`tommath_rational`][boost/multiprecision/tommath.hpp][2][[tommath]][All C/C++ implementation that's Boost Software Licence compatible.][Slower than [gmp].]] 1637[[`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.]] 1638[[`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.]] 1639] 1640 1641[section:cpp_rational cpp_rational] 1642 1643`#include <boost/multiprecision/cpp_int.hpp>` 1644 1645 namespace boost{ namespace multiprecision{ 1646 1647 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 1648 1649 typedef number<cpp_rational_backend> cpp_rational; 1650 1651 }} // namespaces 1652 1653The `cpp_rational_backend` type is used via the typedef `boost::multiprecision::cpp_rational`. It provides 1654a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1655 1656As well as the usual conversions from arithmetic and string types, instances of `cpp_rational` are copy constructible 1657and assignable from type `cpp_int`. 1658 1659There is also a two argument constructor that accepts a numerator and denominator: both of type `cpp_int`. 1660 1661There are also non-member functions: 1662 1663 cpp_int numerator(const cpp_rational&); 1664 cpp_int denominator(const cpp_rational&); 1665 1666which return the numerator and denominator of the number. 1667 1668Things you should know when using this type: 1669 1670* Default constructed `cpp_rational`s have the value zero. 1671* Division by zero results in a `std::overflow_error` being thrown. 1672* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1673interpreted as a valid rational number. 1674 1675[h5 Example:] 1676 1677[cpp_rational_eg] 1678 1679[endsect] [/section:rational Rational Number Types] 1680 1681[section:gmp_rational gmp_rational] 1682 1683`#include <boost/multiprecision/gmp.hpp>` 1684 1685 namespace boost{ namespace multiprecision{ 1686 1687 class gmp_rational; 1688 1689 typedef number<gmp_rational > mpq_rational; 1690 1691 }} // namespaces 1692 1693The `gmp_rational` back-end is used via the typedef `boost::multiprecision::mpq_rational`. It acts as a thin wrapper around the [gmp] `mpq_t` 1694to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1695 1696As well as the usual conversions from arithmetic and string types, instances of `number<gmp_rational>` are copy constructible 1697and assignable from: 1698 1699* The [gmp] native types: `mpz_t`, `mpq_t`. 1700* `number<gmp_int>`. 1701 1702There is also a two-argument constructor that accepts a numerator and denominator (both of type `number<gmp_int>`). 1703 1704There are also non-member functions: 1705 1706 mpz_int numerator(const mpq_rational&); 1707 mpz_int denominator(const mpq_rational&); 1708 1709which return the numerator and denominator of the number. 1710 1711It's also possible to access the underlying `mpq_t` via the `data()` member function of `mpq_rational`. 1712 1713Things you should know when using this type: 1714 1715* Default constructed `mpq_rational`s have the value zero (this is the [gmp] default behavior). 1716* Division by zero results in a `std::overflow_error` being thrown. 1717* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1718interpreted as a valid rational number. 1719* No changes are made to the [gmp] library's global settings, so this type can coexist with existing 1720[gmp] code. 1721* The code can equally be used with [mpir] as the underlying library - indeed that is the preferred option on Win32. 1722 1723[h5 Example:] 1724 1725[mpq_eg] 1726 1727[endsect] [/section:gmp_rational gmp_rational] 1728 1729[section:tommath_rational tommath_rational] 1730 1731`#include <boost/multiprecision/tommath.hpp>` 1732 1733 namespace boost{ namespace multiprecision{ 1734 1735 typedef rational_adpater<tommath_int> tommath_rational; 1736 typedef number<tommath_rational > tom_rational; 1737 1738 }} // namespaces 1739 1740The `tommath_rational` back-end is used via the typedef `boost::multiprecision::tom_rational`. It acts as a thin wrapper around 1741`boost::rational<tom_int>` 1742to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1743 1744The advantage of using this type rather than `boost::rational<tom_int>` directly, is that it is expression-template enabled, 1745greatly reducing the number of temporaries created in complex expressions. 1746 1747There are also non-member functions: 1748 1749 tom_int numerator(const tom_rational&); 1750 tom_int denominator(const tom_rational&); 1751 1752which return the numerator and denominator of the number. 1753 1754Things you should know when using this type: 1755 1756* Default constructed `tom_rational`s have the value zero (this the inherited Boost.Rational behavior). 1757* Division by zero results in a `std::overflow_error` being thrown. 1758* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1759interpreted as a valid rational number. 1760* No changes are made to [tommath]'s global state, so this type can safely coexist with other [tommath] code. 1761* Performance of this type has been found to be pretty poor - this need further investigation - but it appears that Boost.Rational 1762needs some improvement in this area. 1763 1764[h5 Example:] 1765 1766[mp_rat_eg] 1767 1768[endsect] [/section:tommath_rational tommath_rational] 1769 1770[section:br Use With Boost.Rational] 1771 1772All of the integer types in this library can be used as template arguments to `boost::rational<IntType>`. 1773 1774Note that using the library in this way largely negates the effect of the expression templates in `number`. 1775 1776[endsect] [/section:br Use With Boost.Rational] 1777 1778[section:rational_adaptor rational_adaptor] 1779 1780 namespace boost{ namespace multiprecision{ 1781 1782 template <class IntBackend> 1783 class rational_adpater; 1784 1785 }} 1786 1787The class template `rational_adaptor` is a back-end for `number` which converts any existing integer back-end 1788into a rational-number back-end. 1789 1790So for example, given an integer back-end type `MyIntegerBackend`, the use would be something like: 1791 1792 typedef number<MyIntegerBackend> MyInt; 1793 typedef number<rational_adaptor<MyIntegerBackend> > MyRational; 1794 1795 MyRational r = 2; 1796 r /= 3; 1797 MyInt i = numerator(r); 1798 assert(i == 2); 1799 1800[endsect] [/section:rational_adaptor rational_adaptor] 1801 1802[endsect] [/section:rational Rational Number Types] 1803 1804[section:misc Miscellaneous Number Types.] 1805 1806Backend types listed in this section are predominantly designed to aid debugging. 1807 1808[section:logged_adaptor logged_adaptor] 1809 1810`#include <boost/multiprecision/logged_adaptor.hpp>` 1811 1812 namespace boost{ namespace multiprecision{ 1813 1814 template <class Backend> 1815 void log_postfix_event(const Backend& result, const char* event_description); 1816 template <class Backend, class T> 1817 void log_postfix_event(const Backend& result1, const T& result2, const char* event_description); 1818 1819 template <class Backend> 1820 void log_prefix_event(const Backend& arg1, const char* event_description); 1821 template <class Backend, class T> 1822 void log_prefix_event(const Backend& arg1, const T& arg2, const char* event_description); 1823 template <class Backend, class T, class U> 1824 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const char* event_description); 1825 template <class Backend, class T, class U, class V> 1826 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const V& arg4, const char* event_description); 1827 1828 template <Backend> 1829 class logged_adaptor; 1830 1831 }} // namespaces 1832 1833The `logged_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1834some other backend to class `number` and logs all the events that take place on that object. Before any number operation takes 1835place, it calls `log_prefix_event` with the arguments to the operation (up to 4), plus a string describing the operation. 1836Then after the operation it calls `log_postfix_event` with the result of the operation, plus a string describing the operation. 1837Optionally, `log_postfix_event` takes a second result argument: this occurs when the result of the operation is not a `number`, 1838for example when `fpclassify` is called, `log_postfix_event` will be called with `result1` being the argument to the function, and 1839`result2` being the integer result of `fpclassify`. 1840 1841The default versions of `log_prefix_event` and `log_postfix_event` do nothing, it is therefore up to the user to overload these 1842for the particular backend being observed. 1843 1844This type provides `numeric_limits` support whenever the template argument Backend does so. 1845 1846This type is particularly useful when combined with an interval number type - in this case we can use `log_postfix_event` 1847to monitor the error accumulated after each operation. We could either set some kind of trap whenever the accumulated error 1848exceeds some threshold, or simply print out diagnostic information. Using this technique we can quickly locate the cause of 1849numerical instability in a particular routine. The following example demonstrates this technique in a trivial algorithm 1850that deliberately introduces cancellation error: 1851 1852[logged_adaptor] 1853 1854When we examine program output we can clearly see that the diameter of the interval increases after each subtraction: 1855 1856[logged_adaptor_output] 1857 1858[endsect] [/section:logged_adaptor logged_adaptor] 1859 1860[section:debug_adaptor debug_adaptor] 1861 1862`#include <boost/multiprecision/debug_adaptor.hpp>` 1863 1864 namespace boost{ namespace multiprecision{ 1865 1866 template <Backend> 1867 class debug_adaptor; 1868 1869 }} // namespaces 1870 1871The `debug_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1872some other backend to class `number` and intercepts all operations on that object storing the result as a string within itself. 1873 1874This type provides `numeric_limits` support whenever the template argument Backend does so. 1875 1876This type is particularly useful when your debugger provides a good view of `std::string`: when this is the case 1877multiprecision values can easily be inspected in the debugger by looking at the `debug_value` member of `debug_adaptor`. 1878The down side of this approach is that runtimes are much slower when using this type. Set against that it can make 1879debugging very much easier, certainly much easier than sprinkling code with `printf` statements. 1880 1881When used in conjunction with the Visual C++ debugger visualisers, the value of a multiprecision type that uses this 1882backend is displayed in the debugger just a __fundamental value would be, here we're inspecting a value of type 1883`number<debug_adaptor<cpp_dec_float<50> > >`: 1884 1885[$../debugger1.png] 1886 1887Otherwise you will need to expand out the view and look at the "debug_value" member: 1888 1889[$../debugger2.png] 1890 1891It works for all the backend types equally too, here it is inspecting a `number<debug_adaptor<gmp_rational> >`: 1892 1893[$../debugger3.png] 1894 1895 1896[endsect] [/section:debug_adaptor debug_adaptor] 1897 1898[section:visualizers Visual C++ Debugger Visualizers] 1899 1900Let's face it debugger multiprecision numbers is hard - simply because we can't easily inspect the value of the numbers. 1901Visual C++ provides a partial solution in the shape of "visualizers" which provide improved views of complex data structures, 1902these visualizers need to be added to the `[Visualizer]` section of `autoexp.dat` located in the `Common7/Packages/Debugger` 1903directory of your Visual Studio installation. The actual visualizer code is in the sandbox 1904[@https://svn.boost.org/svn/boost/sandbox/boost_docs/subprojects/DebuggerVisualizers/multiprecision.vis.txt here] - just cut and paste the code 1905into your `autoexp.dat` file. 1906 1907[note These visualizers have only been tested with VC10, also given the ability of buggy visualizers to crash your Visual C++ 1908debugger, make sure you back up `autoexp.dat` file before using these!!] 1909 1910The first visualizer provides improved views of `debug_adaptor`: 1911 1912[$../debugger1.png] 1913 1914The next visualizer provides improved views of cpp_int: small numbers are displayed as actual values, while larger numbers are 1915displayed as an array of hexadecimal parts, with the most significant part first. 1916 1917Here's what it looks like for small values: 1918 1919[$../debugger4.png] 1920 1921And for larger values: 1922 1923[$../debugger5.png] 1924 1925There is also a `~raw` child member that 1926lets you see the actual members of the class: 1927 1928[$../debugger6.png] 1929 1930The visualizer for `cpp_dec_float` shows the first few digits of the value in the preview field, and the full array of digits 1931when you expand the view. As before the `~raw` child gives you access to the actual data members: 1932 1933[$../debugger7.png] 1934 1935[endsect] [/section:visualizers Visual C++ Debugger Visualizers] 1936 1937[endsect] [/section:misc Miscellaneous Number Types.] 1938 1939[section:conversions Constructing and Interconverting Between Number Types] 1940 1941All of the number types that are based on `number` have certain conversion rules in common. 1942In particular: 1943 1944* Any number type can be constructed (or assigned) from any __fundamental arithmetic type, as long 1945 as the conversion isn't lossy (for example float to int conversion): 1946 1947 cpp_dec_float_50 df(0.5); // OK construction from double 1948 cpp_int i(450); // OK constructs from signed int 1949 cpp_int j = 3.14; // Error, lossy conversion. 1950 1951* A number can be explicitly constructed from an arithmetic type, even when the conversion is lossy: 1952 1953 cpp_int i(3.14); // OK explicit conversion 1954 i = static_cast<cpp_int>(3.14) // OK explicit conversion 1955 i.assign(3.14); // OK, explicit assign and avoid a temporary from the cast above 1956 i = 3.14; // Error, no implicit assignment operator for lossy conversion. 1957 cpp_int j = 3.14; // Error, no implicit constructor for lossy conversion. 1958 1959* A `number` can be converted to any __fundamental type, via the `convert_to` member function: 1960 1961 mpz_int z(2); 1962 int i = z.convert_to<int>(); // sets i to 2 1963 1964* Conversions to rational numbers from floating-point ones are always allowed, and are exact and implicit 1965as long as the rational number uses an unbounded integer type. Please be aware that constructing a rational 1966number from an extended precision floating-point type with a large exponent range can effectively run the system 1967out of memory, as in the extreme case ['2[super max_exponent] / CHAR_BITS] bytes of storage may be required. This 1968does not represent a problem for __fundamental floating-point types however, as the exponent range for these is rather 1969limited. 1970 1971* Conversions to floating-point numbers from rational ones are rounded to nearest (less than 0.5 __ULP error) 1972as long as the floating-point number is binary, and the integer type used by the rational number is unbounded. 1973 1974Additional conversions may be supported by particular backends. 1975 1976* A `number` can be converted to any __fundamental type, via an explicit conversion operator: 1977this functionality is only available on compilers supporting C++11's explicit conversion syntax. 1978 1979 mpz_int z(2); 1980 int i = z; // Error, implicit conversion not allowed. 1981 int j = static_cast<int>(z); // OK explicit conversion. 1982 1983* Any number type can be ['explicitly] constructed (or assigned) from a `const char*` or a `std::string`: 1984 1985 // pi to 50 places from a string: 1986 cpp_dec_float_50 df("3.14159265358979323846264338327950288419716939937510"); 1987 // Integer type will automatically detect "0x" and "0" prefixes and parse the string accordingly: 1988 cpp_int i("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFF000000000000000"); 1989 // Invalid input always results in a std::runtime_error being thrown: 1990 i = static_cast<cpp_int>("3.14"); 1991 // implicit conversions from strings are not allowed: 1992 i = "23"; // Error, no assignment operator for implicit conversion from string 1993 // assign member function, avoids having to create a temporary via a static_cast: 1994 i.assign("23"); // OK 1995 1996* Any number type will interoperate with the __fundamental types in arithmetic expressions as long as the conversions 1997are not lossy: 1998 1999 // pi to 50 places from a string: 2000 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510"; 2001 // Multiply by 2 - using an integer literal here is usually more efficient 2002 // than constructing a temporary: 2003 df *= 2; 2004 2005 // You can't mix integer types with floats though: 2006 cpp_int i = 2; 2007 i *= 3.14; // Error, no *= operator will be found. 2008 2009* Any number type can be streamed to and from the C++ iostreams: 2010 2011 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510"; 2012 // Now print at full precision: 2013 std::cout << std::setprecision(std::numeric_limits<cpp_dec_float_50>::max_digits10) 2014 << df << std::endl 2015 cpp_int i = 1; 2016 i <<= 256; 2017 // Now print in hex format with prefix: 2018 std::cout << std::hex << std::showbase << i << std::endl; 2019 2020* Interconversions between number types of the same family are allowed and are implicit conversions if no 2021loss of precision is involved, and explicit if it is: 2022 2023 int128_t i128 = 0; 2024 int266_t i256 = i128; // OK implicit widening conversion 2025 i128_t = i256; // Error, no assignment operator found, narrowing conversion is explicit. 2026 i128_t = static_cast<int128_t>(i256); // OK, explicit narrowing conversion. 2027 2028 mpz_int z = 0; 2029 mpf_float f = z; // OK, GMP handles this conversion natively, and it's not lossy and therefore implicit. 2030 2031 mpf_float_50 f50 = 2; 2032 f = f50; // OK, conversion from fixed to variable precision, f will have 50 digits precision. 2033 f50 = f; // Error, conversion from variable to fixed precision is potentially lossy, explicit cast required. 2034 2035* Some interconversions between number types are completely generic, and are always available, albeit the conversions are always ['explicit]: 2036 2037 cpp_int cppi(2); 2038 // We can always convert between numbers of the same category - 2039 // int to int, rational to rational, or float to float, so this is OK 2040 // as long as we use an explicit conversion: 2041 mpz_int z(cppi); 2042 // We can always promote from int to rational, int to float, or rational to float: 2043 cpp_rational cppr(cppi); // OK, int to rational 2044 cpp_dec_float_50 df(cppi); // OK, int to float 2045 df = static_cast<cpp_dec_float_50>(cppr); // OK, explicit rational to float conversion 2046 // However narrowing and/or implicit conversions always fail: 2047 cppi = df; // Compiler error, conversion not allowed 2048 2049* Other interconversions may be allowed as special cases, whenever the backend allows it: 2050 2051 mpf_t m; // Native GMP type. 2052 mpf_init_set_ui(m, 0); // set to a value; 2053 mpf_float i(m); // copies the value of the native type. 2054 2055More information on what additional types a backend supports conversions from are given in the tutorial for each backend. 2056The converting constructor will be implicit if the backend's converting constructor is also implicit, and explicit if the 2057backends converting constructor is also explicit. 2058 2059[endsect] [/section:conversions Constructing and Interconverting Between Number Types] 2060 2061[section:random Generating Random Numbers] 2062 2063Random numbers are generated in conjunction with Boost.Random. 2064 2065There is a single generator that supports generating random integers with large bit counts: 2066[@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`]. 2067This type can be used with either ['unbounded] integer types, or with ['bounded] (ie fixed precision) unsigned integers: 2068 2069[random_eg1] 2070 2071Program output is: 2072 2073[random_eg1_out] 2074 2075In addition, the generator adaptors [@http://www.boost.org/doc/html/boost/random/discard_block_engine.html `discard_block`], 2076[@http://www.boost.org/doc/html/boost/random/xor_combine_engine.html `xor_combine_engine`] and 2077[@http://www.boost.org/doc/html/boost/random/discrete_distribution.html `discrete_distribution`] can be used 2078with multiprecision types. Note that if you seed an `independent_bits_engine`, then you are actually seeding 2079the underlying generator, and should therefore provide a sequence of unsigned 32-bit values as the seed. 2080 2081Alternatively we can generate integers in a given range using 2082[@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`], this will 2083invoke the underlying engine multiple times to build up the required number of bits in the result: 2084 2085[random_eg2] 2086 2087[random_eg2_out] 2088 2089It is also possible to use [@http://www.boost.org/doc/html/boost/random/uniform_int_distribution.html `uniform_int_distribution`] 2090with a multiprecision generator such as [@http://www.boost.org/doc/html/boost/random/independent_bits_engine.html `independent_bits_engine`]. 2091Or to use [@http://www.boost.org/doc/html/boost/random/uniform_smallint.html `uniform_smallint`] or 2092[@http://www.boost.org/doc/html/boost/random/random_number_generator.html `random_number_generator`] with multiprecision types. 2093 2094floating-point values in \[0,1) are most easily generated using [@http://www.boost.org/doc/html/boost/random/generate_canonical.html `generate_canonical`], 2095note that `generate_canonical` will call the generator multiple times to produce the requested number of bits, for example we can use 2096it with a regular generator like so: 2097 2098[random_eg3] 2099 2100[random_eg3_out] 2101 2102Note however, the distributions do not invoke the generator multiple times to fill up the mantissa of a multiprecision floating-point type 2103with random bits. For these therefore, we should probably use a multiprecision generator (ie `independent_bits_engine`) in combination 2104with the distribution: 2105 2106[random_eg4] 2107 2108[random_eg4_out] 2109 2110And 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`] 2111and [@http://www.boost.org/doc/html/boost/random/subtract_with_idp144360752.html `subtract_with_carry_01_engine`] directly with multiprecision floating-point types. 2112It'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 2113use with these generators in this situation. For this reason, these should probably be used for research purposes only: 2114 2115[random_eg5] 2116 2117[endsect] [/section:random Generating Random Numbers] 2118 2119[section:primetest Primality Testing] 2120 2121The library implements a Miller-Rabin test for primality: 2122 2123 #include <boost/multiprecision/miller_rabin.hpp> 2124 2125 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 2126 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials, Engine& gen); 2127 2128 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 2129 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials); 2130 2131These functions perform a Miller-Rabin test for primality, if the result is `false` then /n/ is definitely composite, 2132while if the result is true then n is probably prime. The probability to declare a composite n as probable prime is 2133at most 0.25[super trials]. Note that this does not allow a statement about the probability of n being actually 2134prime (for that, the prior probability would have to be known). The algorithm used performs some 2135trial divisions to exclude small prime factors, does one Fermat test to exclude many more composites, and then 2136uses the Miller-Rabin algorithm straight out of 2137Knuth Vol 2, which recommends 25 trials for a pretty strong likelihood that /n/ is prime. 2138 2139The third optional argument is for a Uniform Random Number Generator from Boost.Random. When not provided the `mt19937` 2140generator is used. Note that when producing random primes then you should probably use a different random number generator 2141to produce candidate prime numbers for testing, than is used internally by `miller_rabin_test` for determining 2142whether the value is prime. It also helps of course to seed the generators with some source of randomness. 2143 2144The following example searches for a prime `p` for which `(p-1)/2` is also probably prime: 2145 2146[safe_prime] 2147 2148[endsect] [/section:primetest Primality Testing] 2149 2150[section:lits Literal Types and `constexpr` Support] 2151 2152There are two kinds of `constexpr` support in this library: 2153 2154* The more basic version requires only C++11 and allow the construction of some number types as literals. 2155* The more advanced support permits constexpr arithmetic and requires at least C++14 2156constexpr support, and for many operations C++2a support 2157 2158[h4 Declaring numeric literals] 2159 2160There are two backend types which are literals: 2161 2162* __float128__ (which requires GCC), and 2163* Instantiations of `cpp_int_backend` where the Allocator parameter is type `void`. 2164In addition, prior to C++14 the Checked parameter must be `boost::multiprecision::unchecked`. 2165 2166For example: 2167 2168 using namespace boost::multiprecision; 2169 2170 constexpr float128 f = 0.1Q // OK, float128's are always literals in C++11 2171 2172 constexpr int128_t i = 0; // OK, fixed precision int128_t has no allocator. 2173 constexpr uint1024_t j = 0xFFFFFFFF00000000uLL; // OK, fixed precision uint1024_t has no allocator. 2174 2175 constexpr checked_uint128_t k = 1; // OK from C++14 and later, not supported for C++11. 2176 constexpr checked_uint128_t k = -1; // Error, as this would normally lead to a runtime failure (exception). 2177 constexpr cpp_int l = 2; // Error, type is not a literal as it performs memory management. 2178 2179There is also support for user defined-literals with __cpp_int - these are limited to unchecked, fixed precision `cpp_int`'s 2180which are specified in hexadecimal notation. The suffixes supported are: 2181 2182[table 2183[[Suffix][Meaning]] 2184[[_cppi][Specifies a value of type: `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`, where N is chosen 2185to contain just enough digits to hold the number specified.]] 2186[[_cppui][Specifies a value of type: `number<cpp_int_backend<N,N,unsigned_magnitude,unchecked,void> >`, where N is chosen 2187to contain just enough digits to hold the number specified.]] 2188[[_cppi['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]] 2189[[_cppui['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]] 2190] 2191 2192In each case, use of these suffixes with hexadecimal values produces a `constexpr` result. 2193 2194Examples: 2195 2196 // Any use of user defined literals requires that we import the literal-operators into current scope first: 2197 using namespace boost::multiprecision::literals; 2198 // 2199 // To keep things simple in the example, we'll make our types used visible to this scope as well: 2200 using namespace boost::multiprecision; 2201 // 2202 // The value zero as a number<cpp_int_backend<4,4,signed_magnitude,unchecked,void> >: 2203 constexpr auto a = 0x0_cppi; 2204 // The type of each constant has 4 bits per hexadecimal digit, 2205 // so this is of type uint256_t (ie number<cpp_int_backend<256,256,unsigned_magnitude,unchecked,void> >): 2206 constexpr auto b = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui; 2207 // 2208 // Smaller values can be assigned to larger values: 2209 int256_t c = 0x1234_cppi; // OK 2210 // 2211 // However, this only works in constexpr contexts from C++14 onwards: 2212 constexpr int256_t d = 0x1_cppi; // Compiler error in C++11, requires C++14 2213 // 2214 // Constants can be padded out with leading zeros to generate wider types: 2215 constexpr uint256_t e = 0x0000000000000000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFF_cppui; // OK 2216 // 2217 // However, specific-width types are best produced with specific-width suffixes, 2218 // ones supported by default are `_cpp[u]i128`, `_cpp[u]i256`, `_cpp[u]i512`, `_cpp[u]i1024`. 2219 // 2220 constexpr int128_t f = 0x1234_cppi128; // OK, always produces an int128_t as the result. 2221 constexpr uint1024_t g = 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbccccccccccccccccccccc_cppui1024; // OK, 2222 // always produces an uint1024_t as the result. 2223 // 2224 // If other specific-width types are required, then there is a macro for generating the operators for these. 2225 // The macro can be used at namespace scope only: 2226 // 2227 BOOST_MP_DEFINE_SIZED_CPP_INT_LITERAL(2048); 2228 // 2229 // Now we can create 2048-bit literals as well: 2230 constexpr auto h = 0xff_cppi2048; // h is of type number<cpp_int_backend<2048,2048,signed_magnitude,unchecked,void> > 2231 // 2232 // Finally, negative values are handled via the unary minus operator: 2233 // 2234 constexpr int1024_t i = -0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui1024; 2235 // 2236 // Which means this also works: 2237 constexpr int1024_t j = -g; // OK: unary minus operator is constexpr. 2238 2239[h4 constexpr arithmetic] 2240 2241The front end of the library is all `constexpr` from C++14 and later. Currently there are only two 2242backend types that are `constexpr` aware: __float128 and __cpp_int. More backends will follow at a later date. 2243 2244Provided the compiler is GCC, type __float128__ support `constexpr` operations on all arithmetic operations from C++14, comparisons, 2245`abs`, `fabs`, `fpclassify`, `isnan`, `isinf`, `isfinite` and `isnormal` are also fully supported, but the transcendental functions are not. 2246 2247The __cpp_int types support constexpr arithmetic, provided it is a fixed precision type with no allocator. It may also 2248be a checked integer: in which case a compiler error will be generated on overflow or undefined behaviour. In addition 2249the free functions `abs`, `swap`, `multiply`, `add`, `subtract`, `divide_qr`, `integer_modulus`, `powm`, `lsb`, `msb`, 2250`bit_test`, `bit_set`, `bit_unset`, `bit_flip`, `sqrt`, `gcd`, `lcm` are all supported. Use of __cpp_int in this way 2251requires either a C++2a compiler (one which supports `std::is_constant_evaluated()` - currently only gcc-9 or clang-9 or later), 2252or GCC-6 or later in C++14 mode. 2253Compilers other than GCC and without `std::is_constant_evaluated()` will support a very limited set of operations: 2254expect to hit roadblocks rather easily. 2255 2256See __compiler_support for __is_constant_evaluated; 2257 2258For example given: 2259 2260[constexpr_circle] 2261 2262We can now calculate areas and circumferences, using all compile-time `constexpr` arithmetic: 2263 2264[constexpr_circle_usage] 2265 2266Note that these make use of the numeric constants from the __math_constants library, which also happen to be `constexpr`. 2267These usually have the full precision of the floating-point type, here 128-bit, about 36 decimal digits. 2268 2269[h5:hermite_poly_coeffics Calculating Hermite Polynomial coefficients at compile time] 2270 2271For a more interesting example, in [@../../example/constexpr_float_arithmetic_examples.cpp constexpr_float_arithmetic_examples.cpp] 2272we define a simple class for `constexpr` polynomial arithmetic: 2273 2274 template <class T, unsigned Order> 2275 struct const_polynomial; 2276 2277Given this, we can use recurrence relations to calculate the coefficients for various orthogonal 2278polynomials - in the example we use the Hermite polynomials. Only the constructor does any work - 2279it uses the recurrence relations to calculate the coefficient array: 2280 2281[hermite_example] 2282 2283Now we just need to define ['H[sub 0]] and ['H[sub 1]] as termination conditions for the recurrence: 2284 2285[hermite_example2] 2286 2287We can now declare ['H[sub 9]] as a `constexpr` object, access the coefficients, and evaluate 2288at an abscissa value, all at compile-time using `constexpr` arithmetic: 2289 2290[hermite_example3] 2291 2292See [@../../example/constexpr_float_arithmetic_examples.cpp constexpr_float_arithmetic_examples.cpp] for working code. 2293 2294Also since the coefficients to the Hermite polynomials are integers, we can also generate the Hermite 2295coefficients using (fixed precision) `cpp_int`s: see [@../../test/constexpr_test_cpp_int_6.cpp constexpr_test_cpp_int_6.cpp]. 2296 2297[h5:factorial_constexpr `constexpr` Factorials] 2298 2299We can also generate integer factorials in [@../../test/constexpr_test_cpp_int_5.cpp constexpr_test_cpp_int_5.cpp] like so: 2300 2301[factorial_decl] 2302 2303and validate the result: 2304 2305 constexpr uint1024_t f1 = factorial(uint1024_t(31)); // Factorial 31! 2306 static_assert(f1 == 0x1956ad0aae33a4560c5cd2c000000_cppi); // Expected result as an Boost.Multiprecision integer literal. 2307 2308[h5:random_constexpr Random `constexpr` values] 2309 2310Another example in [@../../test/constexpr_test_cpp_int_7.cpp constexpr_test_cpp_int_7.cpp] generates 2311a fresh multiprecision random number each time the file is compiled. It includes an C++ template implementation of the 2312[@https://en.wikipedia.org/wiki/KISS_(algorithm) KISS random number algorithm by George Marsaglia] for `cpp_int` integers. 2313 2314[random_constexpr_cppint] 2315 2316See also the __random section. 2317 2318[endsect] [/section:lits Literal Types and `constexpr` Support] 2319 2320 2321[section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`] 2322 2323Any integer number type that uses `cpp_int_backend` as its implementation layer can import or export its bits via two non-member functions: 2324 2325 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator, 2326 expression_template_option ExpressionTemplates, class OutputIterator> 2327 OutputIterator export_bits( 2328 const number<const cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2329 OutputIterator out, 2330 unsigned chunk_size, 2331 bool msv_first = true); 2332 2333 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator, 2334 expression_template_option ExpressionTemplates, class Iterator> 2335 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& 2336 import_bits( 2337 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2338 Iterator i, 2339 Iterator j, 2340 unsigned chunk_size = 0, 2341 bool msv_first = true); 2342 2343These functions are designed for data-interchange with other storage formats, and since __cpp_bin_float uses __cpp_int internally, 2344by extension they can be used for floating-point numbers based on that backend as well (see example below). 2345Parameters and use are as follows: 2346 2347 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator, 2348 expression_template_option ExpressionTemplates, class OutputIterator> 2349 OutputIterator export_bits( 2350 const number<const cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2351 OutputIterator out, 2352 unsigned chunk_size, 2353 bool msv_first = true); 2354 2355Exports the absolute value of `val` to OutputIterator `out`. The function will write `chunk_size` bits at a time 2356to the OutputIterator, and if `msv_first` is true, will write the most-significant block first. Byte and bit order 2357within each `chunk_size` block is always in the machines native format. Further, each block is stored in a 2358`boost::uintmax_t` when it's assigned to `*out`. 2359 2360[note Unfortunately, the standard's OutputIterator concept provides no means of deducing the type to output since 2361`std::iterator_traits<OutputIteratorType>::value_type` is type `void`. This is why the bit count for each block 2362has to be specified manually. It may also result in compiler warnings about the value being narrowed.] 2363 2364[tip If you're exporting to non-native byte layout, then use 2365[@http://www.boost.org/doc/libs/release/libs/endian/doc/index.html Boost.Endian] 2366to create a custom OutputIterator that reverses the byte order of each chunk prior to actually storing the result.] 2367 2368 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked, class Allocator, 2369 expression_template_option ExpressionTemplates, class ForwardIterator> 2370 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& 2371 import_bits( 2372 number<cpp_int_backend<MinBits, MaxBits, SignType, Checked, Allocator>, ExpressionTemplates>& val, 2373 ForwardIterator i, 2374 ForwardIterator j, 2375 unsigned chunk_size = 0, 2376 bool msv_first = true); 2377 2378Imports bits from the iterator range ['\[i,j)] and stores them in `val` to produce an unsigned result (if the result 2379is to be signed you will need to handle that separately). When `msv_first` is true, takes `*i` as the most significant 2380chunk. Assumes there are `chunk_size` bits in each value read from the iterator range, and that these are in machine native 2381bit/byte order. When `chunk_size` is zero, then assumes that each chunk contains 2382`std::numeric_limits<std::iterator_traits<ForwardIterator>::value_type>::digits`, note that this will give the wrong result 2383if dereferencing the iterators leads to a signed-integer type, [*and] the sign bit is significant (be particularly careful 2384if 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). 2385As 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 2386that presents it in native order (see [@http://www.boost.org/doc/libs/release/libs/endian/doc/index.html Boost.Endian]). 2387 2388[note 2389Note 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 2390iterators much be pointers, and everything must be little-endian.] 2391 2392[h4 Examples] 2393 2394[IE1] 2395 2396[IE2] 2397 2398[endsect] [/section:import_export Importing and Exporting Data to and from `cpp_int` and `cpp_bin_float`] 2399 2400[section:rounding Rounding Rules for Conversions] 2401 2402As a general rule, all conversions between unrelated types are performed using basic arithmetic operations, therefore 2403conversions are either exact, or follow the same rounding rules as arithmetic for the type in question. 2404 2405The following table summarises the situation for conversions from native types: 2406 2407[table 2408[[Backend][Rounding Rules]] 2409[[__cpp_int][Conversions from integer types are exact if the target has sufficient precision, otherwise they 2410 truncate to the first 2^MaxBits bits (modulo arithmetic). Conversions from floating-point types 2411 are truncating to the nearest integer.]] 2412[[__gmp_int][Conversions are performed by the GMP library except for conversion from `long double` which is truncating.]] 2413[[__tom_int][Conversions from floating-point types are truncating, all others are performed by libtommath and are exact.]] 2414[[__gmp_float][Conversions are performed by the GMP library except for conversion from `long double` which should be exact 2415 provided the target type has as much precision as a `long double`.]] 2416[[__mpfr_float_backend][All conversions are performed by the underlying MPFR library.]] 2417[[__cpp_dec_float][All conversions are performed using basic arithmetic operations and are truncating.]] 2418[[__gmp_rational][See __gmp_int]] 2419[[__cpp_rational][See __cpp_int]] 2420[[__tommath_rational][See __tom_int]] 2421] 2422 2423[endsect] [/section:rounding Rounding Rules for Conversions] 2424 2425[section:mixed Mixed Precision Arithmetic] 2426 2427Mixed precision arithmetic is fully supported by the library. 2428 2429There are two different forms: 2430 2431* Where the operands are of different precision. 2432* Where the operands are of the same precision, but yield a higher precision result. 2433 2434[h4 Mixing Operands of Differing Precision] 2435 2436If the arguments to a binary operator are of different precision, then the operation is allowed 2437as long as there is an unambiguous implicit conversion from one argument type to the other. 2438In all cases the arithmetic is performed "as if" the lower precision type is promoted to the 2439higher precision type before applying the operator. However, particular backends may optimise 2440this and avoid actually creating a temporary if they are able to do so. 2441 2442For example: 2443 2444 mpfr_float_50 a(2), b; 2445 mpfr_float_100 c(3), d; 2446 static_mpfr_float_50 e(5), f; 2447 mpz_int i(20); 2448 2449 d = a * c; // OK, result of operand is an mpfr_float_100. 2450 b = a * c; // Error, can't convert the result to an mpfr_float_50 as it will lose digits. 2451 f = a * e; // Error, operator is ambiguous, result could be of either type. 2452 f = e * i; // OK, unambiguous conversion from mpz_int to static_mpfr_float_50 2453 2454[h4 Operands of the Same Precision] 2455 2456Sometimes you want to apply an operator to two arguments of the same precision in 2457such a way as to obtain a result of higher precision. The most common situation 2458occurs with fixed precision integers, where you want to multiply two N-bit numbers 2459to obtain a 2N-bit result. This is supported in this library by the following 2460free functions: 2461 2462 template <class ResultType, class Source1 class Source2> 2463 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 2464 2465 template <class ResultType, class Source1 class Source2> 2466 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 2467 2468 template <class ResultType, class Source1 class Source2> 2469 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 2470 2471These functions apply the named operator to the arguments ['a] and ['b] and store the 2472result in ['result], returning ['result]. In all cases they behave "as if" 2473arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 2474operator, though particular backends may well avoid that step by way of an optimization. 2475 2476The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 2477may be either instances of class `number` or native integer types. The latter is an optimization 2478that allows arithmetic to be performed on native integer types producing an extended precision result. 2479 2480For example: 2481 2482[mixed_eg] 2483 2484Produces the output: 2485 2486[mixed_output] 2487 2488[h4 Backends With Optimized Mixed Precision Arithmetic] 2489 2490The following backends have at least some direct support for mixed-precision arithmetic, 2491and therefore avoid creating unnecessary temporaries when using the interfaces above. 2492Therefore when using these types it's more efficient to use mixed-precision arithmetic, 2493than it is to explicitly cast the operands to the result type: 2494 2495__mpfr_float_backend, __mpf_float, __cpp_int. 2496 2497[endsect] [/section:mixed Mixed Precision Arithmetic] 2498 2499[section:gen_int Generic Integer Operations] 2500 2501All of the [link boost_multiprecision.ref.number.integer_functions non-member integer operations] are overloaded for the 2502__fundamental integer types in 2503`<boost/multiprecision/integer.hpp>`. 2504Where these operations require a temporary increase in precision (such as for `powm`), then 2505if no __fundamental type is available, a __cpp_int of appropriate precision will be used. 2506 2507Some of these functions are trivial, others use compiler intrinsics (where available) to ensure optimal evaluation. 2508 2509The overloaded functions are: 2510 2511 template <class Integer, class I2> 2512 Integer& multiply(Integer& result, const I2& a, const I2& b); 2513 2514Multiplies two `I2` values, to produce a wider `Integer` result. 2515 2516Returns `result = a * b` without overflow or loss of precision in the multiplication. 2517 2518 template <class Integer, class I2> 2519 Integer& add(Integer& result, const I2& a, const I2& b); 2520 2521Adds two `I2` values, to produce a wider `Integer` result. 2522 2523Returns `result = a + b` without overflow or loss of precision in the addition. 2524 2525 template <class Integer, class I2> 2526 Integer& subtract(Integer& result, const I2& a, const I2& b); 2527 2528Subtracts two `I2` values, to produce a wider `Integer` result. 2529 2530Returns `result = a - b` without overflow or loss of precision in the subtraction. 2531 2532 template <class Integer> 2533 Integer powm(const Integer& b, const Integer& p, const Integer& m); 2534 2535Returns b[super p] % m. 2536 2537 template <class Integer> 2538 void divide_qr(const Integer& x, const Integer& y, Integer& q, Integer& r); 2539 2540Sets `q = x / y` and `r = x % y`. 2541 2542 template <class Integer1, class Integer2> 2543 Integer2 integer_modulus(const Integer1& x, Integer2 val); 2544 2545Returns x % val; 2546 2547 template <class Integer> 2548 unsigned lsb(const Integer& x); 2549 2550Returns the (zero-based) index of the least significant bit of `x`. 2551 2552Throws a `std::domain_error` if `x <= 0`. 2553 2554 template <class Integer> 2555 unsigned msb(const Integer& x); 2556 2557Returns the (zero-based) index of the most significant bit of `x`. 2558 2559Throws a `std::domain_error` if `x <= 0`. 2560 2561 template <class Integer> 2562 bool bit_test(const Integer& val, unsigned index); 2563 2564Returns `true` if bit `index` is set in `val`. 2565 2566 template <class Integer> 2567 Integer& bit_set(Integer& val, unsigned index); 2568 2569Sets the `index` bit in `val`. 2570 2571 template <class Integer> 2572 Integer& bit_unset(Integer& val, unsigned index); 2573 2574Unsets the `index` bit in `val`. 2575 2576 template <class Integer> 2577 Integer& bit_flip(Integer& val, unsigned index); 2578 2579Flips the `index` bit in `val`. 2580 2581 template <class Integer> 2582 Integer sqrt(const Integer& x); 2583 template <class Integer> 2584 Integer sqrt(const Integer& x, Integer& r); 2585 2586Returns the integer square root `s` of x and sets `r` to the remainder ['x - s[super 2]]. 2587 2588 template <class Engine> 2589 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials, Engine& gen); 2590 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials); 2591 2592The regular Miller-Rabin functions in `<boost/multiprecision/miller_rabin.hpp>` are defined in terms of the above 2593generic operations, and so function equally well for __fundamental_types and multiprecision types. 2594 2595[endsect] [/section:gen_int Generic Integer Operations] 2596 2597[section:serial Boost.Serialization Support] 2598 2599Support for serialization comes in two forms: 2600 2601* Classes __number, __debug_adaptor, __logged_adaptor and __rational_adaptor have "pass through" serialization 2602support which requires the underlying backend to be serializable. 2603* Backends __cpp_int, __cpp_bin_float, __cpp_dec_float and __float128__ have full support for Boost.Serialization. 2604 2605[endsect] [/section:serialization Boost Serialization] 2606 2607[section:limits Numeric Limits] 2608 2609Boost.Multiprecision tries hard to implement `std::numeric_limits` for all types 2610as far as possible and meaningful because experience with Boost.Math has shown that this aids portability. 2611 2612The [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf C++ standard library] 2613defines `std::numeric_limits` in section 18.3.2. 2614 2615This in turn refers to the C standard 2616[@http://www.open-std.org/jtc1/sc22/wg11/docs/n507.pdf SC22/WG11 N507 DRAFT INTERNATIONAL ISO/IEC STANDARD 2617 WD 10967-1] 2618Information technology Language independent arithmetic Part 1: Integer and floating-point arithmetic. 2619 2620That C Standard in turn refers to 2621 2622[@https://doi.org/10.1109/IEEESTD.1985.82928 IEEE754 IEEE Standard for Binary 2623Floating-Point Arithmetic] 2624 2625There is a useful summary of `std::numeric_limits` at 2626[@http://www.cplusplus.com/reference/limits/numeric_limits/ C++ reference]. 2627 2628The chosen backend often determines how completely `std::numeric_limits` is available. 2629 2630Compiler options, processor type, and definition of macros or assembler instructions to control denormal numbers will alter 2631the values in the tables given below. 2632 2633[warning GMP's extendable floatin-point `mpf_t` does not have a concept of overflow: 2634operations that lead to overflow eventually run of out of resources 2635and terminate with stack overflow (often after several seconds).] 2636 2637[section:constants std::numeric_limits<> constants] 2638 2639[h4 is_specialized] 2640 2641`true` for all arithmetic types (integer, floating and fixed-point) 2642for which `std::numeric_limits<T>::numeric_limits` is specialized. 2643 2644A typical test is 2645 2646 if (std::numeric_limits<T>::is_specialized == false) 2647 { 2648 std::cout << "type " << typeid(T).name() << " is not specialized for std::numeric_limits!" << std::endl; 2649 // ... 2650 } 2651 2652Typically `numeric_limits<T>::is_specialized` is `true` for all `T` where the compile-time constant 2653members of `numeric_limits` are indeed known at compile time, and don't vary at runtime. For example 2654floating-point types with runtime-variable precision such as `mpfr_float` have no `numeric_limits` 2655specialization as it would be impossible to define all the members at compile time. In contrast 2656the precision of a type such as `mpfr_float_50` is known at compile time, and so it ['does] have a 2657`numeric_limits` specialization. 2658 2659Note that not all the `std::numeric_limits` member constants and functions are meaningful for all user-defined types (UDT), 2660such as the decimal and binary multiprecision types provided here. More information on this is given in the sections below. 2661 2662[h4 infinity] 2663 2664For floating-point types, [infin] is defined wherever possible, 2665but clearly infinity is meaningless for __arbitrary_precision arithmetic backends, 2666and there is one floating-point type (GMP's `mpf_t`, see __mpf_float) which has no notion 2667of infinity or NaN at all. 2668 2669A typical test whether infinity is implemented is 2670 2671 if(std::numeric_limits<T>::has_infinity) 2672 { 2673 std::cout << std::numeric_limits<T>::infinity() << std::endl; 2674 } 2675 2676and using tests like this is strongly recommended to improve portability. 2677 2678[warning If the backend is switched to a type that does not support infinity (or similarly NaNs) then, 2679without checks like this, there will be trouble.] 2680 2681[h4 is_signed] 2682 2683`std::numeric_limits<T>::is_signed == true` if the type `T` is signed. 2684 2685For __fundamental binary types, the sign is held in a single bit, 2686but for other types (`cpp_dec_float` and `cpp_bin_float`) 2687it may be a separate storage element, usually `bool`. 2688 2689[h4 is_exact] 2690 2691`std::numeric_limits<T>::is_exact == true` if type T uses exact representations. 2692 2693This is defined as `true` for all integer types and `false` for floating-point types. 2694 2695[@http://stackoverflow.com/questions/14203654/stdnumeric-limitsis-exact-what-is-a-usable-definition A usable definition] 2696has been discussed. 2697 2698ISO/IEC 10967-1, Language independent arithmetic, noted by the C++ Standard defines 2699 2700 A floating-point type F shall be a finite subset of [real]. 2701 2702The important practical distinction is that all integers (up to `max()`) can be stored exactly. 2703 2704[@http://en.wikipedia.org/wiki/Rational_number Rational] 2705types using two integer types are also exact. 2706 2707Floating-point types [*cannot store all real values] 2708(those in the set of [real]) [*exactly]. 2709For example, 0.5 can be stored exactly in a binary floating-point, but 0.1 cannot. 2710What is stored is the nearest representable real value, that is, rounded to nearest. 2711 2712Fixed-point types (usually decimal) are also defined as exact, in that they only 2713store a [*fixed precision], so half cents or pennies (or less) cannot be stored. 2714The results of computations are rounded up or down, 2715just like the result of integer division stored as an integer result. 2716 2717There are number of proposals to 2718[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html 2719add Decimal floating-point Support to C++]. 2720 2721[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2849.pdf Decimal TR]. 2722 2723And also 2724[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html 2725C++ Binary Fixed-Point Arithmetic]. 2726 2727[h4 is_bounded] 2728 2729`std::numeric_limits<T>::is_bounded == true` if the set of values represented by the type `T` is finite. 2730 2731This is `true` for all __fundamental_type integer, fixed and floating-point types, 2732and most multi-precision types. 2733 2734It is only `false` for a few __arbitrary_precision types like `cpp_int`. 2735 2736Rational and fixed-exponent representations are exact but not integer. 2737 2738[h4 is_modulo] 2739 2740`std::numeric_limits<T>::is_modulo` is defined as `true` if adding two positive values of type T 2741can yield a result less than either value. 2742 2743`is_modulo == true` means that the type does not overflow, but, for example, 2744'wraps around' to zero, when adding one to the `max()` value. 2745 2746For most __fundamental integer types, `std::numeric_limits<>::is_modulo` is `true`. 2747 2748`bool` is the only exception. 2749 2750The modulo behaviour is sometimes useful, 2751but also can be unexpected, and sometimes undesired, behaviour. 2752 2753Overflow of signed integers can be especially unexpected, 2754possibly causing change of sign. 2755 2756Boost.Multiprecision integer type `cpp_int` is not modulo 2757because as an __arbitrary_precision types, 2758it expands to hold any value that the machine resources permit. 2759 2760However fixed precision __cpp_int's may be modulo if they are unchecked 2761(i.e. they behave just like __fundamental integers), but not if they are checked 2762(overflow causes an exception to be raised). 2763 2764__fundamental and multi-precision floating-point types are normally not modulo. 2765 2766Where possible, overflow is to `std::numeric_limits<>::infinity()`, 2767provided `std::numeric_limits<>::has_infinity == true`. 2768 2769[h4 radix] 2770 2771Constant `std::numeric_limits<T>::radix` returns either 2 (for __fundamental and binary types) 2772or 10 (for decimal types). 2773 2774[h4 digits] 2775 2776The number of `radix` digits that be represented without change: 2777 2778* for integer types, the number of [*non-sign bits] in the significand. 2779* for floating types, the number of [*radix digits] in the significand. 2780 2781The values include any implicit bit, so for example, for the ubiquious 2782`double` using 64 bits 2783([@http://en.wikipedia.org/wiki/Double_precision_floating-point_format IEEE binary64 ]), 2784`digits` == 53, even though there are only 52 actual bits of the significand stored in the representation. 2785The value of `digits` reflects the fact that there is one implicit bit which is always set to 1. 2786 2787The Boost.Multiprecision binary types do not use an implicit bit, so the 2788`digits` member reflects exactly how many bits of precision were requested: 2789 2790 typedef number<cpp_bin_float<53, digit_base_2> > float64; 2791 typedef number<cpp_bin_float<113, digit_base_2> > float128; 2792 std::numeric_limits<float64>::digits == 53. 2793 std::numeric_limits<float128>::digits == 113. 2794 2795For the most common case of `radix == 2`, 2796`std::numeric_limits<T>::digits` is the number of bits in the representation, 2797not counting any sign bit. 2798 2799For a decimal integer type, when `radix == 10`, it is the number of decimal digits. 2800 2801[h4 digits10] 2802 2803Constant `std::numeric_limits<T>::digits10` returns the number of 2804decimal digits that can be represented without change or loss. 2805 2806For example, `numeric_limits<unsigned char>::digits10` is 2. 2807 2808This somewhat inscrutable definition means that an `unsigned char` 2809can hold decimal values `0..99` 2810without loss of precision or accuracy, usually from truncation. 2811 2812Had the definition been 3 then that would imply it could hold 0..999, 2813but as we all know, an 8-bit `unsigned char` can only hold 0..255, 2814and an attempt to store 256 or more will involve loss or change. 2815 2816For bounded integers, it is thus [*one less] than number of decimal digits 2817you need to display the biggest integer `std::numeric_limits<T>::max()`. 2818This value can be used to predict the layout width required for 2819 2820[digits10_1] 2821 2822For example, `unsigned short` is often stored in 16 bits, 2823so the maximum value is 0xFFFF or 65535. 2824 2825[digits10_2] 2826 2827 2828For bounded floating-point types, 2829if we create a `double` with a value with `digits10` (usually 15) decimal digits, 2830`1e15` or `1000000000000000` : 2831 2832[digits10_3] 2833 2834and we can increment this value to `1000000000000001` 2835as expected and show the difference too. 2836 2837But if we try to repeat this with more than `digits10` digits, 2838 2839[digits10_4] 2840 2841then we find that when we add one it has no effect, 2842and display show that there is loss of precision. See 2843[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error]. 2844 2845So `digits10` is the number of decimal digits [*guaranteed] to be correct. 2846 2847For example, 'round-tripping' for `double`: 2848 2849* If a decimal string with at most `digits10`( == 15) significant decimal digits 2850is converted to `double` and then converted back to the 2851same number of significant decimal digits, 2852then the final string will match the original 15 decimal digit string. 2853* If a `double` floating-point number is converted to a decimal string 2854with at least 17 decimal digits 2855and then converted back to `double`, 2856then the result will be binary identical to the original `double` value. 2857 2858For most purposes, you will much more likely want 2859`std::numeric_limits<>::max_digits10`, 2860the number of decimal digits that ensure that a change of one least significant bit (__ULP) 2861produces a different decimal digits string. 2862 2863For the most common `double` floating-point type,`max_digits10` is `digits10+2`, 2864but you should use C++11 `max_digits10` 2865where possible (see [link boost_multiprecision.tut.limits.constants.max_digits10 below]). 2866 2867[h4:max_digits10 max_digits10] 2868 2869`std::numeric_limits<T>::max_digits10` was added for floating-point 2870because `digits10` decimal digits are insufficient to show 2871a least significant bit (ULP) change giving puzzling displays like 2872 2873 0.666666666666667 != 0.666666666666667 2874 2875from failure to 'round-trip', for example: 2876 2877[max_digits10_2] 2878 2879If you wish to ensure that a change of one least significant bit (ULP) 2880produces a different decimal digits string, 2881then `max_digits10` is the precision to use. 2882 2883For example: 2884 2885[max_digits10_3] 2886 2887will display [pi] to the maximum possible precision using a `double`. 2888 2889[max_digits10_4] 2890 2891For integer types, `max_digits10` is implementation-dependent, 2892but is usually `digits10 + 2`. 2893This is the output field-width required for the maximum value of the type T 2894`std::numeric_limits<T>::max()` ['including a sign and a space]. 2895 2896So this will produce neat columns. 2897 2898 std::cout << std::setw(std::numeric_limits<int>::max_digits10) ... 2899 2900The extra two or three least-significant digits are 'noisy' and may be junk, 2901but if you want to 'round-trip' - printing a value out as a decimal digit string and reading it back in - 2902(most commonly during serialization and de-serialization) 2903you must use `os.precision(std::numeric_limits<T>::max_digits10)`. 2904 2905[note For Microsoft Visual Studio 2010, 2906`std::numeric_limits<float>::max_digits10` is wrongly defined as 8. It should be 9. 2907] 2908 2909[note For Microsoft Visual Studio before 2013 and the default floating-point 2910format, a small range of double-precision floating-point values with a 2911significand of approximately 0.0001 to 0.004 and exponent values of 1010 to 29121014 do not round-trip exactly being off by one least significant bit, 2913for probably every third value of the significand. 2914 2915A workaround is using the scientific or exponential format `std::scientific`. 2916 2917Other older compilers also fail to implement round-tripping entirely fault-free, for example, see 2918[@https://www.exploringbinary.com/incorrectly-rounded-conversions-in-gcc-and-glibc/ Incorrectly Rounded Conversions in GCC and GLIBC]. 2919 2920For more details see 2921[@https://www.exploringbinary.com/incorrect-round-trip-conversions-in-visual-c-plus-plus/ Incorrect Round-Trip Conversions in Visual C++], 2922and references therein 2923and 2924[@https://arxiv.org/pdf/1310.8121.pdf Easy Accurate Reading and Writing of Floating-Point Numbers, Aubrey Jaffer (August 2018)]. 2925 2926Microsoft VS2017 and other recent compilers, now use the 2927[@https://doi.org/10.1145/3192366.3192369 Ryu fast float-to-string conversion by Ulf Adams] 2928algorithm, claimed to be both exact and fast for 32 and 64-bit floating-point numbers. 2929] [/note] 2930 2931[note BOOST_NO_CXX11_NUMERIC_LIMITS is a suitable feature-test macro to determine if 2932`std::numeric_limits<float>::max_digits10` is implemented on any platform. 2933] [/note] 2934 2935[note ['requires cxx11_numeric_limits] is a suitable test for use of `std::numeric_limits<float>::max_digits10` 2936to control if a target in a jamfile used by a Boost B2/bjam program is built, or not. 2937] [/note] 2938 2939 2940If `max_digits10` is not available, you should use the 2941[@http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF Kahan formula for floating-point type T]. 2942 2943In C++, the equations for what Kahan (on page 4) describes as 'at least' and 'at most' are: 2944 2945 static long double const log10Two = 0.30102999566398119521373889472449L; // log10(2.) 2946 2947 static_cast<int>(floor((significand_digits - 1) * log10Two)); // == digits10 - 'at least' . 2948 static_cast<int>(ceil(1 + significand_digits * log10Two)); // == max_digits10 - 'at most'. 2949 2950Unfortunately, these cannot be evaluated (at least by C++03) at [*compile-time]. 2951So the following expression is often used instead. 2952 2953 max_digits10 = 2 + std::numeric_limits<T>::digits * 3010U/10000U; 2954 2955 // == 2 + std::numeric_limits<T>::digits for double and 64-bit long double. 2956 // == 3 + std::numeric_limits<T>::digits for float, 80-bit long-double and __float128. 2957 2958often the actual values are computed for the C limits macros: 2959 2960 #define FLT_MAXDIG10 (2+FLT_MANT_DIG * 3010U/10000U) // 9 2961 #define DBL_MAXDIG10 (2+ (DBL_MANT_DIG * 3010U)/10000U) // 17 2962 #define LDBL_MAXDIG10 (2+ (LDBL_MANT_DIG * 3010U)/10000U) // 17 for MSVC, 18 for others. 2963 2964The factor 3010U/10000U is ['log[sub 10](2) = 0.3010] 2965that can be evaluated at compile-time using only `short unsigned int`s to be a desirable `const` or `constexpr` (and usually also `static`). 2966 2967Boost macros allow this to be done portably, see 2968[@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]. 2969 2970(See also 2971[@http://www.loria.fr/~zimmerma/mca/mca-cup-0.5.9.pdf Richard P. Brent and Paul Zimmerman, Modern Computer Arithmetic] 2972Equation 3.8 on page 116). 2973 2974[max_digits10_1] [/ example for using max_digits10] 2975 2976[h4 round_style] 2977 2978The rounding style determines how the result of floating-point operations 2979is treated when the result cannot be [*exactly represented] in the significand. 2980Various rounding modes may be provided: 2981 2982* round to nearest up or down (default for floating-point types). 2983* round up (toward positive infinity). 2984* round down (toward negative infinity). 2985* round toward zero (integer types). 2986* no rounding (if decimal radix). 2987* rounding mode is not determinable. 2988 2989For integer types, `std::numeric_limits<T>::round_style` is always towards zero, so 2990 2991 std::numeric_limits<T>::round_style == std::round_to_zero; 2992 2993A decimal type, `cpp_dec_float` rounds in no particular direction, 2994which is to say it doesn't round at all. 2995And since there are several guard digits, 2996it's not really the same as truncation (round toward zero) either. 2997 2998For floating-point types, it is normal to round to nearest. 2999 3000 std::numeric_limits<T>::round_style == std::round_to_nearest; 3001 3002See function `std::numeric_limits<T>::round_error` for the maximum error (in ULP) 3003that rounding can cause. 3004 3005[h4 has_denorm_loss] 3006 3007`true` if a loss of precision is detected as a 3008[@http://en.wikipedia.org/wiki/Denormalization denormalization] loss, 3009rather than an inexact result. 3010 3011Always `false` for integer types. 3012 3013`false` for all types which do not have `has_denorm` == `std::denorm_present`. 3014 3015[h4 denorm_style] 3016 3017[@http://en.wikipedia.org/wiki/Denormal_number Denormalized values] are 3018representations with a variable number of exponent bits that can permit 3019gradual underflow, so that, if type T is `double`. 3020 3021 std::numeric_limits<T>::denorm_min() < std::numeric_limits<T>::min() 3022 3023A type may have any of the following `enum float_denorm_style` values: 3024 3025* `std::denorm_absent`, if it does not allow denormalized values. 3026(Always used for all integer and exact types). 3027* `std::denorm_present`, if the floating-point type allows denormalized values. 3028*`std::denorm_indeterminate`, if indeterminate at compile time. 3029 3030[h4 Tinyness before rounding] 3031 3032`bool std::numeric_limits<T>::tinyness_before` 3033 3034`true` if a type can determine that a value is too small 3035to be represent as a normalized value before rounding it. 3036 3037Generally true for `is_iec559` floating-point __fundamantal types, 3038but false for integer types. 3039 3040Standard-compliant IEEE 754 floating-point implementations may detect the floating-point underflow at three predefined moments: 3041 3042# After computation of a result with absolute value smaller than 3043`std::numeric_limits<T>::min()`, 3044such implementation detects ['tinyness before rounding] (e.g. UltraSparc). 3045 3046# After rounding of the result to `std::numeric_limits<T>::digits` bits, 3047if the result is tiny, such implementation detects ['tinyness after rounding] 3048(e.g. SuperSparc). 3049 3050# If the conversion of the rounded tiny result to subnormal form 3051resulted in the loss of precision, such implementation detects ['denorm loss]. 3052 3053[endsect] [/section:constants std::numeric_limits<> Constants] 3054 3055[section:functions `std::numeric_limits<>` functions] 3056 3057[h4:max_function `max` function] 3058 3059Function `(std::numeric_limits<T>::max)()` returns the largest finite value 3060that can be represented by the type T. If there is no such value (and 3061`numeric_limits<T>::bounded` is `false`) then returns `T()`. 3062 3063For __fundamental types there is usually a corresponding MACRO value TYPE_MAX, 3064where TYPE is CHAR, INT, FLOAT etc. 3065 3066Other types, including those provided by a typedef, 3067for example `INT64_T_MAX` for `int64_t`, may provide a macro definition. 3068 3069To cater for situations where no `numeric_limits` specialization is available 3070(for example because the precision of the type varies at runtime), 3071packaged versions of this (and other functions) are provided using 3072 3073 #include <boost/math/tools/precision.hpp> 3074 3075 T = boost::math::tools::max_value<T>(); 3076 3077Of course, these simply use `(std::numeric_limits<T>::max)()` if available, 3078but otherwise 'do something sensible'. 3079 3080[h4 lowest function] 3081 3082Since C++11: `std::numeric_limits<T>::lowest()` is 3083 3084* For integral types, the same as function `min()`. 3085* For floating-point types, generally the negative of `max()` 3086(but implementation-dependent). 3087 3088[digits10_5] 3089 3090[h4:min_function `min` function] 3091 3092Function `(std::numeric_limits<T>::min)()` returns the minimum finite value 3093that can be represented by the type T. 3094 3095For __fundamental types, there is usually a corresponding MACRO value TYPE_MIN, 3096where TYPE is CHAR, INT, FLOAT etc. 3097 3098Other types, including those provided by a `typedef`, 3099for example, `INT64_T_MIN` for `int64_t`, may provide a macro definition. 3100 3101For floating-point types, 3102it is more fully defined as the ['minimum positive normalized value]. 3103 3104See `std::numeric_limits<T>::denorm_min()` for the smallest denormalized value, provided 3105 3106 std::numeric_limits<T>::has_denorm == std::denorm_present 3107 3108To cater for situations where no `numeric_limits` specialization is available 3109(for example because the precision of the type varies at runtime), 3110packaged versions of this (and other functions) are provided using 3111 3112 #include <boost/math/tools/precision.hpp> 3113 3114 T = boost::math::tools::min_value<T>(); 3115 3116Of course, these simply use `std::numeric_limits<T>::min()` if available. 3117 3118[h4 denorm_min function] 3119 3120Function `std::numeric_limits<T>::denorm_min()` 3121returns the smallest 3122[@http://en.wikipedia.org/wiki/Denormal_number denormalized value], 3123provided 3124 3125 std::numeric_limits<T>::has_denorm == std::denorm_present 3126 3127[denorm_min_1] 3128 3129The exponent is effectively reduced from -308 to -324 3130(though it remains encoded as zero and leading zeros appear in the significand, 3131thereby losing precision until the significand reaches zero). 3132 3133[h4 round_error] 3134 3135Function `std::numeric_limits<T>::round_error()` returns the maximum error 3136(in units of __ULP) 3137that can be caused by any basic arithmetic operation. 3138 3139 round_style == std::round_indeterminate; 3140 3141The rounding style is indeterminable at compile time. 3142 3143For floating-point types, when rounding is to nearest, 3144only half a bit is lost by rounding, and `round_error == 0.5`. 3145In contrast when rounding is towards zero, or plus/minus infinity, 3146we can loose up to one bit from rounding, and `round_error == 1`. 3147 3148For integer types, rounding always to zero, so at worst almost one bit can be rounded, 3149so `round_error == 1`. 3150 3151`round_error()` can be used with `std::numeric_limits<T>::epsilon()` to estimate 3152the maximum potential error caused by rounding. For typical floating-point types, 3153`round_error() = 1/2`, so half epsilon is the maximum potential error. 3154 3155[round_error_1] 3156 3157There are, of course, many occasions when much bigger loss of precision occurs, 3158for example, caused by 3159[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error] 3160or very many iterations. 3161 3162[h4:epsilon epsilon] 3163 3164Function `std::numeric_limits<T>::epsilon()` is meaningful only for non-integral types. 3165 3166It returns the difference between `1.0` and the next value representable 3167by the floating-point type T. 3168So it is a one least-significant-bit change in this floating-point value. 3169 3170For `double` (`float_64t`) it is `2.2204460492503131e-016` 3171showing all possibly significant 17 decimal digits. 3172 3173[epsilon_1] 3174 3175We can explicitly increment by one bit using the function `boost::math::float_next()` 3176and the result is the same as adding `epsilon`. 3177 3178[epsilon_2] 3179 3180Adding any smaller value, like half `epsilon`, will have no effect on this value. 3181 3182[epsilon_3] 3183 3184So this cancellation error leaves the values equal, despite adding half `epsilon`. 3185 3186To achieve greater portability over platform and floating-point type, 3187Boost.Math and Boost.Multiprecision provide a package of functions that 3188'do something sensible' if the standard `numeric_limits` is not available. 3189To use these `#include <boost/math/tools/precision.hpp>`. 3190 3191[epsilon_4] 3192 3193[h5:FP_tolerance Tolerance for Floating-point Comparisons] 3194 3195[@https://en.wikipedia.org/wiki/Machine_epsilon Machine epsilon [epsilon]] 3196is very useful to compute a tolerance when comparing floating-point values, 3197a much more difficult task than is commonly imagined. 3198 3199The C++ standard specifies [@https://en.cppreference.com/w/cpp/types/numeric_limits/epsilon `std::numeric_limits<>::epsilon()`] 3200and Boost.Multiprecision implements this (where possible) for its program-defined types analogous to the 3201__fundamental floating-point types like `double` `float`. 3202 3203For more information than you probably want (but still need) see 3204[@http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic] 3205 3206The naive test comparing the absolute difference between two values and a tolerance 3207does not give useful results if the values are too large or too small. 3208 3209So Boost.Test uses an algorithm first devised by Knuth 3210for reliably checking if floating-point values are close enough. 3211 3212See Donald. E. Knuth. The art of computer programming (vol II). 3213Copyright 1998 Addison-Wesley Longman, Inc., 0-201-89684-2. 3214Addison-Wesley Professional; 3rd edition. (The relevant equations are in paragraph 4.2.2, Eq. 36 and 37.) 3215 3216See [@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] 3217for more details. 3218 3219See also: 3220 3221[@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] 3222 3223[@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] 3224 3225[@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] 3226 3227[tolerance_1] 3228 3229used thus: 3230 3231 cd ./test 3232 BOOST_CHECK_CLOSE_FRACTION(expected, calculated, tolerance); 3233 3234(There is also a version BOOST_CHECK_CLOSE using tolerance as a [*percentage] rather than a fraction; 3235usually the fraction version is simpler to use). 3236 3237[tolerance_2] 3238 3239[h4:infinity Infinity - positive and negative] 3240 3241For floating-point types only, for which 3242`std::numeric_limits<T>::has_infinity == true`, 3243function `std::numeric_limits<T>::infinity()` 3244provides an implementation-defined representation for [infin]. 3245 3246The 'representation' is a particular bit pattern reserved for infinity. 3247For IEEE754 system (for which `std::numeric_limits<T>::is_iec559 == true`) 3248[@http://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity positive and negative infinity] 3249are assigned bit patterns for all defined floating-point types. 3250 3251Confusingly, the string resulting from outputting this representation, is also 3252implementation-defined. And the string that can be input to generate the representation is also implementation-defined. 3253 3254For example, the output is `1.#INF` on Microsoft systems, but `inf` on most *nix platforms. 3255 3256This implementation-defined-ness has hampered use of infinity (and NaNs) 3257but __Boost_Math and __Boost_Multiprecision work hard to provide a sensible representation 3258for [*all] floating-point types, not just the __fundamental_types, 3259which with the use of suitable facets to define the input and output strings, makes it possible 3260to use these useful features portably and including __Boost_Serialization. 3261 3262[h4 Not-A-Number NaN] 3263 3264[h5 Quiet_NaN] 3265 3266For floating-point types only, for which 3267`std::numeric_limits<T>::has_quiet_NaN == true`, 3268function `std::numeric_limits<T>::quiet_NaN()` 3269provides an implementation-defined representation for NaN. 3270 3271[@http://en.wikipedia.org/wiki/NaN NaNs] are values to indicate that the 3272result of an assignment or computation is meaningless. 3273A typical example is `0/0` but there are many others. 3274 3275NaNs may also be used, to represent missing values: for example, 3276these could, by convention, be ignored in calculations of statistics like means. 3277 3278Many of the problems with a representation for 3279[@http://en.wikipedia.org/wiki/NaN Not-A-Number] has hampered portable use, 3280similar to those with infinity. 3281 3282[nan_1] 3283 3284But using Boost.Math and suitable facets can permit portable use 3285of both NaNs and positive and negative infinity. 3286 3287[facet_1] 3288 3289[h5 Signaling NaN] 3290 3291For floating-point types only, for which 3292`std::numeric_limits<T>::has_signaling_NaN == true`, 3293function `std::numeric_limits<T>::signaling_NaN()` 3294provides an implementation-defined representation for NaN that causes a hardware trap. 3295It should be noted however, that at least one implementation of this function causes a hardware 3296trap to be triggered simply by calling `std::numeric_limits<T>::signaling_NaN()`, and not only 3297by using the value returned. 3298 3299[endsect] [/section:functions std::numeric_limits<> functions] 3300 3301[/ Tables of values for numeric_limits for various __fundamental and cpp_bin_float types] 3302[include numeric_limits_32_tables.qbk] 3303[/include numeric_limits_64_tables.qbk] 3304 3305[section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`] 3306 3307Based on the information above, one can see that different kinds of numbers can be 3308differentiated based on the information stored in `std::numeric_limits`. This is 3309in addition to the traits class [link boost_multiprecision.ref.number.traits_class_support 3310number_category] provided by this library. 3311 3312[h4 Integer Types] 3313 3314For an integer type T, all of the following conditions hold: 3315 3316 std::numeric_limits<T>::is_specialized == true 3317 std::numeric_limits<T>::is_integer == true 3318 std::numeric_limits<T>::is_exact == true 3319 std::numeric_limits<T>::min_exponent == 0 3320 std::numeric_limits<T>::max_exponent == 0 3321 std::numeric_limits<T>::min_exponent10 == 0 3322 std::numeric_limits<T>::max_exponent10 == 0 3323 3324In addition the type is /signed/ if: 3325 3326 std::numeric_limits<T>::is_signed == true 3327 3328If the type is arbitrary precision then: 3329 3330 std::numeric_limits<T>::is_bounded == false 3331 3332Otherwise the type is bounded, and returns a non zero value 3333from: 3334 3335 std::numeric_limits<T>::max() 3336 3337and has: 3338 3339 std::numeric_limits<T>::is_modulo == true 3340 3341if the type implements modulo arithmetic on overflow. 3342 3343[h4 Rational Types] 3344 3345Rational types are just like integers except that: 3346 3347 std::numeric_limits<T>::is_integer == false 3348 3349[h4 Fixed Precision Types] 3350 3351There appears to be no way to tell these apart from rational types, unless they set: 3352 3353 std::numeric_limits<T>::is_exact == false 3354 3355This is because these types are in essence a rational type with a fixed denominator. 3356 3357[h4 floating-point Types] 3358 3359For a floating-point type T, all of the following conditions hold: 3360 3361 std::numeric_limits<T>::is_specialized == true 3362 std::numeric_limits<T>::is_integer == false 3363 std::numeric_limits<T>::is_exact == false 3364 std::numeric_limits<T>::min_exponent != 0 3365 std::numeric_limits<T>::max_exponent != 0 3366 std::numeric_limits<T>::min_exponent10 != 0 3367 std::numeric_limits<T>::max_exponent10 != 0 3368 3369In addition the type is /signed/ if: 3370 3371 std::numeric_limits<T>::is_signed == true 3372 3373And the type may be decimal or binary depending on the value of: 3374 3375 std::numeric_limits<T>::radix 3376 3377In general, there are no arbitrary precision floating-point types, and so: 3378 3379 std::numeric_limits<T>::is_bounded == false 3380 3381[h4 Exact floating-point Types] 3382 3383Exact floating-point types are a [@http://en.wikipedia.org/wiki/Field_%28mathematics%29 field] 3384composed of an arbitrary precision integer scaled by an exponent. Such types 3385have no division operator and are the same as floating-point types except: 3386 3387 std::numeric_limits<T>::is_exact == true 3388 3389[h4 Complex Numbers] 3390 3391For historical reasons, complex numbers do not specialize `std::numeric_limits`, instead you must 3392inspect `std::numeric_limits<typename T::value_type>`. 3393 3394[endsect] [/section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`] 3395 3396[endsect] [/section:limits Numeric Limits] 3397 3398[section:input_output Input Output] 3399 3400[h4 Loopback testing] 3401 3402['Loopback] or ['round-tripping] refers to writing out a value as a decimal digit string using `std::iostream`, 3403usually to a `std::stringstream`, and then reading the string back in to another value, 3404and confirming that the two values are identical. A trivial example using `float` is: 3405 3406 float write; // Value to round-trip. 3407 std::stringstream ss; // Read and write std::stringstream. 3408 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output. 3409 ss.flags(std::ios_base::fmtflags(std::ios_base::scientific)); // Use scientific format. 3410 ss << write; // Output to string. 3411 float read; // Expected. 3412 ss >> read; // Read decimal digits string from stringstream. 3413 BOOST_CHECK_EQUAL(write, read); // Should be the same. 3414 3415and this can be run in a loop for all possible values of a 32-bit float. 3416For other floating-point types `T`, including __fundamental `double`, 3417it takes far too long to test all values, 3418so a reasonable test strategy is to use a large number of random values. 3419 3420 T write; 3421 std::stringstream ss; 3422 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output. 3423 ss.flags(f); // Changed from default iostream format flags if desired. 3424 ss << write; // Output to stringstream. 3425 3426 T read; 3427 ss >> read; // Get read using operator>> from stringstream. 3428 BOOST_CHECK_EQUAL(read, write); 3429 3430 read = static_cast<T>(ss.str()); // Get read by converting from decimal digits string representation of write. 3431 BOOST_CHECK_EQUAL(read, write); 3432 3433 read = static_cast<T>(write.str(0, f)); // Get read using format specified when written. 3434 BOOST_CHECK_EQUAL(read, write); 3435 3436 3437The test at 3438[@../../test/test_cpp_bin_float_io.cpp test_cpp_bin_float_io.cpp] 3439allows any floating-point type to be ['round_tripped] using a wide range of fairly random values. 3440It also includes tests compared a collection of 3441[@../../test/string_data.ipp stringdata] test cases in a file. 3442 3443[h4 Comparing with output using __fundamental types] 3444 3445One can make some comparisons with the output of 3446 3447 <number<cpp_bin_float<53, digit_count_2> > 3448 3449which has the same number of significant bits (53) as 64-bit double precision floating-point. 3450 3451However, although most outputs are identical, there are differences on some platforms 3452caused by the implementation-dependent behaviours allowed by the C99 specification 3453[@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 ISO/IEC 9899:TC2], 3454incorporated by C++. 3455 3456[:['"For e, E, f, F, g, and G conversions, if the number of significant decimal digits 3457is at most DECIMAL_DIG, then the result should be correctly rounded. 3458If the number of significant decimal digits is more than DECIMAL_DIG 3459but the source value is exactly representable with DECIMAL_DIG digits, 3460then the result should be an exact representation with trailing zeros. 3461Otherwise, the source value is bounded by two adjacent decimal strings L < U, 3462both having DECIMAL_DIG significant digits; 3463the value of the resultant decimal string D should satisfy L<= D <= U, 3464with the extra stipulation that the error should have a correct sign 3465for the current rounding direction."]] 3466 3467So not only is correct rounding for the full number of digits not required, 3468but even if the *optional* recommended practice is followed, 3469then the value of these last few digits is unspecified 3470as long as the value is within certain bounds. 3471 3472[note Do not expect the output from different platforms 3473to be [*identical], but `cpp_dec_float`, `cpp_bin_float` (and other backends) outputs should be 3474correctly rounded to the number of digits requested by the set precision and format.] 3475 3476 3477[h4 Macro BOOST_MP_MIN_EXPONENT_DIGITS] 3478 3479[@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 Standard] 3480for [/e and E] format specifiers, 7.19.6 Formatted input/output functions requires: 3481 3482\"The exponent always contains at least two digits, 3483and only as many more digits as necessary to represent the exponent.\" 3484 3485So to conform to the C99 standard (incorporated by C++) 3486 3487 #define BOOST_MP_MIN_EXPONENT_DIGITS 2 3488 3489Confusingly, Microsoft (and MinGW) do not conform to this standard and provide 3490[*at least three digits], for example `1e+001`. 3491So if you want the output to match that from 3492__fundamental floating-point types on compilers that use Microsofts runtime then use: 3493 3494 #define BOOST_MP_MIN_EXPONENT_DIGITS 3 3495 3496Also useful to get the minimum exponent field width is 3497 3498 #define BOOST_MP_MIN_EXPONENT_DIGITS 1 3499 3500producing a compact output like `2e+4`, 3501useful when conserving space is important. 3502 3503Larger values are also supported, for example, value 4 for `2e+0004` 3504which may be useful to ensure that columns line up. 3505 3506[endsect] [/section:input_output Input Output] 3507 3508[section:hash Hash Function Support] 3509 3510[hash1] 3511 3512[hash2] 3513 3514[hash3] 3515 3516[hash4] 3517 3518[endsect] [/section:hash Hash Function Support] 3519 3520[section:eigen Eigen Interoperability] 3521 3522This library provides the header: 3523 3524 #include <boost/multiprecision/eigen.hpp> 3525 3526which defines the traits classes and functions that the Eigen library needs all user-defined number types to provide. 3527 3528For example the following code performs quad-precision matrix solving on complex numbers: 3529 3530[eigen_eg] 3531 3532Which produces the following output: 3533 3534[eigen_out] 3535 3536[endsect] [/section:eigen Eigen Interoperability] 3537 3538[section:new_backend Writing a New Backend] 3539 3540The formal requirements for a backend to class `number` are given in the reference, but to help 3541speed and simplify the process there is a header [@../../test/skeleton_backend.hpp skeleton_backend.hpp] 3542where all the methods needed to be written are declared but nothing is implemented. The process of 3543writing a new backend then simplifies to: 3544 3545* Save skeleton_backend.hpp under a new name and change its #include guards to match. 3546* Search and replace `skeleton_backend` to the name of the new backend type. 3547* Fill in the blanks in the class definition and for the compulsary non-members. 3548* Don't forget to mark the functions as `inline`, `constexpr` and `noexcept` as required. 3549* Optionally fill in some of the optional methods - the header declares these in rather 3550 verbose form, for example with overloads for every single arithmetic type. No sane backend 3551 would ever implement all of these, just choose the ones that make sense and leave the others. 3552* Add convenience typedefs for the actual instantiation(s) of class `number` that will use the new backend. 3553 3554To test the new backend, start with a basic arithmetic test, this is a test case under `libs/math/test` 3555that looks something like: 3556 3557 #include <boost/multiprecision/my_new_number_type.hpp> 3558 #include "test_arithmetic.hpp" 3559 3560 int main() 3561 { 3562 test<boost::multiprecision::my_new_number_type>(); 3563 return boost::report_errors(); 3564 } 3565 3566This will basically "instantiate everything", and perform a few runtime sanity checks; it is a very good test that you have written legal code! 3567 3568You should also create a "header include test" that verifies that the new header includes everything it should, see 3569[@../../test/include_test/mpfr_include_test.cpp mpfr_include_test.cpp] for an example. 3570 3571For integer types, you should add the new type to at least the following tests as well: 3572 3573* test_hash.cpp 3574* test_int_io.cpp 3575* test_move.cpp 3576* test_numeric_limits.cpp 3577 3578For floating point types, you should add the new type to at least the following tests as well: 3579 3580* test_acos.cpp 3581* test_asin.cpp 3582* test_atan.cpp 3583* test_constants.cpp 3584* test_cos.cpp 3585* test_cosh.cpp 3586* test_exp.cpp 3587* test_float_io.cpp 3588* test_fpclassify.cpp 3589* test_hash.cpp 3590* test_log.cpp 3591* test_move.cpp 3592* test_numeric_limits.cpp 3593* test_pow.cpp 3594* test_round.cpp 3595* test_sf_import_c99.cpp 3596* test_sin.cpp 3597* test_sinh.cpp 3598* test_sqrt.cpp 3599* test_tan.cpp 3600* test_tanh.cpp 3601* concepts/number_concept_check.cpp 3602* concepts/sf_concept_check_basic.cpp 3603* concepts/sf_concept_check_bessel.cpp 3604* concepts/sf_concept_check_beta.cpp 3605* concepts/sf_concept_check_beta_2.cpp 3606* concepts/sf_concept_check_beta_3.cpp 3607* concepts/sf_concept_check_elliptic.cpp 3608* concepts/sf_concept_check_gamma.cpp 3609* concepts/sf_concept_check_poly.cpp 3610 3611[endsect] [/section:new_backend Writing a New Backend] 3612 3613[endsect] [/section:tut Tutorial] 3614 3615[section:ref Reference] 3616 3617[section:number number] 3618 3619[h4 Synopsis] 3620 3621 namespace boost{ namespace multiprecision{ 3622 3623 enum expression_template_option { et_on = 1, et_off = 0 }; 3624 3625 template <class Backend> struct expression_template_default 3626 { static const expression_template_option value = et_on; }; 3627 3628 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 3629 class number 3630 { 3631 public: 3632 typedef Backend backend_type; 3633 typedef typename component_type<self_type>::type value_type; 3634 3635 number(); 3636 number(see-below); 3637 number& operator=(see-below); 3638 number& assign(see-below); 3639 3640 // Member operators 3641 number& operator+=(const ``['see-below]``&); 3642 number& operator-=(const ``['see-below]``&); 3643 number& operator*=(const ``['see-below]``&); 3644 number& operator/=(const ``['see-below]``&); 3645 number& operator++(); 3646 number& operator--(); 3647 number operator++(int); 3648 number operator--(int); 3649 3650 number& operator%=(const ``['see-below]``&); 3651 number& operator&=(const ``['see-below]``&); 3652 number& operator|=(const ``['see-below]``&); 3653 number& operator^=(const ``['see-below]``&); 3654 number& operator<<=(const ``['integer-type]``&); 3655 number& operator>>=(const ``['integer-type]``&); 3656 3657 // Use in Boolean context: 3658 operator ``['convertible-to-bool-type]``()const; 3659 // swap: 3660 void swap(number& other); 3661 // Sign: 3662 bool is_zero()const; 3663 int sign()const; 3664 // string conversion: 3665 std::string str()const; 3666 // Generic conversion mechanism 3667 template <class T> 3668 T convert_to()const; 3669 template <class T> 3670 explicit operator T ()const; 3671 // precision control: 3672 static unsigned default_precision(); 3673 static void default_precision(unsigned digits10); 3674 unsigned precision()const; 3675 void precision(unsigned digits10); 3676 // Comparison: 3677 int compare(const number<Backend>& o)const; 3678 template <class V> 3679 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type 3680 compare(const V& o)const; 3681 // real and imaginary parts: 3682 value_type real()const; 3683 value_type imag()const; 3684 template <class T> 3685 void real(const T& val); 3686 template <class T> 3687 void imag(const T& val); 3688 // Access to the underlying implementation: 3689 Backend& backend(); 3690 const Backend& backend()const; 3691 }; 3692 3693 // Non member operators: 3694 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&); 3695 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&); 3696 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&); 3697 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&); 3698 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&); 3699 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&); 3700 // Integer only operations: 3701 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&); 3702 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&); 3703 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&); 3704 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&); 3705 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&); 3706 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&); 3707 // Comparison operators: 3708 bool operator==(const ``['see-below]``&, const ``['see-below]``&); 3709 bool operator!=(const ``['see-below]``&, const ``['see-below]``&); 3710 bool operator< (const ``['see-below]``&, const ``['see-below]``&); 3711 bool operator> (const ``['see-below]``&, const ``['see-below]``&); 3712 bool operator<=(const ``['see-below]``&, const ``['see-below]``&); 3713 bool operator>=(const ``['see-below]``&, const ``['see-below]``&); 3714 3715 // Swap: 3716 template <class Backend, expression_template_option ExpressionTemplates> 3717 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 3718 3719 // iostream support: 3720 template <class Backend, expression_template_option ExpressionTemplates> 3721 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r); 3722 std::ostream& operator << (std::ostream& os, const ``['unmentionable-expression-template-type]``& r); 3723 template <class Backend, expression_template_option ExpressionTemplates> 3724 std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r); 3725 3726 // Arithmetic with a higher precision result: 3727 template <class ResultType, class Source1 class Source2> 3728 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 3729 template <class ResultType, class Source1 class Source2> 3730 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 3731 template <class ResultType, class Source1 class Source2> 3732 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 3733 3734 // min and max overloads: 3735 ``['number]`` min (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3736 ``['number]`` max (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3737 3738 // C99 Non-member function standard library support: 3739 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&); 3740 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&); 3741 ``['number]`` acosh (const ``['number-or-expression-template-type]``&); 3742 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&); 3743 ``['number]`` asinh (const ``['number-or-expression-template-type]``&); 3744 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&); 3745 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3746 ``['number]`` atanh (const ``['number-or-expression-template-type]``&); 3747 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&); 3748 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&); 3749 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3750 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&); 3751 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&); 3752 ``['number]`` erf (const ``['number-or-expression-template-type]``&); 3753 ``['number]`` erfc (const ``['number-or-expression-template-type]``&); 3754 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&); 3755 ``['unmentionable-expression-template-type]`` exp2 (const ``['number-or-expression-template-type]``&); 3756 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&); 3757 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&); 3758 ``['unmentionable-expression-template-type]`` fdim (const ``['number-or-expression-template-type]``&); 3759 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&); 3760 ``['unmentionable-expression-template-type]`` fma (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3761 ``['unmentionable-expression-template-type]`` fmin (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3762 ``['unmentionable-expression-template-type]`` fmax (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3763 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3764 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*); 3765 ``['unmentionable-expression-template-type]`` hypot (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3766 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&); 3767 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 3768 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&); 3769 long long llrint (const ``['number-or-expression-template-type]``&); 3770 long long llround (const ``['number-or-expression-template-type]``&); 3771 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&); 3772 ``['unmentionable-expression-template-type]`` log2 (const ``['number-or-expression-template-type]``&); 3773 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&); 3774 ``['number]`` log1p (const ``['number-or-expression-template-type]``&); 3775 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&); 3776 long lrint (const ``['number-or-expression-template-type]``&); 3777 long lround (const ``['number-or-expression-template-type]``&); 3778 ``['unmentionable-expression-template-type]`` modf (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3779 ``['unmentionable-expression-template-type]`` nearbyint (const ``['number-or-expression-template-type]``&); 3780 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3781 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3782 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3783 ``['unmentionable-expression-template-type]`` remainder (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3784 ``['unmentionable-expression-template-type]`` remquo (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, int*); 3785 ``['unmentionable-expression-template-type]`` rint (const ``['number-or-expression-template-type]``&); 3786 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&); 3787 ``['unmentionable-expression-template-type]`` scalbn (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 3788 ``['unmentionable-expression-template-type]`` scalbln (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 3789 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&); 3790 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&); 3791 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&); 3792 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&); 3793 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&); 3794 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&); 3795 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&); 3796 3797 int fpclassify (const ``['number-or-expression-template-type]``&); 3798 bool isfinite (const ``['number-or-expression-template-type]``&); 3799 bool isinf (const ``['number-or-expression-template-type]``&); 3800 bool isnan (const ``['number-or-expression-template-type]``&); 3801 bool isnormal (const ``['number-or-expression-template-type]``&); 3802 int signbit (const ``['number-or-expression-template-type]``&); 3803 3804 bool isgreater (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3805 bool isgreaterequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3806 bool isless (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3807 bool islessequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-typearea]``&); 3808 bool islessgreater(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3809 bool isunordered(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3810 // Complex number functions: 3811 ``['number<...>::value_type]`` real (const ``['number-or-expression-template-type]``&); 3812 ``['number<...>::value_type]`` imag (const ``['number-or-expression-template-type]``&); 3813 ``['number<...>::value_type]`` abs (const ``['number-or-expression-template-type]``&); 3814 ``['number<...>::value_type]`` arg (const ``['number-or-expression-template-type]``&); 3815 ``['number<...>::value_type]`` norm (const ``['number-or-expression-template-type]``&); 3816 ``['number]`` conj (const ``['number-or-expression-template-type]``&); 3817 ``['number]`` proj (const ``['number-or-expression-template-type]``&); 3818 ``['number]`` polar (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3819 // Misc other common C library functions: 3820 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&); 3821 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&); 3822 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&); 3823 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&); 3824 ``['number]`` changesign(const ``['number-or-expression-template-type]``&); 3825 ``['number]`` copysign(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3826 3827 // Traits support: 3828 template <class T> 3829 struct component_type; 3830 template <class T> 3831 struct number_category; 3832 template <class T> 3833 struct is_number; 3834 template <class T> 3835 struct is_number_expression; 3836 3837 // Integer specific functions: 3838 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3839 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3840 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``&, unsigned); 3841 ``['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); 3842 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``&); 3843 template <class Backend, expression_template_option ExpressionTemplates> 3844 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``&, number<Backend, EXpressionTemplates>&); 3845 template <class Backend, expression_template_option ExpressionTemplates> 3846 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y, 3847 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r); 3848 template <class Integer> 3849 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val); 3850 unsigned lsb(const ``['number-or-expression-template-type]``& x); 3851 unsigned msb(const ``['number-or-expression-template-type]``& x); 3852 template <class Backend, class ExpressionTemplates> 3853 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index); 3854 template <class Backend, class ExpressionTemplates> 3855 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index); 3856 template <class Backend, class ExpressionTemplates> 3857 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index); 3858 template <class Backend, class ExpressionTemplates> 3859 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index); 3860 template <class Engine> 3861 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen); 3862 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials); 3863 3864 // Rational number support: 3865 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&); 3866 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&); 3867 3868 }} // namespaces 3869 3870 namespace boost{ namespace math{ 3871 3872 // Boost.Math interoperability functions: 3873 int fpclassify (const ``['number-or-expression-template-type]``&, int); 3874 bool isfinite (const ``['number-or-expression-template-type]``&, int); 3875 bool isnan (const ``['number-or-expression-template-type]``&, int); 3876 bool isinf (const ``['number-or-expression-template-type]``&, int); 3877 bool isnormal (const ``['number-or-expression-template-type]``&, int); 3878 3879 }} // namespaces 3880 3881 // numeric_limits support: 3882 namespace std{ 3883 3884 template <class Backend, expression_template_option ExpressionTemplates> 3885 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 3886 { 3887 /* Usual members here */ 3888 }; 3889 3890 } 3891 3892[h4 Description] 3893 3894 enum expression_template_option { et_on = 1, et_off = 0 }; 3895 3896This enumerated type is used to specify whether expression templates are turned on (et_on) or turned off (et_off). 3897 3898 template <class Backend> struct expression_template_default 3899 { static const expression_template_option value = et_on; }; 3900 3901This traits class specifies the default expression template option to be used with a particular Backend type. 3902It defaults to `et_on`. 3903 3904 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 3905 class number; 3906 3907Class `number` has two template arguments: 3908 3909[variablelist 3910[[Backend][The actual arithmetic back-end that does all the work.]] 3911[[ExpressionTemplates][A Boolean value: when `et_on`, then expression templates are enabled, otherwise when set to `et_off` they are disabled. 3912 The default for this parameter is computed via the traits class `expression_template_default` whose member `value` defaults to `et_on` unless 3913 the traits class is specialized for a particular backend.]] 3914] 3915 3916 number(); 3917 number(see-below); 3918 number& operator=(see-below); 3919 number& assign(see-below); 3920 3921Type `number` is default constructible, and both copy constructible and assignable from: 3922 3923* Itself. 3924* An expression template which is the result of one of the arithmetic operators. 3925* Any __fundamental arithmetic type, as long as the result would not be lossy (for example float to integer conversion). 3926* Any type that the Backend is implicitly constructible or assignable from. 3927* An rvalue reference to another `number`. Move-semantics are used for construction if the backend also 3928supports rvalue reference construction. In the case of assignment, move semantics are always supported 3929when the argument is an rvalue reference irrespective of the backend. 3930* Any type in the same family, as long as no loss of precision is involved. For example from `int128_t` to `int256_t`, 3931or `cpp_dec_float_50` to `cpp_dec_float_100`. 3932 3933Type `number` is explicitly constructible from: 3934 3935* Any type mentioned above. 3936* A `std::string` or any type which is convertible to `const char*`. 3937* Any arithmetic type (including those that would result in lossy conversions). 3938* Any type in the same family, including those that result in loss of precision. 3939* Any type that the Backend is explicitly constructible from. 3940* Any pair of types for which a generic interconversion exists: that is from integer to integer, integer 3941to rational, integer to float, rational to rational, rational to float, or float to float. 3942 3943The assign member function is available for any type for which an explicit converting constructor exists. 3944It is intended to be used where a temporary generated from an explicit assignment would be expensive, for example: 3945 3946 mpfr_float_50 f50; 3947 mpfr_float_100 f100; 3948 3949 f50 = static_cast<mpfr_float_50>(f100); // explicit cast create a temporary 3950 f50.assign(f100); // explicit call to assign create no temporary 3951 3952In addition, if the type has multiple components (for example rational or complex number types), then there is a 3953two argument constructor: 3954 3955 number(arg1, arg2); 3956 3957Where the two args must either be arithmetic types, or types that are convertible to the two components of `this`. 3958 3959Finally, when the type has a variable precision, then there are constructors: 3960 3961 number(arg1, precision); 3962 number(arg1, arg2, precision); 3963 3964Where `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. 3965 3966Likewise `assign` has a 2-arg overloaded, with the second argument being the precision. 3967 3968 number& operator+=(const ``['see-below]``&); 3969 number& operator-=(const ``['see-below]``&); 3970 number& operator*=(const ``['see-below]``&); 3971 number& operator/=(const ``['see-below]``&); 3972 number& operator++(); 3973 number& operator--(); 3974 number operator++(int); 3975 number operator--(int); 3976 // Integer only operations: 3977 number& operator%=(const ``['see-below]``&); 3978 number& operator&=(const ``['see-below]``&); 3979 number& operator|=(const ``['see-below]``&); 3980 number& operator^=(const ``['see-below]``&); 3981 number& operator<<=(const ``['integer-type]``&); 3982 number& operator>>=(const ``['integer-type]``&); 3983 3984These operators all take their usual arithmetic meanings. 3985 3986The arguments to these operators is either: 3987 3988* Another `number<Backend, ExpressionTemplates>`. 3989* An expression template derived from `number<Backend>`. 3990* Any type implicitly convertible to `number<Backend, ExpressionTemplates>`, including some other instance of class `number`. 3991 3992For the left and right shift operations, the argument must be a __fundamental 3993integer type with a positive value (negative values result in a `std::runtime_error` being thrown). 3994 3995 operator ``['convertible-to-bool-type]``()const; 3996 3997Returns an ['unmentionable-type] that is usable in Boolean contexts (this allows `number` to be used in any 3998Boolean context - if statements, conditional statements, or as an argument to a logical operator - without 3999type `number` being convertible to type `bool`. 4000 4001This operator also enables the use of `number` with any of the following operators: 4002`!`, `||`, `&&` and `?:`. 4003 4004 void swap(number& other); 4005 4006Swaps `*this` with `other`. 4007 4008 bool is_zero()const; 4009 4010Returns `true` is `*this` is zero, otherwise `false`. 4011 4012 int sign()const; 4013 4014Returns a value less than zero if `*this` is negative, a value greater than zero if `*this` is positive, and zero 4015if `*this` is zero. 4016 4017 std::string str(unsigned precision, bool scientific = true)const; 4018 4019Returns the number formatted as a string, with at least /precision/ digits, and in scientific format 4020if /scientific/ is true. 4021 4022 template <class T> 4023 T convert_to()const; 4024 4025 template <class T> 4026 explicit operator T ()const; 4027 4028Provides a generic conversion mechanism to convert `*this` to type `T`. Type `T` may be any arithmetic type. 4029Optionally other types may also be supported by specific `Backend` types. 4030 4031 4032 static unsigned default_precision(); 4033 static void default_precision(unsigned digits10); 4034 unsigned precision()const; 4035 void precision(unsigned digits10); 4036 4037These functions are only available if the Backend template parameter supports runtime changes to precision. They get and set 4038the default precision and the precision of `*this` respectively. 4039 4040 int compare(const number<Backend, ExpressionTemplates>& o)const; 4041 template <class V> 4042 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type 4043 compare(const V& other)const; 4044 4045Returns: 4046 4047* A value less that 0 for `*this < other` 4048* A value greater that 0 for `*this > other` 4049* Zero for `*this == other` 4050 4051 value_type real()const; 4052 value_type imag()const; 4053 4054These return the real and imaginary parts respectively. If the number is not a complex type, then the imaginary part is always zero. 4055 4056 template <class T> 4057 void real(const T& val); 4058 template <class T> 4059 void imag(const T& val); 4060 4061These set the real and imaginary parts respectively of the number. If the number is not a complex type, then setting the real part 4062is equivalent to assignment, and attempting to set the imaginary part will result in a compile time error. 4063 4064 Backend& backend(); 4065 const Backend& backend()const; 4066 4067Returns the underlying back-end instance used by `*this`. 4068 4069[h4 Non-member operators] 4070 4071 // Non member operators: 4072 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&); 4073 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&); 4074 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&); 4075 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&); 4076 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&); 4077 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&); 4078 // Integer only operations: 4079 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&); 4080 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&); 4081 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&); 4082 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&); 4083 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&); 4084 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&); 4085 // Comparison operators: 4086 bool operator==(const ``['see-below]``&, const ``['see-below]``&); 4087 bool operator!=(const ``['see-below]``&, const ``['see-below]``&); 4088 bool operator< (const ``['see-below]``&, const ``['see-below]``&); 4089 bool operator> (const ``['see-below]``&, const ``['see-below]``&); 4090 bool operator<=(const ``['see-below]``&, const ``['see-below]``&); 4091 bool operator>=(const ``['see-below]``&, const ``['see-below]``&); 4092 4093These operators all take their usual arithmetic meanings. 4094 4095The arguments to these functions must contain at least one of the following: 4096 4097* A `number`. 4098* An expression template type derived from `number`. 4099* Any type for which `number` has an implicit constructor - for example a __fundamental arithmetic type. 4100 4101The return type of these operators is either: 4102 4103* An ['unmentionable-type] expression template type when `ExpressionTemplates` is `true`. 4104* Type `number<Backend, et_off>` when `ExpressionTemplates` is `false`. 4105* Type `bool` if the operator is a comparison operator. 4106 4107Finally note that the second argument to the left and right shift operations must be a __fundamental integer type, 4108and that the argument must be positive (negative arguments result in a `std::runtime_error` being thrown). 4109 4110[h4 swap] 4111 4112 template <class Backend, ExpressionTemplates> 4113 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 4114 4115Swaps `a` and `b`. 4116 4117[h4 Iostream Support] 4118 4119 template <class Backend, expression_template_option ExpressionTemplates> 4120 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r); 4121 template <class Unspecified...> 4122 std::ostream& operator << (std::ostream& os, const unmentionable-expression-template& r); 4123 template <class Backend, expression_template_option ExpressionTemplates> 4124 inline std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r) 4125 4126These operators provided formatted input-output operations on `number` types, and expression templates derived from them. 4127 4128It's down to the back-end type to actually implement string conversion. However, the back-ends provided with 4129this library support all of the iostream formatting flags, field width and precision settings. 4130 4131[h4 Arithmetic with a higher precision result] 4132 4133 template <class ResultType, class Source1 class Source2> 4134 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 4135 4136 template <class ResultType, class Source1 class Source2> 4137 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 4138 4139 template <class ResultType, class Source1 class Source2> 4140 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 4141 4142These functions apply the named operator to the arguments ['a] and ['b] and store the 4143result in ['result], returning ['result]. In all cases they behave "as if" 4144arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 4145operator, though particular backends may well avoid that step by way of an optimization. 4146 4147The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 4148may be either instances of class `number` or native integer types. The latter is an optimization 4149that allows arithmetic to be performed on native integer types producing an extended precision result. 4150 4151[h4 Non-member standard library function support] 4152 4153 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&); 4154 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&); 4155 ``['number]`` acosh (const ``['number-or-expression-template-type]``&); 4156 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&); 4157 ``['number]`` asinh (const ``['number-or-expression-template-type]``&); 4158 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&); 4159 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4160 ``['number]`` atanh (const ``['number-or-expression-template-type]``&); 4161 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&); 4162 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&); 4163 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4164 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&); 4165 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&); 4166 ``['number]`` erf (const ``['number-or-expression-template-type]``&); 4167 ``['number]`` erfc (const ``['number-or-expression-template-type]``&); 4168 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&); 4169 ``['unmentionable-expression-template-type]`` exp2 (const ``['number-or-expression-template-type]``&); 4170 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&); 4171 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&); 4172 ``['unmentionable-expression-template-type]`` fdim (const ``['number-or-expression-template-type]``&); 4173 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&); 4174 ``['unmentionable-expression-template-type]`` fma (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4175 ``['unmentionable-expression-template-type]`` fmin (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4176 ``['unmentionable-expression-template-type]`` fmax (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4177 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4178 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*); 4179 ``['unmentionable-expression-template-type]`` hypot (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4180 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&); 4181 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 4182 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&); 4183 long long llrint (const ``['number-or-expression-template-type]``&); 4184 long long llround (const ``['number-or-expression-template-type]``&); 4185 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&); 4186 ``['unmentionable-expression-template-type]`` log2 (const ``['number-or-expression-template-type]``&); 4187 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&); 4188 ``['number]`` log1p (const ``['number-or-expression-template-type]``&); 4189 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&); 4190 long lrint (const ``['number-or-expression-template-type]``&); 4191 long lround (const ``['number-or-expression-template-type]``&); 4192 ``['unmentionable-expression-template-type]`` modf (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4193 ``['unmentionable-expression-template-type]`` nearbyint (const ``['number-or-expression-template-type]``&); 4194 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4195 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4196 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4197 ``['unmentionable-expression-template-type]`` remainder (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4198 ``['unmentionable-expression-template-type]`` remquo (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&, int*); 4199 ``['unmentionable-expression-template-type]`` rint (const ``['number-or-expression-template-type]``&); 4200 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&); 4201 ``['unmentionable-expression-template-type]`` scalbn (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 4202 ``['unmentionable-expression-template-type]`` scalbln (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 4203 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&); 4204 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&); 4205 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&); 4206 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&); 4207 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&); 4208 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&); 4209 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&); 4210 4211 int fpclassify (const ``['number-or-expression-template-type]``&); 4212 bool isfinite (const ``['number-or-expression-template-type]``&); 4213 bool isinf (const ``['number-or-expression-template-type]``&); 4214 bool isnan (const ``['number-or-expression-template-type]``&); 4215 bool isnormal (const ``['number-or-expression-template-type]``&); 4216 int signbit (const ``['number-or-expression-template-type]``&); 4217 4218 bool isgreater (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4219 bool isgreaterequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4220 bool isless (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4221 bool islessequal(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4222 bool islessgreater(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4223 bool isunordered(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4224 4225These functions all behave exactly as their standard library C++11 counterparts do: their argument is either an instance of `number` or 4226an expression template derived from it; If the argument is of type `number<Backend, et_off>` then that is also the return type, 4227otherwise the return type is an expression template unless otherwise stated. 4228 4229The integer type arguments to `ldexp`, `frexp`, `scalbn` and `ilogb` may be either type `int`, or the actual 4230type of the exponent of the number type. 4231 4232Complex number types support the following functions: 4233 4234 // Complex number functions: 4235 ``['number<...>::value_type]`` real (const ``['number-or-expression-template-type]``&); 4236 ``['number<...>::value_type]`` imag (const ``['number-or-expression-template-type]``&); 4237 ``['number<...>::value_type]`` abs (const ``['number-or-expression-template-type]``&); 4238 ``['number<...>::value_type]`` arg (const ``['number-or-expression-template-type]``&); 4239 ``['number<...>::value_type]`` norm (const ``['number-or-expression-template-type]``&); 4240 ``['number]`` conj (const ``['number-or-expression-template-type]``&); 4241 ``['number]`` proj (const ``['number-or-expression-template-type]``&); 4242 ``['number]`` polar (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4243 4244In addition the functions `real`, `imag`, `arg`, `norm`, `conj` and `proj` are overloaded for scalar (ie non-complex) types in the same 4245manner as `<complex>` and treat the argument as a value whose imaginary part is zero. 4246 4247There are also some functions implemented for compatibility with the Boost.Math functions of the same name: 4248 4249 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&); 4250 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&); 4251 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&); 4252 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&); 4253 ``['number]`` changesign(const ``['number-or-expression-template-type]``&); 4254 ``['number]`` copysign(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 4255 4256All these functions are normally implemented by the Backend type. However, default versions are provided for Backend types that 4257don't have native support for these functions. Please note however, that this default support requires the precision of the type 4258to be a compile time constant - this means for example that the [gmp] MPF Backend will not work with these functions when that type is 4259used at variable precision. 4260 4261Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types (if any other types 4262such as fixed precision or complex types are added to the library later, then these functions may be extended to support those number types). 4263 4264The precision of these functions is generally determined by the backend implementation. For example the precision 4265of these functions when used with __mpfr_float_backend is determined entirely by [mpfr]. When these functions use our own 4266implementations, the accuracy of the transcendental functions is generally a few epsilon. Note however, that the trigonometrical 4267functions incur the usual accuracy loss when reducing arguments by large multiples of [pi]. Also note that both __mpf_float 4268and __cpp_dec_float have a number of guard digits beyond their stated precision, so the error rates listed for these 4269are in some sense artificially low. 4270 4271The following table shows the error rates we observe for these functions with various backend types, functions not listed 4272here are exact (tested on Win32 with VC++10, MPFR-3.0.0, MPIR-2.1.1): 4273 4274[table 4275[[Function][mpfr_float_50][mpf_float_50][cpp_dec_float_50]] 4276[[sqrt][1eps][0eps][0eps]] 4277[[exp][1eps][0eps][0eps]] 4278[[log][1eps][0eps][0eps]] 4279[[log10][1eps][0eps][0eps]] 4280[[cos][700eps][0eps][0eps]] 4281[[sin][1eps][0eps][0eps]] 4282[[tan][0eps][0eps][0eps]] 4283[[acos][0eps][0eps][0eps]] 4284[[asin][0eps][0eps][0eps]] 4285[[atan][1eps][0eps][0eps]] 4286[[cosh][1045eps[footnote It's likely that the inherent error in the input values to our test cases are to blame here.]][0eps][0eps]] 4287[[sinh][2eps][0eps][0eps]] 4288[[tanh][1eps][0eps][0eps]] 4289[[pow][0eps][4eps][3eps]] 4290[[atan2][1eps][0eps][0eps]] 4291] 4292[h4 Traits Class Support] 4293 4294 template <class T> 4295 struct component_type; 4296 4297If this is a type with multiple components (for example rational or complex types), then this trait has a single member 4298`type` that is the type of those components. 4299 4300 template <class T> 4301 struct number_category; 4302 4303A traits class that inherits from `mpl::int_<N>` where `N` is one of the enumerated values `number_kind_integer`, `number_kind_floating_point`, 4304`number_kind_rational`, `number_kind_fixed_point`, or `number_kind_unknown`. This traits class is specialized for any type that has 4305`std::numeric_limits` support as well as for classes in this library: which means it can be used for generic code that must work 4306with __fundamental arithmetic types as well as multiprecision ones. 4307 4308 template <class T> 4309 struct is_number; 4310 4311A traits class that inherits from `mpl::true_` if T is an instance of `number<>`, otherwise from `mpl::false_`. 4312 4313 template <class T> 4314 struct is_number_expression; 4315 4316A traits class that inherits from `mpl::true_` if T is an expression template type derived from `number<>`, otherwise from `mpl::false_`. 4317 4318 4319[h4 Integer functions] 4320 4321In addition to functioning with types from this library, these functions are also overloaded for __fundamental integer 4322types if you include `<boost/multiprecision/integer.hpp>`. Further, when used with fixed precision types (whether 4323__fundamental integers or multiprecision ones), the functions will promote to a wider type internally when the algorithm 4324requires it. Versions overloaded for __fundamental integer types return that integer type rather than an expression 4325template. 4326 4327 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 4328 4329Returns the largest integer `x` that divides both `a` and `b`. 4330 4331 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 4332 4333Returns the smallest integer `x` that is divisible by both `a` and `b`. 4334 4335 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``& b, unsigned p); 4336 4337Returns ['b[super p]] as an expression template. Note that this function should be used with extreme care as the result can grow so 4338large as to take "effectively forever" to compute, or else simply run the host machine out of memory. This is the one function in 4339this category that is not overloaded for __fundamental integer types, further, it's probably not a good idea to use it with 4340fixed precision `cpp_int`'s either. 4341 4342 ``['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); 4343 4344Returns ['b[super p] mod m] as an expression template. Fixed precision types are promoted internally to ensure accuracy. 4345 4346 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``& a); 4347 4348Returns the largest integer `x` such that `x * x < a`. 4349 4350 template <class Backend, expression_template_option ExpressionTemplates> 4351 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``& a, number<Backend, EXpressionTemplates>& r); 4352 4353Returns the largest integer `x` such that `x * x < a`, and sets the remainder `r` such that `r = a - x * x`. 4354 4355 template <class Backend, expression_template_option ExpressionTemplates> 4356 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y, 4357 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r); 4358 4359Divides x by y and returns both the quotient and remainder. After the call `q = x / y` and `r = x % y`. 4360 4361 template <class Integer> 4362 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val); 4363 4364Returns the absolute value of `x % val`. 4365 4366 unsigned lsb(const ``['number-or-expression-template-type]``& x); 4367 4368Returns the (zero-based) index of the least significant bit that is set to 1. 4369 4370Throws a `std::range_error` if the argument is <= 0. 4371 4372 unsigned msb(const ``['number-or-expression-template-type]``& x); 4373 4374Returns the (zero-based) index of the most significant bit. 4375 4376Throws a `std::range_error` if the argument is <= 0. 4377 4378 template <class Backend, class ExpressionTemplates> 4379 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index); 4380 4381Returns `true` if the bit at /index/ in /val/ is set. 4382 4383 template <class Backend, class ExpressionTemplates> 4384 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index); 4385 4386Sets the bit at /index/ in /val/, and returns /val/. 4387 4388 template <class Backend, class ExpressionTemplates> 4389 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index); 4390 4391Unsets the bit at /index/ in /val/, and returns /val/. 4392 4393 template <class Backend, class ExpressionTemplates> 4394 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index); 4395 4396Flips the bit at /index/ in /val/, and returns /val/. 4397 4398 template <class Engine> 4399 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen); 4400 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials); 4401 4402Tests to see if the number /n/ is probably prime - the test excludes the vast majority of composite numbers 4403by excluding small prime factors and performing a single Fermat test. Then performs /trials/ Miller-Rabin 4404tests. Returns `false` if /n/ is definitely composite, or `true` if /n/ is probably prime with the 4405probability of it being composite less than 0.25^trials. Fixed precision types are promoted internally 4406to ensure accuracy. 4407 4408[h4 Rational Number Functions] 4409 4410 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&); 4411 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&); 4412 4413These functions return the numerator and denominator of a rational number respectively. 4414 4415[h4 Boost.Math Interoperability Support] 4416 4417 namespace boost{ namespace math{ 4418 4419 int fpclassify (const ``['number-or-expression-template-type]``&, int); 4420 bool isfinite (const ``['number-or-expression-template-type]``&, int); 4421 bool isnan (const ``['number-or-expression-template-type]``&, int); 4422 bool isinf (const ``['number-or-expression-template-type]``&, int); 4423 bool isnormal (const ``['number-or-expression-template-type]``&, int); 4424 4425 }} // namespaces 4426 4427These floating-point classification functions behave exactly as their Boost.Math equivalents. 4428 4429Other Boost.Math functions and templates may also be 4430specialized or overloaded to ensure interoperability. 4431 4432[h4 std::numeric_limits support] 4433 4434 namespace std{ 4435 4436 template <class Backend, ExpressionTemplates> 4437 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 4438 { 4439 /* Usual members here */ 4440 }; 4441 4442 } 4443 4444Class template `std::numeric_limits` is specialized for all instantiations of `number` whose precision is known at compile time, plus those 4445types whose precision is unlimited (though it is much less useful in those cases). It is not specialized for types 4446whose precision can vary at compile time (such as `mpf_float`). 4447 4448[endsect] 4449 4450[section:cpp_int_ref cpp_int] 4451 4452 namespace boost{ namespace multiprecision{ 4453 4454 typedef unspecified-type limb_type; 4455 4456 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 4457 enum cpp_int_check_type { checked, unchecked }; 4458 4459 template <unsigned MinDigits = 0, 4460 unsigned MaxDits = 0, 4461 cpp_integer_type SignType = signed_magnitude, 4462 cpp_int_check_type Checked = unchecked, 4463 class Allocator = std::allocator<limb_type> > 4464 class cpp_int_backend; 4465 // 4466 // Expression templates default to et_off if there is no allocator: 4467 // 4468 template <unsigned MinDigits, unsigned MaxDigits, cpp_integer_type SignType, cpp_int_check_type Checked> 4469 struct expression_template_default<cpp_int_backend<MinDigits, MaxDigits, SignType, Checked, void> > 4470 { static const expression_template_option value = et_off; }; 4471 4472 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer 4473 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 4474 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number 4475 4476 // Fixed precision unsigned types: 4477 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t; 4478 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t; 4479 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t; 4480 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t; 4481 4482 // Fixed precision signed types: 4483 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t; 4484 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t; 4485 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t; 4486 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t; 4487 4488 // Over again, but with checking enabled this time: 4489 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int; 4490 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend; 4491 typedef number<checked_cpp_rational_backend> checked_cpp_rational; 4492 4493 // Checked fixed precision unsigned types: 4494 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t; 4495 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t; 4496 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t; 4497 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t; 4498 4499 // Fixed precision signed types: 4500 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t; 4501 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t; 4502 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t; 4503 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t; 4504 4505 }} // namespaces 4506 4507Class template `cpp_int_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4508Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4509to change. 4510 4511The template arguments are: 4512 4513[variablelist 4514[[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory 4515 allocation. When zero, this field is determined automatically based on how many bits can be stored 4516 in union with the dynamic storage header: setting a larger value may improve performance as larger integer 4517 values will be stored internally before memory allocation is required.]] 4518[[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type. 4519 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic 4520 memory allocation will ever be performed: in this situation the Allocator parameter should be set to 4521 type `void`. Note that this parameter should not be used simply to prevent large memory 4522 allocations, not only is that role better performed by the allocator, but fixed precision 4523 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]] 4524[[SignType][Determines whether the resulting type is signed or not. Note that for 4525[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types 4526 this parameter must be `signed_magnitude`. For fixed precision 4527 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]] 4528[[Checked][This parameter has two values: `checked` or `unchecked`. See the [link boost_multiprecision.tut.ints.cpp_int tutorial] for more information.]] 4529[[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]] 4530] 4531 4532The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4533 4534More information on this type can be found in the [link boost_multiprecision.tut.ints.cpp_int tutorial]. 4535 4536[endsect] 4537 4538[section:gmp_int_ref gmp_int] 4539 4540 namespace boost{ namespace multiprecision{ 4541 4542 class gmp_int; 4543 4544 typedef number<gmp_int > mpz_int; 4545 4546 }} // namespaces 4547 4548Class template `gmp_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4549Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4550to change. 4551 4552The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4553 4554More information on this type can be found in the [link boost_multiprecision.tut.ints.gmp_int tutorial]. 4555 4556[endsect] 4557 4558[section:tom_int_ref tom_int] 4559 4560 namespace boost{ namespace multiprecision{ 4561 4562 class tommath_int; 4563 4564 typedef number<tommath_int > tom_int; 4565 4566 }} // namespaces 4567 4568Class template `tommath_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4569Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4570to change. 4571 4572The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 4573 4574More information on this type can be found in the [link boost_multiprecision.tut.ints.tom_int tutorial]. 4575 4576[endsect] 4577 4578[section:mpf_ref gmp_float] 4579 4580 namespace boost{ namespace multiprecision{ 4581 4582 template <unsigned Digits10> 4583 class gmp_float; 4584 4585 typedef number<gmp_float<50> > mpf_float_50; 4586 typedef number<gmp_float<100> > mpf_float_100; 4587 typedef number<gmp_float<500> > mpf_float_500; 4588 typedef number<gmp_float<1000> > mpf_float_1000; 4589 typedef number<gmp_float<0> > mpf_float; 4590 4591 }} // namespaces 4592 4593Class template `gmp_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4594Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4595to change. 4596 4597The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 4598should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 4599and `number::precision`. Note that this type does not in any way change the GMP library's global state (for example 4600it does not change the default precision of the mpf_t data type), therefore you can safely mix this type with existing 4601code that uses GMP, and also mix `gmp_float`s of differing precision. 4602 4603The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4604 4605More information on this type can be found in the [link boost_multiprecision.tut.floats.gmp_float tutorial]. 4606 4607[endsect] 4608 4609[section:mpfr_ref mpfr_float_backend] 4610 4611 namespace boost{ namespace multiprecision{ 4612 4613 template <unsigned Digits10> 4614 class mpfr_float_backend; 4615 4616 typedef number<mpfr_float_backend<50> > mpfr_float_50; 4617 typedef number<mpfr_float_backend<100> > mpfr_float_100; 4618 typedef number<mpfr_float_backend<500> > mpfr_float_500; 4619 typedef number<mpfr_float_backend<1000> > mpfr_float_1000; 4620 typedef number<mpfr_float_backend<0> > mpfr_float; 4621 4622 }} // namespaces 4623 4624Class template `mpfr_float_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4625Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4626to change. 4627 4628The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 4629should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 4630and `number::precision`. Note that this type does not in any way change the GMP or MPFR library's global state (for example 4631it does not change the default precision of the mpfr_t data type), therefore you can safely mix this type with existing 4632code that uses GMP or MPFR, and also mix `mpfr_float_backend`s of differing precision. 4633 4634The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4635 4636More information on this type can be found in the [link boost_multiprecision.tut.floats.mpfr_float tutorial]. 4637 4638[endsect] 4639 4640[section:cpp_bin_float_ref cpp_bin_float] 4641 4642 namespace boost{ namespace multiprecision{ 4643 4644 enum digit_base_type 4645 { 4646 digit_base_2 = 2, 4647 digit_base_10 = 10 4648 }; 4649 4650 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0> 4651 class cpp_bin_float; 4652 4653 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 4654 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 4655 4656 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single; 4657 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double; 4658 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended; 4659 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad; 4660 typedef number<backends::cpp_bin_float<237, backends::digit_base_2, void, boost::int32_t, -262142, 262143>, et_off> cpp_bin_float_oct; 4661 4662 }} // namespaces 4663 4664Class template `cpp_bin_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4665Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4666to change. 4667 4668The class takes six template parameters: 4669 4670[variablelist 4671[[Digits][The number of digits precision the type 4672should support. This is normally expressed as base-10 digits, but that can be changed via the second template parameter.]] 4673[[base][An enumerated value (either `digit_base_10` or `digit_base_2`) that indicates whether `Digits` is base-10 or base-2]] 4674[[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic 4675allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]] 4676[[Exponent][A signed integer type to use as the type of the exponent - defaults to `int`.]] 4677[[ExponentMin][The smallest (most negative) permitted exponent, defaults to zero, meaning "define as small as possible 4678given the limitations of the type and our internal requirements".]] 4679[[ExponentMax][The largest (most positive) permitted exponent, defaults to zero, meaning "define as large as possible 4680given the limitations of the type and our internal requirements".]] 4681] 4682 4683The type of `number_category<cpp_bin_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4684 4685More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_bin_float tutorial]. 4686 4687[h4 Implementation Notes] 4688 4689Internally, an N-bit `cpp_bin_float` is represented as an N-bit unsigned integer along with an exponent and a sign. 4690The integer part is normalized so that its most significant bit is always 1. The decimal point is assumed to be 4691directly after the most significant bit of the integer part. The special values zero, infinity and NaN all have 4692the integer part set to zero, and the exponent to one of 3 special values above the maximum permitted exponent. 4693 4694Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain a 2N-bit number, then round and 4695adjust the sign and exponent. 4696 4697Addition and subtraction proceed similarly - if the exponents are such that there is overlap between the two 4698values, then left shift the larger value to produce a number with between N and 2N bits, then perform integer 4699addition or subtraction, round, and adjust the exponent. 4700 4701Division proceeds as follows: first scale the numerator by some power of 2 so that integer division will 4702produce either an N-bit or N+1 bit result plus a remainder. If we get an N bit result then the size of 4703twice the remainder compared to the denominator gives us the rounding direction. Otherwise we have one extra bit 4704in the result which we can use to determine rounding (in this case ties occur only if the remainder is zero and 4705the extra bit is a 1). 4706 4707Square root uses integer square root in a manner analogous to division. 4708 4709Decimal string to binary conversion proceeds as follows: first parse the digits to 4710produce an integer multiplied by a decimal exponent. Note that we stop parsing digits 4711once we have parsed as many as can possibly effect the result - this stops the integer 4712part growing too large when there are a very large number of input digits provided. 4713At this stage if the decimal exponent is positive then the result is an integer and we 4714can in principle simply multiply by 10^N to get an exact integer result. In practice 4715however, that could produce some very large integers. We also need to be able to divide 4716by 10^N in the event that the exponent is negative. Therefore calculation of the 10^N 4717values plus the multiplication or division are performed using limited precision 4718integer arithmetic, plus an exponent, and a track of the accumulated error. At the end of 4719the calculation we will either be able to round unambiguously, or the error will be such 4720that we can't tell which way to round. In the latter case we simply up the precision and try 4721again until we have an unambiguously rounded result. 4722 4723Binary to decimal conversion proceeds very similarly to the above, our aim is to calculate 4724`mantissa * 2^shift * 10^E` where `E` is the decimal exponent and `shift` is calculated 4725so that the result is an N bit integer assuming we want N digits printed in the result. 4726As before we use limited precision arithmetic to calculate the result and up the 4727precision as necessary until the result is unambiguously correctly rounded. In addition 4728our initial calculation of the decimal exponent may be out by 1, so we have to correct 4729that and loop as well in the that case. 4730 4731[endsect] 4732 4733[section:cpp_dec_ref cpp_dec_float] 4734 4735 namespace boost{ namespace multiprecision{ 4736 4737 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 4738 class cpp_dec_float; 4739 4740 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 4741 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 4742 4743 }} // namespaces 4744 4745Class template `cpp_dec_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 4746Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 4747to change. 4748 4749The class takes three template parameters: 4750 4751[variablelist 4752[[Digits10][The number of decimal digits precision the type 4753should support. Note that this type does not normally perform any dynamic memory allocation, and as a result the `Digits10` 4754template argument should not be set too high or the class's size will grow unreasonably large.]] 4755[[ExponentType][A signed integer type that represents the exponent of the number]] 4756[[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic 4757allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]] 4758] 4759 4760The type of `number_category<cpp_dec_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 4761 4762More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_dec_float tutorial]. 4763 4764[endsect] 4765 4766[section:internals Internal Support Code] 4767 4768There are some traits classes which authors of new backends should be aware of: 4769 4770 namespace boost{ namespace multiprecision{ namespace detail{ 4771 4772 template<typename From, typename To> 4773 struct is_explicitly_convertible; 4774 4775 }}} 4776 4777Inherits from `boost::integral_constant<bool,true>` if type `From` has an explicit conversion from `To`. 4778 4779For compilers that support C++11 SFINAE-expressions this trait should "just work". Otherwise it inherits 4780from `boost::is_convertible<From, To>::type`, and will need to be specialised for Backends that have 4781constructors marked as `explicit`. 4782 4783 template <class From, class To> 4784 struct is_lossy_conversion 4785 { 4786 static const bool value = see below; 4787 }; 4788 4789Member `value` is true if the conversion from `From` to `To` would result in a loss of precision, and `false` otherwise. 4790 4791The default version of this trait simply checks whether the ['kind] of conversion (for example from a floating-point to an integer type) 4792is inherently lossy. Note that if either of the types `From` or `To` are of an unknown number category (because `number_category` is not 4793specialised for that type) then this trait will be `true`. 4794 4795 template<typename From, typename To> 4796 struct is_restricted_conversion 4797 { 4798 static const bool value = see below; 4799 }; 4800 4801Member `value` is `true` if `From` is only explicitly convertible to `To` and not implicitly convertible, or 4802if `is_lossy_conversion<From, To>::value` is `true`. Otherwise `false`. 4803 4804Note that while this trait is the ultimate arbiter of which constructors are marked as `explicit` in class `number`, 4805authors of backend types should generally specialise one of the traits above, rather than this one directly. 4806 4807 template <class T> 4808 is_signed_number; 4809 template <class T> 4810 is_unsigned_number; 4811 4812These two traits inherit from either `mpl::true_` or `mpl::false_`, by default types are assumed to be signed unless 4813`is_unsigned_number` is specialized for that type. 4814 4815[endsect] 4816 4817[section:backendconc Backend Requirements] 4818 4819The requirements on the `Backend` template argument to `number` are split up into 4820sections: compulsory and optional. 4821 4822Compulsory requirements have no default implementation in the library, therefore if the feature 4823they implement is to be supported at all, then they must be implemented by the backend. 4824 4825Optional requirements have default implementations that are called if the backend doesn't provide 4826its own. Typically the backend will implement these to improve performance. 4827 4828In the following tables, type B is the `Backend` template argument to `number`, `b` and `b2` are 4829a variables of type B, `pb` is a variable of type B*, `cb`, `cb2` and `cb3` are constant variables of type `const B`, 4830`rb` is a variable of type `B&&`, `a` and `a2` are variables of Arithmetic type, 4831`s` is a variable of type `const char*`, `ui` is a variable of type `unsigned`, `bb` is a variable of type `bool`, 4832`pa` is a variable of type pointer-to-arithmetic-type, `exp` is a variable of type `B::exp_type`, 4833`pexp` is a variable of type `B::exp_type*`, `i` is a variable of type `int`, `pi` pointer to a variable of type `int`, 4834B2 is another type that meets these requirements, b2 is a variable of type B2, `ss` is variable of type `std::streamsize` 4835and `ff` is a variable of type `std::ios_base::fmtflags`. 4836 4837[table Compulsory Requirements on the Backend type. 4838[[Expression][Return Type][Comments][Throws]] 4839[[`B::signed_types`][`mpl::list<type-list>`][A list of signed integral types that can be assigned to type B. The types shall be 4840 listed in order of size, smallest first, and shall terminate in the type that is `std::intmax_t`.][[space]]] 4841[[`B::unsigned_types`][`mpl::list<type-list>`][A list of unsigned integral types that can be assigned to type B. The types shall be 4842 listed in order of size, smallest first, and shall terminate in the type that is `std::uintmax_t`.][[space]]] 4843[[`B::float_types`][`mpl::list<type-list>`][A list of floating-point types that can be assigned to type B.The types shall be 4844 listed in order of size, smallest first, and shall terminate in type `long double`.][[space]]] 4845[[`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]]] 4846[[`B()`][ ][Default constructor.][[space]]] 4847[[`B(cb)`][ ][Copy Constructor.][[space]]] 4848[[`b = b`][`B&`][Assignment operator.][[space]]] 4849[[`b = a`][`B&`][Assignment from an Arithmetic type. The type of `a` shall be listed in one of the type lists 4850 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 4851[[`b = s`][`B&`][Assignment from a string.][Throws a `std::runtime_error` if the string could not be interpreted as a valid number.]] 4852[[`b.swap(b)`][`void`][Swaps the contents of its arguments.][`noexcept`]] 4853[[`cb.str(ss, ff)`][`std::string`][Returns the string representation of `b` with `ss` digits and formatted according to the flags set in `ff`. 4854 If `ss` is zero, then returns as many digits as are required to reconstruct the original value.][[space]]] 4855[[`b.negate()`][`void`][Negates `b`.][[space]]] 4856[[`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 4857 if `cb == cb2`.][`noexcept`]] 4858[[`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 4859 if `cb == a`. The type of `a` shall be listed in one of the type lists 4860 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 4861[[`eval_add(b, cb)`][`void`][Adds `cb` to `b`.][[space]]] 4862[[`eval_subtract(b, cb)`][`void`][Subtracts `cb` from `b`.][[space]]] 4863[[`eval_multiply(b, cb)`][`void`][Multiplies `b` by `cb`.][[space]]] 4864[[`eval_divide(b, cb)`][`void`][Divides `b` by `cb`.] 4865 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 4866[[`eval_modulus(b, cb)`][`void`][Computes `b %= cb`, only required when `B` is an integer type.] 4867 [`std::overflow_error` if cb has the value zero.]] 4868[[`eval_bitwise_and(b, cb)`][`void`][Computes `b &= cb`, only required when `B` is an integer type.][[space]]] 4869[[`eval_bitwise_or(b, cb)`][`void`][Computes `b |= cb`, only required when `B` is an integer type.][[space]]] 4870[[`eval_bitwise_xor(b, cb)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type.][[space]]] 4871[[`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]]] 4872[[`eval_left_shift(b, ui)`][`void`][Computes `b <<= ui`, only required when `B` is an integer type.][[space]]] 4873[[`eval_right_shift(b, ui)`][`void`][Computes `b >>= ui`, only required when `B` is an integer type.][[space]]] 4874[[`eval_convert_to(pa, cb)`][`void`][Converts `cb` to the type of `*pa` and store the result in `*pa`. Type `B` shall support 4875 conversion to at least types `std::intmax_t`, `std::uintmax_t` and `long long`. 4876 Conversion to other arithmetic types can then be synthesised using other operations. 4877 Conversions to other types are entirely optional.][[space]]] 4878[[`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]]] 4879[[`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]]] 4880[[`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.] 4881 [`std::runtime_error` if the exponent of cb is too large to be stored in an `int`.]] 4882[[`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]]] 4883[[`eval_floor(b, cb)`][`void`][Stores the floor of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 4884[[`eval_ceil(b, cb)`][`void`][Stores the ceiling of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 4885[[`eval_sqrt(b, cb)`][`void`][Stores the square root of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 4886[[`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`. 4887 Defaults to `number_kind_floating_point`.][[space]]] 4888[[`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]]] 4889[[`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]]] 4890[[`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]]] 4891[[`eval_imag(b, cb)`][`void`][Sets `b` to the imaginary of `cb`. Required for complex types only - other types have a sensible default.][[space]]] 4892[[`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]]] 4893[[`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]]] 4894] 4895 4896[table Optional Requirements on the Backend Type 4897[[Expression][Returns][Comments][Throws]] 4898 4899[[['Construct and assign:]]] 4900[[`B(rb)`][`B`][Move constructor. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 4901 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 4902[[`b = rb`][`B&`][Move-assign. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 4903 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 4904[[`B(a)`][`B`][Direct construction from an arithmetic type. The type of `a` shall be listed in one of the type lists 4905 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4906 When not provided, this operation is simulated using default-construction followed by assignment.][[space]]] 4907[[`B(b2)`][`B`][Copy constructor from a different back-end type. When not provided, a generic interconversion routine is used. 4908 This constructor may be `explicit` if the corresponding frontend constructor should also be `explicit`.][[space]]] 4909[[`b = b2`][`b&`][Assignment operator from a different back-end type. When not provided, a generic interconversion routine is used.][[space]]] 4910[[`assign_components(b, a, a)`][`void`][Assigns to `b` the two components in the following arguments. 4911 Only applies to rational and complex number types. 4912 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 4913[[`assign_components(b, b2, b2)`][`void`][Assigns to `b` the two components in the following arguments. 4914 Only applies to rational and complex number types. 4915 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 4916 4917[[['Comparisons:]]] 4918[[`eval_eq(cb, cb2)`][`bool`][Returns `true` if `cb` and `cb2` are equal in value. 4919 When not provided, the default implementation returns `cb.compare(cb2) == 0`.][`noexcept`]] 4920[[`eval_eq(cb, a)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 4921 The type of `a` shall be listed in one of the type lists 4922 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4923 When not provided, return the equivalent of `eval_eq(cb, B(a))`.][[space]]] 4924[[`eval_eq(a, cb)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 4925 The type of `a` shall be listed in one of the type lists 4926 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4927 When not provided, the default version returns `eval_eq(cb, a)`.][[space]]] 4928[[`eval_lt(cb, cb2)`][`bool`][Returns `true` if `cb` is less than `cb2` in value. 4929 When not provided, the default implementation returns `cb.compare(cb2) < 0`.][`noexcept`]] 4930[[`eval_lt(cb, a)`][`bool`][Returns `true` if `cb` is less than `a` in value. 4931 The type of `a` shall be listed in one of the type lists 4932 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4933 When not provided, the default implementation returns `eval_lt(cb, B(a))`.][[space]]] 4934[[`eval_lt(a, cb)`][`bool`][Returns `true` if `a` is less than `cb` in value. 4935 The type of `a` shall be listed in one of the type lists 4936 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4937 When not provided, the default implementation returns `eval_gt(cb, a)`.][[space]]] 4938[[`eval_gt(cb, cb2)`][`bool`][Returns `true` if `cb` is greater than `cb2` in value. 4939 When not provided, the default implementation returns `cb.compare(cb2) > 0`.][`noexcept`]] 4940[[`eval_gt(cb, a)`][`bool`][Returns `true` if `cb` is greater than `a` in value. 4941 The type of `a` shall be listed in one of the type lists 4942 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4943 When not provided, the default implementation returns `eval_gt(cb, B(a))`.][[space]]] 4944[[`eval_gt(a, cb)`][`bool`][Returns `true` if `a` is greater than `cb` in value. 4945 The type of `a` shall be listed in one of the type lists 4946 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4947 When not provided, the default implementation returns `eval_lt(cb, a)`.][[space]]] 4948[[`eval_is_zero(cb)`][`bool`][Returns `true` if `cb` is zero, otherwise `false`. The default version of this function 4949 returns `cb.compare(ui_type(0)) == 0`, where `ui_type` is `ui_type` is 4950 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4951[[`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. 4952 The default version of this function 4953 returns `cb.compare(ui_type(0))`, where `ui_type` is `ui_type` is 4954 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4955 4956[[['Basic arithmetic:]]] 4957[[`eval_add(b, a)`][`void`][Adds `a` to `b`. The type of `a` shall be listed in one of the type lists 4958 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4959 When not provided, the default version calls `eval_add(b, B(a))`][[space]]] 4960[[`eval_add(b, cb, cb2)`][`void`][Add `cb` to `cb2` and stores the result in `b`. 4961 When not provided, does the equivalent of `b = cb; eval_add(b, cb2)`.][[space]]] 4962[[`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 4963 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4964 When not provided, does the equivalent of `eval_add(b, cb, B(a))`.][[space]]] 4965[[`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 4966 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4967 When not provided, does the equivalent of `eval_add(b, cb, a)`.][[space]]] 4968[[`eval_subtract(b, a)`][`void`][Subtracts `a` from `b`. The type of `a` shall be listed in one of the type lists 4969 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4970 When not provided, the default version calls `eval_subtract(b, B(a))`][[space]]] 4971[[`eval_subtract(b, cb, cb2)`][`void`][Subtracts `cb2` from `cb` and stores the result in `b`. 4972 When not provided, does the equivalent of `b = cb; eval_subtract(b, cb2)`.][[space]]] 4973[[`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 4974 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4975 When not provided, does the equivalent of `eval_subtract(b, cb, B(a))`.][[space]]] 4976[[`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 4977 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4978 When not provided, does the equivalent of `eval_subtract(b, cb, a); b.negate();`.][[space]]] 4979[[`eval_multiply(b, a)`][`void`][Multiplies `b` by `a`. The type of `a` shall be listed in one of the type lists 4980 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4981 When not provided, the default version calls `eval_multiply(b, B(a))`][[space]]] 4982[[`eval_multiply(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and stores the result in `b`. 4983 When not provided, does the equivalent of `b = cb; eval_multiply(b, cb2)`.][[space]]] 4984[[`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 4985 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4986 When not provided, does the equivalent of `eval_multiply(b, cb, B(a))`.][[space]]] 4987[[`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 4988 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4989 When not provided, does the equivalent of `eval_multiply(b, cb, a)`.][[space]]] 4990[[`eval_multiply_add(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and adds the result to `b`. 4991 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 4992 `eval_add(b, t)`.][[space]]] 4993[[`eval_multiply_add(b, cb, a)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 4994 The type of `a` shall be listed in one of the type lists 4995 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4996 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 4997 `eval_add(b, t)`.][[space]]] 4998[[`eval_multiply_add(b, a, cb)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 4999 The type of `a` shall be listed in one of the type lists 5000 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5001 When not provided does the equivalent of `eval_multiply_add(b, cb, a)`.][[space]]] 5002[[`eval_multiply_subtract(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and subtracts the result from `b`. 5003 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 5004 `eval_subtract(b, t)`.][[space]]] 5005[[`eval_multiply_subtract(b, cb, a)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 5006 The type of `a` shall be listed in one of the type lists 5007 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5008 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 5009 `eval_subtract(b, t)`.][[space]]] 5010[[`eval_multiply_subtract(b, a, cb)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 5011 The type of `a` shall be listed in one of the type lists 5012 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5013 When not provided does the equivalent of `eval_multiply_subtract(b, cb, a)`.][[space]]] 5014[[`eval_multiply_add(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and adds the result to `cb3` storing the result in `b`. 5015 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 5016 `eval_add(b, cb3)`. 5017 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 5018 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 5019 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 5020[[`eval_multiply_subtract(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and subtracts from the result `cb3` storing the result in `b`. 5021 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 5022 `eval_subtract(b, cb3)`. 5023 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 5024 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 5025 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 5026[[`eval_divide(b, a)`][`void`][Divides `b` by `a`. The type of `a` shall be listed in one of the type lists 5027 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5028 When not provided, the default version calls `eval_divide(b, B(a))`] 5029 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 5030[[`eval_divide(b, cb, cb2)`][`void`][Divides `cb` by `cb2` and stores the result in `b`. 5031 When not provided, does the equivalent of `b = cb; eval_divide(b, cb2)`.] 5032 [`std::overflow_error` if `cb2` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 5033[[`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 5034 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5035 When not provided, does the equivalent of `eval_divide(b, cb, B(a))`.] 5036 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 5037[[`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 5038 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5039 When not provided, does the equivalent of `eval_divide(b, B(a), cb)`.] 5040 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 5041[[`eval_increment(b)`][void][Increments the value of `b` by one. 5042 When not provided, does the equivalent of `eval_add(b, static_cast<ui_type>(1u))`. 5043 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 5044[[`eval_decrement(b)`][void][Decrements the value of `b` by one. 5045 When not provided, does the equivalent of `eval_subtract(b, static_cast<ui_type>(1u))`. 5046 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 5047 5048[[['Integer specific operations:]]] 5049[[`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 5050 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5051 When not provided, the default version calls `eval_modulus(b, B(a))`] 5052 [`std::overflow_error` if `a` has the value zero.]] 5053[[`eval_modulus(b, cb, cb2)`][`void`][Computes `cb % cb2` and stores the result in `b`, only required when `B` is an integer type. 5054 When not provided, does the equivalent of `b = cb; eval_modulus(b, cb2)`.] 5055 [`std::overflow_error` if `a` has the value zero.]] 5056[[`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 5057 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5058 When not provided, does the equivalent of `eval_modulus(b, cb, B(a))`.] 5059 [`std::overflow_error` if `a` has the value zero.]] 5060[[`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 5061 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5062 When not provided, does the equivalent of `eval_modulus(b, B(a), cb)`.] 5063 [`std::overflow_error` if `a` has the value zero.]] 5064[[`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 5065 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5066 When not provided, the default version calls `eval_bitwise_and(b, B(a))`][[space]]] 5067[[`eval_bitwise_and(b, cb, cb2)`][`void`][Computes `cb & cb2` and stores the result in `b`, only required when `B` is an integer type. 5068 When not provided, does the equivalent of `b = cb; eval_bitwise_and(b, cb2)`.][[space]]] 5069[[`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 5070 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5071 When not provided, does the equivalent of `eval_bitwise_and(b, cb, B(a))`.][[space]]] 5072[[`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 5073 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5074 When not provided, does the equivalent of `eval_bitwise_and(b, cb, a)`.][[space]]] 5075[[`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 5076 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5077 When not provided, the default version calls `eval_bitwise_or(b, B(a))`][[space]]] 5078[[`eval_bitwise_or(b, cb, cb2)`][`void`][Computes `cb | cb2` and stores the result in `b`, only required when `B` is an integer type. 5079 When not provided, does the equivalent of `b = cb; eval_bitwise_or(b, cb2)`.][[space]]] 5080[[`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 5081 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5082 When not provided, does the equivalent of `eval_bitwise_or(b, cb, B(a))`.][[space]]] 5083[[`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 5084 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5085 When not provided, does the equivalent of `eval_bitwise_or(b, cb, a)`.][[space]]] 5086[[`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 5087 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5088 When not provided, the default version calls `eval_bitwise_xor(b, B(a))`][[space]]] 5089[[`eval_bitwise_xor(b, cb, cb2)`][`void`][Computes `cb ^ cb2` and stores the result in `b`, only required when `B` is an integer type. 5090 When not provided, does the equivalent of `b = cb; eval_bitwise_xor(b, cb2)`.][[space]]] 5091[[`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 5092 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5093 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, B(a))`.][[space]]] 5094[[`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 5095 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5096 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, a)`.][[space]]] 5097[[`eval_left_shift(b, cb, ui)`][`void`][Computes `cb << ui` and stores the result in `b`, only required when `B` is an integer type. 5098 When not provided, does the equivalent of `b = cb; eval_left_shift(b, a);`.][[space]]] 5099[[`eval_right_shift(b, cb, ui)`][`void`][Computes `cb >> ui` and stores the result in `b`, only required when `B` is an integer type. 5100 When not provided, does the equivalent of `b = cb; eval_right_shift(b, a);`.][[space]]] 5101[[`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. 5102 The default version of this function is synthesised from other operations above.] 5103 [`std::overflow_error` if `a` has the value zero.]] 5104[[`eval_integer_modulus(cb, ui)`][`unsigned`][Returns the result of `cb % ui`. Only required when `B` is an integer type. 5105 The default version of this function is synthesised from other operations above.] 5106 [`std::overflow_error` if `a` has the value zero.]] 5107[[`eval_lsb(cb)`][`unsigned`][Returns the index of the least significant bit that is set. Only required when `B` is an integer type. 5108 The default version of this function is synthesised from other operations above.][[space]]] 5109[[`eval_msb(cb)`][`unsigned`][Returns the index of the most significant bit that is set. Only required when `B` is an integer type. 5110 The default version of this function is synthesised from other operations above.][[space]]] 5111[[`eval_bit_test(cb, ui)`][`bool`][Returns true if `cb` has bit `ui` set. Only required when `B` is an integer type. 5112 The default version of this function is synthesised from other operations above.][[space]]] 5113[[`eval_bit_set(b, ui)`][`void`][Sets the bit at index `ui` in `b`. Only required when `B` is an integer type. 5114 The default version of this function is synthesised from other operations above.][[space]]] 5115[[`eval_bit_unset(b, ui)`][`void`][Unsets the bit at index `ui` in `b`. Only required when `B` is an integer type. 5116 The default version of this function is synthesised from other operations above.][[space]]] 5117[[`eval_bit_flip(b, ui)`][`void`][Flips the bit at index `ui` in `b`. Only required when `B` is an integer type. 5118 The default version of this function is synthesised from other operations above.][[space]]] 5119[[`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. 5120 The default version of this function is synthesised from other operations above.][[space]]] 5121[[`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. 5122 The default version of this function is synthesised from other operations above.][[space]]] 5123[[`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. 5124 The type of `a` shall be listed in one of the type lists 5125 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5126 The default version of this function calls `eval_gcd(b, cb, B(a))`.][[space]]] 5127[[`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. 5128 The type of `a` shall be listed in one of the type lists 5129 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5130 The default version of this function calls `eval_lcm(b, cb, B(a))`.][[space]]] 5131[[`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. 5132 The type of `a` shall be listed in one of the type lists 5133 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5134 The default version of this function calls `eval_gcd(b, cb, a)`.][[space]]] 5135[[`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. 5136 The type of `a` shall be listed in one of the type lists 5137 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 5138 The default version of this function calls `eval_lcm(b, cb, a)`.][[space]]] 5139[[`eval_powm(b, cb, cb2, cb3)`][`void`][Sets `b` to the result of ['(cb^cb2)%cb3]. 5140 The default version of this function is synthesised from other operations above.][[space]]] 5141[[`eval_powm(b, cb, cb2, a)`][`void`][Sets `b` to the result of ['(cb^cb2)%a]. 5142 The type of `a` shall be listed in one of the type lists 5143 `B::signed_types`, `B::unsigned_types`. 5144 The default version of this function is synthesised from other operations above.][[space]]] 5145[[`eval_powm(b, cb, a, cb2)`][`void`][Sets `b` to the result of ['(cb^a)%cb2]. 5146 The type of `a` shall be listed in one of the type lists 5147 `B::signed_types`, `B::unsigned_types`. 5148 The default version of this function is synthesised from other operations above.][[space]]] 5149[[`eval_powm(b, cb, a, a2)`][`void`][Sets `b` to the result of ['(cb^a)%a2]. 5150 The type of `a` shall be listed in one of the type lists 5151 `B::signed_types`, `B::unsigned_types`. 5152 The default version of this function is synthesised from other operations above.][[space]]] 5153[[`eval_integer_sqrt(b, cb, b2)`][`void`][Sets `b` to the largest integer which when squared is less than `cb`, also 5154 sets `b2` to the remainder, ie to ['cb - b[super 2]]. 5155 The default version of this function is synthesised from other operations above.][[space]]] 5156 5157[[['Sign manipulation:]]] 5158[[`eval_abs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 5159 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 5160 `eval_get_sign(cb) < 0`.][[space]]] 5161[[`eval_fabs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 5162 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 5163 `eval_get_sign(cb) < 0`.][[space]]] 5164 5165[[['floating-point functions:]]] 5166[[`eval_fpclassify(cb)`][`int`][Returns one of the same values returned by `std::fpclassify`. Only required when `B` is an floating-point type. 5167 The default version of this function will only test for zero `cb`.][[space]]] 5168[[`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. 5169 The default version of this function is synthesised from other operations above.][[space]]] 5170[[`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. 5171 The default version of this function is synthesised from other operations above.][[space]]] 5172[[`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. 5173 The default version of this function is synthesised from other operations above.][[space]]] 5174[[`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. 5175 The default version of this function is implemented in terms of `eval_pow`.][[space]]] 5176[[`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. 5177 The default version of this function is synthesised from other operations above.][[space]]] 5178[[`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. 5179 The default version of this function is synthesised from other operations above.][[space]]] 5180[[`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. 5181 The default version of this function is synthesised from other operations above.][[space]]] 5182[[`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. 5183 The default version of this function is synthesised from other operations above.][[space]]] 5184[[`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. 5185 The default version of this function is synthesised from other operations above.][[space]]] 5186[[`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. 5187 The default version of this function is synthesised from other operations above.][[space]]] 5188[[`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. 5189 The default version of this function is synthesised from other operations above.][[space]]] 5190[[`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. 5191 The default version of this function is synthesised from other operations above.][[space]]] 5192[[`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. 5193 The default version of this function is synthesised from other operations above.][[space]]] 5194[[`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. 5195 The default version of this function is synthesised from other operations above.][[space]]] 5196[[`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. 5197 The default version of this function is synthesised from other operations above.][[space]]] 5198[[`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. 5199 The default version of this function is synthesised from other operations above.][[space]]] 5200[[`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`. 5201 Only required when `B` is an floating-point type. 5202 The default version of this function is synthesised from other operations above.][[space]]] 5203[[`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. 5204 The default version of this function is synthesised from other operations above.][[space]]] 5205[[`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. 5206 The default version of this function is synthesised from other operations above.][[space]]] 5207[[`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 5208 is implemented in terms of eval_ldexp, consequently this function must be provided for types with a radix other than 2.]] 5209[[`eval_scalbln(b, cb, e)`][`void`][Calls `eval_scalbn(b, cb, e)`.]] 5210[[`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. 5211 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.]] 5212[[`eval_remquo(b, cb, cb2, pi)`][`void`][Sets `b = cb - n * cb2` and stores `n` in `*pi`.]] 5213[[`eval_remquo(b, cb, a, pi)`][`void`][Default version converts a to type B and calls the overload above.]] 5214[[`eval_remquo(b, a, cb, pi)`][`void`][Default version converts a to type B and calls the overload above.]] 5215[[`eval_remainder(b, cb, cb2)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 5216[[`eval_remainder(b, cb, a)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 5217[[`eval_remainder(b, a, cb)`][`void`][Default version calls eval_remquo with a dummy final argument.]] 5218 5219[[`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.]] 5220[[`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.]] 5221[[`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.]] 5222 5223[[`eval_fmax(b, cb, cb2)`][`void`][Sets `b` to the larger of `cb` and `cb2`.]] 5224[[`eval_fmax(b, cb, a)`][`void`][Sets `b` to the larger of `cb` and `a`.]] 5225[[`eval_fmax(b, a, cb)`][`void`][Sets `b` to the larger of `cb` and `a`.]] 5226[[`eval_fmin(b, cb, cb2)`][`void`][Sets `b` to the smaller of `cb` and `cb2`.]] 5227[[`eval_fmin(b, cb, a)`][`void`][Sets `b` to the smaller of `cb` and `a`.]] 5228[[`eval_fmin(b, a, cb)`][`void`][Sets `b` to the smaller of `cb` and `a`.]] 5229 5230[[`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.]] 5231[[`eval_hypot(b, cb, a)`][`void`][As above.]] 5232[[`eval_hypot(b, a, cb)`][`void`][As above.]] 5233 5234[[`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. 5235 The default version of this function is implemented in terms of `eval_ilogb`.]] 5236[[`eval_nearbyint(b, cb)`][`void`][Calls `eval_round(b, cb)`.]] 5237[[`eval_rint(b, cb)`][`void`][Calls `eval_nearbyint(b, cb)`.]] 5238[[`eval_log2(b, cb)`][`void`][Sets `b` to the logarithm base 2 of `cb`.]] 5239 5240[[['hashing:]]] 5241[[`hash_value(cb)`][`std::size_t`] 5242 [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.]] 5243] 5244 5245When the tables above place no ['throws] requirements on an operation, then it is up to each type modelling this concept to 5246decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or 5247inherit from the type `std::runtime_error`. For example, a floating-point type might choose to throw `std::overflow_error` 5248whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero. 5249 5250[note 5251The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name - 5252in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.] 5253 5254[h4 Overloadable Functions] 5255 5256Some of the C99 math functions do not have `eval_` functions but must be overloaded directly: these functions 5257are either trivial or are forwarded to the Boost.Math implementations by default. 5258The full list of these functions is: 5259 5260 int sign (const ``['number-or-expression-template-type]``&); 5261 int signbit (const ``['number-or-expression-template-type]``&); 5262 ``['number]`` changesign (const ``['number-or-expression-template-type]``&); 5263 ``['number]`` copysign (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 5264 ``['number]`` asinh (const ``['number-or-expression-template-type]``&); 5265 ``['number]`` acosh (const ``['number-or-expression-template-type]``&); 5266 ``['number]`` atanh (const ``['number-or-expression-template-type]``&); 5267 ``['number]`` cbrt (const ``['number-or-expression-template-type]``&); 5268 ``['number]`` erf (const ``['number-or-expression-template-type]``&); 5269 ``['number]`` erfc (const ``['number-or-expression-template-type]``&); 5270 ``['number]`` expm1 (const ``['number-or-expression-template-type]``&); 5271 ``['number]`` log1p (const ``['number-or-expression-template-type]``&); 5272 ``['number]`` tgamma (const ``['number-or-expression-template-type]``&); 5273 ``['number]`` lgamma (const ``['number-or-expression-template-type]``&); 5274 long lrint (const ``['number-or-expression-template-type]``&); 5275 long long llrint (const ``['number-or-expression-template-type]``&); 5276 ``['number]`` nextafter (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 5277 ``['number]`` nexttoward (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 5278 5279[endsect] 5280 5281[section:headers Header File Structure] 5282 5283[table Top level headers 5284[[Header][Contains]] 5285[[cpp_int.hpp][The `cpp_int` backend type.]] 5286[[gmp.hpp][Defines all [gmp] related backends.]] 5287[[miller_rabin.hpp][Miller Rabin primality testing code.]] 5288[[number.hpp][Defines the `number` backend, is included by all the backend headers.]] 5289[[mpfr.hpp][Defines the mpfr_float_backend backend.]] 5290[[random.hpp][Defines code to interoperate with Boost.Random.]] 5291[[rational_adaptor.hpp][Defines the `rational_adaptor` backend.]] 5292[[cpp_dec_float.hpp][Defines the `cpp_dec_float` backend.]] 5293[[tommath.hpp][Defines the `tommath_int` backend.]] 5294[[concepts/number_archetypes.hpp][Defines a backend concept archetypes for testing use.]] 5295] 5296 5297[table Implementation Headers 5298[[Header][Contains]] 5299[[cpp_int/add.hpp][Add and subtract operators for `cpp_int_backend`.]] 5300[[cpp_int/bitwise.hpp][Bitwise operators for `cpp_int_backend`.]] 5301[[cpp_int/checked.hpp][Helper functions for checked arithmetic for `cpp_int_backend`.]] 5302[[cpp_int/comparison.hpp][Comparison operators for `cpp_int_backend`.]] 5303[[cpp_int/cpp_int_config.hpp][Basic setup and configuration for `cpp_int_backend`.]] 5304[[cpp_int/divide.hpp][Division and modulus operators for `cpp_int_backend`.]] 5305[[cpp_int/limits.hpp][`numeric_limits` support for `cpp_int_backend`.]] 5306[[cpp_int/misc.hpp][Miscellaneous operators for `cpp_int_backend`.]] 5307[[cpp_int/multiply.hpp][Multiply operators for `cpp_int_backend`.]] 5308[[detail/big_lanczos.hpp][Lanczos support for Boost.Math integration.]] 5309[[detail/default_ops.hpp][Default versions of the optional backend non-member functions.]] 5310[[detail/generic_interconvert.hpp][Generic interconversion routines.]] 5311[[detail/number_base.hpp][All the expression template code, metaprogramming, and operator overloads for `number`.]] 5312[[detail/no_et_ops.hpp][The non-expression template operators.]] 5313[[detail/functions/constants.hpp][Defines constants used by the floating-point functions.]] 5314[[detail/functions/pow.hpp][Defines default versions of the power and exponential related floating-point functions.]] 5315[[detail/functions/trig.hpp][Defines default versions of the trigonometric related floating-point functions.]] 5316] 5317 5318[endsect] 5319 5320[endsect] 5321 5322[section:perf Performance Comparison] 5323 5324[section:overhead The Overhead in the Number Class Wrapper] 5325 5326Using a simple [@../../performance/arithmetic_backend.hpp backend class] that wraps any __fundamental arithmetic type 5327we can measure the overhead involved in wrapping a type inside the `number` frontend, and the effect that turning 5328on expression templates has. The following table compares the performance between `double` and a `double` wrapped 5329inside class `number`: 5330 5331[table Bessel Functions (16 digit precision) 5332[[Type][Time]] 5333[[arithmetic_backend<double>][2.09301 (0.00133409s)]] 5334[[arithmetic_backend<double> - no expression templates][1 (0.000637403s)]] 5335[[double][1.07956 (0.000688113s)]] 5336] 5337 5338As you can see whether or not there is an overhead, and how large it is depends on the actual situation, 5339but the overhead is in any cases small. Expression templates generally add a greater overhead the 5340more complex the expression becomes due to the logic of figuring out how to best unpack and evaluate 5341the expression, but of course this is also the situation where you save more temporaries. For a 5342"trivial" backend like this, saving temporaries has no benefit, but for larger types it becomes 5343a bigger win. 5344 5345The following table compares arithmetic using either `long long` or `number<arithmetic_backend<long long> >` 5346for the [@../../performance/voronoi_performance.cpp voronoi-diagram builder test]: 5347 5348[table 5349[[Type][Relative time]] 5350[[`int64_t`][[*1.0](0.0128646s)]] 5351[[`number<arithmetic_backend<int64_t>, et_off>`][1.005 (0.0129255s)]] 5352] 5353 5354This test involves mainly creating a lot of temporaries and performing a small amount of arithmetic on them, 5355with very little difference in performance between the native and "wrapped" types. 5356 5357[table:platform Platform Details 5358[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5359[[Compiler][GNU C++ version 9.2.1 20191008]] 5360[[Boost][1.72.0]] 5361[[Run date][Dec 13 2019]] 5362] 5363 5364[endsect] 5365 5366[section:realworld Floating-Point Real World Tests] 5367 5368These tests test the total time taken to execute all of Boost.Math's test cases for these functions. 5369In each case the best performing library gets a relative score of 1, with the total execution time 5370given in brackets. Times are shown for both single threaded runs and concurrent execution - the latter 5371increases contension inside new/delete. 5372 5373[table Bessel Functions (50 digit precision) 5374[[Type][Time][\# Allocations]] 5375[[cpp_bin_float_50][2.20534 (0.315701s)][4]] 5376[[cpp_bin_float_50 (3 concurrent threads)][2.36703 (0.338848s)][44]] 5377[[cpp_dec_float_50][2.6349 (0.377193s)][3]] 5378[[cpp_dec_float_50 (3 concurrent threads)][2.86599 (0.410275s)][37]] 5379[[mpf_float_50][1.17269 (0.167874s)][870726]] 5380[[mpf_float_50 (3 concurrent threads)][1.43643 (0.205629s)][3482853]] 5381[[mpf_float_50 (no expression templates][1.19799 (0.171495s)][1071229]] 5382[[mpf_float_50 (no expression templates (3 concurrent threads)][1.57224 (0.22507s)][4284875]] 5383[[mpfr_float_50][1.42535 (0.204043s)][813605]] 5384[[mpfr_float_50 (3 concurrent threads)][1.66446 (0.238272s)][3255603]] 5385[[mpfr_float_50 (no expression templates][1.51042 (0.216221s)][1001796]] 5386[[mpfr_float_50 (no expression templates (3 concurrent threads)][1.86742 (0.267326s)][4008535]] 5387[[static_mpfr_float_50][1.02344 (0.146508s)][18685]] 5388[[static_mpfr_float_50 (3 concurrent threads)][1.25745 (0.180008s)][75947]] 5389[[static_mpfr_float_50 (no expression templates)][1 (0.143153s)][46826]] 5390[[static_mpfr_float_50 (no expression templates) (3 concurrent threads)][1.12861 (0.161564s)][189192]] 5391] 5392 5393[table Non-central T Distribution (50 digit precision) 5394[[Type][Time][\# Allocations]] 5395[[cpp_bin_float_50][2.3739 (59.0179s)][1]] 5396[[cpp_bin_float_50 (3 concurrent threads)][3.21496 (79.9276s)][29]] 5397[[cpp_dec_float_50][2.47505 (61.5326s)][4]] 5398[[mpf_float_50][1.13495 (28.2162s)][162346817]] 5399[[mpf_float_50 (no expression templates][1 (24.8611s)][154896018]] 5400[[mpfr_float_50][1.84473 (45.8621s)][196986977]] 5401[[mpfr_float_50 (no expression templates][1.66952 (41.5062s)][194554719]] 5402[[static_mpfr_float_50][1.25101 (31.1014s)][1798554]] 5403] 5404 5405[table:platform Platform Details 5406[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5407[[Compiler][GNU C++ version 9.2.1 20191008]] 5408[[GMP][6.1.2]] 5409[[MPFR][262146]] 5410[[Boost][107200]] 5411[[Run date][Dec 13 2019]] 5412] 5413 5414[endsect] 5415 5416[section:int_real_world Integer Real World Tests] 5417 5418The first set of [@../../performance/voronoi_performance.cpp tests] measure the times taken to 5419execute the multiprecision part of the Voronoi-diagram builder from Boost.Polygon. The tests 5420mainly create a large number of temporaries "just in case" multiprecision arithmetic is required, 5421for comparison, also included in the tests is Boost.Polygon's own partial-multiprecision integer 5422type which was custom written for this specific task: 5423 5424[table 5425[[Integer Type][Relative Performance (Actual time in parenthesis)]] 5426[[checked_int1024_t][1.53714(0.0415328s)]] 5427[[checked_int256_t][1.20715(0.0326167s)]] 5428[[checked_int512_t][1.2587(0.0340095s)]] 5429[[cpp_int][1.80575(0.0487904s)]] 5430[[extended_int][1.35652(0.0366527s)]] 5431[[int1024_t][1.36237(0.0368107s)]] 5432[[int256_t][1(0.0270196s)]] 5433[[int512_t][1.0779(0.0291243s)]] 5434[[mpz_int][3.83495(0.103619s)]] 5435[[tom_int][41.6378(1.12504s)]] 5436] 5437 5438Note how for this use case, any dynamic allocation is a performance killer. 5439 5440The next [@../../performance/miller_rabin_performance.cpp tests] measure the time taken to generate 1000 128-bit 5441random numbers and test for primality using the Miller Rabin test. This is primarily a test of modular-exponentiation 5442since that is the rate limiting step: 5443 5444[table 5445[[Integer Type][Relative Performance (Actual time in parenthesis)]] 5446[[checked_uint1024_t][6.90638(0.0477963s)]] 5447[[cpp_int][8.63811(0.0597808s)]] 5448[[cpp_int (1024-bit cache)][7.4261(0.051393s)]] 5449[[cpp_int (128-bit cache)][8.88868(0.061515s)]] 5450[[cpp_int (256-bit cache)][8.83724(0.061159s)]] 5451[[cpp_int (512-bit cache)][7.53024(0.0521137s)]] 5452[[cpp_int (no Expression templates)][9.1372(0.0632349s)]] 5453[[mpz_int][1(0.00692059s)]] 5454[[mpz_int (no Expression templates)][1.08118(0.00748244s)]] 5455[[tom_int][4.16719(0.0288394s)]] 5456[[tom_int (no Expression templates)][4.1723(0.0288748s)]] 5457[[uint1024_t][6.82875(0.047259s)]] 5458] 5459 5460It's interesting to note that expression templates have little effect here - perhaps because the actual expressions involved 5461are relatively trivial in this case - so the time taken for multiplication and division tends to dominate. The much 5462quicker times from GMP and tommath are down to their 5463much better modular-exponentiation algorithms (GMP's is about 5x faster). That's an issue which needs to be addressed 5464in a future release for __cpp_int. 5465 5466[table:platform Platform Details 5467[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5468[[Compiler][GNU C++ version 9.2.1 20191008]] 5469[[GMP][6.1.2]] 5470[[MPFR][262146]] 5471[[Boost][107200]] 5472[[Run date][Dec 13 2019]] 5473] 5474 5475[endsect] 5476 5477[section:float_performance Float Algorithm Performance] 5478 5479Note that these tests are carefully designed to test performance of the underlying algorithms 5480and not memory allocation or variable copying. As usual, performance results should be taken 5481with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5482specifics of the program. In each table relative times are given first, with the best performer 5483given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5484operations. 5485 5486[table Operator * 5487[[Backend][50 Bits][100 Bits][500 Bits]] 5488[[cpp_bin_float][4.30817 (0.0408401s)][1.75015 (0.0653409s)][2.16485 (0.597984s)]] 5489[[cpp_dec_float][3.35696 (0.031823s)][1.77364 (0.0662176s)][1.74752 (0.482708s)]] 5490[[gmp_float][2.01455 (0.0190973s)][[*1] (0.0373344s)][[*1] (0.276224s)]] 5491[[mpfr_float][[*1] (0.00947969s)][1.21316 (0.0452924s)][2.13364 (0.589363s)]] 5492] 5493[table Operator *(int) 5494[[Backend][50 Bits][100 Bits][500 Bits]] 5495[[cpp_bin_float][2.98031 (0.0223518s)][4.27803 (0.0313689s)][4.54817 (0.0632425s)]] 5496[[cpp_dec_float][4.25141 (0.0318849s)][7.59768 (0.0557104s)][33.1653 (0.461166s)]] 5497[[gmp_float][[*1] (0.00749984s)][[*1] (0.00733255s)][[*1] (0.0139051s)]] 5498[[mpfr_float][2.98089 (0.0223562s)][3.32286 (0.0243651s)][3.7808 (0.0525722s)]] 5499] 5500[table Operator *(unsigned long long) 5501[[Backend][50 Bits][100 Bits][500 Bits]] 5502[[cpp_bin_float][3.38766 (0.0235916s)][5.87158 (0.0423397s)][5.05723 (0.0709145s)]] 5503[[cpp_dec_float][5.0049 (0.0348541s)][8.47648 (0.0611235s)][32.4907 (0.455598s)]] 5504[[gmp_float][[*1] (0.00696399s)][[*1] (0.00721095s)][[*1] (0.0140224s)]] 5505[[mpfr_float][3.03806 (0.0211571s)][3.50941 (0.0253062s)][3.44633 (0.0483258s)]] 5506] 5507[table Operator *=(unsigned long long) 5508[[Backend][50 Bits][100 Bits][500 Bits]] 5509[[cpp_bin_float][1.56351 (0.0230891s)][2.0073 (0.031993s)][3.62925 (0.0772075s)]] 5510[[cpp_dec_float][2.55656 (0.0377542s)][4.10056 (0.0653562s)][21.6642 (0.460876s)]] 5511[[gmp_float][[*1] (0.0147675s)][[*1] (0.0159383s)][[*1] (0.0212737s)]] 5512[[mpfr_float][2.23026 (0.0329355s)][2.40387 (0.0383137s)][2.64077 (0.0561789s)]] 5513] 5514[table Operator + 5515[[Backend][50 Bits][100 Bits][500 Bits]] 5516[[cpp_bin_float][3.91168 (0.0381834s)][4.16297 (0.0642049s)][4.90051 (0.102092s)]] 5517[[cpp_dec_float][2.23696 (0.0218359s)][1.69854 (0.0261964s)][6.06882 (0.126431s)]] 5518[[gmp_float][1.50164 (0.0146581s)][[*1] (0.0154229s)][[*1] (0.0208329s)]] 5519[[mpfr_float][[*1] (0.0097614s)][1.21982 (0.0188131s)][1.81579 (0.0378282s)]] 5520] 5521[table Operator +(int) 5522[[Backend][50 Bits][100 Bits][500 Bits]] 5523[[cpp_bin_float][5.27328 (0.0381889s)][6.85509 (0.0518618s)][10.4988 (0.104875s)]] 5524[[cpp_dec_float][3.50749 (0.0254011s)][4.07503 (0.0308294s)][12.8481 (0.128342s)]] 5525[[gmp_float][[*1] (0.00724196s)][[*1] (0.00756543s)][[*1] (0.00998923s)]] 5526[[mpfr_float][4.51538 (0.0327002s)][4.54647 (0.034396s)][5.25239 (0.0524673s)]] 5527] 5528[table Operator +(unsigned long long) 5529[[Backend][50 Bits][100 Bits][500 Bits]] 5530[[cpp_bin_float][5.93334 (0.044578s)][9.73575 (0.0758362s)][11.0837 (0.112203s)]] 5531[[cpp_dec_float][3.99501 (0.030015s)][4.07581 (0.0317483s)][9.33811 (0.0945316s)]] 5532[[gmp_float][[*1] (0.00751313s)][[*1] (0.00778945s)][[*1] (0.0101232s)]] 5533[[mpfr_float][4.28797 (0.0322161s)][4.83393 (0.0376537s)][5.2035 (0.052676s)]] 5534] 5535[table Operator +=(unsigned long long) 5536[[Backend][50 Bits][100 Bits][500 Bits]] 5537[[cpp_bin_float][2.97171 (0.045722s)][3.78495 (0.0640784s)][5.16221 (0.117755s)]] 5538[[cpp_dec_float][1.93543 (0.0297781s)][3.12436 (0.0528949s)][4.83179 (0.110218s)]] 5539[[gmp_float][[*1] (0.0153858s)][[*1] (0.0169298s)][[*1] (0.022811s)]] 5540[[mpfr_float][3.42442 (0.0526874s)][3.32428 (0.0562794s)][3.25356 (0.0742172s)]] 5541] 5542[table Operator - 5543[[Backend][50 Bits][100 Bits][500 Bits]] 5544[[cpp_bin_float][4.15367 (0.0409089s)][2.64914 (0.0485095s)][4.23345 (0.103383s)]] 5545[[cpp_dec_float][2.29639 (0.0226168s)][1.72571 (0.0316003s)][8.13523 (0.198666s)]] 5546[[gmp_float][1.77498 (0.0174816s)][[*1] (0.0183114s)][[*1] (0.0244205s)]] 5547[[mpfr_float][[*1] (0.00984886s)][1.02493 (0.0187679s)][1.56348 (0.0381809s)]] 5548] 5549[table Operator -(int) 5550[[Backend][50 Bits][100 Bits][500 Bits]] 5551[[cpp_bin_float][2.32581 (0.0423205s)][2.99906 (0.0550403s)][4.83118 (0.105425s)]] 5552[[cpp_dec_float][1.90239 (0.0346161s)][2.19948 (0.0403659s)][5.37782 (0.117354s)]] 5553[[gmp_float][[*1] (0.0181961s)][[*1] (0.0183525s)][[*1] (0.0218218s)]] 5554[[mpfr_float][2.30468 (0.041936s)][2.36758 (0.043451s)][2.94644 (0.0642965s)]] 5555] 5556[table Operator -(unsigned long long) 5557[[Backend][50 Bits][100 Bits][500 Bits]] 5558[[cpp_bin_float][3.256 (0.057902s)][4.0869 (0.075218s)][5.533 (0.116255s)]] 5559[[cpp_dec_float][2.20586 (0.0392273s)][1.80053 (0.0331383s)][4.29622 (0.0902684s)]] 5560[[gmp_float][[*1] (0.0177832s)][[*1] (0.0184047s)][[*1] (0.0210111s)]] 5561[[mpfr_float][2.51778 (0.0447741s)][2.70809 (0.0498416s)][3.44152 (0.0723102s)]] 5562] 5563[table Operator -=(unsigned long long) 5564[[Backend][50 Bits][100 Bits][500 Bits]] 5565[[cpp_bin_float][1.95294 (0.0470344s)][2.41267 (0.0618181s)][4.10529 (0.124911s)]] 5566[[cpp_dec_float][1.22584 (0.029523s)][1.42773 (0.0365817s)][3.11172 (0.0946795s)]] 5567[[gmp_float][[*1] (0.0240839s)][[*1] (0.0256223s)][[*1] (0.0304267s)]] 5568[[mpfr_float][2.41227 (0.0580968s)][2.55229 (0.0653955s)][2.75369 (0.0837856s)]] 5569] 5570[table Operator / 5571[[Backend][50 Bits][100 Bits][500 Bits]] 5572[[cpp_bin_float][4.03031 (0.472005s)][7.46615 (1.06338s)][13.3123 (5.3577s)]] 5573[[cpp_dec_float][4.96983 (0.582036s)][7.16767 (1.02087s)][14.7936 (5.95388s)]] 5574[[gmp_float][[*1] (0.117114s)][[*1] (0.142427s)][[*1] (0.402463s)]] 5575[[mpfr_float][1.70874 (0.200117s)][1.79749 (0.256012s)][3.50914 (1.4123s)]] 5576] 5577[table Operator /(int) 5578[[Backend][50 Bits][100 Bits][500 Bits]] 5579[[cpp_bin_float][4.81369 (0.0938506s)][7.27806 (0.162749s)][9.67195 (0.551804s)]] 5580[[cpp_dec_float][15.0254 (0.292944s)][21.5761 (0.482477s)][51.7469 (2.95226s)]] 5581[[gmp_float][[*1] (0.0194966s)][[*1] (0.0223617s)][[*1] (0.0570519s)]] 5582[[mpfr_float][1.38183 (0.0269409s)][1.44879 (0.0323974s)][1.52094 (0.0867728s)]] 5583] 5584[table Operator /(unsigned long long) 5585[[Backend][50 Bits][100 Bits][500 Bits]] 5586[[cpp_bin_float][5.35966 (0.101822s)][8.88121 (0.190303s)][12.708 (0.717622s)]] 5587[[cpp_dec_float][14.7735 (0.280663s)][22.4928 (0.481967s)][51.6265 (2.91535s)]] 5588[[gmp_float][[*1] (0.0189978s)][[*1] (0.0214276s)][[*1] (0.0564701s)]] 5589[[mpfr_float][1.41678 (0.0269157s)][1.6855 (0.0361161s)][1.52543 (0.0861411s)]] 5590] 5591[table Operator /=(unsigned long long) 5592[[Backend][50 Bits][100 Bits][500 Bits]] 5593[[cpp_bin_float][4.84585 (0.125006s)][6.82926 (0.208589s)][10.3294 (0.662579s)]] 5594[[cpp_dec_float][10.7166 (0.276449s)][16.1194 (0.492342s)][44.3971 (2.84786s)]] 5595[[gmp_float][[*1] (0.0257964s)][[*1] (0.0305434s)][[*1] (0.0641451s)]] 5596[[mpfr_float][1.50909 (0.0389292s)][1.49032 (0.0455194s)][1.70466 (0.109346s)]] 5597] 5598[table Operator construct 5599[[Backend][50 Bits][100 Bits][500 Bits]] 5600[[cpp_bin_float][[*1] (0.00303111s)][[*1] (0.00357506s)][[*1] (0.0113051s)]] 5601[[cpp_dec_float][1.00185 (0.00303671s)][1.15155 (0.00411687s)][1.26796 (0.0143345s)]] 5602[[gmp_float][16.5683 (0.0502204s)][14.0851 (0.0503551s)][9.67268 (0.109351s)]] 5603[[mpfr_float][28.144 (0.0853075s)][24.8244 (0.0887486s)][10.3544 (0.117058s)]] 5604] 5605[table Operator construct(unsigned long long) 5606[[Backend][50 Bits][100 Bits][500 Bits]] 5607[[cpp_bin_float][[*1] (0.00524853s)][[*1] (0.00566609s)][[*1] (0.0278919s)]] 5608[[cpp_dec_float][2.97185 (0.0155978s)][1.49757 (0.00848537s)][1.03141 (0.0287679s)]] 5609[[gmp_float][10.4626 (0.0549133s)][9.63997 (0.054621s)][3.98862 (0.11125s)]] 5610[[mpfr_float][20.7883 (0.109108s)][20.2715 (0.11486s)][5.17847 (0.144437s)]] 5611] 5612[table Operator construct(unsigned) 5613[[Backend][50 Bits][100 Bits][500 Bits]] 5614[[cpp_bin_float][[*1] (0.00519769s)][[*1] (0.0054342s)][[*1] (0.0275892s)]] 5615[[cpp_dec_float][1.67001 (0.0086802s)][1.5305 (0.00831702s)][1.05641 (0.0291456s)]] 5616[[gmp_float][10.6639 (0.0554274s)][10.2395 (0.0556435s)][4.03533 (0.111332s)]] 5617[[mpfr_float][25.0325 (0.130111s)][20.8688 (0.113405s)][6.29649 (0.173715s)]] 5618] 5619[table Operator str 5620[[Backend][50 Bits][100 Bits][500 Bits]] 5621[[cpp_bin_float][3.98982 (0.00249639s)][5.55423 (0.00505412s)][10.5272 (0.0320983s)]] 5622[[cpp_dec_float][4.83686 (0.00302637s)][4.39789 (0.0040019s)][3.38032 (0.0103068s)]] 5623[[gmp_float][[*1] (0.000625689s)][[*1] (0.000909959s)][[*1] (0.00304907s)]] 5624[[mpfr_float][1.95049 (0.0012204s)][1.61297 (0.00146774s)][1.52133 (0.00463864s)]] 5625] 5626 5627[table:platform Platform Details 5628[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5629[[Compiler][GNU C++ version 9.2.1 20191008]] 5630[[GMP][6.1.2]] 5631[[MPFR][262146]] 5632[[Boost][107200]] 5633[[Run date][Dec 13 2019]] 5634] 5635 5636[endsect] 5637 5638[section:integer_performance Integer Algorithm Performance] 5639 5640Note that these tests are carefully designed to test performance of the underlying algorithms 5641and not memory allocation or variable copying. As usual, performance results should be taken 5642with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5643specifics of the program. In each table relative times are given first, with the best performer 5644given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5645operations. 5646 5647[table Operator % 5648[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5649[[cpp_int][2.61392 (0.0864932s)][2.33601 (0.180207s)][3.10832 (0.265481s)][4.4334 (0.437939s)][6.58635 (1.84456s)][8.03034 (3.52132s)]] 5650[[cpp_int(fixed)][[*1] (0.0330895s)][1.41347 (0.10904s)][2.16247 (0.184697s)][3.54449 (0.350131s)]] 5651[[gmp_int][1.92882 (0.0638235s)][[*1] (0.0771433s)][[*1] (0.0854098s)][[*1] (0.0987817s)][[*1] (0.280057s)][[*1] (0.438501s)]] 5652[[tommath_int][29.1866 (0.96577s)][15.4935 (1.19522s)][17.3239 (1.47963s)][21.5351 (2.12727s)][30.686 (8.59385s)][46.9089 (20.5696s)]] 5653] 5654[table Operator %(int) 5655[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5656[[cpp_int][3.96358 (0.0411513s)][5.50428 (0.0824453s)][9.42287 (0.158338s)][15.8329 (0.324245s)][30.9984 (1.64821s)][45.0524 (3.18758s)]] 5657[[cpp_int(fixed)][1.94108 (0.020153s)][4.67128 (0.0699684s)][7.70602 (0.129488s)][13.4197 (0.274825s)]] 5658[[gmp_int][[*1] (0.0103823s)][[*1] (0.0149784s)][[*1] (0.0168035s)][[*1] (0.0204792s)][[*1] (0.0531708s)][[*1] (0.0707528s)]] 5659[[tommath_int][63.4583 (0.658846s)][60.8321 (0.911168s)][71.7106 (1.20499s)][94.0003 (1.92505s)][158.133 (8.40805s)][281.804 (19.9384s)]] 5660] 5661[table Operator & 5662[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5663[[cpp_int][5.80585 (0.0183659s)][2.61424 (0.0152432s)][1.92953 (0.0150612s)][2.06584 (0.0169715s)][2.76807 (0.0908961s)][2.71967 (0.150675s)]] 5664[[cpp_int(fixed)][[*1] (0.00316334s)][2.07888 (0.0121216s)][1.66677 (0.0130102s)][2.13 (0.0174986s)]] 5665[[gmp_int][1.92975 (0.00610446s)][[*1] (0.00583083s)][[*1] (0.00780563s)][[*1] (0.00821528s)][[*1] (0.0328374s)][[*1] (0.055402s)]] 5666[[tommath_int][12.8579 (0.0406739s)][7.3359 (0.0427744s)][5.45721 (0.0425969s)][5.59908 (0.0459981s)][2.0162 (0.0662069s)][1.89937 (0.105229s)]] 5667] 5668[table Operator &(int) 5669[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5670[[cpp_int][6.35169 (0.022195s)][1.23274 (0.0225044s)][1.14828 (0.022403s)][[*1] (0.0249629s)][3.1254 (0.114785s)][5.12161 (0.162092s)]] 5671[[cpp_int(fixed)][[*1] (0.00349434s)][[*1] (0.0182556s)][[*1] (0.0195101s)][1.2174 (0.0303898s)]] 5672[[gmp_int][8.90744 (0.0311256s)][1.66139 (0.0303296s)][1.65728 (0.0323335s)][1.22673 (0.0306228s)][[*1] (0.0367266s)][[*1] (0.0316487s)]] 5673[[tommath_int][41.7082 (0.145742s)][8.3058 (0.151627s)][7.92746 (0.154665s)][6.17442 (0.154131s)][5.61372 (0.206173s)][7.94642 (0.251494s)]] 5674] 5675[table Operator * 5676[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5677[[cpp_int][31.2488 (0.0300171s)][1.30604 (0.0236033s)][1.54672 (0.0566226s)][1.99827 (0.200935s)][1.86646 (3.97724s)][3.28041 (15.8254s)]] 5678[[cpp_int(fixed)][[*1] (0.000960586s)][1.05101 (0.0189943s)][1.40113 (0.0512925s)][1.32791 (0.133528s)]] 5679[[gmp_int][6.99778 (0.00672197s)][[*1] (0.0180725s)][[*1] (0.0366081s)][[*1] (0.100555s)][[*1] (2.13089s)][[*1] (4.82421s)]] 5680[[tommath_int][25.6654 (0.0246539s)][1.93625 (0.0349929s)][1.53585 (0.0562246s)][1.40261 (0.141039s)][1.24172 (2.64598s)][1.99971 (9.64701s)]] 5681] 5682[table Operator *(int) 5683[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5684[[cpp_int][12.9191 (0.00819119s)][1.8286 (0.00975751s)][2.09136 (0.0145601s)][2.10205 (0.0199823s)][1.62628 (0.0692257s)][2.08177 (0.122618s)]] 5685[[cpp_int(fixed)][[*1] (0.000634036s)][[*1] (0.00533605s)][1.25356 (0.0087273s)][1.82259 (0.0173257s)]] 5686[[gmp_int][9.40263 (0.00596161s)][1.07614 (0.00574233s)][[*1] (0.00696202s)][[*1] (0.00950608s)][[*1] (0.0425668s)][[*1] (0.0589007s)]] 5687[[tommath_int][186.507 (0.118252s)][23.4915 (0.125352s)][18.6669 (0.129959s)][17.1434 (0.162966s)][6.11737 (0.260397s)][6.03792 (0.355638s)]] 5688] 5689[table Operator *(unsigned long long) 5690[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5691[[cpp_int][9.1035 (0.00634192s)][1.61555 (0.00682732s)][1.38506 (0.00820436s)][1.28658 (0.012381s)][1.28916 (0.0410419s)][1.44948 (0.0850577s)]] 5692[[cpp_int(fixed)][[*1] (0.000696646s)][[*1] (0.00422601s)][[*1] (0.00592347s)][1.35631 (0.013052s)]] 5693[[gmp_int][8.26494 (0.00575774s)][1.31029 (0.00553729s)][1.19721 (0.00709163s)][[*1] (0.00962312s)][[*1] (0.0318361s)][[*1] (0.0586816s)]] 5694[[tommath_int][381.793 (0.265975s)][69.3609 (0.29312s)][50.6122 (0.2998s)][32.8061 (0.315697s)][13.3579 (0.425264s)][10.2399 (0.600894s)]] 5695] 5696[table Operator *=(unsigned long long) 5697[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5698[[cpp_int][16.5844 (0.0124159s)][1.25396 (0.0117921s)][1.25877 (0.0140258s)][1.25408 (0.017396s)][3.09966 (0.135787s)][2.63342 (0.222949s)]] 5699[[cpp_int(fixed)][[*1] (0.000748647s)][[*1] (0.00940387s)][[*1] (0.0111425s)][[*1] (0.0138715s)]] 5700[[gmp_int][13.2789 (0.00994121s)][1.10899 (0.0104288s)][1.05822 (0.0117912s)][1.01821 (0.0141241s)][[*1] (0.043807s)][[*1] (0.0846612s)]] 5701[[tommath_int][382.992 (0.286726s)][30.337 (0.285285s)][29.1674 (0.324997s)][31.5038 (0.437006s)][10.9188 (0.478321s)][15.7365 (1.33227s)]] 5702] 5703[table Operator + 5704[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5705[[cpp_int][15.9318 (0.013332s)][2.10124 (0.0143298s)][2.20691 (0.0167551s)][2.35301 (0.0233641s)][1.33275 (0.0544877s)][2.16492 (0.108428s)]] 5706[[cpp_int(fixed)][[*1] (0.000836815s)][[*1] (0.00681969s)][1.41379 (0.0107337s)][2.07286 (0.0205823s)]] 5707[[gmp_int][7.69219 (0.00643694s)][1.1551 (0.00787741s)][[*1] (0.00759213s)][[*1] (0.00992945s)][1.23736 (0.050588s)][[*1] (0.0500843s)]] 5708[[tommath_int][8.11368 (0.00678965s)][1.17124 (0.00798749s)][1.38788 (0.0105369s)][1.62714 (0.0161566s)][[*1] (0.0408838s)][1.74073 (0.0871834s)]] 5709] 5710[table Operator +(int) 5711[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5712[[cpp_int][12.8717 (0.00838402s)][2.30046 (0.00932673s)][2.45998 (0.00974958s)][1.81876 (0.0103926s)][[*1] (0.0217559s)][1.1339 (0.0382453s)]] 5713[[cpp_int(fixed)][[*1] (0.000651354s)][2.26453 (0.00918106s)][2.24994 (0.00891717s)][2.34592 (0.0134049s)]] 5714[[gmp_int][5.64809 (0.00367891s)][[*1] (0.00405429s)][[*1] (0.00396328s)][[*1] (0.00571412s)][1.34135 (0.0291824s)][[*1] (0.033729s)]] 5715[[tommath_int][163.863 (0.106733s)][27.8217 (0.112797s)][28.2173 (0.111833s)][24.3745 (0.139279s)][6.8073 (0.148099s)][5.34674 (0.18034s)]] 5716] 5717[table Operator +(unsigned long long) 5718[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5719[[cpp_int][10.1497 (0.00642975s)][1.57663 (0.00645253s)][1.42461 (0.00641131s)][1.47836 (0.00821865s)][1.25785 (0.0236995s)][1.1786 (0.0416466s)]] 5720[[cpp_int(fixed)][[*1] (0.00063349s)][2.25723 (0.00923798s)][2.14091 (0.00963492s)][2.49596 (0.0138758s)]] 5721[[gmp_int][6.32948 (0.00400966s)][[*1] (0.00409262s)][[*1] (0.00450039s)][[*1] (0.0055593s)][[*1] (0.0188413s)][[*1] (0.0353357s)]] 5722[[tommath_int][401.541 (0.254372s)][67.4121 (0.275892s)][62.2763 (0.280267s)][53.4937 (0.297388s)][16.2934 (0.306988s)][10.8628 (0.383846s)]] 5723] 5724[table Operator +=(unsigned long long) 5725[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5726[[cpp_int][20.6678 (0.0119696s)][1.49971 (0.0116516s)][1.42955 (0.0113839s)][1.45605 (0.0125775s)][2.06272 (0.0473177s)][1.40574 (0.0700083s)]] 5727[[cpp_int(fixed)][[*1] (0.000579142s)][[*1] (0.00776928s)][[*1] (0.00796329s)][[*1] (0.00863808s)]] 5728[[gmp_int][13.7619 (0.00797012s)][1.0168 (0.00789978s)][1.01968 (0.00812s)][1.05837 (0.00914227s)][[*1] (0.0229395s)][[*1] (0.0498017s)]] 5729[[tommath_int][445.395 (0.257947s)][35.5299 (0.276042s)][34.9701 (0.278477s)][64.4794 (0.556978s)][14.0169 (0.32154s)][17.3947 (0.866288s)]] 5730] 5731[table Operator - 5732[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5733[[cpp_int][12.3892 (0.013267s)][1.54334 (0.0143848s)][1.75333 (0.0168786s)][2.27597 (0.0248697s)][1.33198 (0.0615975s)][2.25424 (0.124313s)]] 5734[[cpp_int(fixed)][[*1] (0.00107085s)][[*1] (0.00932056s)][1.17586 (0.0113195s)][1.94907 (0.0212976s)]] 5735[[gmp_int][8.69616 (0.00931231s)][1.01107 (0.00942373s)][[*1] (0.00962656s)][[*1] (0.0109271s)][[*1] (0.0462452s)][[*1] (0.0551462s)]] 5736[[tommath_int][11.546 (0.0123641s)][1.60814 (0.0149887s)][1.63067 (0.0156977s)][1.69241 (0.018493s)][1.13529 (0.0525017s)][1.80318 (0.0994384s)]] 5737] 5738[table Operator -(int) 5739[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5740[[cpp_int][7.3164 (0.00718041s)][1.97509 (0.00764735s)][1.99047 (0.00793413s)][1.70452 (0.00889396s)][[*1] (0.0198067s)][1.04883 (0.0351681s)]] 5741[[cpp_int(fixed)][[*1] (0.000981414s)][2.01105 (0.00778659s)][1.99052 (0.0079343s)][2.35869 (0.0123073s)]] 5742[[gmp_int][3.83069 (0.00375949s)][[*1] (0.00387191s)][[*1] (0.00398606s)][[*1] (0.00521786s)][1.56189 (0.0309358s)][[*1] (0.0335308s)]] 5743[[tommath_int][115.787 (0.113635s)][29.9688 (0.116037s)][28.9647 (0.115455s)][27.5319 (0.143658s)][7.75868 (0.153674s)][5.42319 (0.181844s)]] 5744] 5745[table Operator -(unsigned long long) 5746[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5747[[cpp_int][7.7478 (0.00750847s)][1.95546 (0.00771183s)][1.80328 (0.00832029s)][1.56695 (0.00851748s)][1.11271 (0.0205857s)][1.19378 (0.0402243s)]] 5748[[cpp_int(fixed)][[*1] (0.00096911s)][2.13061 (0.00840261s)][1.91132 (0.00881879s)][2.37174 (0.0128921s)]] 5749[[gmp_int][4.80618 (0.00465772s)][[*1] (0.00394375s)][[*1] (0.00461397s)][[*1] (0.00543571s)][[*1] (0.0185005s)][[*1] (0.0336949s)]] 5750[[tommath_int][267.937 (0.259661s)][71.5531 (0.282188s)][60.4257 (0.278803s)][53.979 (0.293414s)][17.7584 (0.32854s)][10.8218 (0.364638s)]] 5751] 5752[table Operator -=(unsigned long long) 5753[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5754[[cpp_int][16.3509 (0.0131613s)][1.83102 (0.0134809s)][1.68407 (0.0129795s)][1.64352 (0.0140383s)][2.37302 (0.051436s)][1.47693 (0.0544701s)]] 5755[[cpp_int(fixed)][[*1] (0.000804926s)][[*1] (0.00736247s)][[*1] (0.00770724s)][[*1] (0.0085416s)]] 5756[[gmp_int][10.0648 (0.0081014s)][1.09612 (0.00807013s)][1.09758 (0.00845934s)][1.10598 (0.00944683s)][[*1] (0.0216753s)][[*1] (0.0368808s)]] 5757[[tommath_int][319.944 (0.257531s)][37.1214 (0.273305s)][38.1176 (0.293781s)][66.8689 (0.571167s)][15.141 (0.328186s)][22.6158 (0.834089s)]] 5758] 5759[table Operator / 5760[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5761[[cpp_int][3.7053 (0.120457s)][2.31282 (0.256283s)][2.98148 (0.342198s)][4.15769 (0.552845s)][5.66579 (1.93033s)][9.54675 (3.77425s)]] 5762[[cpp_int(fixed)][[*1] (0.0325094s)][1.01212 (0.112153s)][1.63455 (0.187605s)][2.67551 (0.355761s)]] 5763[[gmp_int][2.62651 (0.0853863s)][[*1] (0.11081s)][[*1] (0.114775s)][[*1] (0.132969s)][[*1] (0.340699s)][[*1] (0.395344s)]] 5764[[tommath_int][30.2016 (0.981836s)][10.7299 (1.18898s)][12.8954 (1.48007s)][16.5608 (2.20208s)][25.7963 (8.78879s)][53.4042 (21.113s)]] 5765] 5766[table Operator /(int) 5767[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5768[[cpp_int][5.43796 (0.0610196s)][8.7229 (0.114124s)][9.80894 (0.188141s)][10.9464 (0.347422s)][8.94304 (1.5446s)][11.4148 (3.04214s)]] 5769[[cpp_int(fixed)][1.66282 (0.0186586s)][5.28422 (0.0691348s)][6.70321 (0.128571s)][8.47034 (0.268837s)]] 5770[[gmp_int][[*1] (0.0112211s)][[*1] (0.0130833s)][[*1] (0.0191805s)][[*1] (0.0317386s)][[*1] (0.172715s)][[*1] (0.266509s)]] 5771[[tommath_int][65.6123 (0.736239s)][74.4427 (0.973953s)][64.7215 (1.24139s)][60.0008 (1.90434s)][47.3896 (8.18491s)][73.3451 (19.5472s)]] 5772] 5773[table Operator /(unsigned long long) 5774[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5775[[cpp_int][5.69361 (0.0679437s)][8.63227 (0.118515s)][10.4819 (0.19782s)][11.652 (0.36737s)][12.6501 (1.71211s)][12.4658 (3.49901s)]] 5776[[cpp_int(fixed)][1.71873 (0.0205101s)][5.54771 (0.0761662s)][7.87722 (0.148664s)][9.73978 (0.307082s)]] 5777[[gmp_int][[*1] (0.0119333s)][[*1] (0.0137293s)][[*1] (0.0188726s)][[*1] (0.0315286s)][[*1] (0.135343s)][[*1] (0.28069s)]] 5778[[tommath_int][70.3948 (0.840045s)][73.9467 (1.01524s)][78.9032 (1.48911s)][74.5804 (2.35142s)][69.6519 (9.42692s)][104.536 (29.3423s)]] 5779] 5780[table Operator /=(unsigned long long) 5781[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5782[[cpp_int][4.81054 (0.0787575s)][8.57398 (0.16217s)][10.886 (0.247055s)][11.2718 (0.405759s)][12.5937 (1.88874s)][12.21 (3.63347s)]] 5783[[cpp_int(fixed)][1.20166 (0.0196733s)][4.32475 (0.0817993s)][6.58644 (0.149478s)][8.32497 (0.29968s)]] 5784[[gmp_int][[*1] (0.0163719s)][[*1] (0.0189142s)][[*1] (0.0226949s)][[*1] (0.0359977s)][[*1] (0.149975s)][[*1] (0.297582s)]] 5785[[tommath_int][53.9084 (0.88258s)][53.1273 (1.00486s)][71.1404 (1.61452s)][67.5031 (2.42996s)][65.7108 (9.85499s)][101.244 (30.1285s)]] 5786] 5787[table Operator << 5788[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5789[[cpp_int][19.177 (0.0162764s)][2.61717 (0.0163378s)][2.37674 (0.021464s)][2.09019 (0.0286746s)][2.56897 (0.164462s)][2.63407 (0.258076s)]] 5790[[cpp_int(fixed)][[*1] (0.000848746s)][[*1] (0.00624253s)][[*1] (0.00903085s)][[*1] (0.0137187s)]] 5791[[gmp_int][13.6905 (0.0116198s)][1.91174 (0.0119341s)][1.66888 (0.0150714s)][1.41131 (0.0193613s)][[*1] (0.0640186s)][[*1] (0.0979761s)]] 5792[[tommath_int][24.7233 (0.0209838s)][4.59302 (0.028672s)][3.68238 (0.033255s)][2.98058 (0.0408897s)][1.84398 (0.118049s)][2.21298 (0.216819s)]] 5793] 5794[table Operator >> 5795[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5796[[cpp_int][20.232 (0.0162325s)][4.69783 (0.0157363s)][4.50992 (0.0149173s)][4.86912 (0.0162095s)][13.239 (0.0539071s)][12.1827 (0.0524954s)]] 5797[[cpp_int(fixed)][[*1] (0.000802316s)][1.58991 (0.00532573s)][2.13899 (0.00707508s)][4.21178 (0.0140212s)]] 5798[[gmp_int][4.29127 (0.00344295s)][[*1] (0.0033497s)][[*1] (0.00330767s)][[*1] (0.00332904s)][[*1] (0.00407185s)][[*1] (0.00430902s)]] 5799[[tommath_int][67.6824 (0.0543026s)][17.5897 (0.05892s)][17.6963 (0.0585334s)][17.7611 (0.0591272s)][40.2804 (0.164016s)][45.6107 (0.196537s)]] 5800] 5801[table Operator ^ 5802[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5803[[cpp_int][5.21469 (0.0176691s)][1.76461 (0.0151583s)][1.54944 (0.01576s)][1.66733 (0.0166044s)][2.67895 (0.0907825s)][2.85374 (0.147776s)]] 5804[[cpp_int(fixed)][[*1] (0.00338833s)][1.61335 (0.013859s)][1.5785 (0.0160556s)][1.8238 (0.0181626s)]] 5805[[gmp_int][2.65843 (0.00900763s)][[*1] (0.00859017s)][[*1] (0.0101714s)][[*1] (0.00995865s)][[*1] (0.0338873s)][[*1] (0.0517833s)]] 5806[[tommath_int][11.7662 (0.0398677s)][4.97263 (0.0427158s)][4.173 (0.0424452s)][4.36742 (0.0434936s)][1.87208 (0.0634399s)][2.15704 (0.111699s)]] 5807] 5808[table Operator ^(int) 5809[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5810[[cpp_int][4.47727 (0.0154762s)][1.1548 (0.0152722s)][1.29522 (0.0149375s)][[*1] (0.0152534s)][1.16178 (0.062951s)][[*1] (0.0542065s)]] 5811[[cpp_int(fixed)][[*1] (0.00345661s)][[*1] (0.013225s)][[*1] (0.0115328s)][1.35474 (0.0206643s)]] 5812[[gmp_int][9.96342 (0.0344397s)][2.54169 (0.0336138s)][3.0636 (0.0353319s)][2.2878 (0.0348967s)][[*1] (0.0541849s)][1.14922 (0.0622954s)]] 5813[[tommath_int][39.5678 (0.136771s)][11.1605 (0.147598s)][12.3859 (0.142844s)][9.57606 (0.146067s)][3.32237 (0.180022s)][3.89337 (0.211046s)]] 5814] 5815[table Operator construct 5816[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5817[[cpp_int][2.70048 (0.00154337s)][[*1] (0.00165673s)][[*1] (0.00160871s)][[*1] (0.00172862s)][[*1] (0.00156009s)][[*1] (0.00174205s)]] 5818[[cpp_int(fixed)][[*1] (0.000571519s)][1.23543 (0.00204677s)][1.9796 (0.00318462s)][4.48025 (0.00774465s)]] 5819[[gmp_int][85.6322 (0.0489404s)][29.2571 (0.0484711s)][30.662 (0.0493265s)][27.83 (0.0481075s)][40.363 (0.0629698s)][27.9451 (0.048682s)]] 5820[[tommath_int][201.724 (0.115289s)][58.7441 (0.0973229s)][52.7386 (0.0848414s)][44.5608 (0.0770287s)][50.8452 (0.079323s)][47.1258 (0.0820957s)]] 5821] 5822[table Operator construct(unsigned long long) 5823[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5824[[cpp_int][2.39475 (0.00192516s)][[*1] (0.00189599s)][[*1] (0.00183399s)][[*1] (0.00196715s)][[*1] (0.00191441s)][[*1] (0.0018252s)]] 5825[[cpp_int(fixed)][[*1] (0.000803908s)][1.19809 (0.00227157s)][1.88086 (0.00344948s)][3.8843 (0.007641s)]] 5826[[gmp_int][65.7819 (0.0528826s)][27.1474 (0.0514712s)][29.3096 (0.0537536s)][26.2945 (0.0517252s)][72.2795 (0.138372s)][27.9893 (0.0510862s)]] 5827[[tommath_int][434.327 (0.349159s)][188.668 (0.357713s)][186.415 (0.341884s)][173.347 (0.341s)][183.361 (0.351027s)][175.369 (0.320084s)]] 5828] 5829[table Operator construct(unsigned) 5830[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5831[[cpp_int][2.14911 (0.00163907s)][[*1] (0.00163286s)][[*1] (0.00171255s)][[*1] (0.0017176s)][[*1] (0.00167292s)][[*1] (0.00156985s)]] 5832[[cpp_int(fixed)][[*1] (0.000762672s)][1.36862 (0.00223478s)][2.03741 (0.00348916s)][4.53966 (0.00779734s)]] 5833[[gmp_int][68.2442 (0.0520479s)][31.4026 (0.0512762s)][30.7091 (0.0525909s)][30.032 (0.0515831s)][41.5223 (0.0694635s)][32.5392 (0.0510816s)]] 5834[[tommath_int][331.014 (0.252455s)][151.468 (0.247326s)][132.724 (0.227296s)][128.015 (0.219878s)][131.833 (0.220546s)][143.372 (0.225072s)]] 5835] 5836[table Operator gcd 5837[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5838[[cpp_int][2.07031 (0.395833s)][3.50598 (2.95518s)][4.44198 (8.63567s)][5.59809 (22.6997s)][9.49572 (269.4s)][15.722 (962.995s)]] 5839[[cpp_int(fixed)][3.47569 (0.664533s)][1.70521 (1.43732s)][2.31892 (4.50823s)][3.55661 (14.4217s)]] 5840[[gmp_int][[*1] (0.191195s)][[*1] (0.842898s)][[*1] (1.9441s)][[*1] (4.0549s)][[*1] (28.3707s)][[*1] (61.2516s)]] 5841[[tommath_int][10.8111 (2.06703s)][5.12095 (4.31644s)][4.59174 (8.92681s)][5.01043 (20.3168s)][7.52621 (213.524s)][12.3495 (756.428s)]] 5842] 5843[table Operator powm 5844[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5845[[cpp_int][10.6592 (0.802191s)][13.9407 (2.61537s)][12.912 (10.4205s)][10.8568 (51.2302s)]] 5846[[cpp_int(fixed)][5.82971 (0.438734s)][8.89247 (1.66829s)][9.93013 (8.01404s)][8.83073 (41.6696s)]] 5847[[gmp_int][[*1] (0.0752583s)][[*1] (0.187607s)][[*1] (0.807043s)][[*1] (4.7187s)]] 5848[[tommath_int][6.1085 (0.459715s)][5.83038 (1.09382s)][3.80545 (3.07116s)][3.02859 (14.291s)]] 5849] 5850[table Operator str 5851[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5852[[cpp_int][1.92305 (0.000421266s)][3.20633 (0.000851021s)][3.65142 (0.00169768s)][5.16642 (0.00504001s)][11.2543 (0.0811042s)][20.2913 (0.313789s)]] 5853[[cpp_int(fixed)][5.11756 (0.00112106s)][1.92296 (0.00051039s)][2.45213 (0.00114008s)][3.72073 (0.00362969s)]] 5854[[gmp_int][[*1] (0.000219061s)][[*1] (0.000265419s)][[*1] (0.000464936s)][[*1] (0.000975531s)][[*1] (0.00720651s)][[*1] (0.0154642s)]] 5855[[tommath_int][21.587 (0.00472888s)][39.7234 (0.0105433s)][55.2128 (0.0256704s)][81.4207 (0.0794284s)][169.04 (1.21819s)][302.626 (4.67986s)]] 5856] 5857[table Operator | 5858[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5859[[cpp_int][5.25873 (0.0172824s)][1.96305 (0.0151621s)][1.75036 (0.015208s)][1.87423 (0.017812s)][2.78566 (0.0913325s)][2.88264 (0.14832s)]] 5860[[cpp_int(fixed)][[*1] (0.00328643s)][1.45652 (0.0112498s)][1.45925 (0.0126787s)][1.95487 (0.0185784s)]] 5861[[gmp_int][2.49444 (0.00819781s)][[*1] (0.00772371s)][[*1] (0.00868852s)][[*1] (0.00950363s)][[*1] (0.0327866s)][[*1] (0.0514528s)]] 5862[[tommath_int][11.7763 (0.038702s)][5.50066 (0.0424855s)][4.90757 (0.0426395s)][4.5757 (0.0434857s)][1.88223 (0.061712s)][2.0004 (0.102926s)]] 5863] 5864[table Operator |(int) 5865[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits][5120 Bits][10240 Bits]] 5866[[cpp_int][4.53358 (0.0155813s)][1.37758 (0.015007s)][1.27482 (0.0145389s)][[*1] (0.0155149s)][1.17798 (0.0620504s)][[*1] (0.0526689s)]] 5867[[cpp_int(fixed)][[*1] (0.00343686s)][[*1] (0.0108938s)][[*1] (0.0114047s)][1.3214 (0.0205014s)]] 5868[[gmp_int][9.60058 (0.0329958s)][3.00706 (0.0327581s)][3.05453 (0.034836s)][2.20715 (0.0342437s)][[*1] (0.0526751s)][1.17671 (0.0619762s)]] 5869[[tommath_int][39.7055 (0.136462s)][13.0365 (0.142016s)][14.0596 (0.160345s)][9.31086 (0.144457s)][3.38341 (0.178221s)][3.81403 (0.200881s)]] 5870] 5871 5872[table:platform Platform Details 5873[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5874[[Compiler][GNU C++ version 9.2.1 20191008]] 5875[[GMP][6.1.2]] 5876[[MPFR][262146]] 5877[[Boost][107200]] 5878[[Run date][Dec 13 2019]] 5879] 5880 5881[endsect] 5882 5883[section:rational_performance Rational Type Performance] 5884 5885Note that these tests are carefully designed to test performance of the underlying algorithms 5886and not memory allocation or variable copying. As usual, performance results should be taken 5887with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 5888specifics of the program. In each table relative times are given first, with the best performer 5889given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 5890operations. 5891 5892[table Operator * 5893[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5894[[cpp_rational][2.59318 (1.11835s)][3.74332 (6.61855s)][4.71871 (18.5981s)][5.48511 (47.0022s)]] 5895[[mpq_rational][[*1] (0.431264s)][[*1] (1.7681s)][[*1] (3.94136s)][[*1] (8.56905s)]] 5896] 5897[table Operator *(int) 5898[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5899[[cpp_rational][5.63431 (0.612884s)][25.5205 (2.83784s)][64.6798 (7.61151s)][135.335 (19.4821s)]] 5900[[mpq_rational][[*1] (0.108777s)][[*1] (0.111198s)][[*1] (0.11768s)][[*1] (0.143955s)]] 5901] 5902[table Operator *(unsigned long long) 5903[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5904[[cpp_rational][4.44786 (0.691659s)][18.4155 (2.97414s)][44.4009 (7.64879s)][98.4603 (19.5719s)]] 5905[[mpq_rational][[*1] (0.155504s)][[*1] (0.161502s)][[*1] (0.172267s)][[*1] (0.19878s)]] 5906] 5907[table Operator *=(unsigned long long) 5908[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5909[[cpp_rational][4.12301 (0.690473s)][20.2597 (3.35519s)][42.8043 (7.47312s)][94.2742 (19.3092s)]] 5910[[mpq_rational][[*1] (0.167468s)][[*1] (0.165609s)][[*1] (0.174588s)][[*1] (0.20482s)]] 5911] 5912[table Operator + 5913[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5914[[cpp_rational][8.51825 (1.97719s)][7.8609 (7.34254s)][9.73008 (21.2507s)][11.1497 (49.7843s)]] 5915[[mpq_rational][[*1] (0.232113s)][[*1] (0.93406s)][[*1] (2.18402s)][[*1] (4.46507s)]] 5916] 5917[table Operator +(int) 5918[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5919[[cpp_rational][7.17647 (0.669913s)][29.8489 (2.91217s)][75.7668 (7.40631s)][254.371 (29.7057s)]] 5920[[mpq_rational][[*1] (0.0933486s)][[*1] (0.0975637s)][[*1] (0.0977514s)][[*1] (0.116781s)]] 5921] 5922[table Operator +(unsigned long long) 5923[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5924[[cpp_rational][12.4996 (1.16835s)][33.6691 (3.37438s)][82.0167 (8.08959s)][171.692 (19.9733s)]] 5925[[mpq_rational][[*1] (0.0934708s)][[*1] (0.100222s)][[*1] (0.0986335s)][[*1] (0.116332s)]] 5926] 5927[table Operator +=(unsigned long long) 5928[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5929[[cpp_rational][11.7663 (1.14891s)][34.4202 (3.45541s)][78.1856 (8.17612s)][161.351 (20.0733s)]] 5930[[mpq_rational][[*1] (0.0976436s)][[*1] (0.100389s)][[*1] (0.104573s)][[*1] (0.124408s)]] 5931] 5932[table Operator - 5933[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5934[[cpp_rational][8.56942 (2.0234s)][7.88071 (7.38282s)][9.54207 (19.913s)][11.4343 (50.8786s)]] 5935[[mpq_rational][[*1] (0.236118s)][[*1] (0.936822s)][[*1] (2.08686s)][[*1] (4.44964s)]] 5936] 5937[table Operator -(int) 5938[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5939[[cpp_rational][6.62286 (0.62794s)][30.6629 (2.96506s)][75.926 (7.56072s)][199.475 (23.42s)]] 5940[[mpq_rational][[*1] (0.094814s)][[*1] (0.0966986s)][[*1] (0.0995801s)][[*1] (0.117408s)]] 5941] 5942[table Operator -(unsigned long long) 5943[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5944[[cpp_rational][12.3835 (1.16081s)][36.0761 (3.40187s)][83.3673 (8.26011s)][169.239 (20.5682s)]] 5945[[mpq_rational][[*1] (0.0937381s)][[*1] (0.094297s)][[*1] (0.099081s)][[*1] (0.121534s)]] 5946] 5947[table Operator -=(unsigned long long) 5948[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5949[[cpp_rational][11.6833 (1.16049s)][36.6427 (3.64132s)][77.0952 (8.10257s)][160.444 (20.0829s)]] 5950[[mpq_rational][[*1] (0.0993285s)][[*1] (0.0993737s)][[*1] (0.105098s)][[*1] (0.12517s)]] 5951] 5952[table Operator / 5953[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5954[[cpp_rational][5.67626 (6.66075s)][5.99288 (21.0634s)][8.08809 (55.0195s)][10.5818 (149.774s)]] 5955[[mpq_rational][[*1] (1.17344s)][[*1] (3.51474s)][[*1] (6.80254s)][[*1] (14.1539s)]] 5956] 5957[table Operator /(int) 5958[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5959[[cpp_rational][5.9046 (0.64166s)][25.5252 (2.84312s)][65.4027 (7.74325s)][134.42 (19.5619s)]] 5960[[mpq_rational][[*1] (0.108671s)][[*1] (0.111385s)][[*1] (0.118393s)][[*1] (0.145528s)]] 5961] 5962[table Operator /(unsigned long long) 5963[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5964[[cpp_rational][4.35172 (0.691696s)][18.2795 (2.94678s)][44.2487 (7.48547s)][99.1392 (19.5526s)]] 5965[[mpq_rational][[*1] (0.158948s)][[*1] (0.161207s)][[*1] (0.169168s)][[*1] (0.197224s)]] 5966] 5967[table Operator /=(unsigned long long) 5968[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5969[[cpp_rational][4.14511 (0.685733s)][18.3237 (3.08065s)][43.3784 (7.43555s)][94.2547 (19.2754s)]] 5970[[mpq_rational][[*1] (0.165432s)][[*1] (0.168124s)][[*1] (0.171411s)][[*1] (0.204503s)]] 5971] 5972[table Operator construct 5973[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5974[[cpp_rational][[*1] (0.00323537s)][[*1] (0.00328614s)][[*1] (0.0032946s)][[*1] (0.00333283s)]] 5975[[mpq_rational][28.9199 (0.0935664s)][28.1463 (0.0924926s)][28.2564 (0.0930936s)][27.5848 (0.0919355s)]] 5976] 5977[table Operator construct(unsigned long long) 5978[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5979[[cpp_rational][[*1] (0.00333944s)][[*1] (0.00335336s)][[*1] (0.00348777s)][[*1] (0.00345967s)]] 5980[[mpq_rational][29.1785 (0.09744s)][29.1475 (0.097742s)][27.4732 (0.0958203s)][28.6655 (0.099173s)]] 5981] 5982[table Operator construct(unsigned) 5983[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5984[[cpp_rational][[*1] (0.00321917s)][[*1] (0.00319471s)][[*1] (0.00327131s)][[*1] (0.00366486s)]] 5985[[mpq_rational][30.8553 (0.0993283s)][30.5973 (0.0977495s)][29.5866 (0.0967869s)][28.3432 (0.103874s)]] 5986] 5987[table Operator str 5988[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 5989[[cpp_rational][5.80834 (0.00206821s)][11.5273 (0.00645497s)][18.1686 (0.0156602s)][38.1095 (0.0705044s)]] 5990[[mpq_rational][[*1] (0.000356077s)][[*1] (0.000559971s)][[*1] (0.000861937s)][[*1] (0.00185005s)]] 5991] 5992 5993[table:platform Platform Details 5994[[Platform][Linux 5.3.0-24-generic, version \#26-Ubuntu SMP Thu Nov 14 01:33:18 UTC 2019, x86_64]] 5995[[Compiler][GNU C++ version 9.2.1 20191008]] 5996[[GMP][6.1.2]] 5997[[MPFR][262146]] 5998[[Boost][107200]] 5999[[Run date][Dec 13 2019]] 6000] 6001 6002[endsect] 6003 6004[endsect] 6005 6006[section:map Roadmap] 6007 6008[section:hist History] 6009 6010[h4 Multiprecision-3.2.4 (Boost-1.73)] 6011 6012* IMPORTANT: Mark C++03 support as deprecated and due for removal in 2021. 6013* Big update to __cpp_int adds faster Karatsuba and Coomba multiplication routines. 6014* Fix conversion of __gmp_rational to `long double` and `__float128`, fixes [@https://github.com/boostorg/multiprecision/issues/178 #178]. 6015* Fix up libtommath support to function with the latest libtom releases. 6016* Fix up some incompatibilities with the latest Intel C++ compiler. 6017* Fix up `constexpr` arithmetic support for forthcoming MSVC release. 6018 6019[h4 Multiprecision-3.2.3 (Boost-1.72)] 6020 6021* Big `constexpr` update allows __cpp_int and __float128__ arithmetic to be fully `constexpr` with gcc and clang 9 or later, 6022or any compiler supporting `std::is_constant_evaluated()`. 6023 6024[h4 Multiprecision-3.1.3 (Boost-1.71)] 6025 6026* Support hexfloat io-formatting for float128. 6027* Fix various bugs in variable precision interconversions. 6028* Respect uppercase for '0x' prefix outputs. 6029* Incorporate some unit tests from the Etherium project. 6030* Fix some gcc warnings. 6031 6032[h4 Multiprecision-3.1.2 (Boost-1.70)] 6033 6034* Fix various conversion issues in the traits classes, check for compatibility with Boost.Optional. 6035* Prevent instantiation of `std::numeric_limits` on any old type when checking for convertibility. See [@https://github.com/boostorg/multiprecision/issues/98 #98]. 6036* Update variable precision code to accound for arbitrary precision integers. See [@https://github.com/boostorg/multiprecision/issues/103 #103]. 6037* Add support for XML serialization archives. 6038* Fix bug in fixed precision iostream formatting in `mpf_float` and `mpfr_float`. See [@https://github.com/boostorg/multiprecision/issues/113 #113]. 6039* Add more overloads for special functions which are better handled natively by MPFR. 6040* Fixed bug in generic `exp` implementation which could cause invariant failure. 6041* Fixed generic conversion from float to integer to avoid undefined behaviour. See [@https://github.com/boostorg/multiprecision/issues/110 #110]. 6042 6043[h4 Multiprecision-3.1.1 (Boost-1.69)] 6044 6045* Big update to better support variable precision types so that the precision of the result 6046is always the largest of all the arguments. 6047* Add support for allocators that are `final` in __cpp_int. 6048* Removed use of deprecated Boost.Endian in favour of Predef. 6049* Add support for `std::string_view`. 6050* Fixed minor bug in constant initialization. See [@https://github.com/boostorg/multiprecision/issues/67 #67]. 6051* Make assignment of non-finite value to `cpp_int` a runtime errors. See [@https://github.com/boostorg/multiprecision/issues/58 #58]. 6052* Added typedefs for `cpp_bin_float_oct` and `cpp_complex_oct`. 6053 6054[h4 Multiprecision-3.1.0 (Boost-1.68)] 6055 6056* Support added for complex multiprecision numbers. 6057* Changed conversion to unsigned integer types to be truncating to match standard defined behaviour. 6058* Correct bug in MPFR string formatting. 6059* Fix undefined behaviour in cpp_dec_float conversion from long long. 6060* Add support for Eigen interoperability. 6061* float128.hpp: Fix Intel on Windows build. 6062* Fix type used in temporaries when expanding expression templates containing mixed expressions. 6063* Fix infinite loop in gmp_float to fixed-point string conversion. 6064* Update the expression templates to issue static_asserts with better error messages when you try and do something unsupported. 6065* Fix bug in cpp_int where incrementing to zero doesn't set the sign correctly. 6066* Remove erroneous use of std::move, and rely on NVRO instead. 6067* Fix up support for changes to MPIR-3.0. 6068* Fix various conversion errors in cpp_bin_float when the exponent type is a `long long`, or else we're converting to 6069an integer that is wider than we are. 6070* Fix compatibility issue with GCC-8 caused by the introduction of `std::byte`. 6071 6072[h4 Multiprecision-3.0.0 (Boost-1.67)] 6073 6074* [*Breaking Change:] When converting a multiprecision integer to a narrower type, if the value is too large (or negative) to 6075fit in the smaller type, then the result is either the maximum (or minimum) value of the target type. This was always the intended 6076behaviour, but was somewhat haphazardly enforced before. If you really do want just the low order N bits of a value, then you will 6077need to mask these out prior to the case, for example: `static_cast<unsigned>(~static_cast<unsigned>(0) & my_value)`. Note that 6078technically (to avoid undefined behaviour) you should do the same thing with __fundamental integer types too. 6079See [@https://svn.boost.org/trac/boost/ticket/13109 #13109]. 6080* Fix bug in conversion of decimal to rational types (zero needs special handling), see [@https://svn.boost.org/trac/boost/ticket/13148 #13148]. 6081* Fix conversion from cpp_bin_float to a wider __fundamental integer type, see [@https://svn.boost.org/trac/boost/ticket/13301 #13301]. 6082* Improve performance heurists used in cpp_bin_float exp function. 6083* 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]. 6084* Disable explicit conversion operator when the target type is already constructible from this type, see [@https://github.com/boostorg/multiprecision/issues/30 #30]. 6085* Fix support for changes new to MPIR-3.0, see [@https://svn.boost.org/trac/boost/ticket/13124 #13124]. 6086 6087[h4 Multiprecision-2.3.2 (Boost-1.65)] 6088 6089* 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]. 6090* Fix various issues with huge values and overflow in the trig, pow and exp functions, see [@https://github.com/boostorg/multiprecision/issues/24 #24]. 6091* Fix error handling of checked cpp_int multiply that could cause some overflows to be missed. 6092 6093[h4 Multiprecision-2.3.1 (Boost-1.64)] 6094 6095* In `cpp_bin_float` prevent double rounding when converting to a denormalized float. See [@https://svn.boost.org/trac/boost/ticket/12527 #12527]. 6096* Fix bug in integer sqrt for very small integers. See [@https://svn.boost.org/trac/boost/ticket/12559 #12559]. 6097* Fix conversion to signed-zero in `cpp_bin_float`. 6098* 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]. 6099* Improve performance of 128-bit bit-scan operations. 6100* Fix subtraction of very small quantities in `cpp_bin_float`. See: [@https://svn.boost.org/trac/boost/ticket/12580 #12580]. 6101* Bring error handling into line with C99 Annex F. See [@https://svn.boost.org/trac/boost/ticket/12581 #12581]. 6102* Fix bitwise export of trivial `cpp_int`'s, see [@https://svn.boost.org/trac/boost/ticket/12627 #12627]. 6103* 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]. 6104* Allow conversion from `__float128__` to `cpp_bin_float`. 6105* Fix bug in left shift of `cpp_int` which would result in bit-loss, see [@https://svn.boost.org/trac/boost/ticket/12790 #12790]. 6106* 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]. 6107 6108 6109[h4 Multiprecision-2.3.0 (Boost-1.63)] 6110 6111* Added support for all the C99 math functions. 6112* Extended generic-interconversions to handle narrowing cases as well, changed convert_to member function and hence explicit 6113conversion operators to use the same conversion code as the explicit constructors. 6114* Fix IO stream parsing error, see [@https://svn.boost.org/trac/boost/ticket/12488 #12488]. 6115* Make default constructed floating point types all zero for consistency, see [@https://svn.boost.org/trac/boost/ticket/12500 #12500]. 6116* 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]. 6117* Fix cpp_bin_float subtractions that yield signed-zeros, see [@https://svn.boost.org/trac/boost/ticket/12524 #12524]. 6118* Fix ceil/trunc/round applied to cpp_bin_float and yielding a signed zero, see [@https://svn.boost.org/trac/boost/ticket/12525 #12525]. 6119 6120[h4 Multiprecision-2.2.8 (Boost-1.62)] 6121 6122* Added support for hashing via `Boost.Hash` or `std::hash`. 6123* 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]. 6124* Prevent inadvertant instantiation of variable-precision `mpfr_float_backend` with fixed allocation. 6125* Fixed division over/underflow in cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12167 #12167]. 6126* Added support for signed-zeros throughout the library, including support for `signbit` and `copysign`, mpfr, float128, and cpp_bin_float types 6127should now respect signed-zeros correctly. 6128* Fixed bug in conversion of cpp_bin_float infinities to double etc, see [@https://svn.boost.org/trac/boost/ticket/12196 #12196]. 6129* Fix add and subtract of cpp_bin_float when the exponents would overflow., see [@https://svn.boost.org/trac/boost/ticket/12198 #12198]. 6130* Improve variable-precision support in mpfr and mpf backends, allow these types to be used with Boost.Math. 6131* Fixed bug in subtraction of signed infinities in cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12209 #12209]. 6132* Fix result of sqrt(infinity) in cpp_bin_float (result should be infinity), see [@https://svn.boost.org/trac/boost/ticket/12227 #12227]. 6133* Added workaround in gmp.hpp for recent MPIR releases which are not quite source-compatible with GMP on Windows x64. 6134* Allow `cpp_int` code to be used with /RTCc with MSVC. 6135* Fix conversion of `cpp_int` to signed integer when the result is INT_MIN, see [@https://svn.boost.org/trac/boost/ticket/12343 #12343]. 6136* Update uBlas support to match latest uBlas code. 6137* Fix some errors present when building on big-endian machines (not all `cpp_int` constructors are available on non-little-endian machines). 6138* Fix fencepost error in rational to float conversion routines, see [@https://svn.boost.org/trac/boost/ticket/12327 #12327]. 6139* Fix some Oracle C++ compiler compatibility issues. 6140* Add modf support to complete C90 compatibility. 6141* 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]. 6142* Fixed some compiler errors that occur when converting from `cpp_int` to `cpp_bin_float`. 6143 6144[h4 Multiprecision-2.2.7 (Boost-1.61)] 6145 6146* Fixed bug in stream input for integer types, see [@https://svn.boost.org/trac/boost/ticket/11857 #11857]. 6147* Fixed some ambiguous conversions involving expression templates see [@https://svn.boost.org/trac/boost/ticket/11922 #11922]. 6148* Add expression template aware min/max overloads see [@https://svn.boost.org/trac/boost/ticket/11149 #11149]. 6149* Fix bug in right shifting negative small integers in cpp_int see [@https://svn.boost.org/trac/boost/ticket/11999 #11999]. 6150* Use memmove for bitshifts in cpp_int when possible see [@https://svn.boost.org/trac/boost/ticket/9233 #9233]. 6151* Use memcpy for data import into cpp_int where possible, see [@https://svn.boost.org/trac/boost/ticket/9235 #9235]. 6152* Changed `cpp_bin_float.convert_to<double>()` to a function template rather than proceding via `long double` to avoid 6153double-rounding bug, see [@https://svn.boost.org/trac/boost/ticket/12039 #12039]. 6154* Fixed conversions from NaNs and Infinities, see [@https://svn.boost.org/trac/boost/ticket/12112 #12112]. 6155* Enabled better support for Clang on Windows. 6156* Fixed handling of NaNs and Infinities in basic arithmetic for cpp_dec_float and cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12090 #12090]. 6157* Fixed fencepost error in cpp_bin_float subtraction. 6158* Fixed double-rounding in conversion to float routines for cpp_bin_float, see [@https://svn.boost.org/trac/boost/ticket/12039 #12039]. 6159* Make float128 denorm aware, see [@https://svn.boost.org/trac/boost/ticket/12075 #12075]. 6160* Allow the library and tests to be used without exception handling support, see [@https://svn.boost.org/trac/boost/ticket/12070 #12070]. 6161* Fixed buggy comparison operator overloads for boost::rational. 6162* Added some workarounds for Oracle C++. 6163* Fixed some missing typecasts for cases where cpp_int's limb_type is wider than unsigned. 6164 6165 6166[h4 Multiprecision-2.2.6 (Boost-1.60)] 6167 6168* Fixed result of Miller Rabin primality test for value 2, see [@https://svn.boost.org/trac/boost/ticket/11495 #11495]. 6169* Improved initialization of cpp_int from very large strings of hex or octal digits, see [@https://svn.boost.org/trac/boost/ticket/11590 #11590]. 6170* Fixed fmod behaviour for negative divisors, see [@https://svn.boost.org/trac/boost/ticket/11641 #11641]. 6171* Fixed infinite division loop in cpp_int special case, see [@https://svn.boost.org/trac/boost/ticket/11648 #11648]. 6172* Patched missing return statement in [@https://svn.boost.org/trac/boost/ticket/11762 #11762]. 6173* Fixed mixed mode arithmetic compiler error in [@https://svn.boost.org/trac/boost/ticket/11764 #11764]. 6174* Fixed over-aggressive use of noexcept in [@https://svn.boost.org/trac/boost/ticket/11826 #11826]. 6175 6176 6177[h4 Multiprecision-2.2.5 (Boost-1.59)] 6178 6179* Depricated boost/multiprecision/random.hpp as it's no longer needed, updated random examples to match. 6180* Fixed a bug in `cpp_int` right shift operator when shifting negative values - semantics now gives the 6181same values as shifting 2's compliment integers, though not the same bit pattern. 6182* Fixed support for GCC-4.6.4 in C++0x mode by disabling conditional noexcept suppoprt for that compiler 6183see [@https://svn.boost.org/trac/boost/ticket/11402 #11402]. 6184* Suppressed numerous compiler warnings. 6185 6186[h4 Multiprecision-2.2.4 (Boost-1.58)] 6187 6188* Changed `frexp` to always be non-expression template generating, see: [@https://svn.boost.org/trac/boost/ticket/10993 10993]. 6189* 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]. 6190* Improved noexcept support and added some more tests, see [@https://svn.boost.org/trac/boost/ticket/10990 10990]. 6191* Various workarounds applied for Intel-15.0 and Solaris-12.4 compilers. 6192 6193[h4 Multiprecision-2.2.3 (Boost-1.57)] 6194 6195* Changed rational to float conversions to exactly round to nearest, see [@https://svn.boost.org/trac/boost/ticket/10085 10085]. 6196* Added improved generic float to rational conversions. 6197* Fixed rare bug in exponent function for __cpp_bin_float. 6198* Fixed various minor documentation issues. 6199 6200[h4 Multiprecision-2.2.2 (Boost-1.56)] 6201 6202* Change floating-point to rational conversions to be implicit, see [@https://svn.boost.org/trac/boost/ticket/10082 10082]. 6203* Fix definition of checked_cpp_rational typedef. 6204 6205[h4 Multiprecision-2.2.1] 6206 6207* Fix bug in assignment from string in cpp_int, see [@https://svn.boost.org/trac/boost/ticket/9936 9936]. 6208 6209[h4 Multiprecision-2.2.0] 6210 6211* Moved to Boost.Multiprecision specific version number - we have one breaking change in Boost-1.54 6212which makes this major version 2, plus two releases with new features since then. 6213* Added new __cpp_bin_float backend for binary floating-point. 6214* Added MSVC-specific #include for compiler intrinsics, see [@https://svn.boost.org/trac/boost/ticket/9336 9336]. 6215* Fixed various typos in docs, see [@https://svn.boost.org/trac/boost/ticket/9432 9432]. 6216* Fixed __gmp_rational to allow move-copy from an already copied-from object, see [@https://svn.boost.org/trac/boost/ticket/9497 9497]. 6217* Added list of values for numeric_limits. 6218 6219[h4 Boost-1.55] 6220 6221* Added support for Boost.Serialization. 6222* Suppressed some GCC warnings. See [@https://svn.boost.org/trac/boost/ticket/8872 8872]. 6223* Fixed bug in pow for large integer arguments. See [@https://svn.boost.org/trac/boost/ticket/8809 8809]. 6224* Fixed bug in pow for calculation of 0[super N]. See [@https://svn.boost.org/trac/boost/ticket/8798 8798]. 6225* Fixed bug in fixed precision cpp_int IO code that causes conversion to string to fail when the 6226bit count is very small (less than CHAR_BIT). See [@https://svn.boost.org/trac/boost/ticket/8745 8745]. 6227* Fixed bug in cpp_int that causes left shift to fail when a fixed precision type would overflow. 6228See [@https://svn.boost.org/trac/boost/ticket/8741 8741]. 6229* Fixed some cosmetic warnings from cpp_int. See [@https://svn.boost.org/trac/boost/ticket/8748 8748]. 6230* Fixed calls to functions which are required to be macros in C99. See [@https://svn.boost.org/trac/boost/ticket/8732 8732]. 6231* 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]. 6232 6233[h4 1.54] 6234 6235* [*Breaking change] renamed `rational_adapter` to `rational_adaptor`. 6236* Add support for [mpfi]. 6237* Add logged_adaptor. 6238* Add support for 128-bit floats via GCC's `__float128` or Intel's `_Quad` data types. 6239* Add support for user-defined literals in cpp_int, improve `constexpr` support. 6240* Fixed bug in integer division of `cpp_int` that results in incorrect sign of `cpp_int` when both arguments are small enough 6241to fit in a `double_limb_type`. See [@https://svn.boost.org/trac/boost/ticket/8126 8126]. 6242* Fixed bug in subtraction of a single limb in `cpp_int` that results in incorrect value when the result should have a 0 6243in the last limb: [@https://svn.boost.org/trac/boost/ticket/8133 8133]. 6244* 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]. 6245* Fixed bug in some transcendental functions that caused incorrect return values when variables are reused, for example with 6246`a = pow(a, b)`. See [@https://svn.boost.org/trac/boost/ticket/8326 8326]. 6247* 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]. 6248* Fixed bug in `cpp_int` that gives incorrect answer for 0%N for large N: [@https://svn.boost.org/trac/boost/ticket/8670 8670]. 6249* Fixed set_precision in mpfr backend so it doesn't trample over an existing value: [@https://svn.boost.org/trac/boost/ticket/8692 8692]. 6250 6251[h4 1.53] 6252 6253* First Release. 6254* Fix bug in [@https://svn.boost.org/trac/boost/ticket/7878 cpp_int division]. 6255* Fix issue [@https://svn.boost.org/trac/boost/ticket/7806 #7806]. 6256 6257[h4 Post review changes] 6258 6259* Non-expression template operators further optimised with rvalue reference support. 6260* Many functions made `constexp`. 6261* Differentiate between explicit and implicit conversions in the number constructor. 6262* Removed "mp_" prefix from types. 6263* Allowed mixed precision arithmetic. 6264* Changed ExpressionTemplates parameter to class `number` to use enumerated values rather than true/false. 6265* Changed ExpressionTemplate parameter default value to use a traits class so that the default value depends on the backend used. 6266* Added support for fused-multiply-add/subtract with GMP support. 6267* Tweaked expression template unpacking to use fewer temporaries when the LHS also appears in the RHS. 6268* Refactored `cpp_int_backend` based on review comments with new template parameter structure. 6269* Added additional template parameter to `mpfr_float_backend` to allow stack-based allocation. 6270* Added section on mixed precision arithmetic, and added support for operations yielding a higher precision result 6271than either of the arguments. 6272* Added overloads of integer-specific functions for __fundamental integer types. 6273 6274[h4 Pre-review history] 6275 6276*2011-2012, John Maddock adds an expression template enabled front-end to Christopher's code, 6277and adds support for other backends. 6278* 2011, Christopher Kormanyos publishes the decimal floating-point code under the Boost 6279Software Licence. The code is published as: [@http://doi.acm.org/10.1145/1916461.1916469 6280"Algorithm 910: A Portable C++ Multiple-Precision 6281System for Special-Function Calculations"], in ACM TOMS, {VOL 37, ISSUE 4, (February 2011)} (C) ACM, 62822011. 6283* 2002-2011, Christopher Kormanyos develops the all C++ decimal arithmetic floating-point code. 6284 6285[endsect] [/section:hist History] 6286 6287 6288[section:todo TODO] 6289 6290More a list of what ['could] be done, rather than what ['should] be done (which may be a much smaller list!). 6291 6292* Add back-end support for libdecNumber. 6293* Add an adaptor back-end for complex number types. 6294* Add better multiplication routines (Karatsuba, FFT etc) to cpp_int_backend. 6295* Add assembly level routines to cpp_int_backend. 6296* Can ring types (exact floating-point types) be supported? The answer should be yes, but someone needs to write it, 6297the hard part is IO and binary-decimal conversion. 6298* Should there be a choice of rounding mode (probably MPFR specific)? 6299* We can reuse temporaries in multiple subtrees (temporary caching). 6300* cpp_dec_float should round to nearest. 6301* A 2's complement fixed precision int that uses exactly N bits and no more. 6302 6303Things requested in review: 6304 6305* The performances of mp_number<a_trivial_adaptor<float>, false>respect to 6306float and mp_number<a_trivial_adaptor<int>, false> and int should be 6307given to show the cost of using the generic interface (Mostly done, just need to update docs to the latest results). 6308* Should we provide min/max overloads for expression templates? (Not done - we can't overload functions declared in the std namespace :-( ). 6309* The rounding applied when converting must be documented (Done). 6310* Document why we don't abstract out addition/multiplication algorithms etc. (done - FAQ) 6311* Document why we don't use proto (compile times) (Done). 6312* We can reuse temporaries in multiple subtrees (temporary caching) Moved to TODO list. 6313* Emphasise in the docs that ET's may reorder operations (done 2012/10/31). 6314* Document what happens to small fixed precision cpp_int's (done 2012/10/31). 6315* The use of bool in template parameters could be improved by the use of 6316an enum class which will be more explicit. E.g `enum class expression_template {disabled, enabled}; 6317enum class sign {unsigned, signed};` (Partly done 2012/09/15, done 2012/10/31). 6318* Each back-end should document the requirements it satisfies (not currently scheduled for inclusion: it's 6319deliberately an implementation detail, and "optional" requirements are optimisations which can't be detected 6320by the user). Not done: this is an implementation detail, the exact list of requirements satisfied is purely 6321an optimization, not something the user can detect. 6322* A backend for an overflow aware integers (done 2012/10/31). 6323* IIUC convert_to is used to emulate in c++98 compilers C++11 explicit 6324conversions. Could the explicit conversion operator be added on 6325compilers supporting it? (Done 2012/09/15). 6326* The front-end should make the differences between implicit and explicit 6327construction (Done 2012/09/15). 6328* The tutorial should add more examples concerning implicit or explicit 6329conversions. (Done 2012/09/15). 6330* The documentation must explain how move semantics helps in this domain 6331and what the backend needs to do to profit from this optimization. (Done 2012/09/15). 6332* The documentation should contain Throws specification on the mp_number 6333and backend requirements operations. (Done 2012/09/15). 6334* The library interface should use the noexcept (BOOST_NOEXCEPT, ...) 6335facilities (Done 2012/09/15). 6336* It is unfortunate that the generic mp_number front end can not make use 6337constexpr as not all the backends can ensure this (done - we can go quite a way). 6338* literals: The library doesn't provide some kind of literals. I think that the 6339mp_number class should provide a way to create literals if the backend 6340is able to. (Done 2012/09/15). 6341* The ExpresionTemplate parameter could be defaulted to a traits class for more sensible defaults (done 2012/09/20). 6342* 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). 6343 6344 6345[h4 Pre-Review Comments] 6346 6347* Make fixed precision orthogonal to Allocator type in cpp_int. Possible solution - add an additional MaxBits 6348template argument that defaults to 0 (meaning keep going till no more space/memory). Done. 6349* Can ring types (exact floating-point types) be supported? The answer should be yes, but someone needs to write it (Moved to TODO list). 6350* Should there be a choice of rounding mode (probably MPFR specific)? Moved to TODO list. 6351* Make the exponent type for cpp_dec_float a template parameter, maybe include support for big-integer exponents. 6352Open question - what should be the default - int32_t or int64_t? (done 2012/09/06) 6353* Document the size requirements of fixed precision ints (done 2012/09/15). 6354* Document std lib function accuracy (done 2012/09/15). 6355* Be a bit clearer on the effects of sign-magnitude representation of cpp_int - min == -max etc - done. 6356* Document cpp_dec_float precision, rounding, and exponent size (done 2012/09/06). 6357* Can we be clearer in the docs that mixed arithmetic doesn't work (no longer applicable as of 2012/09/06)? 6358* Document round functions behaviour better (they behave as in C++11) (added note 2012/09/06). 6359* Document limits on size of cpp_dec_float (done 2012/09/06). 6360* Add support for fused multiply add (and subtract). GMP mpz_t could use this (done 2012/09/20). 6361 6362[endsect] [/section:todo TODO] 6363 6364[section:faq FAQ] 6365 6366[variablelist 6367[[Why do I get compiler errors when passing a `number` to a template function?] 6368 [Most likely you are actually passing an expression template type to the function and 6369 template-argument-deduction deduces the "wrong" type. Try casting the arguments 6370 involving expressions to the actual number type, or as a last resort turning off 6371 expression template support in the number type you are using.]] 6372[[When is expression template support a performance gain?] 6373 [As a general rule, expression template support adds a small runtime overhead 6374 creating and unpacking the expression templates, but greatly reduces the number of 6375 temporaries created. So it's most effective in improving performance when the cost 6376 of creating a temporary is high: for example when creating a temporary involves a memory 6377 allocation. It is least effective (and may even be a dis-optimisation) when temporaries 6378 are cheap: for example if the number type is basically a thin wrapper around a native 6379 arithmetic type. In addition, since the library makes extensive use of thin inline wrapper 6380 functions, turning on compiler optimization is essential to achieving high performance.]] 6381[[Do expression templates reorder operations?] 6382 [Yes they do, sometimes quite radically so, if this is a concern then they should be turned 6383 off for the number type you are using.]] 6384[[I can't construct my number type from ['some other type], but the docs indicate that the conversion should be allowed, what's up?] 6385 [Some conversions are ['explicit], that includes construction from a string, or constructing from any type 6386 that may result in loss of precision (for example constructing an integer type from a float).]] 6387[[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`?] 6388 [Bitwise operations on negative values (or indeed any signed integer type) are unspecified by the standard. As a result 6389 any attempt to carry out a bitwise operation on a negative checked-integer will result in a `std::range_error` being thrown.]] 6390[[Why do I get compiler errors when trying to use the complement operator?] 6391 [Use of the complement operator on signed types is problematic as the result is unspecified by the standard, and is further 6392 complicated by the fact that most extended precision integer types use a sign-magnitude representation rather than the 2's 6393 complement one favored by most native integer types. As a result the complement operator is deliberately disabled for 6394 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.]] 6395[[Why can't I negate an unsigned type?] 6396 [The unary negation operator is deliberately disabled for unsigned integer types as its use would almost always be a programming error.]] 6397[[Why doesn't the library use proto?] 6398 [A very early version of the library did use proto, but compile times became too slow 6399 for the library to be usable. Since the library only required a tiny fraction of what 6400 proto has to offer anyway, a lightweight expression template mechanism was used instead. 6401 Compile times are still too slow...]] 6402[[Why not abstract out addition/multiplication algorithms?] 6403 [This was deemed not to be practical: these algorithms are intimately 6404 tied to the actual data representation used.]] 6405 [[How do I choose between Boost.Multiprecision `cpp_bin_50` and `cpp_dec_50`?] 6406 [Unless you have a specific reason to choose `cpp_dec_`, then the default choice should be `cpp_bin_`, 6407 for example using the convenience `typedefs` like `boost::multiprecision::cpp_bin_50` or `boost::multiprecision::cpp_bin_100`. 6408 6409 In general, both work well and give the same results and at roughly the same speed with `cpp_dec_50` sometimes faster. 6410 6411 `cpp_dec_` was developed first paving the way for `cpp_bin_`. 6412 `cpp_dec_` has several guard digits and is not rounded at all, using 'brute force' to get the promised number of decimal digits correct, 6413 but making it difficult to reason about precision and computational uncertainty, for example see [*https://svn.boost.org/trac10/ticket/12133]. 6414 It also has a fast but imprecise division operator giving surprising results sometimes, see [*https://svn.boost.org/trac10/ticket/11178]. 6415 6416 `cpp_bin_` is correctly/exactly rounded making it possible to reason about both the precision and rounding of the results.]] 6417] [/variablelist] 6418 6419[endsect] [/section:faq FAQ] 6420 6421[section:ack Acknowledgements] 6422 6423This library would not have happened without: 6424 6425* Christopher Kormanyos' C++ decimal number code. 6426* Paul Bristow for patiently testing, and commenting on the library. 6427* All the folks at GMP, MPFR and libtommath, for providing the "guts" that makes this library work. 6428* [@http://www-cs-faculty.stanford.edu/~uno/taocp.html "The Art Of Computer Programming"], 6429Donald E. Knuth, Volume 2: Seminumerical Algorithms, Third Edition 6430(Reading, Massachusetts: Addison-Wesley, 1997), xiv+762pp. ISBN 0-201-89684-2 6431 6432[endsect] [/section:ack Acknowledgements] 6433 6434 6435[endsect] [/section:intro Introduction] 6436 6437 6438[section:indexes Indexes] 6439 6440''' 6441<index type="function_name"> 6442<title>Function Index</title> 6443</index> 6444 6445<index type="class_name"> 6446<title>Class Index</title> 6447</index> 6448 6449<index type="typedef_name"> 6450<title>Typedef Index</title> 6451</index> 6452 6453<index/> 6454''' 6455 6456[endsect] 6457
