|
| 1 | +Boost Multiprecision Library |
| 2 | +============================ |
| 3 | + |
| 4 | +| | Master | Develop | |
| 5 | +|------------------|----------|-------------| |
| 6 | +| Drone | [](https://drone.cpp.al/boostorg/multiprecision) | [](https://drone.cpp.al/boostorg/multiprecision) | |
| 7 | +| Github Actions | [](https://github.com/boostorg/multiprecision/actions) | [](https://github.com/boostorg/multiprecision/actions) | |
| 8 | +| Codecov | [](https://codecov.io/gh/boostorg/multiprecision/branch/master) | [](https://codecov.io/gh/boostorg/multiprecision/branch/develop) | |
| 9 | + |
| 10 | + |
| 11 | +`Boost.Multiprecision` is a C++ library that provides integer, rational, floating-point, complex and interval number types |
| 12 | +having more range and precision than the language's ordinary built-in types. |
| 13 | + |
| 14 | +Language adherence: |
| 15 | + - `Boost.Multiprecision` requires a compliant C++14 compiler. |
| 16 | + - It is compatible with C++14, 17, 20, 23 and beyond. |
| 17 | + |
| 18 | +The big number types in `Boost.Multiprecision` can be used with a wide selection of basic |
| 19 | +mathematical operations, elementary transcendental functions as well as the functions in Boost.Math. The Multiprecision types can |
| 20 | +also interoperate with the built-in types in C++ using clearly defined conversion rules. This allows `Boost.Multiprecision` to be |
| 21 | +used for all kinds of mathematical calculations involving integer, rational and floating-point types requiring extended range and precision. |
| 22 | + |
| 23 | +Multiprecision consists of a generic interface to the mathematics of large numbers as well as a selection of big number back ends, with |
| 24 | +support for integer, rational and floating-point types. `Boost.Multiprecision` provides a selection of back ends provided off-the-rack in |
| 25 | +including interfaces to GMP, MPFR, MPIR, TomMath as well as its own collection of Boost-licensed, header-only back ends for integers, |
| 26 | +rationals, floats and complex. In addition, user-defined back ends can be created and used with the interface of Multiprecision, |
| 27 | +provided the class implementation adheres to the necessary concepts. |
| 28 | + |
| 29 | +Depending upon the number type, precision may be arbitrarily large (limited only by available memory), fixed at compile time |
| 30 | +(for example $50$ or $100$ decimal digits), or a variable controlled at run-time by member functions. |
| 31 | +The types are expression-template-enabled by default. This usually provides better performance than naive user-defined types. |
| 32 | +If not needed, expression templates can be disabled when configuring the `number` type with its backend. |
| 33 | + |
| 34 | +The full documentation is available on [boost.org](http://www.boost.org/doc/libs/release/libs/multiprecision/index.html). |
| 35 | + |
| 36 | +## Using Multiprecision ## |
| 37 | + |
| 38 | +<p align="center"> |
| 39 | + <a href="https://godbolt.org/z/hj75jEqcz" alt="godbolt"> |
| 40 | + <img src="https://img.shields.io/badge/try%20it%20on-godbolt-green" /></a> |
| 41 | +</p> |
| 42 | + |
| 43 | +In the following example, we use Multiprecision's Boost-licensed binary |
| 44 | +floating-point backend type `cpp_bin_float` to compute ${\sim}100$ decimal digits of |
| 45 | + |
| 46 | +$$\sqrt{\pi} = \Gamma \left( \frac{1}{2} \right)~{\approx}~1.772453850905516027298{\ldots}\text{,}$$ |
| 47 | + |
| 48 | +where we also observe that Multiprecision can seemlesly interoperate with |
| 49 | +[Boost.Math](https://github.com/boostorg/math). |
| 50 | + |
| 51 | +```cpp |
| 52 | +#include <iomanip> |
| 53 | +#include <iostream> |
| 54 | +#include <sstream> |
| 55 | + |
| 56 | +#include <boost/multiprecision/cpp_bin_float.hpp> |
| 57 | +#include <boost/math/special_functions/gamma.hpp> |
| 58 | + |
| 59 | +auto main() -> int |
| 60 | +{ |
| 61 | + using big_float_type = boost::multiprecision::cpp_bin_float_100; |
| 62 | + |
| 63 | + const big_float_type sqrt_pi { sqrt(boost::math::constants::pi<big_float_type>()) }; |
| 64 | + |
| 65 | + const big_float_type half { big_float_type(1) / 2 }; |
| 66 | + |
| 67 | + const big_float_type gamma_half { boost::math::tgamma(half) }; |
| 68 | + |
| 69 | + std::stringstream strm { }; |
| 70 | + |
| 71 | + strm << std::setprecision(std::numeric_limits<big_float_type>::digits10) << "sqrt_pi : " << sqrt_pi << '\n'; |
| 72 | + strm << std::setprecision(std::numeric_limits<big_float_type>::digits10) << "gamma_half: " << gamma_half; |
| 73 | + |
| 74 | + std::cout << strm.str() << std::endl; |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## Standalone ## |
| 79 | + |
| 80 | +Defining `BOOST_MP_STANDALONE` allows `Boost.Multiprecision` |
| 81 | +to be used with the only dependency being [Boost.Config](https://github.com/boostorg/config). |
| 82 | + |
| 83 | +Our [package on this page](https://github.com/boostorg/multiprecision/releases) |
| 84 | +already includes a copy of Boost.Config so no other downloads are required. |
| 85 | +Some functionality is reduced in this mode. |
| 86 | +A static_assert message will alert you if a particular feature has been disabled by standalone mode. |
| 87 | +[Boost.Math](https://github.com/boostorg/math) standalone mode is compatiable, |
| 88 | +and recommended if special functions are required for the floating point types. |
| 89 | + |
| 90 | +## Support, bugs and feature requests ## |
| 91 | + |
| 92 | +Bugs and feature requests can be reported through the [Gitub issue tracker](https://github.com/boostorg/multiprecision/issues) |
| 93 | +(see [open issues](https://github.com/boostorg/multiprecision/issues) and |
| 94 | +[closed issues](https://github.com/boostorg/multiprecision/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed)). |
| 95 | + |
| 96 | +You can submit your changes through a [pull request](https://github.com/boostorg/multiprecision/pulls). |
| 97 | + |
| 98 | +There is no mailing-list specific to `Boost Multiprecision`, |
| 99 | +although you can use the general-purpose Boost [mailing-list](http://lists.boost.org/mailman/listinfo.cgi/boost-users) |
| 100 | +using the tag [multiprecision]. |
| 101 | + |
| 102 | + |
| 103 | +## Development ## |
| 104 | + |
| 105 | +Clone the whole boost project, which includes the individual Boost projects as submodules |
| 106 | +([see boost+git doc](https://github.com/boostorg/boost/wiki/Getting-Started)): |
| 107 | + |
| 108 | +```sh |
| 109 | + git clone https://github.com/boostorg/boost |
| 110 | + cd boost |
| 111 | + git submodule update --init |
| 112 | +``` |
| 113 | + |
| 114 | +The Boost Multiprecision Library is located in `libs/multiprecision/`. |
| 115 | + |
| 116 | +### Running tests ### |
| 117 | +First, build the `b2` engine by running `bootstrap.sh` in the root of the boost directory. This will generate `b2` configuration in `project-config.jam`. |
| 118 | + |
| 119 | +```sh |
| 120 | + ./bootstrap.sh |
| 121 | +``` |
| 122 | + |
| 123 | +Now make sure you are in `libs/multiprecision/test`. You can either run all the tests listed in `Jamfile.v2` or run a single test: |
| 124 | + |
| 125 | +```sh |
| 126 | + ../../../b2 <- run all tests |
| 127 | + ../../../b2 test_complex <- single test |
| 128 | +``` |
0 commit comments