1[/ 2 Copyright 2011, 2013 John Maddock. 3 Copyright 2013 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-2013 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] 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/tommath_snips.cpp] 33[import ../example/cpp_int_snips.cpp] 34[import ../example/random_snips.cpp] 35[import ../example/safe_prime.cpp] 36[import ../example/mixed_integer_arithmetic.cpp] 37[import ../example/logged_adaptor.cpp] 38[import ../example/numeric_limits_snips.cpp] 39 40[template mpfr[] [@http://www.mpfr.org MPFR]] 41[template mpfi[] [@http://perso.ens-lyon.fr/nathalie.revol/software.html MPFI]] 42[template gmp[] [@http://gmplib.org GMP]] 43[template mpf_class[] [@http://gmplib.org/manual/C_002b_002b-Interface-Floats.html#C_002b_002b-Interface-Floats mpf_class]] 44[template mpfr_class[] [@http://math.berkeley.edu/~wilken/code/gmpfrxx/ mpfr_class]] 45[template mpreal[] [@http://www.holoborodko.com/pavel/mpfr/ mpreal]] 46[template mpir[] [@http://mpir.org/ MPIR]] 47[template tommath[] [@http://libtom.org/?page=features&newsitems=5&whatfile=ltm libtommath]] 48[template quadmath[] [@http://gcc.gnu.org/onlinedocs/libquadmath/ libquadmath]] 49 50[template super[x]'''<superscript>'''[x]'''</superscript>'''] 51[template sub[x]'''<subscript>'''[x]'''</subscript>'''] 52 53[template equation[name] '''<inlinemediaobject> 54<imageobject role="html"> 55<imagedata fileref="../'''[name]'''.png"></imagedata> 56</imageobject> 57<imageobject role="print"> 58<imagedata fileref="../'''[name]'''.svg"></imagedata> 59</imageobject> 60</inlinemediaobject>'''] 61 62[def __cpp_int [link boost_multiprecision.tut.ints.cpp_int cpp_int]] 63[def __gmp_int [link boost_multiprecision.tut.ints.gmp_int gmp_int]] 64[def __tom_int [link boost_multiprecision.tut.ints.tom_int tom_int]] 65[def __gmp_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]] 66[def __mpf_float [link boost_multiprecision.tut.floats.gmp_float gmp_float]] 67[def __mpfr_float_backend [link boost_multiprecision.tut.floats.mpfr_float mpfr_float]] 68[def __cpp_bin_float [link boost_multiprecision.tut.floats.cpp_bin_float cpp_bin_float]] 69[def __cpp_dec_float [link boost_multiprecision.tut.floats.cpp_dec_float cpp_dec_float]] 70[def __gmp_rational [link boost_multiprecision.tut.rational.gmp_rational gmp_rational]] 71[def __cpp_rational [link boost_multiprecision.tut.rational.cpp_rational cpp_rational]] 72[def __tommath_rational [link boost_multiprecision.tut.rational.tommath_rational tommath_rational]] 73[def __number [link boost_multiprecision.ref.number number]] 74[def __float128 [link boost_multiprecision.tut.floats.float128 float128]] 75[def __debug_adaptor [link boost_multiprecision.tut.misc.debug_adaptor debug_adaptor]] 76[def __logged_adaptor [link boost_multiprecision.tut.misc.logged_adaptor logged_adaptor]] 77[def __rational_adaptor [link boost_multiprecision.tut.rational.rational_adaptor rational_adaptor]] 78 79[section:intro Introduction] 80 81The Multiprecision Library provides [link boost_multiprecision.tut.ints integer], 82[link boost_multiprecision.tut.rational rational] 83and [link boost_multiprecision.tut.floats floating-point] types in C++ that have more 84range and precision than C++'s ordinary built-in types. 85The big number types in Multiprecision can be used with a wide 86selection of basic mathematical operations, elementary transcendental 87functions as well as the functions in Boost.Math. 88The Multiprecision types can also interoperate with the 89built-in types in C++ using clearly defined conversion rules. 90This allows Boost.Multiprecision to be used for all 91kinds of mathematical calculations involving integer, 92rational and floating-point types requiring extended 93range and precision. 94 95Multiprecision consists of a generic interface to the 96mathematics of large numbers as well as a selection of 97big number back ends, with support for integer, rational and 98floating-point types. Boost.Multiprecision provides a selection 99of back ends provided off-the-rack in including 100interfaces to GMP, MPFR, MPIR, TomMath as well as 101its own collection of Boost-licensed, header-only back ends for 102integers, rationals and floats. In addition, user-defined back ends 103can be created and used with the interface of Multiprecision, 104provided the class implementation adheres to the necessary 105[link boost_multiprecision.ref.backendconc concepts]. 106 107Depending upon the number type, precision may be arbitrarily large 108(limited only by available memory), fixed at compile time 109(for example 50 or 100 decimal digits), or a variable controlled at run-time 110by member functions. The types are expression-template-enabled for 111better performance than naive user-defined types. 112 113The Multiprecision library comes in two distinct parts: 114 115* An expression-template-enabled front-end `number` 116that handles all the operator overloading, expression evaluation optimization, and code reduction. 117* A selection of back-ends that implement the actual arithmetic operations, and need conform only to the 118reduced interface requirements of the front-end. 119 120Separation of front-end and back-end allows use of highly refined, but restricted license libraries 121where possible, but provides Boost license alternatives for users who must have a portable 122unconstrained license. Which is to say some back-ends rely on 3rd party libraries, but a header-only Boost license version is always 123available (if somewhat slower). 124 125Should you just wish to cut to the chase and use a fully Boost-licensed number type, then skip to 126__cpp_int for multiprecision integers, __cpp_dec_float for multiprecision floating point types 127and __cpp_rational for rational types. 128 129The library is often used via one of the predefined typedefs: for example if you wanted an 130[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] 131integer type using [gmp] as the underlying implementation then you could use: 132 133 #include <boost/multiprecision/gmp.hpp> // Defines the wrappers around the GMP library's types 134 135 boost::multiprecision::mpz_int myint; // Arbitrary precision integer type. 136 137Alternatively, you can compose your own multiprecision type, by combining `number` with one of the 138predefined back-end types. For example, suppose you wanted a 300 decimal digit floating-point type 139based on the [mpfr] library. In this case, there's no predefined typedef with that level of precision, 140so instead we compose our own: 141 142 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR 143 144 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 145 146 typedef mp::number<mp::mpfr_float_backend<300> > my_float; 147 148 my_float a, b, c; // These variables have 300 decimal digits precision 149 150We can repeat the above example, but with the expression templates disabled (for faster compile times, but slower runtimes) 151by passing a second template argument to `number`: 152 153 #include <boost/multiprecision/mpfr.hpp> // Defines the Backend type that wraps MPFR 154 155 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 156 157 typedef mp::number<mp::mpfr_float_backend<300>, et_off> my_float; 158 159 my_float a, b, c; // These variables have 300 decimal digits precision 160 161We can also mix arithmetic operations between different types, provided there is an unambiguous implicit conversion from one 162type to the other: 163 164 #include <boost/multiprecision/cpp_int.hpp> 165 166 namespace mp = boost::multiprecision; // Reduce the typing a bit later... 167 168 mp::int128_t a(3), b(4); 169 mp::int512_t c(50), d; 170 171 d = c * a; // OK, result of mixed arithmetic is an int512_t 172 173Conversions are also allowed: 174 175 d = a; // OK, widening conversion. 176 d = a * b; // OK, can convert from an expression template too. 177 178However conversions that are inherently lossy are either declared explicit or else forbidden altogether: 179 180 d = 3.14; // Error implicit conversion from float not allowed. 181 d = static_cast<mp::int512_t>(3.14); // OK explicit construction is allowed 182 183Mixed arithmetic will fail if the conversion is either ambiguous or explicit: 184 185 number<cpp_int_backend<>, et_off> a(2); 186 number<cpp_int_backend<>, et_on> b(3); 187 188 b = a * b; // Error, implicit conversion could go either way. 189 b = a * 3.14; // Error, no operator overload if the conversion would be explicit. 190 191[h4 Move Semantics] 192 193On compilers that support rvalue-references, class `number` is move-enabled if the underlying backend is. 194 195In addition the non-expression template operator overloads (see below) are move aware and have overloads 196that look something like: 197 198 template <class B> 199 number<B, et_off> operator + (number<B, et_off>&& a, const number<B, et_off>& b) 200 { 201 return std::move(a += b); 202 } 203 204These operator overloads ensure that many expressions can be evaluated without actually generating any temporaries. 205However, there are still many simple expressions such as: 206 207 a = b * c; 208 209Which don't noticeably benefit from move support. Therefore, optimal performance comes from having both 210move-support, and expression templates enabled. 211 212Note that while "moved-from" objects are left in a sane state, they have an unspecified value, and the only permitted 213operations on them are destruction or the assignment of a new value. Any other operation should be considered 214a programming error and all of our backends will trigger an assertion if any other operation is attempted. This behavior 215allows for optimal performance on move-construction (i.e. no allocation required, we just take ownership of the existing 216object's internal state), while maintaining usability in the standard library containers. 217 218[h4 Expression Templates] 219 220Class `number` is expression-template-enabled: that means that rather than having a multiplication 221operator that looks like this: 222 223 template <class Backend> 224 number<Backend> operator * (const number<Backend>& a, const number<Backend>& b) 225 { 226 number<Backend> result(a); 227 result *= b; 228 return result; 229 } 230 231Instead the operator looks more like this: 232 233 template <class Backend> 234 ``['unmentionable-type]`` operator * (const number<Backend>& a, const number<Backend>& b); 235 236Where the "unmentionable" return type is an implementation detail that, rather than containing the result 237of the multiplication, contains instructions on how to compute the result. In effect it's just a pair 238of references to the arguments of the function, plus some compile-time information that stores what the operation 239is. 240 241The great advantage of this method is the ['elimination of temporaries]: for example the "naive" implementation 242of `operator*` above, requires one temporary for computing the result, and at least another one to return it. It's true 243that sometimes this overhead can be reduced by using move-semantics, but it can't be eliminated completely. For example, 244lets suppose we're evaluating a polynomial via Horner's method, something like this: 245 246 T a[7] = { /* some values */ }; 247 //.... 248 y = (((((a[6] * x + a[5]) * x + a[4]) * x + a[3]) * x + a[2]) * x + a[1]) * x + a[0]; 249 250If type `T` is a `number`, then this expression is evaluated ['without creating a single temporary value]. In contrast, 251if we were using the [mpfr_class] C++ wrapper for [mpfr] - then this expression would result in no less than 11 252temporaries (this is true even though [mpfr_class] does use expression templates to reduce the number of temporaries somewhat). Had 253we used an even simpler wrapper around [mpfr] like [mpreal] things would have been even worse and no less that 24 temporaries 254are created for this simple expression (note - we actually measure the number of memory allocations performed rather than 255the number of temporaries directly, note also that the [mpf_class] wrapper that will be supplied with GMP-5.1 reduces the number of 256temporaries to pretty much zero). Note that if we compile with expression templates disabled and rvalue-reference support 257on, then actually still have no wasted memory allocations as even though temporaries are created, their contents are moved 258rather than copied. 259[footnote The actual number generated will depend on the compiler, how well it optimises the code, and whether it supports 260rvalue references. The number of 11 temporaries was generated with Visual C++ 10] 261 262[important 263Expression templates can radically reorder the operations in an expression, for example: 264 265 a = (b * c) * a; 266 267Will get transformed into: 268 269 a *= c; 270 a *= b; 271 272If this is likely to be an issue for a particular application, then they should be disabled. 273] 274 275This library also extends expression template support to standard library functions like `abs` or `sin` with `number` 276arguments. This means that an expression such as: 277 278 y = abs(x); 279 280can be evaluated without a single temporary being calculated. Even expressions like: 281 282 y = sin(x); 283 284get this treatment, so that variable 'y' is used as "working storage" within the implementation of `sin`, 285thus reducing the number of temporaries used by one. Of course, should you write: 286 287 x = sin(x); 288 289Then we clearly can't use `x` as working storage during the calculation, so then a temporary variable 290is created in this case. 291 292Given the comments above, you might be forgiven for thinking that expression-templates are some kind of universal-panacea: 293sadly though, all tricks like this have their downsides. For one thing, expression template libraries 294like this one, tend to be slower to compile than their simpler cousins, they're also harder to debug 295(should you actually want to step through our code!), and rely on compiler optimizations being turned 296on to give really good performance. Also, since the return type from expressions involving `number`s 297is an "unmentionable implementation detail", you have to be careful to cast the result of an expression 298to the actual number type when passing an expression to a template function. For example, given: 299 300 template <class T> 301 void my_proc(const T&); 302 303Then calling: 304 305 my_proc(a+b); 306 307Will very likely result in obscure error messages inside the body of `my_proc` - since we've passed it 308an expression template type, and not a number type. Instead we probably need: 309 310 my_proc(my_number_type(a+b)); 311 312Having said that, these situations don't occur that often - or indeed not at all for non-template functions. 313In addition, all the functions in the Boost.Math library will automatically convert expression-template arguments 314to the underlying number type without you having to do anything, so: 315 316 mpfr_float_100 a(20), delta(0.125); 317 boost::math::gamma_p(a, a + delta); 318 319Will work just fine, with the `a + delta` expression template argument getting converted to an `mpfr_float_100` 320internally by the Boost.Math library. 321 322One other potential pitfall that's only possible in C++11: you should never store an expression template using: 323 324 auto my_expression = a + b - c; 325 326unless you're absolutely sure that the lifetimes of `a`, `b` and `c` will outlive that of `my_expression`. 327 328And finally... the performance improvements from an expression template library like this are often not as 329dramatic as the reduction in number of temporaries would suggest. For example if we compare this library with 330[mpfr_class] and [mpreal], with all three using the underlying [mpfr] library at 50 decimal digits precision then 331we see the following typical results for polynomial execution: 332 333[table Evaluation of Order 6 Polynomial. 334[[Library] [Relative Time] [Relative number of memory allocations]] 335[[number] [1.0 (0.00957s)] [1.0 (2996 total)]] 336[[[mpfr_class]] [1.1 (0.0102s)] [4.3 (12976 total)]] 337[[[mpreal]] [1.6 (0.0151s)] [9.3 (27947 total)]] 338] 339 340As you can see, the execution time increases a lot more slowly than the number of memory allocations. There are 341a number of reasons for this: 342 343* The cost of extended-precision multiplication and division is so great, that the times taken for these tend to 344swamp everything else. 345* The cost of an in-place multiplication (using `operator*=`) tends to be more than an out-of-place 346`operator*` (typically `operator *=` has to create a temporary workspace to carry out the multiplication, where 347as `operator*` can use the target variable as workspace). Since the expression templates carry out their 348magic by converting out-of-place operators to in-place ones, we necessarily take this hit. Even so the 349transformation is more efficient than creating the extra temporary variable, just not by as much as 350one would hope. 351 352Finally, note that `number` takes a second template argument, which, when set to `et_off` disables all 353the expression template machinery. The result is much faster to compile, but slower at runtime. 354 355We'll conclude this section by providing some more performance comparisons between these three libraries, 356again, all are using [mpfr] to carry out the underlying arithmetic, and all are operating at the same precision 357(50 decimal digits): 358 359[table Evaluation of Boost.Math's Bessel function test data 360[[Library] [Relative Time] [Relative Number of Memory Allocations]] 361[[mpfr_float_50] [1.0 (5.78s)] [1.0 (1611963)]] 362[[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)] 363 [1.1 (6.29s)] [2.64 (4260868)]] 364[[[mpfr_class]] [1.1 (6.28s)] [2.45 (3948316)]] 365[[[mpreal]] [1.65 (9.54s)] [8.21 (13226029)]] 366] 367 368[table Evaluation of Boost.Math's Non-Central T distribution test data 369[[Library][Relative Time][Relative Number of Memory Allocations]] 370[[number] [1.0 (263s)][1.0 (127710873)]] 371[[number<mpfr_float_backend<50>, et_off>[br](but with rvalue reference support)] 372 [1.0 (260s)][1.2 (156797871)]] 373[[[mpfr_class]] [1.1 (287s)][2.1 (268336640)]] 374[[[mpreal]] [1.5 (389s)][3.6 (466960653)]] 375] 376 377The above results were generated on Win32 compiling with Visual C++ 2010, all optimizations on (/Ox), 378with MPFR 3.0 and MPIR 2.3.0. 379 380[endsect] 381 382[section:tut Tutorial] 383 384In order to use this library you need to make two choices: 385 386* What kind of number do I want ([link boost_multiprecision.tut.ints integer], 387[link boost_multiprecision.tut.floats floating point] or [link boost_multiprecision.tut.rational rational]). 388* Which back-end do I want to perform the actual arithmetic (Boost-supplied, GMP, MPFR, Tommath etc)? 389 390[section:ints Integer Types] 391 392The following back-ends provide integer arithmetic: 393 394[table 395[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 396[[`cpp_int`][boost/multiprecision/cpp_int.hpp][2][None] 397 [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]]] 398[[`gmp_int`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 399[[`tom_int`][boost/multiprecision/tommath.hpp][2][[tommath]][Public domain back-end with no licence restrictions.][Slower than [gmp].]] 400] 401 402[section:cpp_int cpp_int] 403 404`#include <boost/multiprecision/cpp_int.hpp>` 405 406 namespace boost{ namespace multiprecision{ 407 408 typedef unspecified-type limb_type; 409 410 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 411 enum cpp_int_check_type { checked, unchecked }; 412 413 template <unsigned MinBits = 0, 414 unsigned MaxBits = 0, 415 cpp_integer_type SignType = signed_magnitude, 416 cpp_int_check_type Checked = unchecked, 417 class Allocator = std::allocator<limb_type> > 418 class cpp_int_backend; 419 // 420 // Expression templates default to et_off if there is no allocator: 421 // 422 template <unsigned MinBits, unsigned MaxBits, cpp_integer_type SignType, cpp_int_check_type Checked> 423 struct expression_template_default<cpp_int_backend<MinBits, MaxBits, SignType, Checked, void> > 424 { static const expression_template_option value = et_off; }; 425 426 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer 427 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 428 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number 429 430 // Fixed precision unsigned types: 431 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t; 432 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t; 433 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t; 434 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t; 435 436 // Fixed precision signed types: 437 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t; 438 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t; 439 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t; 440 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t; 441 442 // Over again, but with checking enabled this time: 443 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int; 444 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend; 445 typedef number<cpp_rational_backend> checked_cpp_rational; 446 447 // Checked fixed precision unsigned types: 448 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t; 449 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t; 450 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t; 451 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t; 452 453 // Fixed precision signed types: 454 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t; 455 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t; 456 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t; 457 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t; 458 459 }} // namespaces 460 461The `cpp_int_backend` type is normally used via one of the convenience typedefs given above. 462 463This back-end is the "Swiss Army Knife" of integer types as it can represent both fixed and 464[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] 465integer types, and both signed and unsigned types. There are five template arguments: 466 467[variablelist 468[[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory 469 allocation. When zero, this field is determined automatically based on how many bits can be stored 470 in union with the dynamic storage header: setting a larger value may improve performance as larger integer 471 values will be stored internally before memory allocation is required.]] 472[[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type. 473 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic 474 memory allocation will ever be performed: in this situation the Allocator parameter should be set to 475 type `void`. Note that this parameter should not be used simply to prevent large memory 476 allocations, not only is that role better performed by the allocator, but fixed precision 477 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]] 478[[SignType][Determines whether the resulting type is signed or not. Note that for 479[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types 480 this parameter must be `signed_magnitude`. For fixed precision 481 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]] 482[[Checked][This parameter has two values: `checked` or `unchecked`. See below.]] 483[[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]] 484] 485 486When the template parameter Checked is set to `checked` then the result is a ['checked-integer], checked 487and unchecked integers have the following properties: 488 489[table 490[[Condition][Checked-Integer][Unchecked-Integer]] 491[[Numeric overflow in fixed precision arithmetic][Throws a `std::overflow_error`.][Performs arithmetic modulo 2[super MaxBits]]] 492[[Constructing an integer from a value that can not be represented in the target type][Throws a `std::range_error`.] 493[Converts the value modulo 2[super MaxBits], signed to unsigned conversions extract the last MaxBits bits of the 4942's complement representation of the input value.]] 495[[Unsigned subtraction yielding a negative value.][Throws a `std::range_error`.][Yields the value that would 496result from treating the unsigned type as a 2's complement signed type.]] 497[[Attempting a bitwise operation on a negative value.][Throws a `std::range_error`][Yields the value, but not the bit pattern, 498that would result from performing the operation on a 2's complement integer type.]] 499] 500 501Things you should know when using this type: 502 503* Default constructed `cpp_int_backend`s have the value zero. 504* Division by zero results in a `std::overflow_error` being thrown. 505* Construction from a string that contains invalid non-numeric characters results in a `std::runtime_error` being thrown. 506* Since the precision of `cpp_int_backend` is necessarily limited when the allocator parameter is void, 507care should be taken to avoid numeric overflow when using this type 508unless you actually want modulo-arithmetic behavior. 509* The type uses a sign-magnitude representation internally, so type `int128_t` has 128-bits of precision plus an extra sign bit. 510In this respect the behaviour of these types differs from built-in 2's complement types. In might be tempting to use a 511127-bit type instead, and indeed this does work, but behaviour is still slightly different from a 2's complement built-in type 512as the min and max values are identical (apart from the sign), where as they differ by one for a true 2's complement type. 513That said it should be noted that there's no requirement for built-in types to be 2's complement either - it's simply that this 514is the most common format by far. 515* Attempting to print negative values as either an Octal or Hexadecimal string results in a `std::runtime_error` being thrown, 516this is a direct consequence of the sign-magnitude representation. 517* The fixed precision types `[checked_][u]intXXX_t` have expression template support turned off - it seems to make little 518difference to the performance of these types either way - so we may as well have the faster compile times by turning 519the feature off. 520* Unsigned types support subtraction - the result is "as if" a 2's complement operation had been performed as long as they are not 521 ['checked-integers] (see above). 522 In other words they behave pretty much as a built in integer type would in this situation. So for example if we were using 523 `uint128_t` then `uint128_t(1)-4` would result in the value `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFD` 524 of type `uint128_t`. However, had this operation been performed on `checked_uint128_t` then a `std::range_error` would have 525 been thrown. 526* Unary negation of unsigned types results in a compiler error (static assertion). 527* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 528* When used at fixed precision, the size of this type is always one machine word larger than you would expect for an N-bit integer: 529the extra word stores both the sign, and how many machine words in the integer are actually in use. 530The latter is an optimisation for larger fixed precision integers, so that a 1024-bit integer has almost the same performance 531characteristics as a 128-bit integer, rather than being 4 times slower for addition and 16 times slower for multiplication 532 (assuming the values involved would always fit in 128 bits). 533Typically this means you can use 534an integer type wide enough for the "worst case scenario" with only minor performance degradation even if most of the time 535the arithmetic could in fact be done with a narrower type. 536* When used at fixed precision and MaxBits is smaller than the number of bits in the largest native integer type, then 537internally `cpp_int_backend` switches to a "trivial" implementation where it is just a thin wrapper around a single 538integer. Note that it will still be slightly slower than a bare native integer, as it emulates a 539signed-magnitude representation rather than simply using the platforms native sign representation: this ensures 540there is no step change in behavior as a cpp_int grows in size. 541* Fixed precision `cpp_int`'s have some support for `constexpr` values and user-defined literals, see 542[link boost_multiprecision.tut.lits here] for the full description. For example `0xfffff_cppi1024` 543specifies a 1024-bit integer with the value 0xffff. This can be used to generate compile time constants that are 544too large to fit into any built in number type. 545 546[h5 Example:] 547 548[cpp_int_eg] 549 550[endsect] 551 552[section:gmp_int gmp_int] 553 554`#include <boost/multiprecision/gmp.hpp>` 555 556 namespace boost{ namespace multiprecision{ 557 558 class gmp_int; 559 560 typedef number<gmp_int > mpz_int; 561 562 }} // namespaces 563 564The `gmp_int` back-end is used via the typedef `boost::multiprecision::mpz_int`. It acts as a thin wrapper around the [gmp] `mpz_t` 565to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 566 567As well as the usual conversions from arithmetic and string types, type `mpz_int` is copy constructible and assignable from: 568 569* The [gmp] native types: `mpf_t`, `mpz_t`, `mpq_t`. 570* Instances of `number<T>` that are wrappers around those types: `number<gmp_float<N> >`, `number<gmp_rational>`. 571 572It's also possible to access the underlying `mpz_t` via the `data()` member function of `gmp_int`. 573 574Things you should know when using this type: 575 576* No changes are made to the GMP library's global settings - so you can safely mix this type with 577existing code that uses [gmp]. 578* Default constructed `gmp_int`s have the value zero (this is GMP's default behavior). 579* Formatted IO for this type does not support octal or hexadecimal notation for negative values, 580as a result performing formatted output on this type when the argument is negative and either of the flags 581`std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown. 582* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 583as a valid integer. 584* Division by zero results in a `std::overflow_error` being thrown. 585* Although this type is a wrapper around [gmp] it will work equally well with [mpir]. Indeed use of [mpir] 586is recommended on Win32. 587* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 588 589[h5 Example:] 590 591[mpz_eg] 592 593[endsect] 594 595[section:tom_int tom_int] 596 597`#include <boost/multiprecision/tommath.hpp>` 598 599 namespace boost{ namespace multiprecision{ 600 601 class tommath_int; 602 603 typedef number<tommath_int > tom_int; 604 605 }} // namespaces 606 607The `tommath_int` back-end is used via the typedef `boost::multiprecision::tom_int`. It acts as a thin wrapper around the [tommath] `tom_int` 608to provide an integer type that is a drop-in replacement for the native C++ integer types, but with unlimited precision. 609 610Things you should know when using this type: 611 612* Default constructed objects have the value zero (this is [tommath]'s default behavior). 613* Although `tom_int` is mostly a drop in replacement for the builtin integer types, it should be noted that it is a 614rather strange beast as it's a signed type that is not a 2's complement type. As a result the bitwise operations 615`| & ^` will throw a `std::runtime_error` exception if either of the arguments is negative. Similarly the complement 616operator`~` is deliberately not implemented for this type. 617* Formatted IO for this type does not support octal or hexadecimal notation for negative values, 618as a result performing formatted output on this type when the argument is negative and either of the flags 619`std::ios_base::oct` or `std::ios_base::hex` are set, will result in a `std::runtime_error` will be thrown. 620* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 621as a valid integer. 622* Division by zero results in a `std::overflow_error` being thrown. 623 624[h5 Example:] 625 626[tommath_eg] 627 628[endsect] 629 630[section:egs Examples] 631 632[import ../example/integer_examples.cpp] 633 634[section:factorials Factorials] 635[FAC1] 636[endsect] 637 638[section:bitops Bit Operations] 639[BITOPS] 640[endsect] 641 642[endsect] 643 644[endsect] 645 646[section:floats Floating Point Numbers] 647 648The following back-ends provide floating point arithmetic: 649 650[table 651[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 652[[`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.]] 653[[`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.]] 654[[`mpf_float<N>`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 655[[`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.]] 656[[`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.]] 657] 658 659[section:cpp_bin_float cpp_bin_float] 660 661`#include <boost/multiprecision/cpp_bin_float.hpp>` 662 663 namespace boost{ namespace multiprecision{ 664 665 enum digit_base_type 666 { 667 digit_base_2 = 2, 668 digit_base_10 = 10 669 }; 670 671 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0> 672 class cpp_bin_float; 673 674 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 675 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 676 677 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single; 678 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double; 679 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended; 680 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad; 681 682 }} // namespaces 683 684The `cpp_bin_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 685floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 686much greater precision. 687 688Type `cpp_bin_float` can be used at fixed precision by specifying a non-zero `Digits` template parameter. 689The typedefs `cpp_bin_float_50` and `cpp_bin_float_100` provide arithmetic types at 50 and 100 decimal digits precision 690respectively. 691 692Optionally, you can specify whether the precision is specified in decimal digits or binary bits - for example 693to declare a `cpp_bin_float` with exactly the same precision as `double` one would use 694`number<cpp_bin_float<53, digit_base_2> >`. The typedefs `cpp_bin_float_single`, `cpp_bin_float_double`, 695`cpp_bin_float_quad` and `cpp_bin_float_double_extended` provide 696software analogues of the IEEE single, double and quad float data types, plus the Intel-extended-double type respectively. 697Note that while these types are functionally equivalent to the native IEEE types, but they do not have the same size 698or bit-layout as true IEEE compatible types. 699 700Normally `cpp_bin_float` allocates no memory: all of the space required for its digits are allocated 701directly within the class. As a result care should be taken not to use the class with too high a digit count 702as stack space requirements can grow out of control. If that represents a problem then providing an allocator 703as a template parameter causes `cpp_bin_float` to dynamically allocate the memory it needs: this 704significantly reduces the size of `cpp_bin_float` and increases the viable upper limit on the number of digits 705at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 706as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 707Note that since the actual type of the objects allocated 708is completely opaque, the suggestion would be to use an allocator with `void` `value_type`, for example: 709`number<cpp_bin_float<1000, digit_base_10, std::allocator<void> > >`. 710 711The final template parameters determine the type and range of the exponent: parameter `Exponent` can be 712any signed integer type, but note that `MinExponent` and `MaxExponent` can not go right up to the limits 713of the `Exponent` type as there has to be a little extra headroom for internal calculations. You will 714get a compile time error if this is the case. In addition if MinExponent or MaxExponent are zero, then 715the library will choose suitable values that are as large as possible given the constraints of the type 716and need for extra headroom for internal calculations. 717 718There is full standard library and `numeric_limits` support available for this type. 719 720Things you should know when using this type: 721 722* Default constructed `cpp_bin_float`s have a value of zero. 723* The radix of this type is 2, even when the precision is specified as decimal digits. 724* The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow, 725and a NaN is generated for any mathematically undefined operation. 726* There is a `std::numeric_limits` specialisation for this type. 727* Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type - 728for example you can convert from `number<cpp_bin_float<50> >` to `number<cpp_bin_float<SomeOtherValue> >`. 729Narrowing conversions round to nearest and are `explicit`. 730* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 731as a valid floating point number. 732* All arithmetic operations are correctly rounded to nearest. String conversions and the `sqrt` function 733are also correctly rounded, but transcendental functions (sin, cos, pow, exp etc) are not. 734 735[h5 cpp_bin_float example:] 736 737[cpp_bin_float_eg] 738 739[endsect] 740 741[section:cpp_dec_float cpp_dec_float] 742 743`#include <boost/multiprecision/cpp_dec_float.hpp>` 744 745 namespace boost{ namespace multiprecision{ 746 747 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 748 class cpp_dec_float; 749 750 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 751 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 752 753 }} // namespaces 754 755The `cpp_dec_float` back-end is used in conjunction with `number`: It acts as an entirely C++ (header only and dependency free) 756floating-point number type that is a drop-in replacement for the native C++ floating-point types, but with 757much greater precision. 758 759Type `cpp_dec_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter. 760The typedefs `cpp_dec_float_50` and `cpp_dec_float_100` provide arithmetic types at 50 and 100 decimal digits precision 761respectively. Optionally, you can specify an integer type to use for the exponent, this defaults to a 32-bit integer type 762which is more than large enough for the vast majority of use cases, but larger types such as `long long` can also be specified 763if you need a truly huge exponent range. In any case the ExponentType must be a built in signed integer type at least 2 bytes 764and 16-bits wide. 765 766Normally `cpp_dec_float` allocates no memory: all of the space required for its digits are allocated 767directly within the class. As a result care should be taken not to use the class with too high a digit count 768as stack space requirements can grow out of control. If that represents a problem then providing an allocator 769as the final template parameter causes `cpp_dec_float` to dynamically allocate the memory it needs: this 770significantly reduces the size of `cpp_dec_float` and increases the viable upper limit on the number of digits 771at the expense of performance. However, please bear in mind that arithmetic operations rapidly become ['very] expensive 772as the digit count grows: the current implementation really isn't optimized or designed for large digit counts. 773 774There is full standard library and `numeric_limits` support available for this type. 775 776Things you should know when using this type: 777 778* Default constructed `cpp_dec_float`s have a value of zero. 779* The radix of this type is 10. As a result it can behave subtly differently from base-2 types. 780* The type has a number of internal guard digits over and above those specified in the template argument. 781Normally these should not be visible to the user. 782* The type supports both infinities and NaN's. An infinity is generated whenever the result would overflow, 783and a NaN is generated for any mathematically undefined operation. 784* There is a `std::numeric_limits` specialisation for this type. 785* Any `number` instantiated on this type, is convertible to any other `number` instantiated on this type - 786for example you can convert from `number<cpp_dec_float<50> >` to `number<cpp_dec_float<SomeOtherValue> >`. 787Narrowing conversions are truncating and `explicit`. 788* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 789as a valid floating point number. 790* The actual precision of a `cpp_dec_float` is always slightly higher than the number of digits specified in 791the template parameter, actually how much higher is an implementation detail but is always at least 8 decimal 792digits. 793* Operations involving `cpp_dec_float` are always truncating. However, note that since their are guard digits 794in effect, in practice this has no real impact on accuracy for most use cases. 795 796[h5 cpp_dec_float example:] 797 798[cpp_dec_float_eg] 799 800[endsect] 801 802[section:gmp_float gmp_float] 803 804`#include <boost/multiprecision/gmp.hpp>` 805 806 namespace boost{ namespace multiprecision{ 807 808 template <unsigned Digits10> 809 class gmp_float; 810 811 typedef number<gmp_float<50> > mpf_float_50; 812 typedef number<gmp_float<100> > mpf_float_100; 813 typedef number<gmp_float<500> > mpf_float_500; 814 typedef number<gmp_float<1000> > mpf_float_1000; 815 typedef number<gmp_float<0> > mpf_float; 816 817 }} // namespaces 818 819The `gmp_float` back-end is used in conjunction with `number` : it acts as a thin wrapper around the [gmp] `mpf_t` 820to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 821much greater precision. 822 823Type `gmp_float` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 824at variable precision by setting the template argument to zero. The typedefs mpf_float_50, mpf_float_100, 825mpf_float_500, mpf_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 826respectively. The typedef mpf_float provides a variable precision type whose precision can be controlled via the 827`number`s member functions. 828 829[note This type only provides standard library and `numeric_limits` support when the precision is fixed at compile time.] 830 831As well as the usual conversions from arithmetic and string types, instances of `number<mpf_float<N> >` are 832copy constructible and assignable from: 833 834* The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`. 835* The `number` wrappers around those types: `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`. 836 837It's also possible to access the underlying `mpf_t` via the `data()` member function of `gmp_float`. 838 839Things you should know when using this type: 840 841* Default constructed `gmp_float`s have the value zero (this is the [gmp] library's default behavior). 842* No changes are made to the [gmp] library's global settings, so this type can be safely mixed with 843existing [gmp] code. 844* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 845* It is not possible to round-trip objects of this type to and from a string and get back 846exactly the same value. This appears to be a limitation of [gmp]. 847* Since the underlying [gmp] types have no notion of infinities or NaN's, care should be taken 848to avoid numeric overflow or division by zero. That latter will result in a std::overflow_error being thrown, 849while generating excessively large exponents may result in instability of the underlying [gmp] 850library (in testing, converting a number with an excessively large or small exponent 851to a string caused [gmp] to segfault). 852* This type can equally be used with [mpir] as the underlying implementation - indeed that is 853the recommended option on Win32. 854* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 855as a valid floating point number. 856* Division by zero results in a `std::overflow_error` being thrown. 857 858[h5 [gmp] example:] 859 860[mpf_eg] 861 862[endsect] 863 864[section:mpfr_float mpfr_float] 865 866`#include <boost/multiprecision/mpfr.hpp>` 867 868 namespace boost{ namespace multiprecision{ 869 870 enum mpfr_allocation_type 871 { 872 allocate_stack, 873 allocate_dynamic 874 }; 875 876 template <unsigned Digits10, mpfr_allocation_type AllocateType = allocate_dynamic> 877 class mpfr_float_backend; 878 879 typedef number<mpfr_float_backend<50> > mpfr_float_50; 880 typedef number<mpfr_float_backend<100> > mpfr_float_100; 881 typedef number<mpfr_float_backend<500> > mpfr_float_500; 882 typedef number<mpfr_float_backend<1000> > mpfr_float_1000; 883 typedef number<mpfr_float_backend<0> > mpfr_float; 884 885 typedef number<mpfr_float_backend<50, allocate_stack> > static_mpfr_float_50; 886 typedef number<mpfr_float_backend<100, allocate_stack> > static_mpfr_float_100; 887 888 }} // namespaces 889 890The `mpfr_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfr] `mpfr_t` 891to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 892much greater precision. 893 894Type `mpfr_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 895at variable precision by setting the template argument to zero. The typedefs mpfr_float_50, mpfr_float_100, 896mpfr_float_500, mpfr_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 897respectively. The typedef mpfr_float provides a variable precision type whose precision can be controlled via the 898`number`s member functions. 899 900In addition the second template parameter lets you choose between dynamic allocation (the default, 901and uses MPFR's normal allocation routines), 902or stack allocation (where all the memory required for the underlying data types is stored 903within `mpfr_float_backend`). The latter option can result in significantly faster code, at the 904expense of growing the size of `mpfr_float_backend`. It can only be used at fixed precision, and 905should only be used for lower digit counts. Note that we can not guarantee that using `allocate_stack` 906won't cause any calls to mpfr's allocation routines, as mpfr may call these inside it's own code. 907The following table gives an idea of the performance tradeoff's at 50 decimal digits 908precision[footnote Compiled with VC++10 and /Ox, with MPFR-3.0.0 and MPIR-2.3.0]: 909 910[table 911[[Type][Bessel function evaluation, relative times]] 912[[`number<mpfr_float_backend<50, allocate_static>, et_on>`][1.0 (5.5s)]] 913[[`number<mpfr_float_backend<50, allocate_static>, et_off>`][1.05 (5.8s)]] 914[[`number<mpfr_float_backend<50, allocate_dynamic>, et_on>`][1.05 (5.8s)]] 915[[`number<mpfr_float_backend<50, allocate_dynamic>, et_off>`][1.16 (6.4s)]] 916] 917 918[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 919 920As well as the usual conversions from arithmetic and string types, instances of `number<mpfr_float_backend<N> >` are 921copy constructible and assignable from: 922 923* The [gmp] native types `mpf_t`, `mpz_t`, `mpq_t`. 924* The [mpfr] native type `mpfr_t`. 925* The `number` wrappers around those types: `number<mpfr_float_backend<M> >`, `number<mpf_float<M> >`, `number<gmp_int>`, `number<gmp_rational>`. 926 927It's also possible to access the underlying `mpfr_t` via the data() member function of `mpfr_float_backend`. 928 929Things you should know when using this type: 930 931* A default constructed `mpfr_float_backend` is set to a NaN (this is the default [mpfr] behavior). 932* All operations use round to nearest. 933* No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing 934[mpfr] or [gmp] code. 935* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. 936* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 937* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 938as a valid floating point number. 939* Division by zero results in an infinity. 940 941[h5 [mpfr] example:] 942 943[mpfr_eg] 944 945[endsect] 946 947[section:float128 float128] 948 949`#include <boost/multiprecision/float128.hpp>` 950 951 namespace boost{ namespace multiprecision{ 952 953 class float128_backend; 954 955 typedef number<float128_backend, et_off> float128; 956 957 }} // namespaces 958 959The `float128` number type is a very thin wrapper around GCC's `__float128` or Intel's `_Quad` data types 960and provides an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 961a 113 bit mantissa, and compatible with FORTRAN's 128-bit QUAD real. 962 963All the usual standard library and `numeric_limits` support are available, performance should be equivalent 964to the underlying native types: for example the LINPACK benchmarks for GCC's `__float128` and 965`boost::multiprecision::float128` both achieved 5.6 MFLOPS[footnote On 64-bit Ubuntu 11.10, GCC-4.8.0, Intel Core 2 Duo T5800.]. 966 967As well as the usual conversions from arithmetic and string types, instances of `float128` are 968copy constructible and assignable from GCC's `__float128` and Intel's `_Quad` data types. 969 970It's also possible to access the underlying `__float128` or `_Quad` type via the `data()` member 971function of `float128_backend`. 972 973Things you should know when using this type: 974 975* Default constructed `float128`s have the value zero. 976* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 977* It is not possible to round-trip objects of this type to and from a string and get back 978exactly the same value when compiled with Intel's C++ compiler and using `_Quad` as the underlying type: this is a current limitation of 979our code. Round tripping when using `__float128` as the underlying type is possible (both for GCC and Intel). 980* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 981as a valid floating point number. 982* Division by zero results in an infinity being produced. 983* Type `float128` can be used as a literal type (constexpr support). 984* When using the Intel compiler, the underlying type defaults to `__float128` if it's available and `_Quad` if not. You can override 985the default by defining either `BOOST_MP_USE_FLOAT128` or `BOOST_MP_USE_QUAD`. 986* When the underlying type is Intel's `_Quad` type, the code must be compiled with the compiler option `-Qoption,cpp,--extended_float_type`. 987 988[h5 float128 example:] 989 990[float128_eg] 991 992[endsect] 993 994[section:fp_eg Examples] 995 996[import ../example/floating_point_examples.cpp] 997 998[section:aos Area of Circle] 999 1000[AOS1] 1001[AOS2] 1002[AOS3] 1003 1004[endsect] 1005 1006[section:jel Defining a Special Function.] 1007 1008[JEL] 1009 1010[endsect] 1011 1012[section:nd Calculating a Derivative] 1013 1014[ND1] 1015[ND2] 1016[ND3] 1017 1018[endsect] 1019 1020[section:gi Calculating an Integral] 1021 1022[GI1] 1023[GI2] 1024 1025[endsect] 1026 1027[section:poly_eg Polynomial Evaluation] 1028 1029[POLY] 1030 1031[endsect] 1032 1033[endsect] 1034 1035[endsect] 1036 1037[section:interval Interval Number Types] 1038 1039There is one currently only one interval number type supported - [mpfi]. 1040 1041[section:mpfi mpfi_float] 1042 1043`#include <boost/multiprecision/mpfi.hpp>` 1044 1045 namespace boost{ namespace multiprecision{ 1046 1047 template <unsigned Digits10> 1048 class mpfi_float_backend; 1049 1050 typedef number<mpfi_float_backend<50> > mpfi_float_50; 1051 typedef number<mpfi_float_backend<100> > mpfifloat_100; 1052 typedef number<mpfi_float_backend<500> > mpfifloat_500; 1053 typedef number<mpfi_float_backend<1000> > mpfi_float_1000; 1054 typedef number<mpfi_float_backend<0> > mpfi_float; 1055 1056 }} // namespaces 1057 1058The `mpfi_float_backend` type is used in conjunction with `number`: It acts as a thin wrapper around the [mpfi] `mpfi_t` 1059to provide an real-number type that is a drop-in replacement for the native C++ floating-point types, but with 1060much greater precision and implementing interval arithmetic. 1061 1062Type `mpfi_float_backend` can be used at fixed precision by specifying a non-zero `Digits10` template parameter, or 1063at variable precision by setting the template argument to zero. The typedefs mpfi_float_50, mpfi_float_100, 1064mpfi_float_500, mpfi_float_1000 provide arithmetic types at 50, 100, 500 and 1000 decimal digits precision 1065respectively. The typedef mpfi_float provides a variable precision type whose precision can be controlled via the 1066`number`s member functions. 1067 1068[note This type only provides `numeric_limits` support when the precision is fixed at compile time.] 1069 1070As well as the usual conversions from arithmetic and string types, instances of `number<mpfi_float_backend<N> >` are 1071copy constructible and assignable from: 1072 1073* The [mpfi] native type `mpfi_t`. 1074* The `number` wrappers around [mpfi] or [mpfr]: `number<mpfi_float_backend<M> >` and `number<mpfr_float<M> >`. 1075* There is a two argument constructor taking two `number<mpfr_float<M> >` arguments specifying the interval. 1076 1077It's also possible to access the underlying `mpfi_t` via the data() member function of `mpfi_float_backend`. 1078 1079Things you should know when using this type: 1080 1081* A default constructed `mpfi_float_backend` is set to a NaN (this is the default [mpfi] behavior). 1082* No changes are made to [gmp] or [mpfr] global settings, so this type can coexist with existing 1083[mpfr] or [gmp] code. 1084* The code can equally use [mpir] in place of [gmp] - indeed that is the preferred option on Win32. 1085* This backend supports rvalue-references and is move-aware, making instantiations of `number` on this backend move aware. 1086* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be interpreted 1087as a valid floating point number. 1088* Division by zero results in an infinity. 1089 1090There are some additional non member functions for working on intervals: 1091 1092 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1093 number<mpfr_float_backend<Digits10>, ExpressionTemplates> lower(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1094 1095Returns the lower end of the interval. 1096 1097 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1098 number<mpfr_float_backend<Digits10>, ExpressionTemplates> upper(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1099 1100Returns the upper end of the interval. 1101 1102 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1103 number<mpfr_float_backend<Digits10>, ExpressionTemplates> median(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1104 1105Returns the mid point of the interval. 1106 1107 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1108 number<mpfr_float_backend<Digits10>, ExpressionTemplates> width(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& val); 1109 1110Returns the absolute width of the interval. 1111 1112 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1113 number<mpfi_float_backend<Digits10>, ExpressionTemplates> intersect( 1114 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1115 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1116 1117Returns the interval which is the intersection of the ['a] and ['b]. Returns an 1118unspecified empty interval if there is no such intersection. 1119 1120 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1121 number<mpfi_float_backend<Digits10>, ExpressionTemplates> hull( 1122 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1123 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1124 1125Returns the interval which is the union of ['a] and ['b]. 1126 1127 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1128 bool overlap(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1129 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1130 1131Returns `true` only if the intervals ['a] and ['b] overlap. 1132 1133 template <unsigned Digits10, expression_template_option ExpressionTemplates1, expression_template_option ExpressionTemplates2> 1134 bool in(const number<mpfr_float_backend<Digits10>, ExpressionTemplates1>& a, 1135 const number<mpfi_float_backend<Digits10>, ExpressionTemplates2>& b); 1136 1137Returns `true` only if point ['a] is contained within the interval ['b]. 1138 1139 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1140 bool zero_in(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1141 1142Returns `true` only if the interval ['a] contains the value zero. 1143 1144 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1145 bool subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1146 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1147 1148Returns `true` only if ['a] is a subset of ['b]. 1149 1150 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1151 bool proper_subset(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a, 1152 const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& b); 1153 1154Returns `true` only if ['a] is a proper subset of ['b]. 1155 1156 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1157 bool empty(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1158 1159Returns `true` only if ['a] is an empty interval, equivalent to `upper(a) < lower(a)`. 1160 1161 template <unsigned Digits10, expression_template_option ExpressionTemplates> 1162 bool singleton(const number<mpfi_float_backend<Digits10>, ExpressionTemplates>& a); 1163 1164Returns `true` if `lower(a) == upper(a)`. 1165 1166[h5 [mpfi] example:] 1167 1168[mpfi_eg] 1169 1170[endsect] 1171 1172[endsect] 1173 1174[section:rational Rational Number Types] 1175 1176The following back-ends provide rational number arithmetic: 1177 1178[table 1179[[Backend Type][Header][Radix][Dependencies][Pros][Cons]] 1180[[`cpp_rational`][boost/multiprecision/cpp_int.hpp][2][None][An all C++ Boost-licensed implementation.][Slower than [gmp].]] 1181[[`gmp_rational`][boost/multiprecision/gmp.hpp][2][[gmp]][Very fast and efficient back-end.][Dependency on GNU licensed [gmp] library.]] 1182[[`tommath_rational`][boost/multiprecision/tommath.hpp][2][[tommath]][All C/C++ implementation that's Boost Software Licence compatible.][Slower than [gmp].]] 1183[[`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.]] 1184[[`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.]] 1185] 1186 1187[section:cpp_rational cpp_rational] 1188 1189`#include <boost/multiprecision/cpp_int.hpp>` 1190 1191 namespace boost{ namespace multiprecision{ 1192 1193 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 1194 1195 typedef number<cpp_rational_backend> cpp_rational; 1196 1197 }} // namespaces 1198 1199The `cpp_rational_backend` type is used via the typedef `boost::multiprecision::cpp_rational`. It provides 1200a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1201 1202As well as the usual conversions from arithmetic and string types, instances of `cpp_rational` are copy constructible 1203and assignable from type `cpp_int`. 1204 1205There is also a two argument constructor that accepts a numerator and denominator: both of type `cpp_int`. 1206 1207There are also non-member functions: 1208 1209 cpp_int numerator(const cpp_rational&); 1210 cpp_int denominator(const cpp_rational&); 1211 1212which return the numerator and denominator of the number. 1213 1214Things you should know when using this type: 1215 1216* Default constructed `cpp_rational`s have the value zero. 1217* Division by zero results in a `std::overflow_error` being thrown. 1218* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1219interpreted as a valid rational number. 1220 1221[h5 Example:] 1222 1223[cpp_rational_eg] 1224 1225[endsect] 1226 1227[section:gmp_rational gmp_rational] 1228 1229`#include <boost/multiprecision/gmp.hpp>` 1230 1231 namespace boost{ namespace multiprecision{ 1232 1233 class gmp_rational; 1234 1235 typedef number<gmp_rational > mpq_rational; 1236 1237 }} // namespaces 1238 1239The `gmp_rational` back-end is used via the typedef `boost::multiprecision::mpq_rational`. It acts as a thin wrapper around the [gmp] `mpq_t` 1240to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1241 1242As well as the usual conversions from arithmetic and string types, instances of `number<gmp_rational>` are copy constructible 1243and assignable from: 1244 1245* The [gmp] native types: `mpz_t`, `mpq_t`. 1246* `number<gmp_int>`. 1247 1248There is also a two-argument constructor that accepts a numerator and denominator (both of type `number<gmp_int>`). 1249 1250There are also non-member functions: 1251 1252 mpz_int numerator(const mpq_rational&); 1253 mpz_int denominator(const mpq_rational&); 1254 1255which return the numerator and denominator of the number. 1256 1257It's also possible to access the underlying `mpq_t` via the `data()` member function of `mpq_rational`. 1258 1259Things you should know when using this type: 1260 1261* Default constructed `mpq_rational`s have the value zero (this is the [gmp] default behavior). 1262* Division by zero results in a `std::overflow_error` being thrown. 1263* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1264interpreted as a valid rational number. 1265* No changes are made to the [gmp] library's global settings, so this type can coexist with existing 1266[gmp] code. 1267* The code can equally be used with [mpir] as the underlying library - indeed that is the preferred option on Win32. 1268 1269[h5 Example:] 1270 1271[mpq_eg] 1272 1273[endsect] 1274 1275[section:tommath_rational tommath_rational] 1276 1277`#include <boost/multiprecision/tommath.hpp>` 1278 1279 namespace boost{ namespace multiprecision{ 1280 1281 typedef rational_adpater<tommath_int> tommath_rational; 1282 typedef number<tommath_rational > tom_rational; 1283 1284 }} // namespaces 1285 1286The `tommath_rational` back-end is used via the typedef `boost::multiprecision::tom_rational`. It acts as a thin wrapper around 1287`boost::rational<tom_int>` 1288to provide a rational number type that is a drop-in replacement for the native C++ number types, but with unlimited precision. 1289 1290The advantage of using this type rather than `boost::rational<tom_int>` directly, is that it is expression-template enabled, 1291greatly reducing the number of temporaries created in complex expressions. 1292 1293There are also non-member functions: 1294 1295 tom_int numerator(const tom_rational&); 1296 tom_int denominator(const tom_rational&); 1297 1298which return the numerator and denominator of the number. 1299 1300Things you should know when using this type: 1301 1302* Default constructed `tom_rational`s have the value zero (this the inherited Boost.Rational behavior). 1303* Division by zero results in a `std::overflow_error` being thrown. 1304* Conversion from a string results in a `std::runtime_error` being thrown if the string can not be 1305interpreted as a valid rational number. 1306* No changes are made to [tommath]'s global state, so this type can safely coexist with other [tommath] code. 1307* Performance of this type has been found to be pretty poor - this need further investigation - but it appears that Boost.Rational 1308needs some improvement in this area. 1309 1310[h5 Example:] 1311 1312[mp_rat_eg] 1313 1314[endsect] 1315 1316[section:br Use With Boost.Rational] 1317 1318All of the integer types in this library can be used as template arguments to `boost::rational<IntType>`. 1319 1320Note that using the library in this way largely negates the effect of the expression templates in `number`. 1321 1322[endsect] 1323 1324[section:rational_adaptor rational_adaptor] 1325 1326 namespace boost{ namespace multiprecision{ 1327 1328 template <class IntBackend> 1329 class rational_adpater; 1330 1331 }} 1332 1333The class template `rational_adaptor` is a back-end for `number` which converts any existing integer back-end 1334into a rational-number back-end. 1335 1336So for example, given an integer back-end type `MyIntegerBackend`, the use would be something like: 1337 1338 typedef number<MyIntegerBackend> MyInt; 1339 typedef number<rational_adaptor<MyIntegerBackend> > MyRational; 1340 1341 MyRational r = 2; 1342 r /= 3; 1343 MyInt i = numerator(r); 1344 assert(i == 2); 1345 1346[endsect] 1347 1348[endsect] 1349 1350[section:misc Miscellaneous Number Types.] 1351 1352Backend types listed in this section are predominantly designed to aid debugging. 1353 1354[section:logged_adaptor logged_adaptor] 1355 1356`#include <boost/multiprecision/logged_adaptor.hpp>` 1357 1358 namespace boost{ namespace multiprecision{ 1359 1360 template <class Backend> 1361 void log_postfix_event(const Backend& result, const char* event_description); 1362 template <class Backend, class T> 1363 void log_postfix_event(const Backend& result1, const T& result2, const char* event_description); 1364 1365 template <class Backend> 1366 void log_prefix_event(const Backend& arg1, const char* event_description); 1367 template <class Backend, class T> 1368 void log_prefix_event(const Backend& arg1, const T& arg2, const char* event_description); 1369 template <class Backend, class T, class U> 1370 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const char* event_description); 1371 template <class Backend, class T, class U, class V> 1372 void log_prefix_event(const Backend& arg1, const T& arg2, const U& arg3, const V& arg4, const char* event_description); 1373 1374 template <Backend> 1375 class logged_adaptor; 1376 1377 }} // namespaces 1378 1379The `logged_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1380some other backend to class `number` and logs all the events that take place on that object. Before any number operation takes 1381place, it calls `log_prefix_event` with the arguments to the operation (up to 4), plus a string describing the operation. 1382Then after the operation it calls `log_postfix_event` with the result of the operation, plus a string describing the operation. 1383Optionally, `log_postfix_event` takes a second result argument: this occurs when the result of the operation is not a `number`, 1384for example when `fpclassify` is called, `log_postfix_event` will be called with `result1` being the argument to the function, and 1385`result2` being the integer result of `fpclassify`. 1386 1387The default versions of `log_prefix_event` and `log_postfix_event` do nothing, it is therefore up to the user to overload these 1388for the particular backend being observed. 1389 1390This type provides `numeric_limits` support whenever the template argument Backend does so. 1391 1392This type is particularly useful when combined with an interval number type - in this case we can use `log_postfix_event` 1393to monitor the error accumulated after each operation. We could either set some kind of trap whenever the accumulated error 1394exceeds some threshold, or simply print out diagnostic information. Using this technique we can quickly locate the cause of 1395numerical instability in a particular routine. The following example demonstrates this technique in a trivial algorithm 1396that deliberately introduces cancellation error: 1397 1398[logged_adaptor] 1399 1400When we examine program output we can clearly see that the diameter of the interval increases after each subtraction: 1401 1402[logged_adaptor_output] 1403 1404[endsect] 1405 1406[section:debug_adaptor debug_adaptor] 1407 1408`#include <boost/multiprecision/debug_adaptor.hpp>` 1409 1410 namespace boost{ namespace multiprecision{ 1411 1412 template <Backend> 1413 class debug_adaptor; 1414 1415 }} // namespaces 1416 1417The `debug_adaptor` type is used in conjunction with `number` and some other backend type: it acts as a thin wrapper around 1418some other backend to class `number` and intercepts all operations on that object storing the result as a string within itself. 1419 1420This type provides `numeric_limits` support whenever the template argument Backend does so. 1421 1422This type is particularly useful when your debugger provides a good view of `std::string`: when this is the case 1423multiprecision values can easily be inspected in the debugger by looking at the `debug_value` member of `debug_adaptor`. 1424The down side of this approach is that runtimes are much slower when using this type. Set against that it can make 1425debugging very much easier, certainly much easier than sprinkling code with `printf` statements. 1426 1427When used in conjunction with the Visual C++ debugger visualisers, the value of a multiprecision type that uses this 1428backend is displayed in the debugger just a builtin value would be, here we're inspecting a value of type 1429`number<debug_adaptor<cpp_dec_float<50> > >`: 1430 1431[$../debugger1.png] 1432 1433Otherwise you will need to expand out the view and look at the "debug_value" member: 1434 1435[$../debugger2.png] 1436 1437It works for all the backend types equally too, here it is inspecting a `number<debug_adaptor<gmp_rational> >`: 1438 1439[$../debugger3.png] 1440 1441 1442[endsect] 1443 1444[section:visualizers Visual C++ Debugger Visualizers] 1445 1446Let's face it debugger multiprecision numbers is hard - simply because we can't easily inspect the value of the numbers. 1447Visual C++ provides a partial solution in the shape of "visualizers" which provide improved views of complex data structures, 1448these visualizers need to be added to the `[Visualizer]` section of `autoexp.dat` located in the `Common7/Packages/Debugger` 1449directory of your Visual Studio installation. The actual visualizer code is in the sandbox 1450[@https://svn.boost.org/svn/boost/sandbox/boost_docs/subprojects/DebuggerVisualizers/multiprecision.vis.txt here] - just cut and paste the code 1451into your `autoexp.dat` file. 1452 1453[note These visualizers have only been tested with VC10, also given the ability of buggy visualizers to crash your Visual C++ 1454debugger, make sure you back up `autoexp.dat` file before using these!!] 1455 1456The first visualizer provides improved views of `debug_adaptor`: 1457 1458[$../debugger1.png] 1459 1460The next visualizer provides improved views of cpp_int: small numbers are displayed as actual values, while larger numbers are 1461displayed as an array of hexadecimal parts, with the most significant part first. 1462 1463Here's what it looks like for small values: 1464 1465[$../debugger4.png] 1466 1467And for larger values: 1468 1469[$../debugger5.png] 1470 1471There is also a `~raw` child member that 1472lets you see the actual members of the class: 1473 1474[$../debugger6.png] 1475 1476The visualizer for `cpp_dec_float` shows the first few digits of the value in the preview field, and the full array of digits 1477when you expand the view. As before the `~raw` child gives you access to the actual data members: 1478 1479[$../debugger7.png] 1480 1481[endsect] 1482 1483[endsect] 1484 1485[section:conversions Constructing and Interconverting Between Number Types] 1486 1487All of the number types that are based on `number` have certain conversion rules in common. 1488In particular: 1489 1490* Any number type can be constructed (or assigned) from any builtin arithmetic type, as long 1491 as the conversion isn't lossy (for example float to int conversion): 1492 1493 cpp_dec_float_50 df(0.5); // OK construction from double 1494 cpp_int i(450); // OK constructs from signed int 1495 cpp_int j = 3.14; // Error, lossy conversion. 1496 1497* A number can be explicitly constructed from an arithmetic type, even when the conversion is lossy: 1498 1499 cpp_int i(3.14); // OK explicit conversion 1500 i = static_cast<cpp_int>(3.14) // OK explicit conversion 1501 i.assign(3.14); // OK, explicit assign and avoid a temporary from the cast above 1502 i = 3.14; // Error, no implicit assignment operator for lossy conversion. 1503 cpp_int j = 3.14; // Error, no implicit constructor for lossy conversion. 1504 1505* A `number` can be converted to any built in type, via the `convert_to` member function: 1506 1507 mpz_int z(2); 1508 int i = z.template convert_to<int>(); // sets i to 2 1509 1510* Conversions to rational numbers from floating point ones are always allowed, and are exact and implicit 1511as long as the rational number uses an unbounded integer type. Please be aware that constructing a rational 1512number from an extended precision floating point type with a large exponent range can effectively run the system 1513out of memory, as in the extreme case ['2[super max_exponent] / CHAR_BITS] bytes of storage may be required. This 1514does not represent a problem for built in floating point types however, as the exponent range for these is rather 1515limited. 1516 1517* Conversions to floating point numbers from rational ones are rounded to nearest (less than 0.5ulp error) 1518as long as the floating point number is binary, and the integer type used by the rational number is unbounded. 1519 1520Additional conversions may be supported by particular backends. 1521 1522* A `number` can be converted to any built in type, via an explicit conversion operator: 1523this functionality is only available on compilers supporting C++11's explicit conversion syntax. 1524 1525 mpz_int z(2); 1526 int i = z; // Error, implicit conversion not allowed. 1527 int j = static_cast<int>(z); // OK explicit conversion. 1528 1529* Any number type can be ['explicitly] constructed (or assigned) from a `const char*` or a `std::string`: 1530 1531 // pi to 50 places from a string: 1532 cpp_dec_float_50 df("3.14159265358979323846264338327950288419716939937510"); 1533 // Integer type will automatically detect "0x" and "0" prefixes and parse the string accordingly: 1534 cpp_int i("0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFF000000000000000"); 1535 // Invalid input always results in a std::runtime_error being thrown: 1536 i = static_cast<cpp_int>("3.14"); 1537 // implicit conversions from strings are not allowed: 1538 i = "23"; // Error, no assignment operator for implicit conversion from string 1539 // assign member function, avoids having to create a temporary via a static_cast: 1540 i.assign("23"); // OK 1541 1542* Any number type will interoperate with the builtin types in arithmetic expressions as long as the conversions 1543are not lossy: 1544 1545 // pi to 50 places from a string: 1546 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510"; 1547 // Multiply by 2 - using an integer literal here is usually more efficient 1548 // than constructing a temporary: 1549 df *= 2; 1550 1551 // You can't mix integer types with floats though: 1552 cpp_int i = 2; 1553 i *= 3.14; // Error, no *= operator will be found. 1554 1555* Any number type can be streamed to and from the C++ iostreams: 1556 1557 1558 cpp_dec_float_50 df = "3.14159265358979323846264338327950288419716939937510"; 1559 // Now print at full precision: 1560 std::cout << std::setprecision(std::numeric_limits<cpp_dec_float_50>::max_digits10) 1561 << df << std::endl 1562 cpp_int i = 1; 1563 i <<= 256; 1564 // Now print in hex format with prefix: 1565 std::cout << std::hex << std::showbase << i << std::endl; 1566 1567* Interconversions between number types of the same family are allowed and are implicit conversions if no 1568loss of precision is involved, and explicit if it is: 1569 1570 int128_t i128 = 0; 1571 int266_t i256 = i128; // OK implicit widening conversion 1572 i128_t = i256; // Error, no assignment operator found, narrowing conversion is explicit 1573 i128_t = static_cast<int128_t>(i256); // OK, explicit narrowing conversion 1574 1575 mpz_int z = 0; 1576 mpf_float f = z; // OK, GMP handles this conversion natively, and it's not lossy and therefore implicit 1577 1578 mpf_float_50 f50 = 2; 1579 f = f50; // OK, conversion from fixed to variable precision, f will have 50 digits precision. 1580 f50 = f; // Error, conversion from variable to fixed precision is potentially lossy, explicit cast required. 1581 1582* Some interconversions between number types are completely generic, and are always available, albeit the conversions are always ['explicit]: 1583 1584 cpp_int cppi(2); 1585 // We can always convert between numbers of the same category - 1586 // int to int, rational to rational, or float to float, so this is OK 1587 // as long as we use an explicit conversion: 1588 mpz_int z(cppi); 1589 // We can always promote from int to rational, int to float, or rational to float: 1590 cpp_rational cppr(cppi); // OK, int to rational 1591 cpp_dec_float_50 df(cppi); // OK, int to float 1592 df = static_cast<cpp_dec_float_50>(cppr); // OK, explicit rational to float conversion 1593 // However narrowing and/or implicit conversions always fail: 1594 cppi = df; // Compiler error, conversion not allowed 1595 1596* Other interconversions may be allowed as special cases, whenever the backend allows it: 1597 1598 mpf_t m; // Native GMP type. 1599 mpf_init_set_ui(m, 0); // set to a value; 1600 mpf_float i(m); // copies the value of the native type. 1601 1602More information on what additional types a backend supports conversions from are given in the tutorial for each backend. 1603The converting constructor will be implicit if the backend's converting constructor is also implicit, and explicit if the 1604backends converting constructor is also explicit. 1605 1606[endsect] 1607 1608[section:random Generating Random Numbers] 1609 1610Random numbers are generated in conjunction with Boost.Random. However, since Boost.Random is unaware 1611of [@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] numbers, it's necessary to include the header: 1612 1613 #include <boost/multiprecision/random.hpp> 1614 1615In order to act as a bridge between the two libraries. 1616 1617Integers with /N/ random bits are generated using `independent_bits_engine`: 1618 1619[random_eg1] 1620 1621Alternatively we can generate integers in a given range using `uniform_int_distribution`, this will 1622invoke the underlying engine multiple times to build up the required number of bits in the result: 1623 1624[random_eg2] 1625 1626Floating point values in \[0,1) are generated using `uniform_01`, the trick here is to ensure 1627that the underlying generator produces as many random bits as there are digits in the floating 1628point type. As above `independent_bits_engine` can be used for this purpose, note that we also have to 1629convert decimal digits (in the floating point type) to bits (in the random number generator): 1630 1631[random_eg3] 1632 1633Finally, we can modify the above example to produce numbers distributed according to some distribution: 1634 1635[random_eg4] 1636 1637[endsect] 1638 1639[section:primetest Primality Testing] 1640 1641The library implements a Miller-Rabin test for primality: 1642 1643 #include <boost/multiprecision/miller_rabin.hpp> 1644 1645 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 1646 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials, Engine& gen); 1647 1648 template <class Backend, expression_template_option ExpressionTemplates, class Engine> 1649 bool miller_rabin_test(const number<Backend, ExpressionTemplates>& n, unsigned trials); 1650 1651These functions perform a Miller-Rabin test for primality, if the result is `false` then /n/ is definitely composite, 1652while if the result is true then n is probably prime. The probability to declare a composite n as probable prime is 1653at most 0.25[super trials]. Note that this does not allow a statement about the probability of n being actually 1654prime (for that, the prior probability would have to be known). The algorithm used performs some 1655trial divisions to exclude small prime factors, does one Fermat test to exclude many more composites, and then 1656uses the Miller-Rabin algorithm straight out of 1657Knuth Vol 2, which recommends 25 trials for a pretty strong likelihood that /n/ is prime. 1658 1659The third optional argument is for a Uniform Random Number Generator from Boost.Random. When not provided the `mt19937` 1660generator is used. Note that when producing random primes then you should probably use a different random number generator 1661to produce candidate prime numbers for testing, than is used internally by `miller_rabin_test` for determining 1662whether the value is prime. It also helps of course to seed the generators with some source of randomness. 1663 1664The following example searches for a prime `p` for which `(p-1)/2` is also probably prime: 1665 1666[safe_prime] 1667 1668[endsect] 1669 1670[section:lits Literal Types and `constexpr` Support] 1671 1672[note The features described in this section make heavy use of C++11 language features, currently 1673(as of May 2013) only 1674GCC-4.7 and later, and Clang 3.3 and later have the support required to make these features work.] 1675 1676There is limited support for `constexpr` and user-defined literals in the library, currently the 1677`number` front end supports `constexpr` 1678on default construction and all forwarding constructors, but not on any of the non-member operators. So if 1679some type `B` is a literal type, then `number<B>` is also a literal type, and you will be able to 1680compile-time-construct such a type from any literal that `B` is compile-time-constructible from. 1681However, you will not be able to perform compile-time arithmetic on such types. 1682 1683Currently the only backend type provided by the library that is also a literal type are instantiations 1684of `cpp_int_backend` where the Allocator parameter is type `void`, and the Checked parameter is 1685`boost::multiprecision::unchecked`. 1686 1687For example: 1688 1689 using namespace boost::multiprecision; 1690 1691 constexpr int128_t i = 0; // OK, fixed precision int128_t has no allocator. 1692 constexpr uint1024_t j = 0xFFFFFFFF00000000uLL; // OK, fixed precision uint1024_t has no allocator. 1693 1694 constexpr checked_uint128_t k = -1; // Error, checked type is not a literal type as we need runtime error checking. 1695 constexpr cpp_int l = 2; // Error, type is not a literal as it performs memory management. 1696 1697There is also limited support for user defined-literals - these are limited to unchecked, fixed precision `cpp_int`'s 1698which are specified in hexadecimal notation. The suffixes supported are: 1699 1700[table 1701[[Suffix][Meaning]] 1702[[_cppi][Specifies a value of type: `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`, where N is chosen 1703to contain just enough digits to hold the number specified.]] 1704[[_cppui][Specifies a value of type: `number<cpp_int_backend<N,N,unsigned_magnitude,unchecked,void> >`, where N is chosen 1705to contain just enough digits to hold the number specified.]] 1706[[_cppi['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]] 1707[[_cppui['N]][Specifies a value of type `number<cpp_int_backend<N,N,signed_magnitude,unchecked,void> >`.]] 1708] 1709 1710In each case, use of these suffixes with hexadecimal values produces a `constexpr` result. 1711 1712Examples: 1713 1714 // 1715 // Any use of user defined literals requires that we import the literal-operators 1716 // into current scope first: 1717 using namespace boost::multiprecision::literals; 1718 // 1719 // To keep things simple in the example, we'll make our types used visible to this scope as well: 1720 using namespace boost::multiprecision; 1721 // 1722 // The value zero as a number<cpp_int_backend<4,4,signed_magnitude,unchecked,void> >: 1723 constexpr auto a = 0x0_cppi; 1724 // The type of each constant has 4 bits per hexadecimal digit, 1725 // so this is of type uint256_t (ie number<cpp_int_backend<256,256,unsigned_magnitude,unchecked,void> >): 1726 constexpr auto b = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui; 1727 // 1728 // Smaller values can be assigned to larger values: 1729 int256_t c = 0x1234_cppi; // OK 1730 // 1731 // However, this does not currently work in constexpr contexts: 1732 constexpr int256_t d = 0x1_cppi; // Compiler error 1733 // 1734 // Constants can be padded out with leading zeros to generate wider types: 1735 constexpr uint256_t e = 0x0000000000000000000000000000000000000000000FFFFFFFFFFFFFFFFFFFFF_cppui; // OK 1736 // 1737 // However, specific width types are best produced with specific-width suffixes, 1738 // ones supported by default are `_cpp[u]i128`, `_cpp[u]i256`, `_cpp[u]i512`, `_cpp[u]i1024`. 1739 // 1740 constexpr int128_t f = 0x1234_cppi128; // OK, always produces an int128_t as the result. 1741 constexpr uint1024_t g = 0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbbbbbbbccccccccccccccccccccc_cppui1024; 1742 // 1743 // If other specific width types are required, then there is a macro for generating the operators 1744 // for these. The macro can be used at namespace scope only: 1745 // 1746 BOOST_MP_DEFINE_SIZED_CPP_INT_LITERAL(2048); 1747 // 1748 // Now we can create 2048-bit literals as well: 1749 constexpr auto h = 0xff_cppi2048; // h is of type number<cpp_int_backend<2048,2048,signed_magnitude,unchecked,void> > 1750 // 1751 // Finally negative values are handled via the unary minus operator: 1752 // 1753 constexpr int1024_t i = -0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF_cppui1024; 1754 // 1755 // Which means this also works: 1756 constexpr int1024_t j = -g; // OK: unary minus operator is constexpr. 1757 1758[endsect] 1759 1760[section:rounding Rounding Rules for Conversions] 1761 1762As a general rule, all conversions between unrelated types are performed using basic arithmetic operations, therefore 1763conversions are either exact, or follow the same rounding rules as arithmetic for the type in question. 1764 1765The following table summarises the situation for conversions from native types: 1766 1767[table 1768[[Backend][Rounding Rules]] 1769[[__cpp_int][Conversions from integer types are exact if the target has sufficient precision, otherwise they 1770 truncate to the first 2^MaxBits bits (modulo arithmetic). Conversions from floating point types 1771 are truncating to the nearest integer.]] 1772[[__gmp_int][Conversions are performed by the GMP library except for conversion from `long double` which is truncating.]] 1773[[__tom_int][Conversions from floating point types are truncating, all others are performed by libtommath and are exact.]] 1774[[__gmp_float][Conversions are performed by the GMP library except for conversion from `long double` which should be exact 1775 provided the target type has as much precision as a `long double`.]] 1776[[__mpfr_float_backend][All conversions are performed by the underlying MPFR library.]] 1777[[__cpp_dec_float][All conversions are performed using basic arithmetic operations and are truncating.]] 1778[[__gmp_rational][See __gmp_int]] 1779[[__cpp_rational][See __cpp_int]] 1780[[__tommath_rational][See __tom_int]] 1781] 1782 1783[endsect] 1784 1785[section:mixed Mixed Precision Arithmetic] 1786 1787Mixed precision arithmetic is fully supported by the library. 1788 1789There are two different forms: 1790 1791* Where the operands are of different precision. 1792* Where the operands are of the same precision, but yield a higher precision result. 1793 1794[h4 Mixing Operands of Differing Precision] 1795 1796If the arguments to a binary operator are of different precision, then the operation is allowed 1797as long as there is an unambiguous implicit conversion from one argument type to the other. 1798In all cases the arithmetic is performed "as if" the lower precision type is promoted to the 1799higher precision type before applying the operator. However, particular backends may optimise 1800this and avoid actually creating a temporary if they are able to do so. 1801 1802For example: 1803 1804 mpfr_float_50 a(2), b; 1805 mpfr_float_100 c(3), d; 1806 static_mpfr_float_50 e(5), f; 1807 mpz_int i(20); 1808 1809 d = a * c; // OK, result of operand is an mpfr_float_100. 1810 b = a * c; // Error, can't convert the result to an mpfr_float_50 as it will lose digits. 1811 f = a * e; // Error, operator is ambiguous, result could be of either type. 1812 f = e * i; // OK, unambiguous conversion from mpz_int to static_mpfr_float_50 1813 1814[h4 Operands of the Same Precision] 1815 1816Sometimes you want to apply an operator to two arguments of the same precision in 1817such a way as to obtain a result of higher precision. The most common situation 1818occurs with fixed precision integers, where you want to multiply two N-bit numbers 1819to obtain a 2N-bit result. This is supported in this library by the following 1820free functions: 1821 1822 template <class ResultType, class Source1 class Source2> 1823 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 1824 1825 template <class ResultType, class Source1 class Source2> 1826 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 1827 1828 template <class ResultType, class Source1 class Source2> 1829 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 1830 1831These functions apply the named operator to the arguments ['a] and ['b] and store the 1832result in ['result], returning ['result]. In all cases they behave "as if" 1833arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 1834operator, though particular backends may well avoid that step by way of an optimization. 1835 1836The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 1837may be either instances of class `number` or native integer types. The latter is an optimization 1838that allows arithmetic to be performed on native integer types producing an extended precision result. 1839 1840For example: 1841 1842[mixed_eg] 1843 1844Produces the output: 1845 1846[mixed_output] 1847 1848[h4 Backends With Optimized Mixed Precision Arithmetic] 1849 1850The following backends have at least some direct support for mixed precision arithmetic, 1851and therefore avoid creating unnecessary temporaries when using the interfaces above. 1852Therefore when using these types it's more efficient to use mixed precision arithmetic, 1853than it is to explicitly cast the operands to the result type: 1854 1855__mpfr_float_backend, __mpf_float, __cpp_int. 1856 1857[endsect] 1858 1859[section:gen_int Generic Integer Operations] 1860 1861All of the [link boost_multiprecision.ref.number.integer_functions non-member integer operations] are overloaded for the 1862built in integer types in 1863`<boost/multiprecision/integer.hpp>`. 1864Where these operations require a temporary increase in precision (such as for powm), then 1865if no built in type is available, a __cpp_int of appropriate precision will be used. 1866 1867Some of these functions are trivial, others use compiler intrinsics (where available) to ensure optimal 1868evaluation. 1869 1870The overloaded functions are: 1871 1872 template <class Integer, class I2> 1873 Integer& multiply(Integer& result, const I2& a, const I2& b); 1874 1875Multiplies two `I2` values, to produce a wider `Integer` result. 1876 1877Returns `result = a * b` without overflow or loss of precision in the multiplication. 1878 1879 template <class Integer, class I2> 1880 Integer& add(Integer& result, const I2& a, const I2& b); 1881 1882Adds two `I2` values, to produce a wider `Integer` result. 1883 1884Returns `result = a + b` without overflow or loss of precision in the addition. 1885 1886 template <class Integer, class I2> 1887 Integer& subtract(Integer& result, const I2& a, const I2& b); 1888 1889Subtracts two `I2` values, to produce a wider `Integer` result. 1890 1891Returns `result = a - b` without overflow or loss of precision in the subtraction. 1892 1893 template <class Integer> 1894 Integer powm(const Integer& b, const Integer& p, const Integer& m); 1895 1896Returns b[super p] % m. 1897 1898 template <class Integer> 1899 void divide_qr(const Integer& x, const Integer& y, Integer& q, Integer& r); 1900 1901Sets `q = x / y` and `r = x % y`. 1902 1903 template <class Integer1, class Integer2> 1904 Integer2 integer_modulus(const Integer1& x, Integer2 val); 1905 1906Returns x % val; 1907 1908 template <class Integer> 1909 unsigned lsb(const Integer& x); 1910 1911Returns the (zero-based) index of the least significant bit of `x`. 1912 1913Throws a `std::domain_error` if `x <= 0`. 1914 1915 template <class Integer> 1916 unsigned msb(const Integer& x); 1917 1918Returns the (zero-based) index of the most significant bit of `x`. 1919 1920Throws a `std::domain_error` if `x <= 0`. 1921 1922 template <class Integer> 1923 bool bit_test(const Integer& val, unsigned index); 1924 1925Returns `true` if bit `index` is set in `val`. 1926 1927 template <class Integer> 1928 Integer& bit_set(Integer& val, unsigned index); 1929 1930Sets the `index` bit in `val`. 1931 1932 template <class Integer> 1933 Integer& bit_unset(Integer& val, unsigned index); 1934 1935Unsets the `index` bit in `val`. 1936 1937 template <class Integer> 1938 Integer& bit_flip(Integer& val, unsigned index); 1939 1940Flips the `index` bit in `val`. 1941 1942 template <class Integer> 1943 Integer sqrt(const Integer& x); 1944 template <class Integer> 1945 Integer sqrt(const Integer& x, Integer& r); 1946 1947Returns the integer square root `s` of x and sets `r` to the remainder ['x - s[super 2]]. 1948 1949 template <class Engine> 1950 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials, Engine& gen); 1951 bool miller_rabin_test(const number-or-expression-template-type& n, unsigned trials); 1952 1953The regular Miller-Rabin functions in `<boost/multiprecision/miller_rabin.hpp>` are defined in terms of the above 1954generic operations, and so function equally well for built in and multiprecision types. 1955 1956[endsect] 1957 1958[section:serial Boost.Serialization Support] 1959 1960Support for serialization comes in two forms: 1961 1962* Classes __number, __debug_adaptor, __logged_adaptor and __rational_adaptor have "pass through" serialization 1963support which requires the underlying backend to be serializable. 1964* Backends __cpp_int, __cpp_bin_float, __cpp_dec_float and __float128 have full support for Boost.Serialization. 1965 1966[endsect] 1967 1968[section:limits Numeric Limits] 1969 1970Boost.Multiprecision tries hard to implement `std::numeric_limits` for all types 1971as far as possible and meaningful because experience with Boost.Math 1972has shown that this aids portability. 1973 1974The [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3690.pdf C++ standard library] 1975defines `std::numeric_limits` in section 18.3.2. 1976 1977This in turn refers to the C standard 1978[@http://www.open-std.org/jtc1/sc22/wg11/docs/n507.pdf SC22/WG11 N507 DRAFT INTERNATIONAL ISO/IEC STANDARD 1979 WD 10967-1] 1980Information technology Language independent arithmetic Part 1: Integer and Floating point arithmetic. 1981 1982That C Standard in turn refers to 1983 1984[@http://754r.ucbtest.org/standards/754.pdf IEEE754 IEEE Standard for Binary 1985Floating-Point Arithmetic] 1986 1987There is a useful summary at 1988[@http://www.cplusplus.com/reference/limits/numeric_limits/ C++ reference]. 1989 1990The chosen backend often determines how completely `std::numeric_limits` is available. 1991 1992Compiler options, processor type, and definition of macros or assembler instructions to control denormal numbers will alter 1993the values in the tables given below. 1994 1995[warning GMP's `mpf_t` does not have a concept of overflow: 1996operations that lead to overflow eventually run of out of resources 1997and terminate with stack overflow (often after several seconds).] 1998 1999[section:constants std::numeric_limits<> constants] 2000 2001 2002[h4 is_specialized] 2003 2004`true` for all arithmetic types (integer, floating and fixed-point) 2005for which `std::numeric_limits<T>::numeric_limits` is specialized. 2006 2007A typical test is 2008 2009 if (std::numeric_limits<T>::is_specialized == false) 2010 { 2011 std::cout << "type " << typeid(T).name() << " is not specialized for std::numeric_limits!" << std::endl; 2012 // ... 2013 } 2014 2015Typically `numeric_limits<T>::is_specialized` is `true` for all `T` where the compile-time constant 2016members of `numeric_limits` are indeed known at compile time, and don't vary at runtime. For example 2017floating point types with runtime-variable precision such as `mpfr_float` have no `numeric_limits` 2018specialization as it would be impossible to define all the members at compile time. In contrast 2019the precision of a type such as `mpfr_float_50` is known at compile time, and so it ['does] have a 2020`numeric_limits` specialization. 2021 2022Note that not all the `std::numeric_limits` member constants and functions are meaningful for all user-defined types (UDT), 2023such as the decimal and binary multiprecision types provided here. More information on this is given in the sections below. 2024 2025[h4 infinity] 2026 2027For floating-point types, [infin] is defined wherever possible, 2028but clearly infinity is meaningless for __arbitrary_precision arithmetic backends, 2029and there is one floating point type (GMP's `mpf_t`, see __mpf_float) which has no notion 2030of infinity or NaN at all. 2031 2032A typical test whether infinity is implemented is 2033 2034 if(std::numeric_limits<T>::has_infinity) 2035 { 2036 std::cout << std::numeric_limits<T>::infinity() << std::endl; 2037 } 2038 2039and using tests like this is strongly recommended to improve portability. 2040 2041If the backend is switched to a type that does not support infinity then, 2042without checks like this, there will be trouble. 2043 2044[h4 is_signed] 2045 2046`std::numeric_limits<T>::is_signed == true` if the type `T` is signed. 2047 2048For built-in binary types, the sign is held in a single bit, 2049but for other types (cpp_dec_float and cpp_bin_float) 2050it may be a separate storage element, usually `bool`. 2051 2052[h4 is_exact] 2053 2054`std::numeric_limits<T>::is_exact == true` if type T uses exact representations. 2055 2056This is defined as `true` for all integer types and `false` for floating-point types. 2057 2058[@http://stackoverflow.com/questions/14203654/stdnumeric-limitsis-exact-what-is-a-usable-definition A usable definition] 2059has been discussed. 2060 2061ISO/IEC 10967-1, Language independent arithmetic, noted by the C++ Standard defines 2062 2063 A floating point type F shall be a finite subset of [real]. 2064 2065The important practical distinction is that all integers (up to `max()`) can be stored exactly. 2066 2067[@http://en.wikipedia.org/wiki/Rational_number Rational] 2068types using two integer types are also exact. 2069 2070Floating-point types [*cannot store all real values] 2071(those in the set of [real]) [*exactly]. 2072For example, 0.5 can be stored exactly in a binary floating-point, but 0.1 cannot. 2073What is stored is the nearest representable real value, that is, rounded to nearest. 2074 2075Fixed-point types (usually decimal) are also defined as exact, in that they only 2076store a [*fixed precision], so half cents or pennies (or less) cannot be stored. 2077The results of computations are rounded up or down, 2078just like the result of integer division stored as an integer result. 2079 2080There are number of proposals to 2081[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3407.html 2082add Decimal Floating Point Support to C++]. 2083 2084[@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2849.pdf Decimal TR]. 2085 2086And also 2087[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html 2088C++ Binary Fixed-Point Arithmetic]. 2089 2090[h4 is_bounded] 2091 2092`std::numeric_limits<T>::is_bounded == true` if the set of values represented by the type `T` is finite. 2093 2094This is `true` for all built-in integer, fixed and floating-point types, 2095and most multi-precision types. 2096 2097It is only `false` for a few __arbitrary_precision types like `cpp_int`. 2098 2099Rational and fixed-exponent representations are exact but not integer. 2100 2101[h4 is_modulo] 2102 2103`std::numeric_limits<T>::is_modulo` is defined as `true` if adding two positive values of type T 2104can yield a result less than either value. 2105 2106`is_modulo == true` means that the type does not overflow, but, for example, 2107'wraps around' to zero, when adding one to the `max()` value. 2108 2109For most built-in integer types, `std::numeric_limits<>::is_modulo` is `true`. 2110 2111`bool` is the only exception. 2112 2113The modulo behaviour is sometimes useful, 2114but also can be unexpected, and sometimes undesired, behaviour. 2115 2116Overflow of signed integers can be especially unexpected, 2117possibly causing change of sign. 2118 2119Boost.Multiprecision integer type `cpp_int` is not modulo 2120because as an __arbitrary_precision types, 2121it expands to hold any value that the machine resources permit. 2122 2123However fixed precision __cpp_int's may be modulo if they are unchecked 2124(i.e. they behave just like built in integers), but not if they are checked 2125(overflow causes an exception to be raised). 2126 2127Built-in and multi-precision floating-point types are normally not modulo. 2128 2129Where possible, overflow is to `std::numeric_limits<>::infinity()`, 2130provided `std::numeric_limits<>::has_infinity == true`. 2131 2132[h4 radix] 2133 2134Constant `std::numeric_limits<T>::radix` returns either 2 (for built-in and binary types) 2135or 10 (for decimal types). 2136 2137[h4 digits] 2138 2139The number of `radix` digits that be represented without change: 2140 2141* for integer types, the number of [*non-sign bits] in the significand. 2142* for floating types, the number of [*radix digits] in the significand. 2143 2144The values include any implicit bit, so for example, for the ubiquious 2145`double` using 64 bits 2146([@http://en.wikipedia.org/wiki/Double_precision_floating-point_format IEEE binary64 ]), 2147`digits` == 53, even though there are only 52 actual bits of the significand stored in the representation. 2148The value of `digits` reflects the fact that there is one implicit bit which is always set to 1. 2149 2150The Boost.Multiprecision binary types do not use an implicit bit, so the 2151`digits` member reflects exactly how many bits of precision were requested: 2152 2153 typedef number<cpp_bin_float<53, digit_base_2> > float64; 2154 typedef number<cpp_bin_float<113, digit_base_2> > float128; 2155 std::numeric_limits<float64>::digits == 53. 2156 std::numeric_limits<float128>::digits == 113. 2157 2158For the most common case of `radix == 2`, 2159`std::numeric_limits<T>::digits` is the number of bits in the representation, 2160not counting any sign bit. 2161 2162For a decimal integer type, when `radix == 10`, it is the number of decimal digits. 2163 2164[h4 digits10] 2165 2166Constant `std::numeric_limits<T>::digits10` returns the number of 2167decimal digits that can be represented without change or loss. 2168 2169For example, `numeric_limits<unsigned char>::digits10` is 2. 2170 2171This somewhat inscrutable definition means that an `unsigned char` 2172can hold decimal values `0..99` 2173without loss of precision or accuracy, usually from truncation. 2174 2175Had the definition been 3 then that would imply it could hold 0..999, 2176but as we all know, an 8-bit `unsigned char` can only hold 0..255, 2177and an attempt to store 256 or more will involve loss or change. 2178 2179For bounded integers, it is thus [*one less] than number of decimal digits 2180you need to display the biggest integer `std::numeric_limits<T>::max()`. 2181This value can be used to predict the layout width required for 2182 2183[digits10_1] 2184 2185For example, `unsigned short` is often stored in 16 bits, 2186so the maximum value is 0xFFFF or 65535. 2187 2188[digits10_2] 2189 2190 2191For bounded floating-point types, 2192if we create a `double` with a value with `digits10` (usually 15) decimal digits, 2193`1e15` or `1000000000000000` : 2194 2195[digits10_3] 2196 2197and we can increment this value to `1000000000000001` 2198as expected and show the difference too. 2199 2200But if we try to repeat this with more than `digits10` digits, 2201 2202[digits10_4] 2203 2204then we find that when we add one it has no effect, 2205and display show that there is loss of precision. See 2206[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error]. 2207 2208So `digits10` is the number of decimal digits [*guaranteed] to be correct. 2209 2210For example, 'round-tripping' for `double`: 2211 2212* If a decimal string with at most `digits10`( == 15) significant decimal digits 2213is converted to `double` and then converted back to the 2214same number of significant decimal digits, 2215then the final string will match the original 15 decimal digit string. 2216* If a `double` floating-point number is converted to a decimal string 2217with at least 17 decimal digits 2218and then converted back to `double`, 2219then the result will be binary identical to the original `double` value. 2220 2221For most purposes, you will much more likely want 2222`std::numeric_limits<>::max_digits10`, 2223the number of decimal digits that ensure that a change of one least significant bit (ULP) 2224produces a different decimal digits string. 2225 2226For nearly all floating-point types, `max_digits10` is `digits10+2`, 2227but you should use `max_digits10` where possible. 2228 2229If `max_digits10` is not available, you should using the 2230[@http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF Kahan formula for floating-point type T] 2231 2232 max_digits10 = std::numeric_limits<T>::digits * 3010U/10000U; 2233 2234The factor is log[sub 10](2) = 0.3010 2235but must be evaluated at compile time using only integers. 2236 2237(See also 2238[@http://www.loria.fr/~zimmerma/mca/mca-cup-0.5.9.pdf Richard P. Brent and Paul Zimmerman, Modern Computer Arithmetic] 2239Equation 3.8 on page 116.). 2240 2241The extra two (or 3) least significant digits are 'noisy' and may be junk, 2242but if you want to 'round-trip' - printing a value out and reading it back in - 2243you must use `os.precision(std::numeric_limits<T>::max_digits10)`. 2244For at least one popular compiler, you must also use `std::scientific` format. 2245 2246[h4 max_digits10] 2247 2248`std::numeric_limits<T>::max_digits10` was added for floating-point 2249because `digits10` decimal digits are insufficient to show 2250a least significant bit (ULP) change giving puzzling displays like 2251 2252 0.666666666666667 != 0.666666666666667 2253 2254from failure to 'round-trip', for example: 2255 2256[max_digits10_2] 2257 2258If you wish to ensure that a change of one least significant bit (ULP) 2259produces a different decimal digits string, 2260then `max_digits10` is the precision to use. 2261 2262For example: 2263 2264[max_digits10_3] 2265 2266will display [pi] to the maximum possible precision using a `double`. 2267 2268[max_digits10_4] 2269 2270For integer types, `max_digits10` is implementation-dependant, 2271but is usually `digits10 + 2`. 2272This is the output field width required for the maximum value of the type T 2273`std::numeric_limits<T>::max()` including a sign and a space. 2274 2275So this will produce neat columns. 2276 2277 std::cout << std::setw(std::numeric_limits<int>::max_digits10) ... 2278 2279[note For Microsoft Visual Studio 2010, 2280`std::numeric_limits<float>::max_digits10` is wrongly defined as 8. It should be 9.] 2281 2282[note For Microsoft Visual Studio, and default float format, a small range of values 2283approximately 0.0001 to 0.004, with exponent values of 3f2 to 3f6, 2284are wrongly input by one least significant bit, 2285probably every third value of significand. 2286 2287A workaround is using scientific or exponential format `<< std::scientific`.] 2288 2289[note BOOST_NO_CXX11_NUMERIC_LIMITS is a suitable feature-test macro to determine if 2290`std::numeric_limits<float>::max_digits10` is implemented on any platform. 2291If `max_digits10` is not available, you should using the 2292[@http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF Kahan formula for floating-point type T]. 2293See above.] 2294 2295[max_digits10_1] [/ example for using max_digits10] 2296 2297[h4 round_style] 2298 2299The rounding style determines how the result of floating-point operations 2300is treated when the result cannot be [*exactly represented] in the significand. 2301Various rounding modes may be provided: 2302 2303* round to nearest up or down (default for floating-point types). 2304* round up (toward positive infinity). 2305* round down (toward negative infinity). 2306* round toward zero (integer types). 2307* no rounding (if decimal radix). 2308* rounding mode is not determinable. 2309 2310For integer types, `std::numeric_limits<T>::round_style` is always towards zero, so 2311 2312 std::numeric_limits<T>::round_style == std::round_to_zero; 2313 2314A decimal type, `cpp_dec_float` rounds in no particular direction, 2315which is to say it doesn't round at all. 2316And since there are several guard digits, 2317it's not really the same as truncation (round toward zero) either. 2318 2319For floating-point types, it is normal to round to nearest. 2320 2321 std::numeric_limits<T>::round_style == std::round_to_nearest; 2322 2323See function `std::numeric_limits<T>::round_error` for the maximum error (in ULP) 2324that rounding can cause. 2325 2326[h4 has_denorm_loss] 2327 2328`true` if a loss of precision is detected as a 2329[@http://en.wikipedia.org/wiki/Denormalization denormalization] loss, 2330rather than an inexact result. 2331 2332Always `false` for integer types. 2333 2334`false` for all types which do not have `has_denorm` == `std::denorm_present`. 2335 2336[h4 denorm_style] 2337 2338[@http://en.wikipedia.org/wiki/Denormal_number Denormalized values] are 2339representations with a variable number of exponent bits that can permit 2340gradual underflow, so that, if type T is `double`. 2341 2342 std::numeric_limits<T>::denorm_min() < std::numeric_limits<T>::min() 2343 2344A type may have any of the following `enum float_denorm_style` values: 2345 2346* `std::denorm_absent`, if it does not allow denormalized values. 2347(Always used for all integer and exact types). 2348* `std::denorm_present`, if the floating-point type allows denormalized values. 2349*`std::denorm_indeterminate`, if indeterminate at compile time. 2350 2351[h4 Tinyness before rounding] 2352 2353`bool std::numeric_limits<T>::tinyness_before` 2354 2355`true` if a type can determine that a value is too small 2356to be represent as a normalized value before rounding it. 2357 2358Generally true for `is_iec559` floating-point built-in types, 2359but false for integer types. 2360 2361Standard-compliant IEEE 754 floating-point implementations may detect the floating-point underflow at three predefined moments: 2362 2363# After computation of a result with absolute value smaller than 2364`std::numeric_limits<T>::min()`, 2365such implementation detects ['tinyness before rounding] (e.g. UltraSparc). 2366 2367# After rounding of the result to `std::numeric_limits<T>::digits` bits, 2368if the result is tiny, such implementation detects ['tinyness after rounding] 2369(e.g. SuperSparc). 2370 2371# If the conversion of the rounded tiny result to subnormal form 2372resulted in the loss of precision, such implementation detects ['denorm loss]. 2373 2374[endsect] [/section:constants std::numeric_limits<> Constants] 2375 2376[section:functions std::numeric_limits<> functions] 2377 2378[h4 max function] 2379 2380Function `std::numeric_limits<T>::max()` returns the largest finite value 2381that can be represented by the type T. If there is no such value (and 2382`numeric_limits<T>::bounded` is `false`) then returns `T()`. 2383 2384For built-in types there is usually a corresponding MACRO value TYPE_MAX, 2385where TYPE is CHAR, INT, FLOAT etc. 2386 2387Other types, including those provided by a typedef, 2388for example `INT64_T_MAX` for `int64_t`, may provide a macro definition. 2389 2390To cater for situations where no `numeric_limits` specialization is available 2391(for example because the precision of the type varies at runtime), 2392packaged versions of this (and other functions) are provided using 2393 2394 #include <boost/math/tools/precision.hpp> 2395 2396 T = boost::math::tools::max_value<T>(); 2397 2398Of course, these simply use `std::numeric_limits<T>::max()` if available, 2399but otherwise 'do something sensible'. 2400 2401[h4 lowest function] 2402 2403Since C++11: `std::numeric_limits<T>::lowest()` is 2404 2405* For integral types, the same as function `min()`. 2406* For floating-point types, generally the negative of `max()` 2407(but implementation-dependent). 2408 2409[digits10_5] 2410 2411[h4 min function] 2412 2413Function `std::numeric_limits<T>::min()` returns the minimum finite value 2414that can be represented by the type T. 2415 2416For built-in types there is usually a corresponding MACRO value TYPE_MIN, 2417where TYPE is CHAR, INT, FLOAT etc. 2418 2419Other types, including those provided by a typedef, 2420for example `INT64_T_MIN` for `int64_t`, may provide a macro definition. 2421 2422For floating-point types, 2423it is more fully defined as the ['minimum positive normalized value]. 2424 2425See `std::numeric_limits<T>::denorm_min()` for the smallest denormalized value, provided 2426 2427 std::numeric_limits<T>::has_denorm == std::denorm_present 2428 2429 2430To cater for situations where no `numeric_limits` specialization is available 2431(for example because the precision of the type varies at runtime), 2432packaged versions of this (and other functions) are provided using 2433 2434 #include <boost/math/tools/precision.hpp> 2435 2436 T = boost::math::tools::min_value<T>(); 2437 2438Of course, these simply use `std::numeric_limits<T>::min()` if available. 2439 2440[h4 denorm_min function] 2441 2442Function `std::numeric_limits<T>::denorm_min()` 2443returns the smallest 2444[@http://en.wikipedia.org/wiki/Denormal_number denormalized value], 2445provided 2446 2447 std::numeric_limits<T>::has_denorm == std::denorm_present 2448 2449[denorm_min_1] 2450 2451The exponent is effectively reduced from -308 to -324 2452(though it remains encoded as zero and leading zeros appear in the significand, 2453thereby losing precision until the significand reaches zero). 2454 2455[h4 round_error] 2456 2457Function `std::numeric_limits<T>::round_error()` returns the maximum error 2458(in units of [@http://en.wikipedia.org/wiki/Unit_in_the_last_place ULP]) 2459that can be caused by any basic arithmetic operation. 2460 2461 round_style == std::round_indeterminate; 2462 2463The rounding style is indeterminable at compile time. 2464 2465For floating-point types, when rounding is to nearest, 2466only half a bit is lost by rounding, and `round_error == 0.5`. 2467In contrast when rounding is towards zero, or plus/minus infinity, 2468we can loose up to one bit from rounding, and `round_error == 1`. 2469 2470For integer types, rounding always to zero, so at worst almost one bit can be rounded, 2471so `round_error == 1`. 2472 2473`round_error()` can be used with `std::numeric_limits<T>::epsilon()` to estimate 2474the maximum potential error caused by rounding. For typical floating-point types, 2475`round_error() = 1/2`, so half epsilon is the maximum potential error. 2476 2477[round_error_1] 2478 2479There are, of course, many occasions when much bigger loss of precision occurs, 2480for example, caused by 2481[@http://en.wikipedia.org/wiki/Loss_of_significance Loss of significance or cancellation error] 2482or very many iterations. 2483 2484[h4 epsilon] 2485 2486Function `std::numeric_limits<T>::epsilon()` is meaningful only for non-integral types. 2487 2488It returns the difference between `1.0` and the next value representable 2489by the floating-point type T. 2490So it is a one least-significant-bit change in this floating-point value. 2491 2492For `double` (`float_64t`) it is `2.2204460492503131e-016` 2493showing all possibly significant 17 decimal digits. 2494 2495[epsilon_1] 2496 2497We can explicitly increment by one bit using the function `boost::math::float_next()` 2498and the result is the same as adding `epsilon`. 2499 2500[epsilon_2] 2501 2502Adding any smaller value, like half `epsilon`, will have no effect on this value. 2503 2504[epsilon_3] 2505 2506So this cancellation error leaves the values equal, despite adding half `epsilon`. 2507 2508To achieve greater portability over platform and floating-point type, 2509Boost.Math and Boost.Multiprecion provide a package of functions that 2510'do something sensible' if the standard `numeric_limits` is not available. 2511To use these `#include <boost/math/tools/precision.hpp>`. 2512 2513[epsilon_4] 2514 2515[h5 Tolerance for Floating-point Comparisons] 2516 2517`epsilon` is very useful to compute a tolerance when comparing floating-point values, 2518a much more difficult task than is commonly imagined. 2519 2520For more information you probably want (but still need) see 2521[@http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html What Every Computer Scientist Should Know About Floating-Point Arithmetic] 2522 2523The naive test comparing the absolute difference between two values and a tolerance 2524does not give useful results if the values are too large or too small. 2525 2526So Boost.Test uses an algorithm first devised by Knuth 2527for reliably checking if floating-point values are close enough. 2528 2529See Donald. E. Knuth. The art of computer programming (vol II). 2530Copyright 1998 Addison-Wesley Longman, Inc., 0-201-89684-2. 2531Addison-Wesley Professional; 3rd edition. 2532 2533See also: 2534 2535[@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] 2536 2537[@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] 2538 2539[@boost:/libs/test/doc/html/utf/testing-tools/floating_point_comparison.html floating-point comparison]. 2540 2541[tolerance_1] 2542 2543used thus: 2544 2545 BOOST_CHECK_CLOSE_FRACTION(expected, calculated, tolerance); 2546 2547(There is also a version using tolerance as a percentage rather than a fraction). 2548 2549[tolerance_2] 2550 2551[h4 Infinity - positive and negative] 2552 2553For floating-point types only, for which 2554`std::numeric_limits<T>::has_infinity == true`, 2555function `std::numeric_limits<T>::infinity()` 2556provides an implementation-defined representation for [infin]. 2557 2558The 'representation' is a particular bit pattern reserved for infinity. 2559For IEEE754 system (for which `std::numeric_limits<T>::is_iec559 == true`) 2560[@http://en.wikipedia.org/wiki/IEEE_754-1985#Positive_and_negative_infinity positive and negative infinity] 2561are assigned bit patterns for all defined floating-point types. 2562 2563Confusingly, the string resulting from outputting this representation, is also 2564implementation-defined. And the string that can be input to generate the representation is also implementation-defined. 2565 2566For example, the output is `1.#INF` on Microsoft systems, but `inf` on most *nix platforms. 2567 2568This implementation-defined-ness has hampered use of infinity (and NaNs) 2569but Boost.Math and Boost.Multiprecision work hard to provide a sensible representation 2570for [*all] floating-point types, not just the built-in types, 2571which with the use of suitable facets to define the input and output strings, makes it possible 2572to use these useful features portably and including Boost.Serialization. 2573 2574[h4 Not-A-Number NaN] 2575 2576[h5 Quiet_NaN] 2577 2578For floating-point types only, for which 2579`std::numeric_limits<T>::has_quiet_NaN == true`, 2580function `std::numeric_limits<T>::quiet_NaN()` 2581provides an implementation-defined representation for NaN. 2582 2583[@http://en.wikipedia.org/wiki/NaN NaNs] are values to indicate that the 2584result of an assignment or computation is meaningless. 2585A typical example is `0/0` but there are many others. 2586 2587NaNs may also be used, to represent missing values: for example, 2588these could, by convention, be ignored in calculations of statistics like means. 2589 2590Many of the problems with a representation for 2591[@http://en.wikipedia.org/wiki/NaN Not-A-Number] has hampered portable use, 2592similar to those with infinity. 2593 2594[nan_1] 2595 2596But using Boost.Math and suitable facets can permit portable use 2597of both NaNs and positive and negative infinity. 2598 2599[facet_1] 2600 2601[h5 Signaling NaN] 2602 2603For floating-point types only, for which 2604`std::numeric_limits<T>::has_signaling_NaN == true`, 2605function `std::numeric_limits<T>::signaling_NaN()` 2606provides an implementation-defined representation for NaN that causes a hardware trap. 2607It should be noted however, that at least one implementation of this function causes a hardware 2608trap to be triggered simply by calling `std::numeric_limits<T>::signaling_NaN()`, and not only 2609by using the value returned. 2610 2611[endsect] [/section:functions std::numeric_limits<> functions] 2612 2613[/ Tables of values for numeric_limits for various built-in and cpp_bin_float types] 2614[include numeric_limits_32_tables.qbk] 2615[/include numeric_limits_64_tables.qbk] 2616 2617[section:how_to_tell How to Determine the Kind of a Number From `std::numeric_limits`] 2618 2619Based on the information above, one can see that different kinds of numbers can be 2620differentiated based on the information stored in `std::numeric_limits`. This is 2621in addition to the traits class [link boost_multiprecision.ref.number.traits_class_support 2622number_category] provided by this library. 2623 2624[h4 Integer Types] 2625 2626For an integer type T, all of the following conditions hold: 2627 2628 std::numeric_limits<T>::is_specialized == true 2629 std::numeric_limits<T>::is_integer == true 2630 std::numeric_limits<T>::is_exact == true 2631 std::numeric_limits<T>::min_exponent == 0 2632 std::numeric_limits<T>::max_exponent == 0 2633 std::numeric_limits<T>::min_exponent10 == 0 2634 std::numeric_limits<T>::max_exponent10 == 0 2635 2636In addition the type is /signed/ if: 2637 2638 std::numeric_limits<T>::is_signed == true 2639 2640If the type is arbitrary precision then: 2641 2642 std::numeric_limits<T>::is_bounded == false 2643 2644Otherwise the type is bounded, and returns a non zero value 2645from: 2646 2647 std::numeric_limits<T>::max() 2648 2649and has: 2650 2651 std::numeric_limits<T>::is_modulo == true 2652 2653if the type implements modulo arithmetic on overflow. 2654 2655[h4 Rational Types] 2656 2657Rational types are just like integers except that: 2658 2659 std::numeric_limits<T>::is_integer == false 2660 2661[h4 Fixed Precision Types] 2662 2663There appears to be no way to tell these apart from rational types, unless they set: 2664 2665 std::numeric_limits<T>::is_exact == false 2666 2667This is because these types are in essence a rational type with a fixed denominator. 2668 2669[h4 Floating Point Types] 2670 2671For a floating point type T, all of the following conditions hold: 2672 2673 std::numeric_limits<T>::is_specialized == true 2674 std::numeric_limits<T>::is_integer == false 2675 std::numeric_limits<T>::is_exact == false 2676 std::numeric_limits<T>::min_exponent != 0 2677 std::numeric_limits<T>::max_exponent != 0 2678 std::numeric_limits<T>::min_exponent10 != 0 2679 std::numeric_limits<T>::max_exponent10 != 0 2680 2681In addition the type is /signed/ if: 2682 2683 std::numeric_limits<T>::is_signed == true 2684 2685And the type may be decimal or binary depending on the value of: 2686 2687 std::numeric_limits<T>::radix 2688 2689In general, there are no arbitrary precision floating point types, and so: 2690 2691 std::numeric_limits<T>::is_bounded == false 2692 2693[h4 Exact Floating Point Types] 2694 2695Exact floating point types are a [@http://en.wikipedia.org/wiki/Field_%28mathematics%29 field] 2696composed of an arbitrary precision integer scaled by an exponent. Such types 2697have no division operator and are the same as floating point types except: 2698 2699 std::numeric_limits<T>::is_exact == true 2700 2701[h4 Complex Numbers] 2702 2703For historical reasons, complex numbers do not specialize `std::numeric_limits`, instead you must 2704inspect `std::numeric_limits<T::value_type>`. 2705 2706[endsect] 2707 2708[endsect] [/section:limits Numeric Limits] 2709 2710 2711[section:input_output Input Output] 2712 2713 2714[h4 Loopback testing] 2715 2716['Loopback] or ['round-tripping] refers to writing out a value as a decimal digit string using `std::iostream`, 2717usually to a `std::stringstream`, and then reading the string back in to another value, 2718and confirming that the two values are identical. A trivial example using `float` is: 2719 2720 float write; // Value to round-trip. 2721 std::stringstream ss; // Read and write std::stringstream. 2722 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output. 2723 ss.flags(std::ios_base::fmtflags(std::ios_base::scientific)); // Use scientific format. 2724 ss << write; // Output to string. 2725 float read; // Expected. 2726 ss >> read; // Read decimal digits string from stringstream. 2727 BOOST_CHECK_EQUAL(write, read); // Should be the same. 2728 2729and this can be run in a loop for all possible values of a 32-bit float. 2730For other floating-point types `T`, including built-in `double`, 2731it takes far too long to test all values, 2732so a reasonable test strategy is to use a large number of random values. 2733 2734 T write; 2735 std::stringstream ss; 2736 ss.precision(std::numeric_limits<T>::max_digits10); // Ensure all potentially significant bits are output. 2737 ss.flags(f); // Changed from default iostream format flags if desired. 2738 ss << write; // Output to stringstream. 2739 2740 T read; 2741 ss >> read; // Get read using operator>> from stringstream. 2742 BOOST_CHECK_EQUAL(read, write); 2743 2744 read = static_cast<T>(ss.str()); // Get read by converting from decimal digits string representation of write. 2745 BOOST_CHECK_EQUAL(read, write); 2746 2747 read = static_cast<T>(write.str(0, f)); // Get read using format specified when written. 2748 BOOST_CHECK_EQUAL(read, write); 2749 2750 2751The test at 2752[@../../test/test_cpp_bin_float_io.cpp test_cpp_bin_float_io.cpp] 2753allows any floating-point type to be ['round_tripped] using a wide range of fairly random values. 2754It also includes tests compared a collection of 2755[@../../test/string_data.ipp stringdata] test cases in a file. 2756 2757[h4 Comparing with output using Built-in types] 2758 2759One can make some comparisons with the output of 2760 2761 <number<cpp_bin_float<53, digit_count_2> > 2762 2763which has the same number of significant bits (53) as 64-bit double precision floating-point. 2764 2765However, although most outputs are identical, there are differences on some platforms 2766caused by the implementation-dependent behaviours allowed by the C99 specification 2767[@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 ISO/IEC 9899:TC2], 2768incorporated by C++. 2769 2770[:['"For e, E, f, F, g, and G conversions, if the number of significant decimal digits 2771is at most DECIMAL_DIG, then the result should be correctly rounded. 2772If the number of significant decimal digits is more than DECIMAL_DIG 2773but the source value is exactly representable with DECIMAL_DIG digits, 2774then the result should be an exact representation with trailing zeros. 2775Otherwise, the source value is bounded by two adjacent decimal strings L < U, 2776both having DECIMAL_DIG significant digits; 2777the value of the resultant decimal string D should satisfy L<= D <= U, 2778with the extra stipulation that the error should have a correct sign 2779for the current rounding direction."]] 2780 2781So not only is correct rounding for the full number of digits not required, 2782but even if the *optional* recommended practice is followed, 2783then the value of these last few digits is unspecified 2784as long as the value is within certain bounds. 2785 2786[note Do not expect the output from different platforms 2787to be [*identical], but `cpp_dec_float`, `cpp_bin_float` (and other backends) outputs should be 2788correctly rounded to the number of digits requested by the set precision and format.] 2789 2790 2791[h4 Macro BOOST_MP_MIN_EXPONENT_DIGITS] 2792 2793[@http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf C99 Standard] 2794for [/e and E] format specifiers, 7.19.6 Formatted input/output functions requires: 2795 2796\"The exponent always contains at least two digits, 2797and only as many more digits as necessary to represent the exponent.\" 2798 2799So to conform to the C99 standard (incorporated by C++) 2800 2801 #define BOOST_MP_MIN_EXPONENT_DIGITS 2 2802 2803Confusingly, Microsoft (and MinGW) do not conform to this standard and provide 2804[*at least three digits], for example `1e+001`. 2805So if you want the output to match that from 2806built-in floating-point types on compilers that use Microsofts runtime then use: 2807 2808 #define BOOST_MP_MIN_EXPONENT_DIGITS 3 2809 2810Also useful to get the minimum exponent field width is 2811 2812 #define BOOST_MP_MIN_EXPONENT_DIGITS 1 2813 2814producing a compact output like `2e+4`, 2815useful when conserving space is important. 2816 2817Larger values are also supported, for example, value 4 for `2e+0004` 2818which may be useful to ensure that columns line up. 2819 2820[endsect] [/section:input_output Input Output] 2821 2822 2823[endsect] 2824 2825[section:ref Reference] 2826 2827[section:number number] 2828 2829[h4 Synopsis] 2830 2831 namespace boost{ namespace multiprecision{ 2832 2833 enum expression_template_option { et_on = 1, et_off = 0 }; 2834 2835 template <class Backend> struct expression_template_default 2836 { static const expression_template_option value = et_on; }; 2837 2838 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 2839 class number 2840 { 2841 number(); 2842 number(see-below); 2843 number& operator=(see-below); 2844 number& assign(see-below); 2845 2846 // Member operators 2847 number& operator+=(const ``['see-below]``&); 2848 number& operator-=(const ``['see-below]``&); 2849 number& operator*=(const ``['see-below]``&); 2850 number& operator/=(const ``['see-below]``&); 2851 number& operator++(); 2852 number& operator--(); 2853 number operator++(int); 2854 number operator--(int); 2855 2856 number& operator%=(const ``['see-below]``&); 2857 number& operator&=(const ``['see-below]``&); 2858 number& operator|=(const ``['see-below]``&); 2859 number& operator^=(const ``['see-below]``&); 2860 number& operator<<=(const ``['integer-type]``&); 2861 number& operator>>=(const ``['integer-type]``&); 2862 2863 // Use in Boolean context: 2864 operator ``['convertible-to-bool-type]``()const; 2865 // swap: 2866 void swap(number& other); 2867 // Sign: 2868 bool is_zero()const; 2869 int sign()const; 2870 // string conversion: 2871 std::string str()const; 2872 // Generic conversion mechanism 2873 template <class T> 2874 T convert_to()const; 2875 template <class T> 2876 explicit operator T ()const; 2877 // precision control: 2878 static unsigned default_precision(); 2879 static void default_precision(unsigned digits10); 2880 unsigned precision()const; 2881 void precision(unsigned digits10); 2882 // Comparison: 2883 int compare(const number<Backend>& o)const; 2884 template <class V> 2885 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type 2886 compare(const V& o)const; 2887 // Access to the underlying implementation: 2888 Backend& backend(); 2889 const Backend& backend()const; 2890 }; 2891 2892 // Non member operators: 2893 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&); 2894 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&); 2895 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&); 2896 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&); 2897 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&); 2898 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&); 2899 // Integer only operations: 2900 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&); 2901 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&); 2902 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&); 2903 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&); 2904 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&); 2905 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&); 2906 // Comparison operators: 2907 bool operator==(const ``['see-below]``&, const ``['see-below]``&); 2908 bool operator!=(const ``['see-below]``&, const ``['see-below]``&); 2909 bool operator< (const ``['see-below]``&, const ``['see-below]``&); 2910 bool operator> (const ``['see-below]``&, const ``['see-below]``&); 2911 bool operator<=(const ``['see-below]``&, const ``['see-below]``&); 2912 bool operator>=(const ``['see-below]``&, const ``['see-below]``&); 2913 2914 // Swap: 2915 template <class Backend, expression_template_option ExpressionTemplates> 2916 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 2917 2918 // iostream support: 2919 template <class Backend, expression_template_option ExpressionTemplates> 2920 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r); 2921 std::ostream& operator << (std::ostream& os, const ``['unmentionable-expression-template-type]``& r); 2922 template <class Backend, expression_template_option ExpressionTemplates> 2923 std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r); 2924 2925 // Arithmetic with a higher precision result: 2926 template <class ResultType, class Source1 class Source2> 2927 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 2928 template <class ResultType, class Source1 class Source2> 2929 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 2930 template <class ResultType, class Source1 class Source2> 2931 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 2932 2933 // Non-member function standard library support: 2934 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&); 2935 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&); 2936 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&); 2937 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&); 2938 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&); 2939 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&); 2940 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&); 2941 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&); 2942 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&); 2943 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&); 2944 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&); 2945 ``['unmentionable-expression-template-type]`` lround (const ``['number-or-expression-template-type]``&); 2946 ``['unmentionable-expression-template-type]`` llround(const ``['number-or-expression-template-type]``&); 2947 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&); 2948 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&); 2949 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&); 2950 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&); 2951 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&); 2952 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&); 2953 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&); 2954 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&); 2955 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&); 2956 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&); 2957 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&); 2958 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&); 2959 2960 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 2961 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*); 2962 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 2963 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 2964 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 2965 ``['unmentionable-expression-template-type]`` scalbn(const ``['number-or-expression-template-type]``&, ``['integer-type]``); 2966 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&); 2967 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&); 2968 2969 // Traits support: 2970 template <class T> 2971 struct component_type; 2972 template <class T> 2973 struct number_category; 2974 template <class T> 2975 struct is_number; 2976 template <class T> 2977 struct is_number_expression; 2978 2979 // Integer specific functions: 2980 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 2981 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 2982 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``&, unsigned); 2983 ``['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); 2984 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``&); 2985 template <class Backend, expression_template_option ExpressionTemplates> 2986 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``&, number<Backend, EXpressionTemplates>&); 2987 template <class Backend, expression_template_option ExpressionTemplates> 2988 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y, 2989 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r); 2990 template <class Integer> 2991 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val); 2992 unsigned lsb(const ``['number-or-expression-template-type]``& x); 2993 unsigned msb(const ``['number-or-expression-template-type]``& x); 2994 template <class Backend, class ExpressionTemplates> 2995 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index); 2996 template <class Backend, class ExpressionTemplates> 2997 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index); 2998 template <class Backend, class ExpressionTemplates> 2999 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index); 3000 template <class Backend, class ExpressionTemplates> 3001 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index); 3002 template <class Engine> 3003 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen); 3004 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials); 3005 3006 // Rational number support: 3007 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&); 3008 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&); 3009 3010 }} // namespaces 3011 3012 namespace boost{ namespace math{ 3013 3014 // Boost.Math interoperability functions: 3015 int fpclassify (const ``['number-or-expression-template-type]``&, int); 3016 bool isfinite (const ``['number-or-expression-template-type]``&, int); 3017 bool isnan (const ``['number-or-expression-template-type]``&, int); 3018 bool isinf (const ``['number-or-expression-template-type]``&, int); 3019 bool isnormal (const ``['number-or-expression-template-type]``&, int); 3020 3021 }} // namespaces 3022 3023 // numeric_limits support: 3024 namespace std{ 3025 3026 template <class Backend, expression_template_option ExpressionTemplates> 3027 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 3028 { 3029 /* Usual members here */ 3030 }; 3031 3032 } 3033 3034[h4 Description] 3035 3036 enum expression_template_option { et_on = 1, et_off = 0 }; 3037 3038This enumerated type is used to specify whether expression templates are turned on (et_on) or turned off (et_off). 3039 3040 template <class Backend> struct expression_template_default 3041 { static const expression_template_option value = et_on; }; 3042 3043This traits class specifies the default expression template option to be used with a particular Backend type. 3044It defaults to `et_on`. 3045 3046 template <class Backend, expression_template_option ExpressionTemplates = expression_template_default<Backend>::value> 3047 class number; 3048 3049Class `number` has two template arguments: 3050 3051[variablelist 3052[[Backend][The actual arithmetic back-end that does all the work.]] 3053[[ExpressionTemplates][A Boolean value: when `et_on`, then expression templates are enabled, otherwise when set to `et_off` they are disabled. 3054 The default for this parameter is computed via the traits class `expression_template_default` whose member `value` defaults to `et_on` unless 3055 the traits class is specialized for a particular backend.]] 3056] 3057 3058 number(); 3059 number(see-below); 3060 number& operator=(see-below); 3061 number& assign(see-below); 3062 3063Type `number` is default constructible, and both copy constructible and assignable from: 3064 3065* Itself. 3066* An expression template which is the result of one of the arithmetic operators. 3067* Any builtin arithmetic type, as long as the result would not be lossy (for example float to integer conversion). 3068* Any type that the Backend is implicitly constructible or assignable from. 3069* An rvalue reference to another `number`. Move-semantics are used for construction if the backend also 3070supports rvalue reference construction. In the case of assignment, move semantics are always supported 3071when the argument is an rvalue reference irrespective of the backend. 3072* Any type in the same family, as long as no loss of precision is involved. For example from `int128_t` to `int256_t`, 3073or `cpp_dec_float_50` to `cpp_dec_float_100`. 3074 3075Type `number` is explicitly constructible from: 3076 3077* Any type mentioned above. 3078* A `std::string` or any type which is convertible to `const char*`. 3079* Any arithmetic type (including those that would result in lossy conversions). 3080* Any type in the same family, including those that result in loss of precision. 3081* Any type that the Backend is explicitly constructible from. 3082* Any pair of types for which a generic interconversion exists: that is from integer to integer, integer 3083to rational, integer to float, rational to rational, rational to float, or float to float. 3084 3085The assign member function is available for any type for which an explicit converting constructor exists. 3086It is intended to be used where a temporary generated from an explicit assignment would be expensive, for example: 3087 3088 mpfr_float_50 f50; 3089 mpfr_float_100 f100; 3090 3091 f50 = static_cast<mpfr_float_50>(f100); // explicit cast create a temporary 3092 f50.assign(f100); // explicit call to assign create no temporary 3093 3094In addition, if the type has multiple components (for example rational or complex number types), then there is a 3095two argument constructor: 3096 3097 number(arg1, arg2); 3098 3099Where the two args must either be arithmetic types, or types that are convertible to the two components of `this`. 3100 3101 number& operator+=(const ``['see-below]``&); 3102 number& operator-=(const ``['see-below]``&); 3103 number& operator*=(const ``['see-below]``&); 3104 number& operator/=(const ``['see-below]``&); 3105 number& operator++(); 3106 number& operator--(); 3107 number operator++(int); 3108 number operator--(int); 3109 // Integer only operations: 3110 number& operator%=(const ``['see-below]``&); 3111 number& operator&=(const ``['see-below]``&); 3112 number& operator|=(const ``['see-below]``&); 3113 number& operator^=(const ``['see-below]``&); 3114 number& operator<<=(const ``['integer-type]``&); 3115 number& operator>>=(const ``['integer-type]``&); 3116 3117These operators all take their usual arithmetic meanings. 3118 3119The arguments to these operators is either: 3120 3121* Another `number<Backend, ExpressionTemplates>`. 3122* An expression template derived from `number<Backend>`. 3123* Any type implicitly convertible to `number<Backend, ExpressionTemplates>`, including some other instance of class `number`. 3124 3125For the left and right shift operations, the argument must be a builtin 3126integer type with a positive value (negative values result in a `std::runtime_error` being thrown). 3127 3128 operator ``['convertible-to-bool-type]``()const; 3129 3130Returns an ['unmentionable-type] that is usable in Boolean contexts (this allows `number` to be used in any 3131Boolean context - if statements, conditional statements, or as an argument to a logical operator - without 3132type `number` being convertible to type `bool`. 3133 3134This operator also enables the use of `number` with any of the following operators: 3135`!`, `||`, `&&` and `?:`. 3136 3137 void swap(number& other); 3138 3139Swaps `*this` with `other`. 3140 3141 bool is_zero()const; 3142 3143Returns `true` is `*this` is zero, otherwise `false`. 3144 3145 int sign()const; 3146 3147Returns a value less than zero if `*this` is negative, a value greater than zero if `*this` is positive, and zero 3148if `*this` is zero. 3149 3150 std::string str(unsigned precision, bool scientific = true)const; 3151 3152Returns the number formatted as a string, with at least /precision/ digits, and in scientific format 3153if /scientific/ is true. 3154 3155 template <class T> 3156 T convert_to()const; 3157 3158 template <class T> 3159 explicit operator T ()const; 3160 3161Provides a generic conversion mechanism to convert `*this` to type `T`. Type `T` may be any arithmetic type. 3162Optionally other types may also be supported by specific `Backend` types. 3163 3164 3165 static unsigned default_precision(); 3166 static void default_precision(unsigned digits10); 3167 unsigned precision()const; 3168 void precision(unsigned digits10); 3169 3170These functions are only available if the Backend template parameter supports runtime changes to precision. They get and set 3171the default precision and the precision of `*this` respectively. 3172 3173 int compare(const number<Backend, ExpressionTemplates>& o)const; 3174 template <class V> 3175 typename enable_if<is_convertible<V, number<Backend, ExpressionTemplates> >, int>::type 3176 compare(const V& other)const; 3177 3178Returns: 3179 3180* A value less that 0 for `*this < other` 3181* A value greater that 0 for `*this > other` 3182* Zero for `*this == other` 3183 3184 Backend& backend(); 3185 const Backend& backend()const; 3186 3187Returns the underlying back-end instance used by `*this`. 3188 3189[h4 Non-member operators] 3190 3191 // Non member operators: 3192 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&); 3193 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&); 3194 ``['unmentionable-expression-template-type]`` operator+(const ``['see-below]``&, const ``['see-below]``&); 3195 ``['unmentionable-expression-template-type]`` operator-(const ``['see-below]``&, const ``['see-below]``&); 3196 ``['unmentionable-expression-template-type]`` operator*(const ``['see-below]``&, const ``['see-below]``&); 3197 ``['unmentionable-expression-template-type]`` operator/(const ``['see-below]``&, const ``['see-below]``&); 3198 // Integer only operations: 3199 ``['unmentionable-expression-template-type]`` operator%(const ``['see-below]``&, const ``['see-below]``&); 3200 ``['unmentionable-expression-template-type]`` operator&(const ``['see-below]``&, const ``['see-below]``&); 3201 ``['unmentionable-expression-template-type]`` operator|(const ``['see-below]``&, const ``['see-below]``&); 3202 ``['unmentionable-expression-template-type]`` operator^(const ``['see-below]``&, const ``['see-below]``&); 3203 ``['unmentionable-expression-template-type]`` operator<<(const ``['see-below]``&, const ``['integer-type]``&); 3204 ``['unmentionable-expression-template-type]`` operator>>(const ``['see-below]``&, const ``['integer-type]``&); 3205 // Comparison operators: 3206 bool operator==(const ``['see-below]``&, const ``['see-below]``&); 3207 bool operator!=(const ``['see-below]``&, const ``['see-below]``&); 3208 bool operator< (const ``['see-below]``&, const ``['see-below]``&); 3209 bool operator> (const ``['see-below]``&, const ``['see-below]``&); 3210 bool operator<=(const ``['see-below]``&, const ``['see-below]``&); 3211 bool operator>=(const ``['see-below]``&, const ``['see-below]``&); 3212 3213These operators all take their usual arithmetic meanings. 3214 3215The arguments to these functions must contain at least one of the following: 3216 3217* A `number`. 3218* An expression template type derived from `number`. 3219* Any type for which `number` has an implicit constructor - for example a builtin arithmetic type. 3220 3221The return type of these operators is either: 3222 3223* An ['unmentionable-type] expression template type when `ExpressionTemplates` is `true`. 3224* Type `number<Backend, et_off>` when `ExpressionTemplates` is `false`. 3225* Type `bool` if the operator is a comparison operator. 3226 3227Finally note that the second argument to the left and right shift operations must be a builtin integer type, 3228and that the argument must be positive (negative arguments result in a `std::runtime_error` being thrown). 3229 3230[h4 swap] 3231 3232 template <class Backend, ExpressionTemplates> 3233 void swap(number<Backend, ExpressionTemplates>& a, number<Backend, ExpressionTemplates>& b); 3234 3235Swaps `a` and `b`. 3236 3237[h4 Iostream Support] 3238 3239 template <class Backend, expression_template_option ExpressionTemplates> 3240 std::ostream& operator << (std::ostream& os, const number<Backend, ExpressionTemplates>& r); 3241 template <class Unspecified...> 3242 std::ostream& operator << (std::ostream& os, const unmentionable-expression-template& r); 3243 template <class Backend, expression_template_option ExpressionTemplates> 3244 inline std::istream& operator >> (std::istream& is, number<Backend, ExpressionTemplates>& r) 3245 3246These operators provided formatted input-output operations on `number` types, and expression templates derived from them. 3247 3248It's down to the back-end type to actually implement string conversion. However, the back-ends provided with 3249this library support all of the iostream formatting flags, field width and precision settings. 3250 3251[h4 Arithmetic with a higher precision result] 3252 3253 template <class ResultType, class Source1 class Source2> 3254 ResultType& add(ResultType& result, const Source1& a, const Source2& b); 3255 3256 template <class ResultType, class Source1 class Source2> 3257 ResultType& subtract(ResultType& result, const Source1& a, const Source2& b); 3258 3259 template <class ResultType, class Source1 class Source2> 3260 ResultType& multiply(ResultType& result, const Source1& a, const Source2& b); 3261 3262These functions apply the named operator to the arguments ['a] and ['b] and store the 3263result in ['result], returning ['result]. In all cases they behave "as if" 3264arguments ['a] and ['b] were first promoted to type `ResultType` before applying the 3265operator, though particular backends may well avoid that step by way of an optimization. 3266 3267The type `ResultType` must be an instance of class `number`, and the types `Source1` and `Source2` 3268may be either instances of class `number` or native integer types. The latter is an optimization 3269that allows arithmetic to be performed on native integer types producing an extended precision result. 3270 3271[h4 Non-member standard library function support] 3272 3273 ``['unmentionable-expression-template-type]`` abs (const ``['number-or-expression-template-type]``&); 3274 ``['unmentionable-expression-template-type]`` fabs (const ``['number-or-expression-template-type]``&); 3275 ``['unmentionable-expression-template-type]`` sqrt (const ``['number-or-expression-template-type]``&); 3276 ``['unmentionable-expression-template-type]`` floor (const ``['number-or-expression-template-type]``&); 3277 ``['unmentionable-expression-template-type]`` ceil (const ``['number-or-expression-template-type]``&); 3278 ``['unmentionable-expression-template-type]`` trunc (const ``['number-or-expression-template-type]``&); 3279 ``['unmentionable-expression-template-type]`` itrunc (const ``['number-or-expression-template-type]``&); 3280 ``['unmentionable-expression-template-type]`` ltrunc (const ``['number-or-expression-template-type]``&); 3281 ``['unmentionable-expression-template-type]`` lltrunc(const ``['number-or-expression-template-type]``&); 3282 ``['unmentionable-expression-template-type]`` round (const ``['number-or-expression-template-type]``&); 3283 ``['unmentionable-expression-template-type]`` iround (const ``['number-or-expression-template-type]``&); 3284 ``['unmentionable-expression-template-type]`` lround (const ``['number-or-expression-template-type]``&); 3285 ``['unmentionable-expression-template-type]`` llround(const ``['number-or-expression-template-type]``&); 3286 ``['unmentionable-expression-template-type]`` exp (const ``['number-or-expression-template-type]``&); 3287 ``['unmentionable-expression-template-type]`` log (const ``['number-or-expression-template-type]``&); 3288 ``['unmentionable-expression-template-type]`` log10 (const ``['number-or-expression-template-type]``&); 3289 ``['unmentionable-expression-template-type]`` cos (const ``['number-or-expression-template-type]``&); 3290 ``['unmentionable-expression-template-type]`` sin (const ``['number-or-expression-template-type]``&); 3291 ``['unmentionable-expression-template-type]`` tan (const ``['number-or-expression-template-type]``&); 3292 ``['unmentionable-expression-template-type]`` acos (const ``['number-or-expression-template-type]``&); 3293 ``['unmentionable-expression-template-type]`` asin (const ``['number-or-expression-template-type]``&); 3294 ``['unmentionable-expression-template-type]`` atan (const ``['number-or-expression-template-type]``&); 3295 ``['unmentionable-expression-template-type]`` cosh (const ``['number-or-expression-template-type]``&); 3296 ``['unmentionable-expression-template-type]`` sinh (const ``['number-or-expression-template-type]``&); 3297 ``['unmentionable-expression-template-type]`` tanh (const ``['number-or-expression-template-type]``&); 3298 3299 ``['unmentionable-expression-template-type]`` ldexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``); 3300 ``['unmentionable-expression-template-type]`` frexp (const ``['number-or-expression-template-type]``&, ``['integer-type]``*); 3301 ``['unmentionable-expression-template-type]`` pow (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3302 ``['unmentionable-expression-template-type]`` fmod (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3303 ``['unmentionable-expression-template-type]`` atan2 (const ``['number-or-expression-template-type]``&, const ``['number-or-expression-template-type]``&); 3304 ``['unmentionable-expression-template-type]`` scalbn(const ``['number-or-expression-template-type]``&, ``['integer-type]``); 3305 ``['unmentionable-expression-template-type]`` logb (const ``['number-or-expression-template-type]``&); 3306 ``['integer-type]`` ilogb (const ``['number-or-expression-template-type]``&); 3307 3308These functions all behave exactly as their standard library C++11 counterparts do: their argument is either an instance of `number` or 3309an expression template derived from it; If the argument is of type `number<Backend, et_off>` then that is also the return type, 3310otherwise the return type is an expression template. 3311 3312The integer type arguments to `ldexp`, `frexp`, `scalbn` and `ilogb` may be either type `int`, or the actual 3313type of the exponent of the number type. 3314 3315These functions are normally implemented by the Backend type. However, default versions are provided for Backend types that 3316don't have native support for these functions. Please note however, that this default support requires the precision of the type 3317to be a compile time constant - this means for example that the [gmp] MPF Backend will not work with these functions when that type is 3318used at variable precision. 3319 3320Also note that with the exception of `abs` that these functions can only be used with floating-point Backend types (if any other types 3321such as fixed precision or complex types are added to the library later, then these functions may be extended to support those number types). 3322 3323The precision of these functions is generally determined by the backend implementation. For example the precision 3324of these functions when used with __mpfr_float_backend is determined entirely by [mpfr]. When these functions use our own 3325implementations, the accuracy of the transcendental functions is generally a few epsilon. Note however, that the trigonometrical 3326functions incur the usual accuracy loss when reducing arguments by large multiples of [pi]. Also note that both __mpf_float 3327and __cpp_dec_float have a number of guard digits beyond their stated precision, so the error rates listed for these 3328are in some sense artificially low. 3329 3330The following table shows the error rates we observe for these functions with various backend types, functions not listed 3331here are exact (tested on Win32 with VC++10, MPFR-3.0.0, MPIR-2.1.1): 3332 3333[table 3334[[Function][mpfr_float_50][mpf_float_50][cpp_dec_float_50]] 3335[[sqrt][1eps][0eps][0eps]] 3336[[exp][1eps][0eps][0eps]] 3337[[log][1eps][0eps][0eps]] 3338[[log10][1eps][0eps][0eps]] 3339[[cos][700eps][0eps][0eps]] 3340[[sin][1eps][0eps][0eps]] 3341[[tan][0eps][0eps][0eps]] 3342[[acos][0eps][0eps][0eps]] 3343[[asin][0eps][0eps][0eps]] 3344[[atan][1eps][0eps][0eps]] 3345[[cosh][1045eps[footnote It's likely that the inherent error in the input values to our test cases are to blame here.]][0eps][0eps]] 3346[[sinh][2eps][0eps][0eps]] 3347[[tanh][1eps][0eps][0eps]] 3348[[pow][0eps][4eps][3eps]] 3349[[atan2][1eps][0eps][0eps]] 3350] 3351[h4 Traits Class Support] 3352 3353 template <class T> 3354 struct component_type; 3355 3356If this is a type with multiple components (for example rational or complex types), then this trait has a single member 3357`type` that is the type of those components. 3358 3359 template <class T> 3360 struct number_category; 3361 3362A traits class that inherits from `mpl::int_<N>` where `N` is one of the enumerated values `number_kind_integer`, `number_kind_floating_point`, 3363`number_kind_rational`, `number_kind_fixed_point`, or `number_kind_unknown`. This traits class is specialized for any type that has 3364`std::numeric_limits` support as well as for classes in this library: which means it can be used for generic code that must work 3365with built in arithmetic types as well as multiprecision ones. 3366 3367 template <class T> 3368 struct is_number; 3369 3370A traits class that inherits from `mpl::true_` if T is an instance of `number<>`, otherwise from `mpl::false_`. 3371 3372 template <class T> 3373 struct is_number_expression; 3374 3375A traits class that inherits from `mpl::true_` if T is an expression template type derived from `number<>`, otherwise from `mpl::false_`. 3376 3377 3378 3379[h4 Integer functions] 3380 3381In addition to functioning with types from this library, these functions are also overloaded for built in integer 3382types if you include `<boost/multiprecision/integer.hpp>`. Further, when used with fixed precision types (whether 3383built in integers or multiprecision ones), the functions will promote to a wider type internally when the algorithm 3384requires it. Versions overloaded for built in integer types return that integer type rather than an expression 3385template. 3386 3387 ``['unmentionable-expression-template-type]`` gcd(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 3388 3389Returns the largest integer `x` that divides both `a` and `b`. 3390 3391 ``['unmentionable-expression-template-type]`` lcm(const ``['number-or-expression-template-type]``& a, const ``['number-or-expression-template-type]``& b); 3392 3393Returns the smallest integer `x` that is divisible by both `a` and `b`. 3394 3395 ``['unmentionable-expression-template-type]`` pow(const ``['number-or-expression-template-type]``& b, unsigned p); 3396 3397Returns ['b[super p]] as an expression template. Note that this function should be used with extreme care as the result can grow so 3398large as to take "effectively forever" to compute, or else simply run the host machine out of memory. This is the one function in 3399this category that is not overloaded for built in integer types, further, it's probably not a good idea to use it with 3400fixed precision `cpp_int`'s either. 3401 3402 ``['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); 3403 3404Returns ['b[super p] mod m] as an expression template. Fixed precision types are promoted internally to ensure accuracy. 3405 3406 ``['unmentionable-expression-template-type]`` sqrt(const ``['number-or-expression-template-type]``& a); 3407 3408Returns the largest integer `x` such that `x * x < a`. 3409 3410 template <class Backend, expression_template_option ExpressionTemplates> 3411 number<Backend, EXpressionTemplates> sqrt(const ``['number-or-expression-template-type]``& a, number<Backend, EXpressionTemplates>& r); 3412 3413Returns the largest integer `x` such that `x * x < a`, and sets the remainder `r` such that `r = a - x * x`. 3414 3415 template <class Backend, expression_template_option ExpressionTemplates> 3416 void divide_qr(const ``['number-or-expression-template-type]``& x, const ``['number-or-expression-template-type]``& y, 3417 number<Backend, ExpressionTemplates>& q, number<Backend, ExpressionTemplates>& r); 3418 3419Divides x by y and returns both the quotient and remainder. After the call `q = x / y` and `r = x % y`. 3420 3421 template <class Integer> 3422 Integer integer_modulus(const ``['number-or-expression-template-type]``& x, Integer val); 3423 3424Returns the absolute value of `x % val`. 3425 3426 unsigned lsb(const ``['number-or-expression-template-type]``& x); 3427 3428Returns the (zero-based) index of the least significant bit that is set to 1. 3429 3430Throws a `std::range_error` if the argument is <= 0. 3431 3432 unsigned msb(const ``['number-or-expression-template-type]``& x); 3433 3434Returns the (zero-based) index of the most significant bit. 3435 3436Throws a `std::range_error` if the argument is <= 0. 3437 3438 template <class Backend, class ExpressionTemplates> 3439 bool bit_test(const number<Backend, ExpressionTemplates>& val, unsigned index); 3440 3441Returns `true` if the bit at /index/ in /val/ is set. 3442 3443 template <class Backend, class ExpressionTemplates> 3444 number<Backend, ExpressionTemplates>& bit_set(number<Backend, ExpressionTemplates>& val, unsigned index); 3445 3446Sets the bit at /index/ in /val/, and returns /val/. 3447 3448 template <class Backend, class ExpressionTemplates> 3449 number<Backend, ExpressionTemplates>& bit_unset(number<Backend, ExpressionTemplates>& val, unsigned index); 3450 3451Unsets the bit at /index/ in /val/, and returns /val/. 3452 3453 template <class Backend, class ExpressionTemplates> 3454 number<Backend, ExpressionTemplates>& bit_flip(number<Backend, ExpressionTemplates>& val, unsigned index); 3455 3456Flips the bit at /index/ in /val/, and returns /val/. 3457 3458 template <class Engine> 3459 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials, Engine& gen); 3460 bool miller_rabin_test(const ``['number-or-expression-template-type]``& n, unsigned trials); 3461 3462Tests to see if the number /n/ is probably prime - the test excludes the vast majority of composite numbers 3463by excluding small prime factors and performing a single Fermat test. Then performs /trials/ Miller-Rabin 3464tests. Returns `false` if /n/ is definitely composite, or `true` if /n/ is probably prime with the 3465probability of it being composite less than 0.25^trials. Fixed precision types are promoted internally 3466to ensure accuracy. 3467 3468[h4 Rational Number Functions] 3469 3470 typename component_type<``['number-or-expression-template-type]``>::type numerator (const ``['number-or-expression-template-type]``&); 3471 typename component_type<``['number-or-expression-template-type]``>::type denominator(const ``['number-or-expression-template-type]``&); 3472 3473These functions return the numerator and denominator of a rational number respectively. 3474 3475[h4 Boost.Math Interoperability Support] 3476 3477 namespace boost{ namespace math{ 3478 3479 int fpclassify (const ``['number-or-expression-template-type]``&, int); 3480 bool isfinite (const ``['number-or-expression-template-type]``&, int); 3481 bool isnan (const ``['number-or-expression-template-type]``&, int); 3482 bool isinf (const ``['number-or-expression-template-type]``&, int); 3483 bool isnormal (const ``['number-or-expression-template-type]``&, int); 3484 3485 }} // namespaces 3486 3487These floating-point classification functions behave exactly as their Boost.Math equivalents. 3488 3489Other Boost.Math functions and templates may also be 3490specialized or overloaded to ensure interoperability. 3491 3492[h4 std::numeric_limits support] 3493 3494 namespace std{ 3495 3496 template <class Backend, ExpressionTemplates> 3497 struct numeric_limits<boost::multiprecision<Backend, ExpressionTemplates> > 3498 { 3499 /* Usual members here */ 3500 }; 3501 3502 } 3503 3504Class template `std::numeric_limits` is specialized for all instantiations of `number` whose precision is known at compile time, plus those 3505types whose precision is unlimited (though it is much less useful in those cases). It is not specialized for types 3506whose precision can vary at compile time (such as `mpf_float`). 3507 3508[endsect] 3509 3510[section:cpp_int_ref cpp_int] 3511 3512 namespace boost{ namespace multiprecision{ 3513 3514 typedef unspecified-type limb_type; 3515 3516 enum cpp_integer_type { signed_magnitude, unsigned_magnitude }; 3517 enum cpp_int_check_type { checked, unchecked }; 3518 3519 template <unsigned MinDigits = 0, 3520 unsigned MaxDits = 0, 3521 cpp_integer_type SignType = signed_magnitude, 3522 cpp_int_check_type Checked = unchecked, 3523 class Allocator = std::allocator<limb_type> > 3524 class cpp_int_backend; 3525 // 3526 // Expression templates default to et_off if there is no allocator: 3527 // 3528 template <unsigned MinDigits, unsigned MaxDigits, cpp_integer_type SignType, cpp_int_check_type Checked> 3529 struct expression_template_default<cpp_int_backend<MinDigits, MaxDigits, SignType, Checked, void> > 3530 { static const expression_template_option value = et_off; }; 3531 3532 typedef number<cpp_int_backend<> > cpp_int; // arbitrary precision integer 3533 typedef rational_adaptor<cpp_int_backend<> > cpp_rational_backend; 3534 typedef number<cpp_rational_backend> cpp_rational; // arbitrary precision rational number 3535 3536 // Fixed precision unsigned types: 3537 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, unchecked, void> > uint128_t; 3538 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, unchecked, void> > uint256_t; 3539 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, unchecked, void> > uint512_t; 3540 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, unchecked, void> > uint1024_t; 3541 3542 // Fixed precision signed types: 3543 typedef number<cpp_int_backend<128, 128, signed_magnitude, unchecked, void> > int128_t; 3544 typedef number<cpp_int_backend<256, 256, signed_magnitude, unchecked, void> > int256_t; 3545 typedef number<cpp_int_backend<512, 512, signed_magnitude, unchecked, void> > int512_t; 3546 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, unchecked, void> > int1024_t; 3547 3548 // Over again, but with checking enabled this time: 3549 typedef number<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_int; 3550 typedef rational_adaptor<cpp_int_backend<0, 0, signed_magnitude, checked> > checked_cpp_rational_backend; 3551 typedef number<cpp_rational_backend> checked_cpp_rational; 3552 3553 // Checked fixed precision unsigned types: 3554 typedef number<cpp_int_backend<128, 128, unsigned_magnitude, checked, void> > checked_uint128_t; 3555 typedef number<cpp_int_backend<256, 256, unsigned_magnitude, checked, void> > checked_uint256_t; 3556 typedef number<cpp_int_backend<512, 512, unsigned_magnitude, checked, void> > checked_uint512_t; 3557 typedef number<cpp_int_backend<1024, 1024, unsigned_magnitude, checked, void> > checked_uint1024_t; 3558 3559 // Fixed precision signed types: 3560 typedef number<cpp_int_backend<128, 128, signed_magnitude, checked, void> > checked_int128_t; 3561 typedef number<cpp_int_backend<256, 256, signed_magnitude, checked, void> > checked_int256_t; 3562 typedef number<cpp_int_backend<512, 512, signed_magnitude, checked, void> > checked_int512_t; 3563 typedef number<cpp_int_backend<1024, 1024, signed_magnitude, checked, void> > checked_int1024_t; 3564 3565 }} // namespaces 3566 3567Class template `cpp_int_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3568Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3569to change. 3570 3571The template arguments are: 3572 3573[variablelist 3574[[MinBits][Determines the number of Bits to store directly within the object before resorting to dynamic memory 3575 allocation. When zero, this field is determined automatically based on how many bits can be stored 3576 in union with the dynamic storage header: setting a larger value may improve performance as larger integer 3577 values will be stored internally before memory allocation is required.]] 3578[[MaxBits][Determines the maximum number of bits to be stored in the type: resulting in a fixed precision type. 3579 When this value is the same as MinBits, then the Allocator parameter is ignored, as no dynamic 3580 memory allocation will ever be performed: in this situation the Allocator parameter should be set to 3581 type `void`. Note that this parameter should not be used simply to prevent large memory 3582 allocations, not only is that role better performed by the allocator, but fixed precision 3583 integers have a tendency to allocate all of MaxBits of storage more often than one would expect.]] 3584[[SignType][Determines whether the resulting type is signed or not. Note that for 3585[@http://en.wikipedia.org/wiki/Arbitrary-precision_arithmetic arbitrary precision] types 3586 this parameter must be `signed_magnitude`. For fixed precision 3587 types then this type may be either `signed_magnitude` or `unsigned_magnitude`.]] 3588[[Checked][This parameter has two values: `checked` or `unchecked`. See the [link boost_multiprecision.tut.ints.cpp_int tutorial] for more information.]] 3589[[Allocator][The allocator to use for dynamic memory allocation, or type `void` if MaxBits == MinBits.]] 3590] 3591 3592The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 3593 3594More information on this type can be found in the [link boost_multiprecision.tut.ints.cpp_int tutorial]. 3595 3596[endsect] 3597 3598[section:gmp_int_ref gmp_int] 3599 3600 namespace boost{ namespace multiprecision{ 3601 3602 class gmp_int; 3603 3604 typedef number<gmp_int > mpz_int; 3605 3606 }} // namespaces 3607 3608Class template `gmp_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3609Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3610to change. 3611 3612The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 3613 3614More information on this type can be found in the [link boost_multiprecision.tut.ints.gmp_int tutorial]. 3615 3616[endsect] 3617 3618[section:tom_int_ref tom_int] 3619 3620 namespace boost{ namespace multiprecision{ 3621 3622 class tommath_int; 3623 3624 typedef number<tommath_int > tom_int; 3625 3626 }} // namespaces 3627 3628Class template `tommath_int` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3629Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3630to change. 3631 3632The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_integer>`. 3633 3634More information on this type can be found in the [link boost_multiprecision.tut.ints.tom_int tutorial]. 3635 3636[endsect] 3637 3638[section:mpf_ref gmp_float] 3639 3640 namespace boost{ namespace multiprecision{ 3641 3642 template <unsigned Digits10> 3643 class gmp_float; 3644 3645 typedef number<gmp_float<50> > mpf_float_50; 3646 typedef number<gmp_float<100> > mpf_float_100; 3647 typedef number<gmp_float<500> > mpf_float_500; 3648 typedef number<gmp_float<1000> > mpf_float_1000; 3649 typedef number<gmp_float<0> > mpf_float; 3650 3651 }} // namespaces 3652 3653Class template `gmp_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3654Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3655to change. 3656 3657The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 3658should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 3659and `number::precision`. Note that this type does not in any way change the GMP library's global state (for example 3660it does not change the default precision of the mpf_t data type), therefore you can safely mix this type with existing 3661code that uses GMP, and also mix `gmp_float`s of differing precision. 3662 3663The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 3664 3665More information on this type can be found in the [link boost_multiprecision.tut.floats.gmp_float tutorial]. 3666 3667[endsect] 3668 3669[section:mpfr_ref mpfr_float_backend] 3670 3671 namespace boost{ namespace multiprecision{ 3672 3673 template <unsigned Digits10> 3674 class mpfr_float_backend; 3675 3676 typedef number<mpfr_float_backend<50> > mpfr_float_50; 3677 typedef number<mpfr_float_backend<100> > mpfr_float_100; 3678 typedef number<mpfr_float_backend<500> > mpfr_float_500; 3679 typedef number<mpfr_float_backend<1000> > mpfr_float_1000; 3680 typedef number<mpfr_float_backend<0> > mpfr_float; 3681 3682 }} // namespaces 3683 3684Class template `mpfr_float_backend` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3685Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3686to change. 3687 3688The class takes a single template parameter - `Digits10` - which is the number of decimal digits precision the type 3689should support. When this parameter is zero, then the precision can be set at runtime via `number::default_precision` 3690and `number::precision`. Note that this type does not in any way change the GMP or MPFR library's global state (for example 3691it does not change the default precision of the mpfr_t data type), therefore you can safely mix this type with existing 3692code that uses GMP or MPFR, and also mix `mpfr_float_backend`s of differing precision. 3693 3694The type of `number_category<cpp_int<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 3695 3696More information on this type can be found in the [link boost_multiprecision.tut.floats.mpfr_float tutorial]. 3697 3698[endsect] 3699 3700[section:cpp_bin_float_ref cpp_bin_float] 3701 3702 namespace boost{ namespace multiprecision{ 3703 3704 enum digit_base_type 3705 { 3706 digit_base_2 = 2, 3707 digit_base_10 = 10 3708 }; 3709 3710 template <unsigned Digits, digit_base_type base = digit_base_10, class Allocator = void, class Exponent = int, ExponentMin = 0, ExponentMax = 0> 3711 class cpp_bin_float; 3712 3713 typedef number<cpp_bin_float<50> > cpp_bin_float_50; 3714 typedef number<cpp_bin_float<100> > cpp_bin_float_100; 3715 3716 typedef number<backends::cpp_bin_float<24, backends::digit_base_2, void, boost::int16_t, -126, 127>, et_off> cpp_bin_float_single; 3717 typedef number<backends::cpp_bin_float<53, backends::digit_base_2, void, boost::int16_t, -1022, 1023>, et_off> cpp_bin_float_double; 3718 typedef number<backends::cpp_bin_float<64, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_double_extended; 3719 typedef number<backends::cpp_bin_float<113, backends::digit_base_2, void, boost::int16_t, -16382, 16383>, et_off> cpp_bin_float_quad; 3720 3721 }} // namespaces 3722 3723Class template `cpp_bin_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3724Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3725to change. 3726 3727The class takes six template parameters: 3728 3729[variablelist 3730[[Digits][The number of digits precision the type 3731should support. This is normally expressed as base-10 digits, but that can be changed via the second template parameter.]] 3732[[base][An enumerated value (either `digit_base_10` or `digit_base_2`) that indicates whether `Digits` is base-10 or base-2]] 3733[[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic 3734allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]] 3735[[Exponent][A signed integer type to use as the type of the exponent - defaults to `int`.]] 3736[[ExponentMin][The smallest (most negative) permitted exponent, defaults to zero, meaning "define as small as possible 3737given the limitations of the type and our internal requirements".]] 3738[[ExponentMax][The largest (most positive) permitted exponent, defaults to zero, meaning "define as large as possible 3739given the limitations of the type and our internal requirements".]] 3740] 3741 3742The type of `number_category<cpp_bin_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 3743 3744More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_bin_float tutorial]. 3745 3746[h4 Implementation Notes] 3747 3748Internally, an N-bit `cpp_bin_float` is represented as an N-bit unsigned integer along with an exponent and a sign. 3749The integer part is normalized so that it's most significant bit is always 1. The decimal point is assumed to be 3750directly after the most significant bit of the integer part. The special values zero, infinity and NaN all have 3751the integer part set to zero, and the exponent to one of 3 special values above the maximum permitted exponent. 3752 3753Multiplication is trivial: multiply the two N-bit integer mantissa's to obtain a 2N-bit number, then round and 3754adjust the sign and exponent. 3755 3756Addition and subtraction proceed similarly - if the exponents are such that there is overlap between the two 3757values, then left shift the larger value to produce a number with between N and 2N bits, then perform integer 3758addition or subtraction, round, and adjust the exponent. 3759 3760Division proceeds as follows: first scale the numerator by some power of 2 so that integer division will 3761produce either an N-bit or N+1 bit result plus a remainder. If we get an N bit result then the size of 3762twice the remainder compared to the denominator gives us the rounding direction. Otherwise we have one extra bit 3763in the result which we can use to determine rounding (in this case ties occur only if the remainder is zero and 3764the extra bit is a 1). 3765 3766Square root uses integer square root in a manner analogous to division. 3767 3768Decimal string to binary conversion proceeds as follows: first parse the digits to 3769produce an integer multiplied by a decimal exponent. Note that we stop parsing digits 3770once we have parsed as many as can possibly effect the result - this stops the integer 3771part growing too large when there are a very large number of input digits provided. 3772At this stage if the decimal exponent is positive then the result is an integer and we 3773can in principle simply multiply by 10^N to get an exact integer result. In practice 3774however, that could produce some very large integers. We also need to be able to divide 3775by 10^N in the event that the exponent is negative. Therefore calculation of the 10^N 3776values plus the multiplication or division are performed using limited precision 3777integer arithmetic, plus an exponent, and a track of the accumulated error. At the end of 3778the calculation we will either be able to round unambiguously, or the error will be such 3779that we can't tell which way to round. In the latter case we simply up the precision and try 3780again until we have an unambiguously rounded result. 3781 3782Binary to decimal conversion proceeds very similarly to the above, our aim is to calculate 3783`mantissa * 2^shift * 10^E` where `E` is the decimal exponent and `shift` is calculated 3784so that the result is an N bit integer assuming we want N digits printed in the result. 3785As before we use limited precision arithmetic to calculate the result and up the 3786precision as necessary until the result is unambiguously correctly rounded. In addition 3787our initial calculation of the decimal exponent may be out by 1, so we have to correct 3788that and loop as well in the that case. 3789 3790[endsect] 3791 3792[section:cpp_dec_ref cpp_dec_float] 3793 3794 namespace boost{ namespace multiprecision{ 3795 3796 template <unsigned Digits10, class ExponentType = boost::int32_t, class Allocator = void> 3797 class cpp_dec_float; 3798 3799 typedef number<cpp_dec_float<50> > cpp_dec_float_50; 3800 typedef number<cpp_dec_float<100> > cpp_dec_float_100; 3801 3802 }} // namespaces 3803 3804Class template `cpp_dec_float` fulfils all of the requirements for a [link boost_multiprecision.ref.backendconc Backend] type. 3805Its members and non-member functions are deliberately not documented: these are considered implementation details that are subject 3806to change. 3807 3808The class takes three template parameters: 3809 3810[variablelist 3811[[Digits10][The number of decimal digits precision the type 3812should support. Note that this type does not normally perform any dynamic memory allocation, and as a result the `Digits10` 3813template argument should not be set too high or the class's size will grow unreasonably large.]] 3814[[ExponentType][A signed integer type that represents the exponent of the number]] 3815[[Allocator][The allocator used: defaults to type `void`, meaning all storage is within the class, and no dynamic 3816allocation is performed, but can be set to a standard library allocator if dynamic allocation makes more sense.]] 3817] 3818 3819The type of `number_category<cpp_dec_float<Args...> >::type` is `mpl::int_<number_kind_floating_point>`. 3820 3821More information on this type can be found in the [link boost_multiprecision.tut.floats.cpp_dec_float tutorial]. 3822 3823[endsect] 3824 3825[section:internals Internal Support Code] 3826 3827There are some traits classes which authors of new backends should be aware of: 3828 3829 namespace boost{ namespace multiprecision{ namespace detail{ 3830 3831 template<typename From, typename To> 3832 struct is_explicitly_convertible; 3833 3834 }}} 3835 3836Inherits from `boost::integral_constant<bool,true>` if type `From` has an explicit conversion from `To`. 3837 3838For compilers that support C++11 SFINAE-expressions this trait should "just work". Otherwise it inherits 3839from `boost::is_convertible<From, To>::type`, and will need to be specialised for Backends that have 3840constructors marked as `explicit`. 3841 3842 template <class From, class To> 3843 struct is_lossy_conversion 3844 { 3845 static const bool value = see below; 3846 }; 3847 3848Member `value` is true if the conversion from `From` to `To` would result in a loss of precision, and `false` otherwise. 3849 3850The default version of this trait simply checks whether the ['kind] of conversion (for example from a floating point to an integer type) 3851is inherently lossy. Note that if either of the types `From` or `To` are of an unknown number category (because `number_category` is not 3852specialised for that type) then this trait will be `true`. 3853 3854 template<typename From, typename To> 3855 struct is_restricted_conversion 3856 { 3857 static const bool value = see below; 3858 }; 3859 3860Member `value` is `true` if `From` is only explicitly convertible to `To` and not implicitly convertible, or 3861if `is_lossy_conversion<From, To>::value` is `true`. Otherwise `false`. 3862 3863Note that while this trait is the ultimate arbiter of which constructors are marked as `explicit` in class `number`, 3864authors of backend types should generally specialise one of the traits above, rather than this one directly. 3865 3866 template <class T> 3867 is_signed_number; 3868 template <class T> 3869 is_unsigned_number; 3870 3871These two traits inherit from either `mpl::true_` or `mpl::false_`, by default types are assumed to be signed unless 3872`is_unsigned_number` is specialized for that type. 3873 3874[endsect] 3875 3876[section:backendconc Backend Requirements] 3877 3878The requirements on the `Backend` template argument to `number` are split up into 3879sections: compulsory and optional. 3880 3881Compulsory requirements have no default implementation in the library, therefore if the feature 3882they implement is to be supported at all, then they must be implemented by the backend. 3883 3884Optional requirements have default implementations that are called if the backend doesn't provide 3885it's own. Typically the backend will implement these to improve performance. 3886 3887In the following tables, type B is the `Backend` template argument to `number`, `b` and `b2` are 3888a variables of type B, `cb`, `cb2` and `cb3` are constant variables of type `const B`, 3889`rb` is a variable of type `B&&`, `a` and `a2` are variables of Arithmetic type, 3890`s` is a variable of type `const char*`, `ui` is a variable of type `unsigned`, `bb` is a variable of type `bool`, 3891`pa` is a variable of type pointer-to-arithmetic-type, `exp` is a variable of type `B::exp_type`, 3892`pexp` is a variable of type `B::exp_type*`, `i` is a variable of type `int`, `pi` pointer to a variable of type `int`, 3893B2 is another type that meets these requirements, b2 is a variable of type B2, `ss` is variable of type `std::streamsize` 3894and `ff` is a variable of type `std::ios_base::fmtflags`. 3895 3896[table Compulsory Requirements on the Backend type. 3897[[Expression][Return Type][Comments][Throws]] 3898[[`B::signed_types`][`mpl::list<type-list>`][A list of signed integral types that can be assigned to type B. The types shall be 3899 listed in order of size, smallest first, and shall terminate in the type that is `std::intmax_t`.][[space]]] 3900[[`B::unsigned_types`][`mpl::list<type-list>`][A list of unsigned integral types that can be assigned to type B. The types shall be 3901 listed in order of size, smallest first, and shall terminate in the type that is `std::uintmax_t`.][[space]]] 3902[[`B::float_types`][`mpl::list<type-list>`][A list of floating-point types that can be assigned to type B.The types shall be 3903 listed in order of size, smallest first, and shall terminate in type `long double`.][[space]]] 3904[[`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]]] 3905[[`B()`][ ][Default constructor.][[space]]] 3906[[`B(cb)`][ ][Copy Constructor.][[space]]] 3907[[`b = b`][`B&`][Assignment operator.][[space]]] 3908[[`b = a`][`B&`][Assignment from an Arithmetic type. The type of `a` shall be listed in one of the type lists 3909 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 3910[[`b = s`][`B&`][Assignment from a string.][Throws a `std::runtime_error` if the string could not be interpreted as a valid number.]] 3911[[`b.swap(b)`][`void`][Swaps the contents of its arguments.][`noexcept`]] 3912[[`cb.str(ss, ff)`][`std::string`][Returns the string representation of `b` with `ss` digits and formatted according to the flags set in `ff`. 3913 If `ss` is zero, then returns as many digits as are required to reconstruct the original value.][[space]]] 3914[[`b.negate()`][`void`][Negates `b`.][[space]]] 3915[[`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 3916 if `cb == cb2`.][`noexcept`]] 3917[[`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 3918 if `cb == a`. The type of `a` shall be listed in one of the type lists 3919 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 3920[[`eval_add(b, cb)`][`void`][Adds `cb` to `b`.][[space]]] 3921[[`eval_subtract(b, cb)`][`void`][Subtracts `cb` from `b`.][[space]]] 3922[[`eval_multiply(b, cb)`][`void`][Multiplies `b` by `cb`.][[space]]] 3923[[`eval_divide(b, cb)`][`void`][Divides `b` by `cb`.] 3924 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 3925[[`eval_modulus(b, cb)`][`void`][Computes `b %= cb`, only required when `B` is an integer type.] 3926 [`std::overflow_error` if cb has the value zero.]] 3927[[`eval_bitwise_and(b, cb)`][`void`][Computes `b &= cb`, only required when `B` is an integer type.][[space]]] 3928[[`eval_bitwise_or(b, cb)`][`void`][Computes `b |= cb`, only required when `B` is an integer type.][[space]]] 3929[[`eval_bitwise_xor(b, cb)`][`void`][Computes `b ^= cb`, only required when `B` is an integer type.][[space]]] 3930[[`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]]] 3931[[`eval_left_shift(b, ui)`][`void`][Computes `b <<= ui`, only required when `B` is an integer type.][[space]]] 3932[[`eval_right_shift(b, ui)`][`void`][Computes `b >>= ui`, only required when `B` is an integer type.][[space]]] 3933[[`eval_convert_to(pa, cb)`][`void`][Converts `cb` to the type of `*pa` and store the result in `*pa`. Type `B` shall support 3934 conversion to at least types `std::intmax_t`, `std::uintmax_t` and `long long`. 3935 Conversion to other arithmetic types can then be synthesised using other operations. 3936 Conversions to other types are entirely optional.][[space]]] 3937[[`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]]] 3938[[`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]]] 3939[[`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.] 3940 [`std::runtime_error` if the exponent of cb is too large to be stored in an `int`.]] 3941[[`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]]] 3942[[`eval_floor(b, cb)`][`void`][Stores the floor of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 3943[[`eval_ceil(b, cb)`][`void`][Stores the ceiling of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 3944[[`eval_sqrt(b, cb)`][`void`][Stores the square root of `cb` in `b`, only required when `B` is a floating-point type.][[space]]] 3945[[`boost::multiprecision::number_category<B>::type`][`mpl::int_<N>`][`N` is one of the values `number_kind_integer`, `number_kind_floating_point`, `number_kind_rational` or `number_kind_fixed_point`. 3946 Defaults to `number_kind_floating_point`.][[space]]] 3947] 3948 3949[table Optional Requirements on the Backend Type 3950[[Expression][Returns][Comments][Throws]] 3951 3952[[['Construct and assign:]]] 3953[[`B(rb)`][`B`][Move constructor. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 3954 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 3955[[`b = rb`][`B&`][Move-assign. Afterwards variable `rb` shall be in sane state, albeit with unspecified value. 3956 Only destruction and assignment to the moved-from variable `rb` need be supported after the operation.][`noexcept`]] 3957[[`B(a)`][`B`][Direct construction from an arithmetic type. The type of `a` shall be listed in one of the type lists 3958 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3959 When not provided, this operation is simulated using default-construction followed by assignment.][[space]]] 3960[[`B(b2)`][`B`][Copy constructor from a different back-end type. When not provided, a generic interconversion routine is used. 3961 This constructor may be `explicit` if the corresponding frontend constructor should also be `explicit`.][[space]]] 3962[[`b = b2`][`b&`][Assignment operator from a different back-end type. When not provided, a generic interconversion routine is used.][[space]]] 3963[[`assign_components(b, a, a)`][`void`][Assigns to `b` the two components in the following arguments. 3964 Only applies to rational and complex number types. 3965 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 3966[[`assign_components(b, b2, b2)`][`void`][Assigns to `b` the two components in the following arguments. 3967 Only applies to rational and complex number types. 3968 When not provided, arithmetic operations are used to synthesise the result from the two values.][[space]]] 3969 3970[[['Comparisons:]]] 3971[[`eval_eq(cb, cb2)`][`bool`][Returns `true` if `cb` and `cb2` are equal in value. 3972 When not provided, the default implementation returns `cb.compare(cb2) == 0`.][`noexcept`]] 3973[[`eval_eq(cb, a)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 3974 The type of `a` shall be listed in one of the type lists 3975 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3976 When not provided, return the equivalent of `eval_eq(cb, B(a))`.][[space]]] 3977[[`eval_eq(a, cb)`][`bool`][Returns `true` if `cb` and `a` are equal in value. 3978 The type of `a` shall be listed in one of the type lists 3979 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3980 When not provided, the default version returns `eval_eq(cb, a)`.][[space]]] 3981[[`eval_lt(cb, cb2)`][`bool`][Returns `true` if `cb` is less than `cb2` in value. 3982 When not provided, the default implementation returns `cb.compare(cb2) < 0`.][`noexcept`]] 3983[[`eval_lt(cb, a)`][`bool`][Returns `true` if `cb` is less than `a` in value. 3984 The type of `a` shall be listed in one of the type lists 3985 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3986 When not provided, the default implementation returns `eval_lt(cb, B(a))`.][[space]]] 3987[[`eval_lt(a, cb)`][`bool`][Returns `true` if `a` is less than `cb` in value. 3988 The type of `a` shall be listed in one of the type lists 3989 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3990 When not provided, the default implementation returns `eval_gt(cb, a)`.][[space]]] 3991[[`eval_gt(cb, cb2)`][`bool`][Returns `true` if `cb` is greater than `cb2` in value. 3992 When not provided, the default implementation returns `cb.compare(cb2) > 0`.][`noexcept`]] 3993[[`eval_gt(cb, a)`][`bool`][Returns `true` if `cb` is greater than `a` in value. 3994 The type of `a` shall be listed in one of the type lists 3995 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 3996 When not provided, the default implementation returns `eval_gt(cb, B(a))`.][[space]]] 3997[[`eval_gt(a, cb)`][`bool`][Returns `true` if `a` is greater than `cb` in value. 3998 The type of `a` shall be listed in one of the type lists 3999 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4000 When not provided, the default implementation returns `eval_lt(cb, a)`.][[space]]] 4001[[`eval_is_zero(cb)`][`bool`][Returns `true` if `cb` is zero, otherwise `false`. The default version of this function 4002 returns `cb.compare(ui_type(0)) == 0`, where `ui_type` is `ui_type` is 4003 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4004[[`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. 4005 The default version of this function 4006 returns `cb.compare(ui_type(0))`, where `ui_type` is `ui_type` is 4007 `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4008 4009[[['Basic arithmetic:]]] 4010[[`eval_add(b, a)`][`void`][Adds `a` to `b`. The type of `a` shall be listed in one of the type lists 4011 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4012 When not provided, the default version calls `eval_add(b, B(a))`][[space]]] 4013[[`eval_add(b, cb, cb2)`][`void`][Add `cb` to `cb2` and stores the result in `b`. 4014 When not provided, does the equivalent of `b = cb; eval_add(b, cb2)`.][[space]]] 4015[[`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 4016 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4017 When not provided, does the equivalent of `eval_add(b, cb, B(a))`.][[space]]] 4018[[`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 4019 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4020 When not provided, does the equivalent of `eval_add(b, cb, a)`.][[space]]] 4021[[`eval_subtract(b, a)`][`void`][Subtracts `a` from `b`. The type of `a` shall be listed in one of the type lists 4022 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4023 When not provided, the default version calls `eval_subtract(b, B(a))`][[space]]] 4024[[`eval_subtract(b, cb, cb2)`][`void`][Subtracts `cb2` from `cb` and stores the result in `b`. 4025 When not provided, does the equivalent of `b = cb; eval_subtract(b, cb2)`.][[space]]] 4026[[`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 4027 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4028 When not provided, does the equivalent of `eval_subtract(b, cb, B(a))`.][[space]]] 4029[[`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 4030 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4031 When not provided, does the equivalent of `eval_subtract(b, cb, a); b.negate();`.][[space]]] 4032[[`eval_multiply(b, a)`][`void`][Multiplies `b` by `a`. The type of `a` shall be listed in one of the type lists 4033 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4034 When not provided, the default version calls `eval_multiply(b, B(a))`][[space]]] 4035[[`eval_multiply(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and stores the result in `b`. 4036 When not provided, does the equivalent of `b = cb; eval_multiply(b, cb2)`.][[space]]] 4037[[`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 4038 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4039 When not provided, does the equivalent of `eval_multiply(b, cb, B(a))`.][[space]]] 4040[[`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 4041 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4042 When not provided, does the equivalent of `eval_multiply(b, cb, a)`.][[space]]] 4043[[`eval_multiply_add(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and adds the result to `b`. 4044 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 4045 `eval_add(b, t)`.][[space]]] 4046[[`eval_multiply_add(b, cb, a)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 4047 The type of `a` shall be listed in one of the type lists 4048 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4049 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 4050 `eval_add(b, t)`.][[space]]] 4051[[`eval_multiply_add(b, a, cb)`][`void`][Multiplies `a` by `cb` and adds the result to `b`. 4052 The type of `a` shall be listed in one of the type lists 4053 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4054 When not provided does the equivalent of `eval_multiply_add(b, cb, a)`.][[space]]] 4055[[`eval_multiply_subtract(b, cb, cb2)`][`void`][Multiplies `cb` by `cb2` and subtracts the result from `b`. 4056 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, cb2)` followed by 4057 `eval_subtract(b, t)`.][[space]]] 4058[[`eval_multiply_subtract(b, cb, a)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 4059 The type of `a` shall be listed in one of the type lists 4060 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4061 When not provided does the equivalent of creating a temporary `B t` and `eval_multiply(t, cb, a)` followed by 4062 `eval_subtract(b, t)`.][[space]]] 4063[[`eval_multiply_subtract(b, a, cb)`][`void`][Multiplies `a` by `cb` and subtracts the result from `b`. 4064 The type of `a` shall be listed in one of the type lists 4065 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4066 When not provided does the equivalent of `eval_multiply_subtract(b, cb, a)`.][[space]]] 4067[[`eval_multiply_add(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and adds the result to `cb3` storing the result in `b`. 4068 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 4069 `eval_add(b, cb3)`. 4070 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 4071 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 4072 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 4073[[`eval_multiply_subtract(b, cb, cb2, cb3)`][`void`][Multiplies `cb` by `cb2` and subtracts from the result `cb3` storing the result in `b`. 4074 When not provided does the equivalent of `eval_multiply(b, cb, cb2)` followed by 4075 `eval_subtract(b, cb3)`. 4076 For brevity, only a version showing all arguments of type `B` is shown here, but you can replace up to any 2 of 4077 `cb`, `cb2` and `cb3` with any type listed in one of the type lists 4078 `B::signed_types`, `B::unsigned_types` or `B::float_types`.][[space]]] 4079[[`eval_divide(b, a)`][`void`][Divides `b` by `a`. The type of `a` shall be listed in one of the type lists 4080 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4081 When not provided, the default version calls `eval_divide(b, B(a))`] 4082 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 4083[[`eval_divide(b, cb, cb2)`][`void`][Divides `cb` by `cb2` and stores the result in `b`. 4084 When not provided, does the equivalent of `b = cb; eval_divide(b, cb2)`.] 4085 [`std::overflow_error` if `cb2` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 4086[[`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 4087 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4088 When not provided, does the equivalent of `eval_divide(b, cb, B(a))`.] 4089 [`std::overflow_error` if `a` has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 4090[[`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 4091 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4092 When not provided, does the equivalent of `eval_divide(b, B(a), cb)`.] 4093 [`std::overflow_error` if cb has the value zero, and `std::numeric_limits<number<B> >::has_infinity == false`]] 4094[[`eval_increment(b)`][void][Increments the value of `b` by one. 4095 When not provided, does the equivalent of `eval_add(b, static_cast<ui_type>(1u))`. 4096 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4097[[`eval_decrement(b)`][void][Decrements the value of `b` by one. 4098 When not provided, does the equivalent of `eval_subtract(b, static_cast<ui_type>(1u))`. 4099 Where `ui_type` is `typename mpl::front<typename B::unsigned_types>::type`.][[space]]] 4100 4101[[['Integer specific operations:]]] 4102[[`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 4103 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4104 When not provided, the default version calls `eval_modulus(b, B(a))`] 4105 [`std::overflow_error` if `a` has the value zero.]] 4106[[`eval_modulus(b, cb, cb2)`][`void`][Computes `cb % cb2` and stores the result in `b`, only required when `B` is an integer type. 4107 When not provided, does the equivalent of `b = cb; eval_modulus(b, cb2)`.] 4108 [`std::overflow_error` if `a` has the value zero.]] 4109[[`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 4110 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4111 When not provided, does the equivalent of `eval_modulus(b, cb, B(a))`.] 4112 [`std::overflow_error` if `a` has the value zero.]] 4113[[`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 4114 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4115 When not provided, does the equivalent of `eval_modulus(b, B(a), cb)`.] 4116 [`std::overflow_error` if `a` has the value zero.]] 4117[[`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 4118 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4119 When not provided, the default version calls `eval_bitwise_and(b, B(a))`][[space]]] 4120[[`eval_bitwise_and(b, cb, cb2)`][`void`][Computes `cb & cb2` and stores the result in `b`, only required when `B` is an integer type. 4121 When not provided, does the equivalent of `b = cb; eval_bitwise_and(b, cb2)`.][[space]]] 4122[[`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 4123 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4124 When not provided, does the equivalent of `eval_bitwise_and(b, cb, B(a))`.][[space]]] 4125[[`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 4126 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4127 When not provided, does the equivalent of `eval_bitwise_and(b, cb, a)`.][[space]]] 4128[[`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 4129 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4130 When not provided, the default version calls `eval_bitwise_or(b, B(a))`][[space]]] 4131[[`eval_bitwise_or(b, cb, cb2)`][`void`][Computes `cb | cb2` and stores the result in `b`, only required when `B` is an integer type. 4132 When not provided, does the equivalent of `b = cb; eval_bitwise_or(b, cb2)`.][[space]]] 4133[[`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 4134 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4135 When not provided, does the equivalent of `eval_bitwise_or(b, cb, B(a))`.][[space]]] 4136[[`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 4137 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4138 When not provided, does the equivalent of `eval_bitwise_or(b, cb, a)`.][[space]]] 4139[[`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 4140 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4141 When not provided, the default version calls `eval_bitwise_xor(b, B(a))`][[space]]] 4142[[`eval_bitwise_xor(b, cb, cb2)`][`void`][Computes `cb ^ cb2` and stores the result in `b`, only required when `B` is an integer type. 4143 When not provided, does the equivalent of `b = cb; eval_bitwise_xor(b, cb2)`.][[space]]] 4144[[`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 4145 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4146 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, B(a))`.][[space]]] 4147[[`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 4148 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4149 When not provided, does the equivalent of `eval_bitwise_xor(b, cb, a)`.][[space]]] 4150[[`eval_left_shift(b, cb, ui)`][`void`][Computes `cb << ui` and stores the result in `b`, only required when `B` is an integer type. 4151 When not provided, does the equivalent of `b = cb; eval_left_shift(b, a);`.][[space]]] 4152[[`eval_right_shift(b, cb, ui)`][`void`][Computes `cb >> ui` and stores the result in `b`, only required when `B` is an integer type. 4153 When not provided, does the equivalent of `b = cb; eval_right_shift(b, a);`.][[space]]] 4154[[`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. 4155 The default version of this function is synthesised from other operations above.] 4156 [`std::overflow_error` if `a` has the value zero.]] 4157[[`eval_integer_modulus(cb, ui)`][`unsigned`][Returns the result of `cb % ui`. Only required when `B` is an integer type. 4158 The default version of this function is synthesised from other operations above.] 4159 [`std::overflow_error` if `a` has the value zero.]] 4160[[`eval_lsb(cb)`][`unsigned`][Returns the index of the least significant bit that is set. Only required when `B` is an integer type. 4161 The default version of this function is synthesised from other operations above.][[space]]] 4162[[`eval_msb(cb)`][`unsigned`][Returns the index of the most significant bit that is set. Only required when `B` is an integer type. 4163 The default version of this function is synthesised from other operations above.][[space]]] 4164[[`eval_bit_test(cb, ui)`][`bool`][Returns true if `cb` has bit `ui` set. Only required when `B` is an integer type. 4165 The default version of this function is synthesised from other operations above.][[space]]] 4166[[`eval_bit_set(b, ui)`][`void`][Sets the bit at index `ui` in `b`. Only required when `B` is an integer type. 4167 The default version of this function is synthesised from other operations above.][[space]]] 4168[[`eval_bit_unset(b, ui)`][`void`][Unsets the bit at index `ui` in `b`. Only required when `B` is an integer type. 4169 The default version of this function is synthesised from other operations above.][[space]]] 4170[[`eval_bit_flip(b, ui)`][`void`][Flips the bit at index `ui` in `b`. Only required when `B` is an integer type. 4171 The default version of this function is synthesised from other operations above.][[space]]] 4172[[`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. 4173 The default version of this function is synthesised from other operations above.][[space]]] 4174[[`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. 4175 The default version of this function is synthesised from other operations above.][[space]]] 4176[[`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. 4177 The type of `a` shall be listed in one of the type lists 4178 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4179 The default version of this function calls `eval_gcd(b, cb, B(a))`.][[space]]] 4180[[`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. 4181 The type of `a` shall be listed in one of the type lists 4182 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4183 The default version of this function calls `eval_lcm(b, cb, B(a))`.][[space]]] 4184[[`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. 4185 The type of `a` shall be listed in one of the type lists 4186 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4187 The default version of this function calls `eval_gcd(b, cb, a)`.][[space]]] 4188[[`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. 4189 The type of `a` shall be listed in one of the type lists 4190 `B::signed_types`, `B::unsigned_types` or `B::float_types`. 4191 The default version of this function calls `eval_lcm(b, cb, a)`.][[space]]] 4192[[`eval_powm(b, cb, cb2, cb3)`][`void`][Sets `b` to the result of ['(cb^cb2)%cb3]. 4193 The default version of this function is synthesised from other operations above.][[space]]] 4194[[`eval_powm(b, cb, cb2, a)`][`void`][Sets `b` to the result of ['(cb^cb2)%a]. 4195 The type of `a` shall be listed in one of the type lists 4196 `B::signed_types`, `B::unsigned_types`. 4197 The default version of this function is synthesised from other operations above.][[space]]] 4198[[`eval_powm(b, cb, a, cb2)`][`void`][Sets `b` to the result of ['(cb^a)%cb2]. 4199 The type of `a` shall be listed in one of the type lists 4200 `B::signed_types`, `B::unsigned_types`. 4201 The default version of this function is synthesised from other operations above.][[space]]] 4202[[`eval_powm(b, cb, a, a2)`][`void`][Sets `b` to the result of ['(cb^a)%a2]. 4203 The type of `a` shall be listed in one of the type lists 4204 `B::signed_types`, `B::unsigned_types`. 4205 The default version of this function is synthesised from other operations above.][[space]]] 4206[[`eval_integer_sqrt(b, cb, b2)`][`void`][Sets `b` to the largest integer which when squared is less than `cb`, also 4207 sets `b2` to the remainder, ie to ['cb - b[super 2]]. 4208 The default version of this function is synthesised from other operations above.][[space]]] 4209 4210[[['Sign manipulation:]]] 4211[[`eval_abs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 4212 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 4213 `eval_get_sign(cb) < 0`.][[space]]] 4214[[`eval_fabs(b, cb)`][`void`][Set `b` to the absolute value of `cb`. 4215 The default version of this functions assigns `cb` to `b`, and then calls `b.negate()` if 4216 `eval_get_sign(cb) < 0`.][[space]]] 4217 4218[[['Floating point functions:]]] 4219[[`eval_fpclassify(cb)`][`int`][Returns one of the same values returned by `std::fpclassify`. Only required when `B` is an floating-point type. 4220 The default version of this function will only test for zero `cb`.][[space]]] 4221[[`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. 4222 The default version of this function is synthesised from other operations above.][[space]]] 4223[[`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. 4224 The default version of this function is synthesised from other operations above.][[space]]] 4225[[`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. 4226 The default version of this function is synthesised from other operations above.][[space]]] 4227[[`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. 4228 The default version of this function is synthesised from other operations above.][[space]]] 4229[[`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. 4230 The default version of this function is synthesised from other operations above.][[space]]] 4231[[`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. 4232 The default version of this function is synthesised from other operations above.][[space]]] 4233[[`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. 4234 The default version of this function is synthesised from other operations above.][[space]]] 4235[[`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. 4236 The default version of this function is synthesised from other operations above.][[space]]] 4237[[`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. 4238 The default version of this function is synthesised from other operations above.][[space]]] 4239[[`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. 4240 The default version of this function is synthesised from other operations above.][[space]]] 4241[[`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. 4242 The default version of this function is synthesised from other operations above.][[space]]] 4243[[`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. 4244 The default version of this function is synthesised from other operations above.][[space]]] 4245[[`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. 4246 The default version of this function is synthesised from other operations above.][[space]]] 4247[[`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. 4248 The default version of this function is synthesised from other operations above.][[space]]] 4249[[`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. 4250 The default version of this function is synthesised from other operations above.][[space]]] 4251[[`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. 4252 The default version of this function is synthesised from other operations above.][[space]]] 4253[[`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. 4254 The default version of this function is synthesised from other operations above.][[space]]] 4255[[`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 4256 is implemented in terms of eval_ldexp, consequently this function must be provided for types with a radix other than 2.]] 4257[[`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. 4258 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.]] 4259[[`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. 4260 The default version of this function is implemented in terms of `eval_ilogb`.]] 4261] 4262 4263When the tables above place no ['throws] requirements on an operation, then it is up to each type modelling this concept to 4264decide when or whether throwing an exception is desirable. However, thrown exceptions should always either be the type, or 4265inherit from the type `std::runtime_error`. For example, a floating point type might choose to throw `std::overflow_error` 4266whenever the result of an operation would be infinite, and `std::underflow_error` whenever it would round to zero. 4267 4268[note 4269The non-member functions are all named with an "eval_" prefix to avoid conflicts with template classes of the same name - 4270in point of fact this naming convention shouldn't be necessary, but rather works around some compiler bugs.] 4271 4272[endsect] 4273 4274[section:headers Header File Structure] 4275 4276[table Top level headers 4277[[Header][Contains]] 4278[[cpp_int.hpp][The `cpp_int` backend type.]] 4279[[gmp.hpp][Defines all [gmp] related backends.]] 4280[[miller_rabin.hpp][Miller Rabin primality testing code.]] 4281[[number.hpp][Defines the `number` backend, is included by all the backend headers.]] 4282[[mpfr.hpp][Defines the mpfr_float_backend backend.]] 4283[[random.hpp][Defines code to interoperate with Boost.Random.]] 4284[[rational_adaptor.hpp][Defines the `rational_adaptor` backend.]] 4285[[cpp_dec_float.hpp][Defines the `cpp_dec_float` backend.]] 4286[[tommath.hpp][Defines the `tommath_int` backend.]] 4287[[concepts/number_archetypes.hpp][Defines a backend concept archetypes for testing use.]] 4288] 4289 4290[table Implementation Headers 4291[[Header][Contains]] 4292[[cpp_int/add.hpp][Add and subtract operators for `cpp_int_backend`.]] 4293[[cpp_int/bitwise.hpp][Bitwise operators for `cpp_int_backend`.]] 4294[[cpp_int/checked.hpp][Helper functions for checked arithmetic for `cpp_int_backend`.]] 4295[[cpp_int/comparison.hpp][Comparison operators for `cpp_int_backend`.]] 4296[[cpp_int/cpp_int_config.hpp][Basic setup and configuration for `cpp_int_backend`.]] 4297[[cpp_int/divide.hpp][Division and modulus operators for `cpp_int_backend`.]] 4298[[cpp_int/limits.hpp][`numeric_limits` support for `cpp_int_backend`.]] 4299[[cpp_int/misc.hpp][Miscellaneous operators for `cpp_int_backend`.]] 4300[[cpp_int/multiply.hpp][Multiply operators for `cpp_int_backend`.]] 4301[[detail/big_lanczos.hpp][Lanczos support for Boost.Math integration.]] 4302[[detail/default_ops.hpp][Default versions of the optional backend non-member functions.]] 4303[[detail/generic_interconvert.hpp][Generic interconversion routines.]] 4304[[detail/number_base.hpp][All the expression template code, metaprogramming, and operator overloads for `number`.]] 4305[[detail/no_et_ops.hpp][The non-expression template operators.]] 4306[[detail/functions/constants.hpp][Defines constants used by the floating point functions.]] 4307[[detail/functions/pow.hpp][Defines default versions of the power and exponential related floating point functions.]] 4308[[detail/functions/trig.hpp][Defines default versions of the trigonometric related floating point functions.]] 4309] 4310 4311[endsect] 4312 4313[endsect] 4314 4315[section:perf Performance Comparison] 4316 4317[section:overhead The Overhead in the Number Class Wrapper] 4318 4319Using a simple [@../../performance/arithmetic_backend.hpp backend class] that wraps any built in arithmetic type 4320we can measure the overhead involved in wrapping a type inside the `number` frontend, and the effect that turning 4321on expression templates has. The following table compares the performance between `double` and a `double` wrapped 4322inside class `number`: 4323 4324[table 4325[[Type][Bessel Function Evaluation][Non-Central T Evaluation]] 4326[[`double`] [[*1.0 (0.016s)]] [[*1.0] (0.46s)]] 4327[[`number<arithmetic_backend<double>, et_off>`] [1.2 (0.019s)] [[*1.0](0.46s)]] 4328[[`number<arithmetic_backend<double>, et_on>`] [1.2 (0.019s)] [1.7 (0.79s)]] 4329] 4330 4331As you can see whether or not there is an overhead, and how large it is depends on the actual situation, 4332but the overhead is in any cases small. Expression templates generally add a greater overhead the 4333more complex the expression becomes due to the logic of figuring out how to best unpack and evaluate 4334the expression, but of course this is also the situation where you save more temporaries. For a 4335"trivial" backend like this, saving temporaries has no benefit, but for larger types it becomes 4336a bigger win. 4337 4338The following table compares arithmetic using either `long long` or `number<arithmetic_backend<long long> >` 4339for the [@../../performance/voronoi_performance.cpp voronoi-diagram builder test]: 4340 4341[table 4342[[Type][Relative time]] 4343[[`long long`][[*1.0](0.0823s)]] 4344[[`number<arithmetic_backend<long long>, et_off>`][1.05 (0.0875s)]] 4345] 4346 4347This test involves mainly creating a lot of temporaries and performing a small amount of arithmetic on them, 4348with very little difference in performance between the native and "wrapped" types. 4349 4350The test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4351turned on (/Ox), and used MPIR-2.3.0 and [tommath]-0.42.0. The tests were run on 32-bit 4352Windows Vista machine. 4353 4354[endsect] 4355 4356[section:realworld Floating-Point Real World Tests] 4357 4358These tests test the total time taken to execute all of Boost.Math's test cases for these functions. 4359In each case the best performing library gets a relative score of 1, with the total execution time 4360given in brackets. The first three libraries listed are the various floating point types provided 4361by this library, while for comparison, two popular C++ front-ends to [mpfr] ([mpfr_class] and [mpreal]) 4362are also shown. 4363 4364[table Bessel Function Performance 4365[[Library][50 Decimal Digits][100 Decimal Digits]] 4366[[mpfr_float] [1.2 (5.78s)] [1.2 (9.56s)]] 4367[[static_mpfr_float] [1.1 (5.47s)] [1.1 (9.09s)]] 4368[[mpf_float] [[*1.0] (4.82s)] [[*1.0](8.07s)]] 4369[[cpp_dec_float] [1.8 (8.54s)] [2.6 (20.66s)]] 4370[[[mpfr_class]] [1.3 (6.28s)] [1.2(10.06s)]] 4371[[[mpreal]] [2.0 (9.54s)] [1.7 (14.08s)]] 4372] 4373 4374[table Non-Central T Distribution Performance 4375[[Library][50 Decimal Digits]] 4376[[mpfr_float] [1.3 (263.27s)]] 4377[[static_mpfr_float] [1.2 (232.88s)]] 4378[[mpf_float] [[*1.0] (195.73s)]] 4379[[cpp_dec_float] [1.9 (366.38s)]] 4380[[[mpfr_class]] [1.5 (286.94s)]] 4381[[[mpreal]] [2.0 (388.70s)]] 4382] 4383 4384Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4385turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 4386Windows Vista machine. 4387 4388[endsect] 4389 4390[section:int_real_world Integer Real World Tests] 4391 4392The first set of [@../../performance/voronoi_performance.cpp tests] measure the times taken to 4393execute the multiprecision part of the Voronoi-diagram builder from Boost.Polygon. The tests 4394mainly create a large number of temporaries "just in case" multiprecision arithmetic is required, 4395for comparison, also included in the tests is Boost.Polygon's own partial-multiprecision integer 4396type which was custom written for this specific task: 4397 4398[table 4399[[Integer Type][Relative Performance (Actual time in parenthesis)]] 4400[[polygon::detail::extended_int][1(0.138831s)]] 4401[[int256_t][1.19247(0.165551s)]] 4402[[int512_t][1.23301(0.17118s)]] 4403[[int1024_t][1.21463(0.168628s)]] 4404[[checked_int256_t][1.31711(0.182855s)]] 4405[[checked_int512_t][1.57413(0.218538s)]] 4406[[checked_int1024_t][1.36992(0.190187s)]] 4407[[cpp_int][1.63244(0.226632s)]] 4408[[mpz_int][5.42511(0.753172s)]] 4409[[tom_int][29.0793(4.03709s)]] 4410] 4411 4412Note how for this use case, any dynamic allocation is a performance killer. 4413 4414The next [@../../performance/miller_rabin_performance.cpp tests] measure the time taken to generate 1000 128-bit 4415random numbers and test for primality using the Miller Rabin test. This is primarily a test of modular-exponentiation 4416since that is the rate limiting step: 4417 4418[table 4419[[Integer Type][Relative Performance (Actual time in parenthesis)]] 4420[[cpp_int][5.25827(0.379597s)]] 4421[[cpp_int (no Expression templates)][5.15675(0.372268s)]] 4422[[cpp_int (128-bit cache)][5.10882(0.368808s)]] 4423[[cpp_int (256-bit cache)][5.50623(0.397497s)]] 4424[[cpp_int (512-bit cache)][4.82257(0.348144s)]] 4425[[cpp_int (1024-bit cache)][5.00053(0.360991s)]] 4426[[int1024_t][4.37589(0.315897s)]] 4427[[checked_int1024_t][4.52396(0.326587s)]] 4428[[mpz_int][1(0.0721905s)]] 4429[[mpz_int (no Expression templates)][1.0248(0.0739806s)]] 4430[[tom_int][2.60673(0.188181s)]] 4431[[tom_int (no Expression templates)][2.64997(0.191303s)]] 4432] 4433 4434It's interesting to note that expression templates have little effect here - perhaps because the actual expressions involved 4435are relatively trivial in this case - so the time taken for multiplication and division tends to dominate. Also note 4436how increasing the internal cache size used by `cpp_int` is quite effective in this case in cutting out memory allocations 4437altogether - cutting about a third off the total runtime. Finally the much quicker times from GMP and tommath are down to their 4438much better modular-exponentiation algorithms (GMP's is about 5x faster). That's an issue which needs to be addressed 4439in a future release for __cpp_int. 4440 4441Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4442turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 4443Windows Vista machine. 4444 4445[endsect] 4446 4447[section:float_performance Float Algorithm Performance] 4448 4449Note that these tests are carefully designed to test performance of the underlying algorithms 4450and not memory allocation or variable copying. As usual, performance results should be taken 4451with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 4452specifics of the program. In each table relative times are given first, with the best performer 4453given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 4454operations. 4455 4456[table Operator + 4457[[Backend][50 Bits][100 Bits][500 Bits]] 4458[[cpp_dec_float][[*1] (0.0575156s)][[*1] (0.0740086s)][[*1] (0.219073s)]] 4459[[gmp_float][2.45065 (0.14095s)][2.01398 (0.149052s)][1.09608 (0.240122s)]] 4460[[mpfr_float][2.6001 (0.149546s)][2.12079 (0.156957s)][1.09078 (0.23896s)]] 4461] 4462[table Operator +(int) 4463[[Backend][50 Bits][100 Bits][500 Bits]] 4464[[cpp_dec_float][1.46115 (0.0855392s)][2.60353 (0.114398s)][3.62562 (0.264905s)]] 4465[[gmp_float][[*1] (0.0585424s)][[*1] (0.0439398s)][[*1] (0.0730648s)]] 4466[[mpfr_float][2.40441 (0.14076s)][3.2877 (0.144461s)][2.40379 (0.175632s)]] 4467] 4468[table Operator +(unsigned long long) 4469[[Backend][50 Bits][100 Bits][500 Bits]] 4470[[cpp_dec_float][[*1] (0.118146s)][[*1] (0.144714s)][[*1] (0.315639s)]] 4471[[gmp_float][4.5555 (0.538213s)][3.83096 (0.554395s)][1.95079 (0.615745s)]] 4472[[mpfr_float][5.74477 (0.678719s)][4.85295 (0.702291s)][2.70354 (0.853342s)]] 4473] 4474[table Operator +=(unsigned long long) 4475[[Backend][50 Bits][100 Bits][500 Bits]] 4476[[cpp_dec_float][[*1] (0.101188s)][[*1] (0.122394s)][[*1] (0.251975s)]] 4477[[gmp_float][5.199 (0.526079s)][4.39327 (0.537712s)][2.42151 (0.610159s)]] 4478[[mpfr_float][6.08318 (0.615547s)][5.18525 (0.634645s)][3.1022 (0.781677s)]] 4479] 4480[table Operator - 4481[[Backend][50 Bits][100 Bits][500 Bits]] 4482[[cpp_dec_float][[*1] (0.0895163s)][[*1] (0.129248s)][1.5088 (0.374512s)]] 4483[[gmp_float][1.72566 (0.154474s)][1.22567 (0.158415s)][[*1] (0.248219s)]] 4484[[mpfr_float][1.83764 (0.164499s)][1.34284 (0.173559s)][1.00226 (0.248781s)]] 4485] 4486[table Operator -(int) 4487[[Backend][50 Bits][100 Bits][500 Bits]] 4488[[cpp_dec_float][[*1] (0.105285s)][[*1] (0.142741s)][[*1] (0.278718s)]] 4489[[gmp_float][2.34437 (0.246828s)][1.28814 (0.183871s)][1.00731 (0.280754s)]] 4490[[mpfr_float][2.8032 (0.295136s)][2.09178 (0.298582s)][1.25213 (0.34899s)]] 4491] 4492[table Operator -(unsigned long long) 4493[[Backend][50 Bits][100 Bits][500 Bits]] 4494[[cpp_dec_float][[*1] (0.13719s)][[*1] (0.184428s)][[*1] (0.344212s)]] 4495[[gmp_float][4.0804 (0.559791s)][3.06776 (0.565781s)][2.07736 (0.715053s)]] 4496[[mpfr_float][5.10114 (0.699828s)][3.88684 (0.716843s)][2.50074 (0.860784s)]] 4497] 4498[table Operator -=(unsigned long long) 4499[[Backend][50 Bits][100 Bits][500 Bits]] 4500[[cpp_dec_float][[*1] (0.100984s)][[*1] (0.123148s)][[*1] (0.246181s)]] 4501[[gmp_float][5.68353 (0.573944s)][4.68636 (0.577116s)][2.6958 (0.663655s)]] 4502[[mpfr_float][6.19738 (0.625834s)][5.18544 (0.638577s)][3.18738 (0.784673s)]] 4503] 4504[table Operator * 4505[[Backend][50 Bits][100 Bits][500 Bits]] 4506[[cpp_dec_float][1.03667 (0.284251s)][1.30576 (0.536527s)][1.44686 (4.81057s)]] 4507[[gmp_float][[*1] (0.274196s)][[*1] (0.410891s)][[*1] (3.32484s)]] 4508[[mpfr_float][1.24537 (0.341477s)][1.15785 (0.475749s)][1.1796 (3.92199s)]] 4509] 4510[table Operator *(int) 4511[[Backend][50 Bits][100 Bits][500 Bits]] 4512[[cpp_dec_float][3.97453 (0.240262s)][9.91222 (0.463473s)][50.7926 (4.36527s)]] 4513[[gmp_float][[*1] (0.0604505s)][[*1] (0.0467577s)][[*1] (0.0859431s)]] 4514[[mpfr_float][2.56974 (0.155342s)][3.56312 (0.166603s)][3.22964 (0.277565s)]] 4515] 4516[table Operator *(unsigned long long) 4517[[Backend][50 Bits][100 Bits][500 Bits]] 4518[[cpp_dec_float][[*1] (0.331877s)][1.01058 (0.586122s)][6.688 (4.7931s)]] 4519[[gmp_float][1.72433 (0.572266s)][[*1] (0.579987s)][[*1] (0.716672s)]] 4520[[mpfr_float][2.5553 (0.848047s)][1.74987 (1.0149s)][1.80403 (1.2929s)]] 4521] 4522[table Operator *=(unsigned long long) 4523[[Backend][50 Bits][100 Bits][500 Bits]] 4524[[cpp_dec_float][[*1] (0.321397s)][1.00772 (0.574887s)][6.65946 (4.7468s)]] 4525[[gmp_float][1.77419 (0.570218s)][[*1] (0.570482s)][[*1] (0.712791s)]] 4526[[mpfr_float][2.62172 (0.842611s)][1.77691 (1.01369s)][1.77511 (1.26528s)]] 4527] 4528[table Operator / 4529[[Backend][50 Bits][100 Bits][500 Bits]] 4530[[cpp_dec_float][2.96096 (4.00777s)][4.53244 (7.86435s)][6.11936 (51.5509s)]] 4531[[gmp_float][[*1] (1.35354s)][[*1] (1.73512s)][[*1] (8.42422s)]] 4532[[mpfr_float][1.30002 (1.75963s)][1.39045 (2.41261s)][1.66762 (14.0484s)]] 4533] 4534[table Operator /(int) 4535[[Backend][50 Bits][100 Bits][500 Bits]] 4536[[cpp_dec_float][8.60726 (1.8181s)][15.4122 (3.67479s)][34.5119 (24.729s)]] 4537[[gmp_float][1.24394 (0.262756s)][[*1] (0.238433s)][[*1] (0.716536s)]] 4538[[mpfr_float][[*1] (0.211229s)][1.12178 (0.26747s)][1.02237 (0.732562s)]] 4539] 4540[table Operator /(unsigned long long) 4541[[Backend][50 Bits][100 Bits][500 Bits]] 4542[[cpp_dec_float][2.10976 (1.97569s)][3.73601 (3.9133s)][11.3085 (25.4533s)]] 4543[[gmp_float][[*1] (0.936452s)][[*1] (1.04746s)][[*1] (2.25081s)]] 4544[[mpfr_float][1.3423 (1.257s)][1.51575 (1.58768s)][3.31513 (7.46175s)]] 4545] 4546[table Operator /=(unsigned long long) 4547[[Backend][50 Bits][100 Bits][500 Bits]] 4548[[cpp_dec_float][2.17401 (1.96883s)][3.79591 (3.8965s)][11.2328 (25.2606s)]] 4549[[gmp_float][[*1] (0.905621s)][[*1] (1.0265s)][[*1] (2.24882s)]] 4550[[mpfr_float][1.37953 (1.24933s)][1.53073 (1.57129s)][3.30546 (7.43339s)]] 4551] 4552[table Operator construct 4553[[Backend][50 Bits][100 Bits][500 Bits]] 4554[[cpp_dec_float][[*1] (0.00929804s)][[*1] (0.0268321s)][[*1] (0.0310685s)]] 4555[[gmp_float][30.8781 (0.287106s)][7.59969 (0.203916s)][6.51873 (0.202527s)]] 4556[[mpfr_float][23.5296 (0.218779s)][8.11058 (0.217624s)][7.16325 (0.222552s)]] 4557] 4558[table Operator construct(unsigned) 4559[[Backend][50 Bits][100 Bits][500 Bits]] 4560[[cpp_dec_float][[*1] (0.0603971s)][[*1] (0.0735485s)][[*1] (0.116464s)]] 4561[[gmp_float][3.91573 (0.236498s)][2.88171 (0.211945s)][1.81075 (0.210887s)]] 4562[[mpfr_float][4.90052 (0.295977s)][4.01118 (0.295017s)][2.62005 (0.305141s)]] 4563] 4564[table Operator construct(unsigned long long) 4565[[Backend][50 Bits][100 Bits][500 Bits]] 4566[[cpp_dec_float][[*1] (0.0610288s)][[*1] (0.0759005s)][[*1] (0.118511s)]] 4567[[gmp_float][8.26247 (0.504249s)][6.69042 (0.507806s)][4.32819 (0.51294s)]] 4568[[mpfr_float][10.1593 (0.620013s)][8.45884 (0.64203s)][5.51472 (0.653557s)]] 4569] 4570[table Operator str 4571[[Backend][50 Bits][100 Bits][500 Bits]] 4572[[cpp_dec_float][2.95848 (0.0223061s)][3.33461 (0.033471s)][3.0159 (0.132732s)]] 4573[[gmp_float][[*1] (0.00753971s)][[*1] (0.0100374s)][[*1] (0.0440106s)]] 4574[[mpfr_float][1.25424 (0.00945658s)][1.24943 (0.012541s)][1.09428 (0.0481601s)]] 4575] 4576 4577Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4578turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 4579Windows Vista machine. 4580 4581[endsect] 4582 4583[section:integer_performance Integer Algorithm Performance] 4584 4585Note that these tests are carefully designed to test performance of the underlying algorithms 4586and not memory allocation or variable copying. As usual, performance results should be taken 4587with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 4588specifics of the program. In each table relative times are given first, with the best performer 4589given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 4590operations. 4591 4592[table Operator + 4593[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4594[[cpp_int][1.23704 (0.0274266s)][1.09358 (0.0383278s)][1.26645 (0.0558828s)][1.32188 (0.0916899s)]] 4595[[cpp_int(fixed)][1.62044 (0.0359271s)][1.5277 (0.053543s)][1.73059 (0.076363s)][1.71537 (0.118983s)]] 4596[[gmp_int][1.87515 (0.0415741s)][1.21699 (0.042653s)][1.15599 (0.0510088s)][[*1] (0.0693631s)]] 4597[[tommath_int][[*1] (0.0221711s)][[*1] (0.035048s)][[*1] (0.0441255s)][1.04441 (0.0724435s)]] 4598] 4599[table Operator +(int) 4600[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4601[[cpp_int][[*1] (0.0155377s)][[*1] (0.0209523s)][[*1] (0.0306377s)][[*1] (0.043125s)]] 4602[[cpp_int(fixed)][1.31904 (0.0204948s)][1.76211 (0.0369203s)][1.52941 (0.0468577s)][1.60412 (0.0691778s)]] 4603[[gmp_int][1.96204 (0.0304855s)][2.02569 (0.0424428s)][2.11505 (0.0648002s)][2.65993 (0.114709s)]] 4604[[tommath_int][14.0654 (0.218543s)][10.8239 (0.226786s)][7.76691 (0.23796s)][6.10039 (0.263079s)]] 4605] 4606[table Operator +(unsigned long long) 4607[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4608[[cpp_int][[*1] (0.026624s)][[*1] (0.0291407s)][[*1] (0.0373209s)][[*1] (0.0464919s)]] 4609[[cpp_int(fixed)][1.31378 (0.034978s)][1.54897 (0.045138s)][1.53649 (0.0573431s)][1.27833 (0.0594319s)]] 4610[[gmp_int][25.5775 (0.680974s)][24.0117 (0.699717s)][19.5633 (0.730121s)][16.8939 (0.785432s)]] 4611[[tommath_int][19.4694 (0.518354s)][18.4246 (0.536907s)][14.7715 (0.551288s)][12.3637 (0.574812s)]] 4612] 4613[table Operator +=(unsigned long long) 4614[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4615[[cpp_int][1.18405 (0.0196905s)][1.22304 (0.0206476s)][1.25861 (0.0217397s)][1.29525 (0.0220829s)]] 4616[[cpp_int(fixed)][[*1] (0.0166298s)][[*1] (0.0168822s)][[*1] (0.0172728s)][[*1] (0.0170492s)]] 4617[[gmp_int][39.9082 (0.663668s)][39.4584 (0.666147s)][38.5504 (0.665873s)][39.2231 (0.668722s)]] 4618[[tommath_int][30.6219 (0.509238s)][30.4135 (0.513447s)][30.9077 (0.533863s)][32.3086 (0.550835s)]] 4619] 4620[table Operator - 4621[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4622[[cpp_int][1.06986 (0.0296064s)][[*1] (0.0381508s)][1.05932 (0.053186s)][1.1766 (0.0844721s)]] 4623[[cpp_int(fixed)][1.3304 (0.0368163s)][1.44506 (0.0551303s)][1.4431 (0.0724545s)][1.57255 (0.112898s)]] 4624[[gmp_int][1.48072 (0.0409761s)][1.19003 (0.0454007s)][1.0794 (0.0541942s)][[*1] (0.0717934s)]] 4625[[tommath_int][[*1] (0.0276731s)][1.10891 (0.0423057s)][[*1] (0.0502076s)][1.08479 (0.0778811s)]] 4626] 4627[table Operator -(int) 4628[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4629[[cpp_int][[*1] (0.0147372s)][[*1] (0.0170001s)][[*1] (0.0232882s)][[*1] (0.0310734s)]] 4630[[cpp_int(fixed)][1.4267 (0.0210256s)][1.98887 (0.0338109s)][1.83788 (0.0428009s)][1.81269 (0.0563264s)]] 4631[[gmp_int][2.07504 (0.0305803s)][2.40928 (0.0409579s)][2.58711 (0.0602493s)][3.26438 (0.101435s)]] 4632[[tommath_int][13.5424 (0.199577s)][12.1793 (0.207048s)][9.28855 (0.216314s)][7.49327 (0.232842s)]] 4633] 4634[table Operator -(unsigned long long) 4635[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4636[[cpp_int][[*1] (0.0277377s)][[*1] (0.0296807s)][[*1] (0.0372392s)][[*1] (0.0455855s)]] 4637[[cpp_int(fixed)][1.19867 (0.0332484s)][1.48639 (0.0441169s)][1.43253 (0.0533464s)][1.27697 (0.0582111s)]] 4638[[gmp_int][24.1794 (0.670683s)][22.9073 (0.679904s)][18.8758 (0.702922s)][16.5837 (0.755975s)]] 4639[[tommath_int][18.149 (0.503413s)][17.4116 (0.516787s)][14.0411 (0.52288s)][11.8237 (0.538987s)]] 4640] 4641[table Operator -=(unsigned long long) 4642[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4643[[cpp_int][1.26896 (0.0203467s)][1.25722 (0.0206147s)][1.36108 (0.0225485s)][1.18351 (0.0226161s)]] 4644[[cpp_int(fixed)][[*1] (0.0160342s)][[*1] (0.0163971s)][[*1] (0.0165667s)][[*1] (0.0191094s)]] 4645[[gmp_int][41.1339 (0.659547s)][40.3982 (0.662411s)][39.925 (0.661425s)][34.636 (0.661874s)]] 4646[[tommath_int][31.1543 (0.499533s)][31.0303 (0.508806s)][30.7699 (0.509756s)][27.7054 (0.529434s)]] 4647] 4648[table Operator * 4649[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4650[[cpp_int][1.11839 (0.0757577s)][1.61061 (0.207951s)][1.4501 (0.696912s)][1.72796 (2.64108s)]] 4651[[cpp_int(fixed)][1.01115 (0.0684934s)][1.28687 (0.166152s)][[*1] (0.480595s)][[*1] (1.52844s)]] 4652[[gmp_int][[*1] (0.0677384s)][[*1] (0.129113s)][1.09011 (0.523902s)][1.03374 (1.58s)]] 4653[[tommath_int][1.6322 (0.110562s)][2.71751 (0.350866s)][2.05222 (0.986288s)][2.0644 (3.15531s)]] 4654] 4655[table Operator *(int) 4656[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4657[[cpp_int][1.01611 (0.0229536s)][1.12175 (0.0298152s)][1.16413 (0.0416439s)][1.31747 (0.0666043s)]] 4658[[cpp_int(fixed)][1.30215 (0.0294152s)][1.669 (0.0443606s)][1.72395 (0.0616701s)][1.88315 (0.095202s)]] 4659[[gmp_int][[*1] (0.0225897s)][[*1] (0.0265791s)][[*1] (0.0357725s)][[*1] (0.0505547s)]] 4660[[tommath_int][10.8281 (0.244603s)][10.1516 (0.26982s)][8.76424 (0.313519s)][8.04364 (0.406644s)]] 4661] 4662[table Operator *(unsigned long long) 4663[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4664[[cpp_int][[*1] (0.0570721s)][[*1] (0.0856141s)][[*1] (0.143279s)][[*1] (0.252785s)]] 4665[[cpp_int(fixed)][1.10857 (0.0632686s)][1.2951 (0.110878s)][1.20827 (0.173121s)][1.18463 (0.299456s)]] 4666[[gmp_int][12.0605 (0.68832s)][8.13434 (0.696415s)][5.21762 (0.747577s)][3.11601 (0.787681s)]] 4667[[tommath_int][10.0524 (0.57371s)][7.33116 (0.627651s)][4.85202 (0.695193s)][3.35808 (0.848871s)]] 4668] 4669[table Operator *=(unsigned long long) 4670[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4671[[cpp_int][111.27 (7.43118s)][67.7078 (7.34138s)][43.3851 (7.4075s)][25.3089 (7.55455s)]] 4672[[cpp_int(fixed)][[*1] (0.0667848s)][[*1] (0.108427s)][[*1] (0.170738s)][[*1] (0.298493s)]] 4673[[gmp_int][46.3718 (3.09693s)][28.4639 (3.08626s)][18.1719 (3.10264s)][10.5223 (3.14083s)]] 4674[[tommath_int][276.674 (18.4776s)][169.146 (18.34s)][108.491 (18.5236s)][63.3261 (18.9024s)]] 4675] 4676[table Operator / 4677[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4678[[cpp_int][2.68035 (0.595251s)][2.04702 (0.707471s)][1.62314 (0.921536s)][1.43112 (1.38811s)]] 4679[[cpp_int(fixed)][[*1] (0.222079s)][[*1] (0.34561s)][[*1] (0.567748s)][[*1] (0.969945s)]] 4680[[gmp_int][3.79283 (0.842308s)][2.73668 (0.945824s)][1.86649 (1.05969s)][1.32141 (1.2817s)]] 4681[[tommath_int][13.2531 (2.94324s)][11.2054 (3.87271s)][9.83293 (5.58262s)][13.0164 (12.6252s)]] 4682] 4683[table Operator /(int) 4684[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4685[[cpp_int][4.06026 (0.225473s)][3.45732 (0.340049s)][3.00195 (0.547957s)][2.80587 (0.978029s)]] 4686[[cpp_int(fixed)][2.43766 (0.135367s)][2.56264 (0.252052s)][2.44011 (0.445402s)][2.38009 (0.829617s)]] 4687[[gmp_int][[*1] (0.0555316s)][[*1] (0.0983563s)][[*1] (0.182534s)][[*1] (0.348566s)]] 4688[[tommath_int][35.9988 (1.99907s)][27.1024 (2.66569s)][21.8333 (3.98531s)][25.8066 (8.99528s)]] 4689] 4690[table Operator /(unsigned long long) 4691[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4692[[cpp_int][1.50505 (0.705756s)][1.39347 (1.58556s)][2.63348 (3.57438s)][4.75451 (8.52733s)]] 4693[[cpp_int(fixed)][[*1] (0.468925s)][1.12378 (1.27869s)][2.29966 (3.12128s)][4.4844 (8.04288s)]] 4694[[gmp_int][2.17234 (1.01866s)][[*1] (1.13785s)][[*1] (1.35728s)][[*1] (1.79352s)]] 4695[[tommath_int][4.74612 (2.22557s)][2.70088 (3.07319s)][3.65634 (4.96268s)][6.79408 (12.1853s)]] 4696] 4697[table Operator /=(unsigned long long) 4698[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4699[[cpp_int][1.76281 (0.0574966s)][1.76471 (0.0604224s)][1.56085 (0.0716403s)][1.31422 (0.124043s)]] 4700[[cpp_int(fixed)][[*1] (0.0326164s)][[*1] (0.0342393s)][[*1] (0.0458981s)][[*1] (0.0943852s)]] 4701[[gmp_int][20.2862 (0.661664s)][19.4043 (0.664389s)][14.4881 (0.664976s)][7.14238 (0.674135s)]] 4702[[tommath_int][32.9555 (1.07489s)][30.1525 (1.0324s)][22.8324 (1.04796s)][11.7456 (1.10861s)]] 4703] 4704[table Operator % 4705[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4706[[cpp_int][1.8501 (0.364131s)][1.46527 (0.476653s)][1.27509 (0.689738s)][1.20064 (1.11769s)]] 4707[[cpp_int(fixed)][[*1] (0.196817s)][[*1] (0.325301s)][[*1] (0.540932s)][[*1] (0.930916s)]] 4708[[gmp_int][3.2533 (0.640305s)][2.15441 (0.700832s)][1.47898 (0.800029s)][1.07439 (1.00016s)]] 4709[[tommath_int][15.3501 (3.02116s)][12.1106 (3.9396s)][11.0689 (5.98752s)][13.5535 (12.6172s)]] 4710] 4711[table Operator %(int) 4712[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4713[[cpp_int][1.82761 (0.104331s)][2.01496 (0.202512s)][2.10004 (0.389523s)][2.17252 (0.768097s)]] 4714[[cpp_int(fixed)][1.78851 (0.102099s)][1.96844 (0.197838s)][2.02956 (0.376451s)][2.07257 (0.73276s)]] 4715[[gmp_int][[*1] (0.057086s)][[*1] (0.100505s)][[*1] (0.185483s)][[*1] (0.353552s)]] 4716[[tommath_int][36.3018 (2.07233s)][26.3075 (2.64402s)][21.9525 (4.07183s)][25.6759 (9.07775s)]] 4717] 4718[table Operator construct 4719[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4720[[cpp_int][1.40211 (0.0026854s)][[*1] (0.00278639s)][[*1] (0.00322813s)][[*1] (0.0027185s)]] 4721[[cpp_int(fixed)][[*1] (0.00191526s)][1.40721 (0.00392103s)][1.90346 (0.00614463s)][2.14621 (0.00583447s)]] 4722[[gmp_int][98.705 (0.189046s)][68.9726 (0.192184s)][58.8994 (0.190135s)][70.0525 (0.190438s)]] 4723[[tommath_int][105.602 (0.202255s)][74.1994 (0.206748s)][63.6455 (0.205456s)][76.8935 (0.209035s)]] 4724] 4725[table Operator construct(unsigned) 4726[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4727[[cpp_int][1.73436 (0.00348927s)][[*1] (0.00263476s)][[*1] (0.0027009s)][[*1] (0.00318651s)]] 4728[[cpp_int(fixed)][[*1] (0.00201185s)][1.36851 (0.0036057s)][2.07362 (0.00560064s)][1.66856 (0.00531688s)]] 4729[[gmp_int][97.2414 (0.195635s)][76.3759 (0.201232s)][72.7396 (0.196462s)][63.8129 (0.20334s)]] 4730[[tommath_int][210.112 (0.422713s)][162.652 (0.42855s)][158.33 (0.427634s)][134.626 (0.428987s)]] 4731] 4732[table Operator construct(unsigned long long) 4733[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4734[[cpp_int][2.34403 (0.00739542s)][1.66376 (0.00713834s)][1.22989 (0.0074969s)][1.23708 (0.00711417s)]] 4735[[cpp_int(fixed)][[*1] (0.00315501s)][[*1] (0.00429049s)][[*1] (0.00609561s)][[*1] (0.0057508s)]] 4736[[gmp_int][222.866 (0.703144s)][164.331 (0.705059s)][115.363 (0.70321s)][122.347 (0.703596s)]] 4737[[tommath_int][218.681 (0.689941s)][163.796 (0.702765s)][114.57 (0.698376s)][122.422 (0.704027s)]] 4738] 4739[table Operator gcd 4740[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4741[[cpp_int][1.16358 (2.74442s)][1.39847 (8.11559s)][1.64677 (22.2518s)][1.95096 (64.4961s)]] 4742[[cpp_int(fixed)][[*1] (2.35859s)][1.30986 (7.60133s)][1.67681 (22.6577s)][2.0895 (69.0758s)]] 4743[[gmp_int][1.03392 (2.4386s)][[*1] (5.80319s)][[*1] (13.5124s)][[*1] (33.0586s)]] 4744[[tommath_int][5.25978 (12.4057s)][4.4619 (25.8932s)][4.15577 (56.1542s)][3.91192 (129.323s)]] 4745] 4746[table Operator powm 4747[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4748[[cpp_int][2.50722 (2.91621s)][3.5561 (13.406s)][4.37066 (73.483s)][4.88831 (473.91s)]] 4749[[cpp_int(fixed)][1.93385 (2.24931s)][3.18107 (11.9922s)][4.20753 (70.7403s)][4.8158 (466.88s)]] 4750[[gmp_int][[*1] (1.16313s)][[*1] (3.76986s)][[*1] (16.8128s)][[*1] (96.9476s)]] 4751[[tommath_int][1.44081 (1.67584s)][1.8794 (7.08507s)][2.19115 (36.8394s)][2.17186 (210.557s)]] 4752] 4753[table Operator str 4754[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4755[[cpp_int][1.17175 (0.00160006s)][1.41999 (0.00329476s)][1.40856 (0.00813784s)][1.52964 (0.0229767s)]] 4756[[cpp_int(fixed)][[*1] (0.00136554s)][[*1] (0.00232027s)][[*1] (0.00577741s)][1.14754 (0.0172372s)]] 4757[[gmp_int][1.50501 (0.00205515s)][1.52968 (0.00354926s)][1.01989 (0.0058923s)][[*1] (0.015021s)]] 4758[[tommath_int][12.2161 (0.0166816s)][16.9577 (0.0393463s)][18.7474 (0.108311s)][22.7368 (0.341528s)]] 4759] 4760[table Operator | 4761[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4762[[cpp_int][[*1] (0.0301617s)][[*1] (0.0423404s)][[*1] (0.0522358s)][[*1] (0.0813156s)]] 4763[[cpp_int(fixed)][1.0638 (0.0320861s)][1.22566 (0.0518951s)][1.28515 (0.0671305s)][1.16118 (0.094422s)]] 4764[[gmp_int][1.76553 (0.0532514s)][1.51489 (0.0641408s)][1.70708 (0.0891706s)][1.77346 (0.14421s)]] 4765[[tommath_int][4.37637 (0.131999s)][3.46212 (0.146587s)][2.91875 (0.152463s)][4.19621 (0.341217s)]] 4766] 4767[table Operator |(int) 4768[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4769[[cpp_int][[*1] (0.0289129s)][[*1] (0.0351119s)][[*1] (0.0406779s)][[*1] (0.0525891s)]] 4770[[cpp_int(fixed)][1.06091 (0.030674s)][1.25979 (0.0442336s)][1.36194 (0.0554009s)][1.37438 (0.0722772s)]] 4771[[gmp_int][4.92854 (0.142498s)][4.34687 (0.152627s)][3.71442 (0.151095s)][2.981 (0.156768s)]] 4772[[tommath_int][10.9847 (0.317598s)][9.37065 (0.329021s)][8.53651 (0.347248s)][11.2155 (0.589813s)]] 4773] 4774[table Operator ^ 4775[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4776[[cpp_int][[*1] (0.0305149s)][[*1] (0.04217s)][[*1] (0.0525977s)][[*1] (0.0816632s)]] 4777[[cpp_int(fixed)][1.01544 (0.0309861s)][1.24872 (0.0526585s)][1.26661 (0.066621s)][1.15965 (0.0947007s)]] 4778[[gmp_int][1.64675 (0.0502505s)][1.47181 (0.0620663s)][1.66038 (0.0873322s)][1.67895 (0.137108s)]] 4779[[tommath_int][4.30668 (0.131418s)][3.45859 (0.145849s)][2.91462 (0.153303s)][4.15538 (0.339342s)]] 4780] 4781[table Operator ^(int) 4782[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4783[[cpp_int][1.01566 (0.0296088s)][[*1] (0.0356634s)][[*1] (0.0401898s)][[*1] (0.0514097s)]] 4784[[cpp_int(fixed)][[*1] (0.0291524s)][1.2393 (0.0441976s)][1.38556 (0.0556856s)][1.38899 (0.0714075s)]] 4785[[gmp_int][4.68027 (0.136441s)][4.15243 (0.14809s)][3.74237 (0.150405s)][3.0483 (0.156712s)]] 4786[[tommath_int][10.919 (0.318314s)][9.16311 (0.326788s)][8.62554 (0.346659s)][11.6212 (0.597442s)]] 4787] 4788[table Operator & 4789[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4790[[cpp_int][1.0346 (0.0303431s)][[*1] (0.0427309s)][[*1] (0.0535587s)][1.06945 (0.0828084s)]] 4791[[cpp_int(fixed)][[*1] (0.0293284s)][1.10435 (0.04719s)][1.05262 (0.0563769s)][[*1] (0.0774309s)]] 4792[[gmp_int][1.86057 (0.0545675s)][1.58432 (0.0676995s)][1.69164 (0.0906018s)][1.86625 (0.144505s)]] 4793[[tommath_int][4.4157 (0.129506s)][3.60396 (0.154s)][2.95985 (0.158525s)][4.4032 (0.340944s)]] 4794] 4795[table Operator &(int) 4796[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4797[[cpp_int][1.05874 (0.038946s)][[*1] (0.0483903s)][[*1] (0.063842s)][[*1] (0.100361s)]] 4798[[cpp_int(fixed)][[*1] (0.0367853s)][1.05827 (0.0512099s)][1.09114 (0.0696605s)][1.09432 (0.109826s)]] 4799[[gmp_int][3.92298 (0.144308s)][2.99447 (0.144903s)][2.228 (0.14224s)][1.42296 (0.142809s)]] 4800[[tommath_int][8.79208 (0.323419s)][7.02288 (0.339839s)][5.65271 (0.36088s)][6.27104 (0.629365s)]] 4801] 4802[table Operator << 4803[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4804[[cpp_int][[*1] (0.0248801s)][1.23196 (0.04s)][[*1] (0.0424149s)][[*1] (0.060157s)]] 4805[[cpp_int(fixed)][1.08931 (0.027102s)][1.40572 (0.0456418s)][1.3475 (0.0571542s)][1.24573 (0.0749397s)]] 4806[[gmp_int][1.05561 (0.0262636s)][[*1] (0.0324686s)][1.09914 (0.0466199s)][1.16315 (0.0699719s)]] 4807[[tommath_int][1.60497 (0.0399319s)][2.13048 (0.0691737s)][2.31219 (0.0980712s)][2.74695 (0.165248s)]] 4808] 4809[table Operator >> 4810[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4811[[cpp_int][[*1] (0.0213349s)][1.02127 (0.0295019s)][[*1] (0.0327116s)][1.13168 (0.0433804s)]] 4812[[cpp_int(fixed)][1.13514 (0.0242181s)][1.16938 (0.0337803s)][1.46999 (0.0480859s)][1.60077 (0.061362s)]] 4813[[gmp_int][1.26614 (0.0270129s)][[*1] (0.0288873s)][1.42219 (0.0465221s)][[*1] (0.0383329s)]] 4814[[tommath_int][12.0066 (0.25616s)][10.2837 (0.297067s)][9.99696 (0.327017s)][16.0943 (0.616942s)]] 4815] 4816 4817Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4818turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 4819Windows Vista machine. 4820 4821Linux x86_64 results are broadly similar, except that libtommath performs much better there. 4822 4823[endsect] 4824 4825[section:rational_performance Rational Type Performance] 4826 4827Note that these tests are carefully designed to test performance of the underlying algorithms 4828and not memory allocation or variable copying. As usual, performance results should be taken 4829with a healthy dose of scepticism, and real-world performance may vary widely depending upon the 4830specifics of the program. In each table relative times are given first, with the best performer 4831given a score of 1. Total actual times are given in brackets, measured in seconds for 500000 4832operations. 4833 4834[table Operator + 4835[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4836[[cpp_rational][5.89417 (18.4116s)][6.87256 (47.4698s)][6.65008 (107.715s)][6.53801 (256.244s)]] 4837[[mpq_rational][[*1] (3.1237s)][[*1] (6.90715s)][[*1] (16.1975s)][[*1] (39.1929s)]] 4838] 4839[table Operator +(int) 4840[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4841[[cpp_rational][3.62367 (2.46488s)][4.18291 (2.94603s)][4.726 (3.74866s)][6.1388 (5.56817s)]] 4842[[mpq_rational][[*1] (0.680215s)][[*1] (0.704303s)][[*1] (0.7932s)][[*1] (0.907046s)]] 4843] 4844[table Operator +(unsigned long long) 4845[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4846[[cpp_rational][1.1527 (2.6378s)][1.31751 (3.09863s)][1.58996 (4.00714s)][2.15642 (5.75702s)]] 4847[[mpq_rational][[*1] (2.28837s)][[*1] (2.35189s)][[*1] (2.52028s)][[*1] (2.66971s)]] 4848] 4849[table Operator +=(unsigned long long) 4850[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4851[[cpp_rational][1.18436 (2.7059s)][1.32279 (3.11099s)][1.61398 (4.05389s)][2.20048 (5.84623s)]] 4852[[mpq_rational][[*1] (2.2847s)][[*1] (2.35183s)][[*1] (2.51174s)][[*1] (2.6568s)]] 4853] 4854[table Operator - 4855[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4856[[cpp_rational][5.81893 (18.3457s)][6.82209 (47.1928s)][6.64143 (107.498s)][6.51362 (255.137s)]] 4857[[mpq_rational][[*1] (3.15277s)][[*1] (6.91765s)][[*1] (16.1859s)][[*1] (39.1698s)]] 4858] 4859[table Operator -(int) 4860[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4861[[cpp_rational][3.72441 (2.48756s)][4.27663 (2.98713s)][4.62109 (3.72114s)][6.17605 (5.56503s)]] 4862[[mpq_rational][[*1] (0.667908s)][[*1] (0.698479s)][[*1] (0.805252s)][[*1] (0.901066s)]] 4863] 4864[table Operator -(unsigned long long) 4865[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4866[[cpp_rational][1.15627 (2.63239s)][1.32096 (3.12092s)][1.61044 (4.00106s)][2.19378 (5.7644s)]] 4867[[mpq_rational][[*1] (2.27663s)][[*1] (2.36262s)][[*1] (2.48445s)][[*1] (2.62761s)]] 4868] 4869[table Operator -=(unsigned long long) 4870[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4871[[cpp_rational][1.1984 (2.73444s)][1.34141 (3.15698s)][1.64159 (4.06997s)][2.23017 (5.88108s)]] 4872[[mpq_rational][[*1] (2.28174s)][[*1] (2.35348s)][[*1] (2.47929s)][[*1] (2.63706s)]] 4873] 4874[table Operator * 4875[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4876[[cpp_rational][5.4306 (32.5882s)][6.91805 (89.9436s)][6.94556 (207.307s)][6.88704 (492.151s)]] 4877[[mpq_rational][[*1] (6.00084s)][[*1] (13.0013s)][[*1] (29.8475s)][[*1] (71.4604s)]] 4878] 4879[table Operator *(int) 4880[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4881[[cpp_rational][2.12892 (2.51376s)][2.47245 (3.07841s)][2.86832 (3.93619s)][3.94086 (6.02565s)]] 4882[[mpq_rational][[*1] (1.18077s)][[*1] (1.24508s)][[*1] (1.3723s)][[*1] (1.52902s)]] 4883] 4884[table Operator *(unsigned long long) 4885[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4886[[cpp_rational][1.32254 (5.43565s)][1.56078 (6.73163s)][1.97701 (9.32522s)][2.85404 (15.1573s)]] 4887[[mpq_rational][[*1] (4.11002s)][[*1] (4.313s)][[*1] (4.71682s)][[*1] (5.31082s)]] 4888] 4889[table Operator *=(unsigned long long) 4890[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4891[[cpp_rational][6.29806 (58.1188s)][6.30556 (59.5076s)][6.3385 (62.1007s)][6.55345 (67.6905s)]] 4892[[mpq_rational][[*1] (9.22804s)][[*1] (9.43733s)][[*1] (9.79739s)][[*1] (10.329s)]] 4893] 4894[table Operator / 4895[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4896[[cpp_rational][4.4269 (66.8031s)][6.40103 (173.527s)][6.32347 (348.193s)][6.61148 (824.063s)]] 4897[[mpq_rational][[*1] (15.0903s)][[*1] (27.1093s)][[*1] (55.0637s)][[*1] (124.641s)]] 4898] 4899[table Operator /(int) 4900[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4901[[cpp_rational][1.78772 (2.50984s)][2.10623 (3.10606s)][2.46986 (3.99358s)][3.37428 (5.96678s)]] 4902[[mpq_rational][[*1] (1.40393s)][[*1] (1.4747s)][[*1] (1.61693s)][[*1] (1.76831s)]] 4903] 4904[table Operator /(unsigned long long) 4905[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4906[[cpp_rational][1.29695 (5.45454s)][1.55248 (6.85353s)][1.93237 (9.28765s)][2.75211 (14.8541s)]] 4907[[mpq_rational][[*1] (4.20568s)][[*1] (4.41458s)][[*1] (4.80635s)][[*1] (5.39734s)]] 4908] 4909[table Operator /=(unsigned long long) 4910[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4911[[cpp_rational][6.19401 (58.4278s)][6.20135 (59.643s)][6.21327 (62.0338s)][6.40576 (67.6778s)]] 4912[[mpq_rational][[*1] (9.43295s)][[*1] (9.61774s)][[*1] (9.98407s)][[*1] (10.5652s)]] 4913] 4914[table Operator construct 4915[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4916[[cpp_rational][[*1] (0.00978288s)][[*1] (0.0100574s)][[*1] (0.0101393s)][[*1] (0.0101847s)]] 4917[[mpq_rational][39.1516 (0.383015s)][38.3523 (0.385725s)][37.5812 (0.381048s)][37.6007 (0.382953s)]] 4918] 4919[table Operator construct(unsigned) 4920[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4921[[cpp_rational][[*1] (0.0548151s)][[*1] (0.0557542s)][[*1] (0.055825s)][[*1] (0.0552808s)]] 4922[[mpq_rational][7.21073 (0.395257s)][7.1016 (0.395944s)][7.02046 (0.391917s)][7.16881 (0.396297s)]] 4923] 4924[table Operator construct(unsigned long long) 4925[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4926[[cpp_rational][[*1] (0.0605156s)][[*1] (0.0616657s)][[*1] (0.0592056s)][[*1] (0.0603081s)]] 4927[[mpq_rational][35.1604 (2.12775s)][34.7575 (2.14335s)][35.7232 (2.11502s)][35.0437 (2.11342s)]] 4928] 4929[table Operator str 4930[[Backend][128 Bits][256 Bits][512 Bits][1024 Bits]] 4931[[cpp_rational][5.48898 (0.0208949s)][8.49668 (0.0546688s)][10.107 (0.121897s)][10.5339 (0.310584s)]] 4932[[mpq_rational][[*1] (0.0038067s)][[*1] (0.00643413s)][[*1] (0.0120606s)][[*1] (0.0294843s)]] 4933] 4934 4935Test code was compiled with Microsoft Visual Studio 2010 with all optimisations 4936turned on (/Ox), and used MPIR-2.3.0 and [mpfr]-3.0.0. The tests were run on 32-bit 4937Windows Vista machine. 4938 4939[endsect] 4940 4941[endsect] 4942 4943[section:map Roadmap] 4944 4945[section:hist History] 4946 4947[h4 Multiprecision-2.2.5 (Boost-1.59)] 4948 4949* Fixed a bug in cpp_int's right shift operator when shifting negative values - semantics now gives the 4950same values as shifting 2's compliment integers, though not the same bit pattern. 4951* Fixed support for GCC-4.6.4 in C++0x mode by disabling conditional noexcept suppoprt for that compiler 4952see [@https://svn.boost.org/trac/boost/ticket/11402 #11402]. 4953* Fixed issue with GCC-4.6.x not handling `noexcept` fully enough for this library to use. 4954* Suppressed numerous compiler warnings. 4955* Fixed some bugs in cpp_int's bitwise operators when one or both numbers are signed. 4956 4957 4958[h4 Multiprecision-2.2.4 (Boost-1.58)] 4959 4960* Changed `frexp` to always be non-expression template generating, see: [@https://svn.boost.org/trac/boost/ticket/10993 10993]. 4961* 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]. 4962* Improved noexcept support and added some more tests, see [@https://svn.boost.org/trac/boost/ticket/10990 10990]. 4963* Various workarounds applied for Intel-15.0 and Solaris-12.4 compilers. 4964 4965[h4 Multiprecision-2.2.3 (Boost-1.57)] 4966 4967* Changed rational to float conversions to exactly round to nearest, see [@https://svn.boost.org/trac/boost/ticket/10085 10085]. 4968* Added improved generic float to rational conversions. 4969* Fixed rare bug in exponent function for __cpp_bin_float. 4970* Fixed various minor documentation issues. 4971 4972[h4 Multiprecision-2.2.2 (Boost-1.56)] 4973 4974* Change floating point to rational conversions to be implicit, see [@https://svn.boost.org/trac/boost/ticket/10082 10082]. 4975* Fix definition of checked_cpp_rational typedef. 4976 4977[h4 Multiprecision-2.2.1] 4978 4979* Fix bug in assignment from string in cpp_int, see [@https://svn.boost.org/trac/boost/ticket/9936 9936]. 4980 4981[h4 Multiprecision-2.2.0] 4982 4983* Moved to Boost.Multiprecision specific version number - we have one breaking change in Boost-1.54 4984which makes this major version 2, plus two releases with new features since then. 4985* Added new __cpp_bin_float backend for binary floating point. 4986* Added MSVC-specific #include for compiler intrinsics, see [@https://svn.boost.org/trac/boost/ticket/9336 9336]. 4987* Fixed various typos in docs, see [@https://svn.boost.org/trac/boost/ticket/9432 9432]. 4988* Fixed __gmp_rational to allow move-copy from an already copied-from object, see [@https://svn.boost.org/trac/boost/ticket/9497 9497]. 4989* Added list of values for numeric_limits. 4990 4991[h4 Boost-1.55] 4992 4993* Added support for Boost.Serialization. 4994* Suppressed some GCC warnings. See [@https://svn.boost.org/trac/boost/ticket/8872 8872]. 4995* Fixed bug in pow for large integer arguments. See [@https://svn.boost.org/trac/boost/ticket/8809 8809]. 4996* Fixed bug in pow for calculation of 0[super N]. See [@https://svn.boost.org/trac/boost/ticket/8798 8798]. 4997* Fixed bug in fixed precision cpp_int IO code that causes conversion to string to fail when the 4998bit count is very small (less than CHAR_BIT). See [@https://svn.boost.org/trac/boost/ticket/8745 8745]. 4999* Fixed bug in cpp_int that causes left shift to fail when a fixed precision type would overflow. 5000See [@https://svn.boost.org/trac/boost/ticket/8741 8741]. 5001* Fixed some cosmetic warnings from cpp_int. See [@https://svn.boost.org/trac/boost/ticket/8748 8748]. 5002* Fixed calls to functions which are required to be macros in C99. See [@https://svn.boost.org/trac/boost/ticket/8732 8732]. 5003* 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]. 5004 5005[h4 1.54] 5006 5007* [*Breaking change] renamed `rational_adapter` to `rational_adaptor`. 5008* Add support for [mpfi]. 5009* Add logged_adaptor. 5010* Add support for 128-bit floats via GCC's `__float128` or Intel's `_Quad` data types. 5011* Add support for user-defined literals in cpp_int, improve `constexpr` support. 5012* Fixed bug in integer division of `cpp_int` that results in incorrect sign of `cpp_int` when both arguments are small enough 5013to fit in a `double_limb_type`. See [@https://svn.boost.org/trac/boost/ticket/8126 8126]. 5014* Fixed bug in subtraction of a single limb in `cpp_int` that results in incorrect value when the result should have a 0 5015in the last limb: [@https://svn.boost.org/trac/boost/ticket/8133 8133]. 5016* 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]. 5017* Fixed bug in some transcendental functions that caused incorrect return values when variables are reused, for example with 5018`a = pow(a, b)`. See [@https://svn.boost.org/trac/boost/ticket/8326 8326]. 5019* 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]. 5020* Fixed bug in `cpp_int` that gives incorrect answer for 0%N for large N: [@https://svn.boost.org/trac/boost/ticket/8670 8670]. 5021* Fixed set_precision in mpfr backend so it doesn't trample over an existing value: [@https://svn.boost.org/trac/boost/ticket/8692 8692]. 5022 5023[h4 1.53] 5024 5025* First Release. 5026* Fix bug in [@https://svn.boost.org/trac/boost/ticket/7878 cpp_int division]. 5027* Fix issue [@https://svn.boost.org/trac/boost/ticket/7806 #7806]. 5028 5029[h4 Post review changes] 5030 5031* Non-expression template operators further optimised with rvalue reference support. 5032* Many functions made `constexp`. 5033* Differentiate between explicit and implicit conversions in the number constructor. 5034* Removed "mp_" prefix from types. 5035* Allowed mixed precision arithmetic. 5036* Changed ExpressionTemplates parameter to class `number` to use enumerated values rather than true/false. 5037* Changed ExpressionTemplate parameter default value to use a traits class so that the default value depends on the backend used. 5038* Added support for fused-multiply-add/subtract with GMP support. 5039* Tweaked expression template unpacking to use fewer temporaries when the LHS also appears in the RHS. 5040* Refactored `cpp_int_backend` based on review comments with new template parameter structure. 5041* Added additional template parameter to `mpfr_float_backend` to allow stack-based allocation. 5042* Added section on mixed precision arithmetic, and added support for operations yielding a higher precision result 5043than either of the arguments. 5044* Added overloads of integer-specific functions for built in integer types. 5045 5046[h4 Pre-review history] 5047 5048*2011-2012, John Maddock adds an expression template enabled front end to Christopher's code, 5049and adds support for other backends. 5050* 2011, Christopher Kormanyos publishes the decimal floating point code under the Boost 5051Software Licence. The code is published as: [@http://doi.acm.org/10.1145/1916461.1916469 5052"Algorithm 910: A Portable C++ Multiple-Precision 5053System for Special-Function Calculations"], in ACM TOMS, {VOL 37, ISSUE 4, (February 2011)} (C) ACM, 50542011. 5055* 2002-2011, Christopher Kormanyos develops the all C++ decimal arithmetic floating point 5056code. 5057 5058[endsect] 5059 5060[section:todo TODO] 5061 5062 5063 5064More a list of what ['could] be done, rather than what ['should] be done (which may be a much smaller list!). 5065 5066* Add back-end support for libdecNumber. 5067* Add an adaptor back-end for complex number types. 5068* Add better multiplication routines (Karatsuba, FFT etc) to cpp_int_backend. 5069* Add assembly level routines to cpp_int_backend. 5070* Can ring types (exact floating point types) be supported? The answer should be yes, but someone needs to write it, 5071the hard part is IO and binary-decimal conversion. 5072* Should there be a choice of rounding mode (probably MPFR specific)? 5073* We can reuse temporaries in multiple subtrees (temporary caching). 5074* cpp_dec_float should round to nearest. 5075* A 2's complement fixed precision int that uses exactly N bits and no more. 5076 5077Things requested in review: 5078 5079* The performances of mp_number<a_trivial_adaptor<float>, false>respect to 5080float and mp_number<a_trivial_adaptor<int>, false> and int should be 5081given to show the cost of using the generic interface (Mostly done, just need to update docs to the latest results). 5082* Should we provide min/max overloads for expression templates? (Not done - we can't overload functions declared in the std namespace :-( ). 5083* The rounding applied when converting must be documented (Done). 5084* Document why we don't abstract out addition/multiplication algorithms etc. (done - FAQ) 5085* Document why we don't use proto (compile times) (Done). 5086* We can reuse temporaries in multiple subtrees (temporary caching) Moved to TODO list. 5087* Emphasise in the docs that ET's may reorder operations (done 2012/10/31). 5088* Document what happens to small fixed precision cpp_int's (done 2012/10/31). 5089* The use of bool in template parameters could be improved by the use of 5090an enum class which will be more explicit. E.g `enum class expression_template {disabled, enabled}; 5091enum class sign {unsigned, signed};` (Partly done 2012/09/15, done 2012/10/31). 5092* Each back-end should document the requirements it satisfies (not currently scheduled for inclusion: it's 5093deliberately an implementation detail, and "optional" requirements are optimisations which can't be detected 5094by the user). Not done: this is an implementation detail, the exact list of requirements satisfied is purely 5095an optimization, not something the user can detect. 5096* A backend for an overflow aware integers (done 2012/10/31). 5097* IIUC convert_to is used to emulate in c++98 compilers C++11 explicit 5098conversions. Could the explicit conversion operator be added on 5099compilers supporting it? (Done 2012/09/15). 5100* The front-end should make the differences between implicit and explicit 5101construction (Done 2012/09/15). 5102* The tutorial should add more examples concerning implicit or explicit 5103conversions. (Done 2012/09/15). 5104* The documentation must explain how move semantics helps in this domain 5105and what the backend needs to do to profit from this optimization. (Done 2012/09/15). 5106* The documentation should contain Throws specification on the mp_number 5107and backend requirements operations. (Done 2012/09/15). 5108* The library interface should use the noexcept (BOOST_NOEXCEPT, ...) 5109facilities (Done 2012/09/15). 5110* It is unfortunate that the generic mp_number front end can not make use 5111constexpr as not all the backends can ensure this (done - we can go quite a way). 5112* literals: The library doesn't provide some kind of literals. I think that the 5113mp_number class should provide a way to create literals if the backend 5114is able to. (Done 2012/09/15). 5115* The ExpresionTemplate parameter could be defaulted to a traits class for more sensible defaults (done 2012/09/20). 5116* 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). 5117 5118 5119 5120[h4 Pre-Review Comments] 5121 5122* Make fixed precision orthogonal to Allocator type in cpp_int. Possible solution - add an additional MaxBits 5123template argument that defaults to 0 (meaning keep going till no more space/memory). Done. 5124* Can ring types (exact floating point types) be supported? The answer should be yes, but someone needs to write it (Moved to TODO list). 5125* Should there be a choice of rounding mode (probably MPFR specific)? Moved to TODO list. 5126* Make the exponent type for cpp_dec_float a template parameter, maybe include support for big-integer exponents. 5127Open question - what should be the default - int32_t or int64_t? (done 2012/09/06) 5128* Document the size requirements of fixed precision ints (done 2012/09/15). 5129* Document std lib function accuracy (done 2012/09/15). 5130* Be a bit clearer on the effects of sign-magnitude representation of cpp_int - min == -max etc - done. 5131* Document cpp_dec_float precision, rounding, and exponent size (done 2012/09/06). 5132* Can we be clearer in the docs that mixed arithmetic doesn't work (no longer applicable as of 2012/09/06)? 5133* Document round functions behaviour better (they behave as in C++11) (added note 2012/09/06). 5134* Document limits on size of cpp_dec_float (done 2012/09/06). 5135* Add support for fused multiply add (and subtract). GMP mpz_t could use this (done 2012/09/20). 5136 5137[endsect] 5138 5139[section:faq FAQ] 5140 5141[variablelist 5142[[Why do I get compiler errors when passing a `number` to a template function?] 5143 [Most likely you are actually passing an expression template type to the function and 5144 template-argument-deduction deduces the "wrong" type. Try casting the arguments 5145 involving expressions to the actual number type, or as a last resort turning off 5146 expression template support in the number type you are using.]] 5147[[When is expression template support a performance gain?] 5148 [As a general rule, expression template support adds a small runtime overhead 5149 creating and unpacking the expression templates, but greatly reduces the number of 5150 temporaries created. So it's most effective in improving performance when the cost 5151 of creating a temporary is high: for example when creating a temporary involves a memory 5152 allocation. It is least effective (and may even be a dis-optimisation) when temporaries 5153 are cheap: for example if the number type is basically a thin wrapper around a native 5154 arithmetic type. In addition, since the library makes extensive use of thin inline wrapper 5155 functions, turning on compiler optimization is essential to achieving high performance.]] 5156[[Do expression templates reorder operations?] 5157 [Yes they do, sometimes quite radically so, if this is a concern then they should be turned 5158 off for the number type you are using.]] 5159[[I can't construct my number type from ['some other type], but the docs indicate that the conversion should be allowed, what's up?] 5160 [Some conversions are ['explicit], that includes construction from a string, or constructing from any type 5161 that may result in loss of precision (for example constructing an integer type from a float).]] 5162[[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`?] 5163 [Bitwise operations on negative values (or indeed any signed integer type) are unspecified by the standard. As a result 5164 any attempt to carry out a bitwise operation on a negative checked-integer will result in a `std::range_error` being thrown.]] 5165[[Why do I get compiler errors when trying to use the complement operator?] 5166 [Use of the complement operator on signed types is problematic as the result is unspecified by the standard, and is further 5167 complicated by the fact that most extended precision integer types use a sign-magnitude representation rather than the 2's 5168 complement one favored by most native integer types. As a result the complement operator is deliberately disabled for 5169 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.]] 5170[[Why can't I negate an unsigned type?] 5171 [The unary negation operator is deliberately disabled for unsigned integer types as its use would almost always be a programming error.]] 5172[[Why doesn't the library use proto?] 5173 [A very early version of the library did use proto, but compile times became too slow 5174 for the library to be usable. Since the library only required a tiny fraction of what 5175 proto has to offer anyway, a lightweight expression template mechanism was used instead. 5176 Compile times are still too slow...]] 5177[[Why not abstract out addition/multiplication algorithms?] 5178 [This was deemed not to be practical: these algorithms are intimately 5179 tied to the actual data representation used.]] 5180] 5181 5182[endsect] 5183 5184[section:ack Acknowledgements] 5185 5186This library would not have happened without: 5187 5188* Christopher Kormanyos' C++ decimal number code. 5189* Paul Bristow for patiently testing, and commenting on the library. 5190* All the folks at GMP, MPFR and libtommath, for providing the "guts" that makes this library work. 5191* [@http://www-cs-faculty.stanford.edu/~uno/taocp.html "The Art Of Computer Programming"], 5192Donald E. Knuth, Volume 2: Seminumerical Algorithms, Third Edition 5193(Reading, Massachusetts: Addison-Wesley, 1997), xiv+762pp. ISBN 0-201-89684-2 5194 5195[endsect] 5196 5197[endsect] 5198 5199[section:indexes Indexes] 5200 5201''' 5202<index type="function_name"> 5203<title>Function Index</title> 5204</index> 5205 5206<index type="class_name"> 5207<title>Class Index</title> 5208</index> 5209 5210<index type="typedef_name"> 5211<title>Typedef Index</title> 5212</index> 5213 5214<index/> 5215''' 5216 5217[endsect] 5218 5219 5220 5221 5222