Multiprecision floats

Multiprecision floats#

Note

The functionality described in this section is available only if mp++ was configured with the MPPP_WITH_MPFR option enabled (see the installation instructions).

Added in version 0.5.

#include <mp++/real.hpp>

The real class#

class mppp::real#

Multiprecision floating-point class.

This class represents arbitrary-precision real values encoded in a binary floating-point format. It acts as a wrapper around the MPFR mpfr_t type, pairing a multiprecision significand (whose size can be set at runtime) to a fixed-size exponent. In other words, real values can have an arbitrary number of binary digits of precision (limited only by the available memory), but the exponent range is limited.

real aims to behave like a floating-point C++ type whose precision is a runtime property of the class instances rather than a compile-time property of the type. Because of this, the way precision is handled in real differs from the way it is managed in MPFR. The most important difference is that in operations involving real the precision of the result is usually determined by the precision of the operands, whereas in MPFR the precision of the operation is determined by the precision of the return value (which is always passed as the first function parameter in the MPFR API). For instance, in the following code,

auto x = real{5, 200} + real{6, 150};

the first operand has a value of 5 and precision of 200 bits, while the second operand has a value of 6 and precision 150 bits. The precision of the result x will be the maximum precision among the two operands, that is, 200 bits.

The precision of a real can be set at construction, or it can be changed later via functions such as mppp::real::set_prec(), mppp::real::prec_round(), etc. By default, the precision of a real is automatically deduced upon construction following a set of heuristics aimed at ensuring that the constructed real preserves the value used for initialisation, if possible. For instance, by default the construction of a real from a 32 bit integer will yield a real with a precision of 32 bits. This behaviour can be altered by specifying explicitly the desired precision value.

Most of the functionality is exposed via plain functions, with the general convention that the functions are named after the corresponding MPFR functions minus the leading mpfr_ prefix. For instance, the MPFR call

mpfr_add(rop, a, b, MPFR_RNDN);

that writes the result of a + b, rounded to nearest, into rop, becomes simply

add(rop, a, b);

where the add() function is resolved via argument-dependent lookup. Function calls with overlapping arguments are allowed, unless noted otherwise. Unless otherwise specified, the real API always rounds to nearest (that is, the MPFR_RNDN rounding mode is used).

Various overloaded operators are provided. The arithmetic operators always return a real result. Alternative comparison functions treating NaNs specially are provided for use in the C++ standard library (and wherever strict weak ordering relations are needed).

Member functions are provided to access directly the internal mpfr_t instance (see mppp::real::get_mpfr_t() and mppp::real::_get_mpfr_t()), so that it is possible to use transparently the MPFR API with real objects.

The real class supports a simple binary serialisation API, through member functions such as binary_save() and binary_load(), and the corresponding free function overloads.

A tutorial showcasing various features of real is available.

real()#

Default constructor.

The value will be initialised to positive zero, the precision will be the value returned by mppp::real_prec_min().

real(const real &other)#

real(real &&other) noexcept#

Copy and move constructors.

The copy constructor performs an exact deep copy of the input object.

After move construction, the only valid operations on other are destruction, copy/move assignment and the invocation of the is_valid() member function. After re-assignment, other can be used normally again.

Parameters:: other – the construction argument.

explicit real(const real &other, mpfr_prec_t p)#

explicit real(real &&other, mpfr_prec_t p)#

Copy/move constructors with custom precision.

These constructors will set this to the value of other with precision p. If p is smaller than the precision of other, a rounding operation will be performed, otherwise the value will be copied exactly.

Added in version 0.20: The move overload.

Parameters:

other – the construction argument.
p – the desired precision.

Throws:

std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

explicit real(real_kind k, int sign, mpfr_prec_t p)#

explicit real(real_kind k, mpfr_prec_t p)#

Constructors from a special value, sign and precision.

This constructor will initialise this with one of the special values specified by the mppp::real_kind enum. The precision of this will be p.

If k is not NaN, the sign bit will be set to positive if sign is nonnegative, negative otherwise.

The second overload invokes the first one with a sign of zero.

If k is not one of nan, inf or zero, an error will be raised.

Parameters:

k – the desired special value.
sign – the desired sign for this.
p – the desired precision for this.

Throws:

std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max(), or k is an invalid enumerator.

template<std::size_t SSize> explicit real(const integer<SSize> &n, mpfr_exp_t e, mpfr_prec_t p)#

explicit real(unsigned long n, mpfr_exp_t e, mpfr_prec_t p)#

explicit real(long n, mpfr_exp_t e, mpfr_prec_t p)#

Added in version 0.20.

Constructors from an integral multiple of a power of two.

These constructors will set this to \(n\times 2^e\) with a precision of p.

Parameters:

n – the integral multiple.
e – the power of 2.
p – the desired precision.

Throws:

std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

template<real_interoperable T> real(const T &x)#

template<real_interoperable T> explicit real(const T &x, mpfr_prec_t p)#

Generic constructors.

The generic constructors will set this to the value of x.

The variant with the p argument will set the precision of this exactly to p.

The variant without the p argument will set the precision of this according to the following heuristics:

if x is an integral C++ type I, then the precision is set to the bit width of I;
if x is a floating-point C++ type F, then the precision is set to the number of binary digits in the significand of F;
if x is integer, then the precision is set to the number of bits in use by x (rounded up to the next multiple of the limb type’s bit width);
if x is rational, then the precision is set to the sum of the number of bits used by numerator and denominator (as established by the previous heuristic for integer);
if x is real128, then the precision is set to 113.

These heuristics aim at preserving the value of x in the constructed real.

Construction from bool will initialise this to 1 for true, and 0 for false.

Parameters:

x – the construction argument.
p – the desired precision.

Throws:

std::overflow_error – if an overflow occurs in the computation of the automatically-deduced precision.
std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

template<cpp_complex T> explicit real(const T &c)#

template<cpp_complex T> explicit real(const T &c, mpfr_prec_t p)#

Added in version 0.20.

Constructors from complex C++ types.

These constructors will set this to the real part of c. If the imaginary part of c is not zero, an error will be raised.

The precision of this will be set exactly to p, if provided. Otherwise, the precision will be set following the same heuristics explained in the generic constructor for the real-valued floating-point type underlying T.

Parameters:

c – the construction argument.
p – the desired precision.

Throws:

std::domain_error – if the imaginary part of c is not zero.
std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

template<string_type T> explicit real(const T &s, int base, mpfr_prec_t p)#

template<string_type T> explicit real(const T &s, mpfr_prec_t p)#

Constructors from string, base and precision.

The first constructor will set this to the value represented by the string_type s, which is interpreted as a floating-point number in base base. base must be either zero (in which case the base will be automatically deduced) or a number in the \(\left[ 2,62 \right]\) range. The valid string formats are detailed in the documentation of the MPFR function mpfr_set_str(). Note that leading whitespaces are ignored, but trailing whitespaces will raise an error.

The precision of this will be set to p.

The second constructor calls the first one with a base value of 10.

Parameters:

s – the input string.
base – the base used in the string representation.
p – the desired precision.

Throws:

std::invalid_argument –
in the following cases:
- base is not zero and not in the \(\left[ 2,62 \right]\) range,
- p is outside the valid bounds for a precision value,
- s cannot be interpreted as a floating-point number.
unspecified – any exception thrown by memory errors in standard containers.

explicit real(const char *begin, const char *end, int base, mpfr_prec_t p)#

explicit real(const char *begin, const char *end, mpfr_prec_t p)#

Constructors from range of characters, base and precision.

The first constructor will initialise this from the content of the input half-open range, which is interpreted as the string representation of a floating-point value in base base.

Internally, the constructor will copy the content of the range to a local buffer, add a string terminator, and invoke the constructor from string, base and precision.

The second constructor calls the first one with a base value of 10.

Parameters:

begin – the start of the input range.
end – the end of the input range.
base – the base used in the string representation.
p – the desired precision.

Throws:

unspecified – any exception thrown by the constructor from string, or by memory allocation errors in standard containers.

explicit real(const mpfr_t x)#

Constructor from an mpfr_t.

This constructor will initialise this with an exact deep copy of x.

Warning

It is the user’s responsibility to ensure that x has been correctly initialised with a precision within the bounds established by mppp::real_prec_min() and mppp::real_prec_max().

Parameters:: x – the mpfr_t that will be deep-copied.

explicit real(mpfr_t &&x)#

Move constructor from an mpfr_t.

This constructor will initialise this with a shallow copy of x.

Warning

It is the user’s responsibility to ensure that x has been correctly initialised with a precision within the bounds established by mppp::real_prec_min() and mppp::real_prec_max().

Additionally, the user must ensure that, after construction, mpfr_clear() is never called on x: the resources previously owned by x are now owned by this, which will take care of releasing them when the destructor is called.

Note

Due to a compiler bug, this constructor is not available on Microsoft Visual Studio.

Parameters:: x – the mpfr_t that will be moved.

~real()#

Destructor.

The destructor will run sanity checks in debug mode.

real &operator=(const real &other)#

real &operator=(real &&other) noexcept#

Copy and move assignment operators.

Parameters:: other – the assignment argument.
Returns:: a reference to this.

template<real_interoperable T> real &operator=(const T &x)#

The generic assignment operator will set this to the value of x.

The precision of this will be set according to the same heuristics described in the generic constructor.

Parameters:: x – the assignment argument.
Returns:: a reference to this.
Throws:: std::overflow_error – if an overflow occurs in the computation of the automatically-deduced precision.

template<cpp_complex T> real &operator=(const T &c)#

Added in version 0.20.

Assignment from complex C++ types.

This operator will first attempt to convert c to real, and it will then assign the result of the conversion to this.

Parameters:: c – the assignment argument.
Returns:: a reference to this.
Throws:: unspecified – any exception thrown by the conversion of c to real.

real &operator=(const complex128 &x)#

real &operator=(const complex &x)#

Note

The complex128 overload is available only if mp++ was configured with the MPPP_WITH_QUADMATH option enabled. The complex overload is available only if mp++ was configured with the MPPP_WITH_MPC option enabled.

Added in version 0.20.

Assignment operators from other mp++ classes.

These operators are formally equivalent to converting x to real and then move-assigning the result to this.

Parameters:: x – the assignment argument.
Returns:: a reference to this.
Throws:: unspecified – any exception raised by the conversion of x to real.

real &operator=(const mpfr_t x)#

Copy assignment from mpfr_t.

This operator will set this to a deep copy of x.

Warning

It is the user’s responsibility to ensure that x has been correctly initialised with a precision within the bounds established by mppp::real_prec_min() and mppp::real_prec_max().

Parameters:: x – the assignment argument.
Returns:: a reference to this.

real &operator=(mpfr_t &&x)#

Move assignment from mpfr_t.

This operator will set this to a shallow copy of x.

Warning

It is the user’s responsibility to ensure that x has been correctly initialised with a precision within the bounds established by mppp::real_prec_min() and mppp::real_prec_max().

Additionally, the user must ensure that, after the assignment, mpfr_clear() is never called on x: the resources previously owned by x are now owned by this, which will take care of releasing them when the destructor is called.

Note

Due to a compiler bug, this operator is not available on Microsoft Visual Studio.

Parameters:: x – the assignment argument.
Returns:: a reference to this.

bool is_valid() const noexcept#

Check validity.

A real becomes invalid after it is used as an argument to the move constructor.

Returns:: true if this is valid, false otherwise.

real &set(const real &other)#

Set to another real.

This member function will set this to the value of other. Contrary to the copy assignment operator, the precision of the assignment is dictated by the precision of this, rather than the precision of other. Consequently, the precision of this will not be altered by the assignment, and a rounding might occur, depending on the values and the precisions of the operands.

This function is a thin wrapper around the mpfr_set() assignment function from the MPFR API.

Parameters:: other – the value to which this will be set.
Returns:: a reference to this.

template<real_interoperable T> real &set(const T &x)#

Generic setter.

This member function will set this to the value of x. Contrary to the generic assignment operator, the precision of the assignment is dictated by the precision of this, rather than being deduced from the type and value of x. Consequently, the precision of this will not be altered by the assignment, and a rounding might occur, depending on the operands.

This function is a thin wrapper around various mpfr_set_*() assignment functions from the MPFR API.

Parameters:: x – the value to which this will be set.
Returns:: a reference to this.

template<cpp_complex T> real &set(const T &c)#

Added in version 0.20.

Setter to complex C++ types.

This member function will set this to the value of c. Contrary to the generic assignment operator, the precision of the assignment is dictated by the precision of this, rather than being deduced from the type and value of c. Consequently, the precision of this will not be altered by the assignment, and a rounding might occur, depending on the operands.

If the imaginary part of c is not zero, an error will be raised.

Parameters:: c – the value to which this will be set.
Returns:: a reference to this.
Throws:: std::domain_error – if the imaginary part of c is not zero.

template<string_type T> real &set(const T &s, int base = 10)#

Setter to string.

This member function will set this to the value represented by s, which will be interpreted as a floating-point number in base base. base must be either 0 (in which case the base is automatically deduced), or a value in the \(\left[ 2,62 \right]\) range. The precision of the assignment is dictated by the precision of this, and a rounding might thus occur.

If s is not a valid representation of a floating-point number in base base, this will be set to NaN and an error will be raised.

This function is a thin wrapper around the mpfr_set_str() assignment function from the MPFR API.

Parameters:

s – the string to which this will be set.
base – the base used in the string representation.

Returns:

a reference to this.

Throws:

std::invalid_argument – if s cannot be parsed as a floating-point value, or if the value of base is invalid.
unspecified – any exception thrown by memory allocation errors in standard containers.

real &set(const char *begin, const char *end, int base = 10)#

Set to character range.

This setter will set this to the content of the input half-open range, which is interpreted as the string representation of a floating-point value in base base.

Internally, the setter will copy the content of the range to a local buffer, add a string terminator, and invoke the setter to string.

Parameters:

begin – the start of the input range.
end – the end of the input range.
base – the base used in the string representation.

Returns:

a reference to this.

Throws:

unspecified – any exception thrown by the setter to string, or by memory allocation errors in standard containers.

real &set(const mpfr_t x)#

Set to an mpfr_t.

This member function will set this to the value of x. Contrary to the corresponding assignment operator, the precision of the assignment is dictated by the precision of this, rather than the precision of x. Consequently, the precision of this will not be altered by the assignment, and a rounding might occur, depending on the values and the precisions of the operands.

This function is a thin wrapper around the mpfr_set() assignment function from the MPFR API.

Warning

It is the user’s responsibility to ensure that x has been correctly initialised.

Parameters:: x – the assignment argument.
Returns:: a reference to this.

real &set_nan()#

real &set_inf(int sign = 0)#

real &set_zero(int sign = 0)#

Set to special values.

These member functions will set this to, respectively:

NaN (with an unspecified sign bit),
infinity (with positive sign if sign is nonnegative, negative sign otherwise),
zero (with positive sign if sign is nonnegative, negative sign otherwise).

The precision of this will not be altered.

Parameters:: sign – the sign of the special value (positive if sign is nonnegative, negative otherwise).
Returns:: a reference to this.

const mpfr_struct_t *get_mpfr_t() const#

mpfr_struct_t *_get_mpfr_t()#

Getters for the internal mpfr_t instance.

These member functions will return a const or mutable pointer to the internal mpfr_t instance.

Warning

When using the mutable getter, it is the user’s responsibility to ensure that the internal MPFR structure is kept in a state which respects the invariants of the real class. Specifically, the precision value must be in the bounds established by mppp::real_prec_min() and mppp::real_prec_max(), and upon destruction a real object must contain a valid mpfr_t object.

Returns:: a const or mutable pointer to the internal MPFR structure.

bool nan_p() const#

bool inf_p() const#

bool number_p() const#

bool zero_p() const#

bool regular_p() const#

bool integer_p() const#

bool is_one() const#

Detect special values.

These member functions will return true if this is, respectively:

NaN,
an infinity,
a finite number,
zero,
a regular number (i.e., not NaN, infinity or zero),
an integral value,
one,

false otherwise.

Returns:: the result of the detection.

int sgn() const#

Sign detection.

Returns:: a positive value if this is positive, zero if this is zero, a negative value if this is negative.
Throws:: std::domain_error – if this is NaN.

bool signbit() const#

Get the sign bit.

The sign bit is set if this is negative, -0, or a NaN whose representation has its sign bit set.

Returns:: the sign bit of this.

mpfr_prec_t get_prec() const#

Precision getter.

Returns:: the precision of this.

real &set_prec(mpfr_prec_t p)#

Destructively set the precision

This member function will set the precision of this to exactly p bits. The value of this will be set to NaN.

Parameters:: p – the desired precision.
Returns:: a reference to this.
Throws:: std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

real &prec_round(mpfr_prec_t p)#

Set the precision maintaining the current value.

This member function will set the precision of this to exactly p bits. If p is smaller than the current precision of this, a rounding operation will be performed, otherwise the current value will be preserved exactly.

Parameters:: p – the desired precision.
Returns:: a reference to this.
Throws:: std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

std::size_t get_nlimbs() const#

Added in version 0.27.

Get the number of limbs.

Returns:: the number of multiprecision limbs (of type mp_limb_t) necessary to represent the significand of this.

template<real_interoperable T> explicit operator T() const#

Generic conversion operator.

This operator will convert this to T. The conversion proceeds as follows:

if T is bool, then the conversion returns false if this is zero, true otherwise (including if this is NaN);
if T is an integral C++ type other than bool, the conversion will yield the truncated counterpart of this (i.e., the conversion rounds to zero). The conversion may fail due to overflow or domain errors (i.e., when trying to convert non-finite values);
if T if a floating-point C++ type, the conversion calls directly the low-level MPFR functions (e.g., mpfr_get_d()), and might yield infinities for finite input values;
if T is integer, the conversion rounds to zero and might fail due to domain errors, but it will never overflow;
if T is rational, the conversion may fail if this is not finite or if the conversion produces an overflow in the manipulation of the exponent of this (that is, if the absolute value of this is very large or very small). If the conversion succeeds, it will be exact;
if T is real128, the conversion might yield infinities for finite input values.

Returns:

this converted to T.

Throws:

std::domain_error – if this is not finite and the target type cannot represent non-finite numbers.
std::overflow_error – if the conversion results in overflow.

template<cpp_complex T> explicit operator T() const#

Added in version 0.20.

Conversion to complex C++ types.

The real part of the return value is constructed by converting this to the value type of T. The imaginary part of the return value is set to zero.

Returns:: this converted to T.

template<real_interoperable T> bool get(T &rop) const#

Generic conversion function.

This member function, similarly to the conversion operator, will convert this to T, storing the result of the conversion into rop. Differently from the conversion operator, this function does not raise any exception: if the conversion is successful, the function will return true, otherwise the function will return false. If the conversion fails, rop will not be altered.

Parameters:: rop – the variable which will store the result of the conversion.
Returns:: true if the conversion succeeded, false otherwise. The conversion can fail in the ways specified in the documentation of the conversion operator.

template<cpp_complex T> bool get(T &rop) const#

Added in version 0.20.

Conversion function to complex C++ types.

The conversion is always successful.

Parameters:: rop – the variable which will store the result of the conversion.
Returns:: true.

std::string to_string(int base = 10) const#

Conversion to string.

This member function will convert this to a string representation in base base. The returned string is guaranteed to produce exactly the original value when used in one of the constructors from string of real (provided that the original precision and base are used in the construction).

Parameters:

base – the base to be used for the string representation.

Returns:

this converted to a string.

Throws:

std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.
std::runtime_error – if the call to the mpfr_get_str() function of the MPFR API fails.

std::size_t get_str_ndigits(int base = 10) const#

Added in version 0.25.

Note

This function is available from MPFR 4.1 onwards.

Minimum number of digits necessary for round-tripping.

This member function will return the minimum number of digits necessary to ensure that the current value of this can be recovered exactly from a string representation in the given base.

Parameters:: base – the base to be used for the string representation.
Returns:: the minimum number of digits necessary for round-tripping.
Throws:: std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.

real &neg()#

real &abs()#

In-place negation and absolute value.

Returns:: a reference to this.

real &sqr()#

Added in version 0.19.

Square this in place.

Returns:: a reference to this.

real &sqrt()#

real &rec_sqrt()#

real &sqrt1pm1()#

real &cbrt()#

Note

The sqrt1pm1() function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

In-place roots.

These member functions will set this to, respectively:

\(\sqrt{x}\),
\(\frac{1}{\sqrt{x}}\),
\(\sqrt{1+x}-1\),
\(\sqrt[3]{x}\),

where \(x\) is the current value of this.

Added in version 0.12: The rec_sqrt() and cbrt() functions.

Added in version 0.19: The sqrt1pm1() function.

Returns:: a reference to this.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

real &sin()#

real &cos()#

real &tan()#

real &sec()#

real &csc()#

real &cot()#

real &sin_pi()#

real &cos_pi()#

real &tan_pi()#

real &cot_pi()#

real &sinc()#

real &sinc_pi()#

Note

The sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

In-place trigonometric functions.

These member functions will set this to, respectively:

\(\sin{x}\),
\(\cos{x}\),
\(\tan{x}\),
\(\sec{x}\),
\(\csc{x}\),
\(\cot{x}\),
\(\sin\left( \pi x \right)\),
\(\cos\left( \pi x \right)\),
\(\tan\left( \pi x \right)\),
\(\cot\left( \pi x \right)\),
\(\frac{\sin\left( x \right)}{x}\),
\(\frac{\sin\left( \pi x \right)}{\pi x}\).

where \(x\) is the current value of this.

Added in version 0.19: The sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi() functions.

Returns:: a reference to this.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

real &acos()#

real &asin()#

real &atan()#

In-place inverse trigonometric functions.

These member functions will set this to, respectively:

\(\arccos{x}\),
\(\arcsin{x}\),
\(\arctan{x}\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &sinh()#

real &cosh()#

real &tanh()#

real &sech()#

real &csch()#

real &coth()#

In-place hyperbolic functions.

These member functions will set this to, respectively:

\(\sinh{x}\),
\(\cosh{x}\),
\(\tanh{x}\),
\(\operatorname{sech}{x}\),
\(\operatorname{csch}{x}\),
\(\coth{x}\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &acosh()#

real &asinh()#

real &atanh()#

In-place inverse hyperbolic functions.

These member functions will set this to, respectively:

\(\operatorname{arccosh}{x}\),
\(\operatorname{arcsinh}{x}\),
\(\operatorname{arctanh}{x}\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &exp()#

real &exp2()#

real &exp10()#

real &expm1()#

real &log()#

real &log2()#

real &log10()#

real &log1p()#

In-place exponentials and logarithms.

These member functions will set this to, respectively:

\(e^x\),
\(2^x\),
\(10^x\),
\(e^x-1\),
\(\log x\),
\(\log_2 x\),
\(\log_{10} x\),
\(\log\left( 1+x\right)\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &gamma()#

real &lngamma()#

real &lgamma()#

real &digamma()#

In-place gamma functions.

These member functions will set this to, respectively:

\(\Gamma\left( x \right)\),
\(\log \Gamma\left( x \right)\),
\(\log \left|\Gamma\left( x \right)\right|\),
\(\psi\left( x \right)\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &j0()#

real &j1()#

real &y0()#

real &y1()#

In-place Bessel functions of the first and second kind.

These member functions will set this to, respectively:

\(J_0\left( x \right)\),
\(J_1\left( x \right)\),
\(Y_0\left( x \right)\),
\(Y_1\left( x \right)\),

where \(x\) is the current value of this.

Returns:: a reference to this.

real &eint()#

real &li2()#

real &zeta()#

real &erf()#

real &erfc()#

real &ai()#

real &lambert_w0()#

real &lambert_wm1()#

Note

The lambert_w0() and lambert_wm1() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Other special functions, in-place variants.

These member functions will set this to, respectively:

\(\operatorname{Ei}\left( x \right)\),
\(\operatorname{Li}_2\left( x \right)\),
\(\zeta\left( x \right)\),
\(\operatorname{erf}\left( x \right)\),
\(\operatorname{erfc}\left( x \right)\),
\(\operatorname{Ai}\left( x \right)\),
the Lambert W functions \(W_0\left( x \right)\) and \(W_{-1}\left( x \right)\),

where \(x\) is the current value of this.

Added in version 0.24: The lambert_w0() and lambert_wm1() functions.

Returns:: a reference to this.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

real &ceil()#

real &floor()#

real &round()#

real &roundeven()#

real &trunc()#

real &frac()#

Note

The roundeven() function is available from MPFR 4 onwards.

In-place integer and remainder-related functions.

These member functions will set this to, respectively:

\(\left\lceil x \right\rceil\),
\(\left\lfloor x \right\rfloor\),
x rounded to nearest (IEEE roundTiesToAway mode),
x rounded to nearest (IEEE roundTiesToEven mode),
\(\operatorname{trunc}\left( x \right)\),
the fractional part of x,

where \(x\) is the current value of this.

Added in version 0.21: The ceil(), floor(), round(), roundeven() and frac() functions.

Returns:: a reference to this.
Throws:: std::domain_error – if this represents a NaN value.

std::size_t binary_size() const#

Added in version 0.22.

Size of the serialised binary representation.

This member function will return a value representing the number of bytes necessary to serialise this into a memory buffer in binary format via one of the available binary_save() overloads. The returned value is platform-dependent.

Returns:: the number of bytes needed for the binary serialisation of this.
Throws:: std::overflow_error – if the size in limbs of this is larger than an implementation-defined limit.

std::size_t binary_save(char *dest) const#

std::size_t binary_save(std::vector<char> &dest) const#

template<std::size_t S> std::size_t binary_save(std::array<char, S> &dest) const#

std::size_t binary_save(std::ostream &dest) const#

Added in version 0.22.

Serialise into a memory buffer or an output stream.

These member functions will write into dest a binary representation of this. The serialised representation produced by these member functions can be read back with one of the binary_load() overloads.

For the first overload, dest must point to a memory area whose size is at least equal to the value returned by binary_size(), otherwise the behaviour will be undefined. dest does not have any special alignment requirements.

For the second overload, the size of dest must be at least equal to the value returned by binary_size(). If that is not the case, dest will be resized to binary_size().

For the third overload, the size of dest must be at least equal to the value returned by binary_size(). If that is not the case, no data will be written to dest and zero will be returned.

For the fourth overload, if the serialisation is successful (that is, no stream error state is ever detected in dest after write operations), then the binary size of this (that is, the number of bytes written into dest) will be returned. Otherwise, zero will be returned. Note that a return value of zero does not necessarily imply that no bytes were written into dest, just that an error occurred at some point during the serialisation process.

Warning

The binary representation produced by these member functions is compiler, platform and architecture specific, and it is subject to possible breaking changes in future versions of mp++. Thus, it should not be used as an exchange format or for long-term data storage.

Parameters:

dest – the output buffer or stream.

Returns:

the number of bytes written into dest (i.e., the output of binary_size(), if the serialisation was successful).

Throws:

std::overflow_error – in case of (unlikely) overflow errors.
unspecified – any exception thrown by binary_size(), by memory errors in standard containers, or by the public interface of std::ostream.

std::size_t binary_load(const char *src)#

std::size_t binary_load(const std::vector<char> &src)#

template<std::size_t S> std::size_t binary_load(const std::array<char, S> &src)#

std::size_t binary_load(std::istream &src)#

Added in version 0.22.

Deserialise from a memory buffer or an input stream.

These member functions will load into this the content of the memory buffer or input stream src, which must contain the serialised representation of a real produced by one of the binary_save() overloads.

For the first overload, src does not have any special alignment requirements.

For the second and third overloads, the serialised representation of the real must start at the beginning of src, but it can end before the end of src. Data past the end of the serialised representation of the real will be ignored.

For the fourth overload, the serialised representation of the real must start at the current position of src, but src can contain other data before and after the serialised real value. Data past the end of the serialised representation of the real will be ignored. If a stream error state is detected at any point of the deserialisation process after a read operation, zero will be returned and this will not have been modified. Note that a return value of zero does not necessarily imply that no bytes were read from src, just that an error occurred at some point during the serialisation process.

Warning

Although these member functions perform a few consistency checks on the data in src, they cannot ensure complete safety against maliciously-crafted data. Users are advised to use these member functions only with trusted data.

Parameters:

src – the source memory buffer or stream.

Returns:

the number of bytes read from src (that is, the output of binary_size() after the deserialisation into this has successfully completed).

Throws:

std::overflow_error – in case of (unlikely) overflow errors.
std::invalid_argument – if invalid data is detected in src.
unspecified – any exception thrown by memory errors in standard containers, the public interface of std::istream, binary_size() or set_prec().

Types#

type mpfr_t#: This is the type used by the MPFR library to represent multiprecision floats. It is defined as an array of size 1 of an unspecified structure (see mpfr_struct_t).

See also

https://www.mpfr.org/mpfr-current/mpfr.html#Nomenclature-and-Types

using mppp::mpfr_struct_t = std::remove_extent_t<mpfr_t>#: The C structure used by MPFR to represent arbitrary-precision floats. The MPFR type mpfr_t is defined as an array of size 1 of this structure.

type mpfr_prec_t#: An integral type defined by the MPFR library, used to represent the precision of mpfr_t and (by extension) real objects.

type mpfr_exp_t#: An integral type defined by the MPFR library, used to represent the exponent of mpfr_t and (by extension) real objects.

enum class mppp::real_kind : std::underlying_type<mpfr_kind_t>::type#

This scoped enum is used to initialise a real with one of the three special values NaN, infinity or zero.

enumerator nan = MPFR_NAN_KIND#

enumerator inf = MPFR_INF_KIND#

enumerator zero = MPFR_ZERO_KIND#

Concepts#

template<typename T> concept mppp::cvr_real#: This concept is satisfied if the type T, after the removal of reference and cv qualifiers, is the same as mppp::real.

template<typename T> concept mppp::real_interoperable#

This concept is satisfied if the type T can interoperate with real. Specifically, this concept will be true if T is either:

a cpp_arithmetic type, or
an integer, or
a rational, or
real128.

template<typename ...Args> concept mppp::real_set_args#

This concept is satisfied if the types in the parameter pack Args can be used as argument types in one of the mppp::real::set() member function overloads. In other words, this concept is satisfied if the expression

r.set(x, y, z, ...);

is valid (where r is a non-const real and x, y, z, etc. are const references to the types in Args).

template<typename T, typename U> concept mppp::real_op_types#

This concept is satisfied if the types T and U are suitable for use in the generic binary operators and functions involving real. Specifically, the concept will be true if either:

T and U both satisfy cvr_real,
one type satisfies cvr_real and the other type, after the removal of reference and cv qualifiers, satisfies real_interoperable.

template<typename T, typename U> concept mppp::real_in_place_op_types#: This concept is satisfied if the types T and U are suitable for use in the generic in-place operators involving real. Specifically, the concept will be true if T and U satisfy real_op_types and T, after the removal of reference, is not const.

template<typename T, typename U> concept mppp::real_eq_op_types#

Added in version 0.20.

This concept is satisfied if the types T and U are suitable for use in the generic binary equality and inequality operators involving real and other types. Specifically, the concept will be true if either:

T and U satisfy real_op_types, or
one type is real and the other is a cpp_complex type.

Functions#

Precision handling#

mpfr_prec_t mppp::get_prec(const mppp::real &r)#

Get the precision of a real.

Parameters:: r – the input argument.
Returns:: the precision of r.

void mppp::set_prec(mppp::real &r, mpfr_prec_t p)#

void mppp::prec_round(mppp::real &r, mpfr_prec_t p)#

Set the precision of a real.

The first variant will set the precision of r to exactly p bits. The value of r will be set to NaN.

The second variant will preserve the current value of r, performing a rounding operation if p is less than the current precision of r.

Parameters:

r – the input argument.
p – the desired precision.

Throws:

unspecified – any exception thrown by mppp::real::set_prec() or mppp::real::prec_round().

constexpr mpfr_prec_t mppp::real_prec_min()#

constexpr mpfr_prec_t mppp::real_prec_max()#

Minimum/maximum precisions for a real.

These compile-time constants represent the minimum/maximum valid precisions for a real. The returned values are guaranteed to be, respectively, not less than the MPFR_PREC_MIN MPFR constant and not greater than the MPFR_PREC_MAX MPFR constant.

Returns:: the minimum/maximum valid precisions for a real.

std::size_t mppp::get_nlimbs(const mppp::real &r)#

Added in version 0.27.

Get the number of limbs of a real.

Parameters:: r – the input argument.
Returns:: the number of multiprecision limbs (of type mp_limb_t) necessary to represent the significand of r.

std::size_t mppp::prec_to_nlimbs(mpfr_prec_t p)#

Added in version 0.27.

Convert a precision value into a number of limbs.

Parameters:: p – the input precision value.
Returns:: the number of multiprecision limbs (of type mp_limb_t) necessary to represent the significand of a real with p bits of precision.
Throws:: std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

Assignment#

template<mppp::real_set_args... Args> mppp::real &mppp::set(mppp::real &r, const Args&... args)#

Generic setter.

This function will use the arguments args to set the value of the real r, using one of the available mppp::real::set() overloads. That is, the body of this function is equivalent to

return r.set(args...);

The input arguments must satisfy the mppp::real_set_args concept.

Parameters:

r – the return value.
args – the arguments that will be passed to mppp::real::set().

Returns:

a reference to r.

Throws:

unspecified – any exception thrown by the invoked mppp::real::set() overload.

mppp::real &mppp::set_ui_2exp(mppp::real &r, unsigned long n, mpfr_exp_t e)#

mppp::real &mppp::set_si_2exp(mppp::real &r, long n, mpfr_exp_t e)#

template<std::size_t SSize> mppp::real &mppp::set_z_2exp(mppp::real &r, const mppp::integer<SSize> &n, mpfr_exp_t e)#

Set to \(n\times 2^e\).

These functions will set r to \(n\times 2^e\). The precision of r will not be altered. If n is zero, the result will be positive zero.

Added in version 0.20: The set_ui_2exp() and set_si_2exp() functions.

Parameters:

r – the return value.
n – the input integer multiplier.
e – the exponent.

Returns:

a reference to r.

mppp::real &mppp::set_nan(mppp::real &r)#

mppp::real &mppp::set_inf(mppp::real &r, int sign = 0)#

mppp::real &mppp::set_zero(mppp::real &r, int sign = 0)#

Set to NaN, infinity or zero.

The precision of r will not be altered. When setting to infinity or zero, the sign bit will be positive if sign is nonnegative, negative otherwise. When setting to NaN, the sign bit is unspecified.

Parameters:

r – the input argument.
sign – the sign of the infinity or zero to which r will be set.

Returns:

a reference to r.

void mppp::swap(mppp::real &a, mppp::real &b) noexcept#

Swap efficiently a and b.

Parameters:

a – the first argument.
b – the second argument.

Conversion#

template<mppp::real_interoperable T> bool mppp::get(T &rop, const mppp::real &x)#

Generic conversion function.

This function will convert the input real x to T, storing the result of the conversion into rop. If the conversion is successful, the function will return true, otherwise the function will return false. If the conversion fails, rop will not be altered.

Parameters:

rop – the variable which will store the result of the conversion.
x – the input argument.

Returns:

true if the conversion succeeded, false otherwise. The conversion can fail in the ways specified in the documentation of the conversion operator for real.

template<mppp::cpp_complex T> bool mppp::get(T &rop, const mppp::real &x)#

Added in version 0.20.

Conversion to complex C++ types.

The conversion is always successful.

Parameters:

rop – the variable which will store the result of the conversion.
x – the input argument.

Returns:

true.

template<std::size_t SSize> mpfr_exp_t mppp::get_z_2exp(mppp::integer<SSize> &n, const mppp::real &r)#

Extract significand and exponent.

This function will extract the scaled significand of r into n, and return the exponent e such that \(r = n\times 2^e\).

If r is not finite, an error will be raised.

Parameters:

n – the integer that will contain the scaled significand of r.
r – the input argument.

Returns:

the exponent e such that \(r = n\times 2^e\).

Throws:

std::domain_error – if r is not finite.
std::overflow_error – if the output exponent is larger than an implementation-defined value.

std::size_t mppp::get_str_ndigits(const mppp::real &r, int base = 10)#

Added in version 0.25.

Note

This function is available from MPFR 4.1 onwards.

Minimum number of digits necessary for round-tripping.

This member function will return the minimum number of digits necessary to ensure that the current value of r can be recovered exactly from a string representation in the given base.

Parameters:

r – the input value.
base – the base to be used for the string representation.

Returns:

the minimum number of digits necessary for round-tripping.

Throws:

std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.

Arithmetic#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::add(mppp::real &rop, T &&a, U &&b)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::sub(mppp::real &rop, T &&a, U &&b)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::mul(mppp::real &rop, T &&a, U &&b)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::div(mppp::real &rop, T &&a, U &&b)#

Ternary basic real arithmetics.

These functions will set rop to, respectively:

\(a+b\),
\(a-b\),
\(a \times b\),
\(\frac{a}{b}\).

The precision of the result will be set to the largest precision among the operands.

Parameters:

rop – the return value.
a – the first operand.
b – the second operand.

Returns:

a reference to rop.

template<mppp::cvr_real T, mppp::cvr_real U, mppp::cvr_real V> mppp::real &mppp::fma(mppp::real &rop, T &&a, U &&b, V &&c)#

template<mppp::cvr_real T, mppp::cvr_real U, mppp::cvr_real V> mppp::real &mppp::fms(mppp::real &rop, T &&a, U &&b, V &&c)#

Quaternary real multiply-add/sub.

These functions will set rop to, respectively:

\(a \times b + c\),
\(a \times b - c\).

The precision of the result will be set to the largest precision among the operands.

Parameters:

rop – the return value.
a – the first operand.
b – the second operand.
c – the third operand.

Returns:

a reference to rop.

template<mppp::cvr_real T, mppp::cvr_real U, mppp::cvr_real V> mppp::real mppp::fma(T &&a, U &&b, V &&c)#

template<mppp::cvr_real T, mppp::cvr_real U, mppp::cvr_real V> mppp::real mppp::fms(T &&a, U &&b, V &&c)#

Ternary real multiply-add/sub.

These functions will return, respectively:

\(a \times b + c\),
\(a \times b - c\).

The precision of the result will be the largest precision among the operands.

Parameters:

a – the first operand.
b – the second operand.
c – the third operand.

Returns:

\(a \times b \pm c\).

template<mppp::cvr_real T> mppp::real &mppp::neg(mppp::real &rop, T &&x)#

Binary real negation.

This function will set rop to \(-x\). The precision of the result will be equal to the precision of x.

Parameters:

rop – the return value.
x – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::neg(T &&x)#

Unary real negation.

This function will return \(-x\). The precision of the result will be equal to the precision of x.

Parameters:: x – the operand.
Returns:: \(-x\).

template<mppp::cvr_real T> mppp::real &mppp::abs(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::fabs(mppp::real &rop, T &&x)#

Binary real absolute value.

These functions will set rop to \(\left| x \right|\). The precision of the result will be equal to the precision of x.

Added in version 0.27: The fabs() overload.

Parameters:

rop – the return value.
x – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::abs(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::fabs(T &&x)#

Unary real absolute value.

These functions will return \(\left| x \right|\). The precision of the result will be equal to the precision of x.

Added in version 0.27: The fabs() overload.

Parameters:: x – the operand.
Returns:: \(\left| x \right|\).

template<mppp::cvr_real T> mppp::real &mppp::mul_2ui(mppp::real &rop, T &&x, unsigned long n)#

template<mppp::cvr_real T> mppp::real &mppp::mul_2si(mppp::real &rop, T &&x, long n)#

template<mppp::cvr_real T> mppp::real &mppp::div_2ui(mppp::real &rop, T &&x, unsigned long n)#

template<mppp::cvr_real T> mppp::real &mppp::div_2si(mppp::real &rop, T &&x, long n)#

Added in version 0.19.

Ternary real primitives for multiplication/division by powers of 2.

These functions will set rop to, respectively:

\(x \times 2^n\) (mul_2 variants),
\(\frac{x}{2^n}\) (div_2 variants).

The precision of the result will be equal to the precision of x.

Parameters:

rop – the return value.
x – the operand.
n – the power of 2.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::mul_2ui(T &&x, unsigned long n)#

template<mppp::cvr_real T> mppp::real mppp::mul_2si(T &&x, long n)#

template<mppp::cvr_real T> mppp::real mppp::div_2ui(T &&x, unsigned long n)#

template<mppp::cvr_real T> mppp::real mppp::div_2si(T &&x, long n)#

Added in version 0.19.

Binary real primitives for multiplication/division by powers of 2.

These functions will return, respectively:

\(x \times 2^n\) (mul_2 variants),
\(\frac{x}{2^n}\) (div_2 variants).

The precision of the result will be equal to the precision of x.

Parameters:

x – the operand.
n – the power of 2.

Returns:

x multiplied/divided by \(2^n\).

template<mppp::cvr_real T> mppp::real &mppp::sqr(mppp::real &rop, T &&op)#

Added in version 0.19.

Binary real squaring.

This function will compute the square of op and store it into rop. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::sqr(T &&r)#

Added in version 0.19.

Unary real squaring.

This function will compute and return the square of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the operand.
Returns:: the square of r.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::dim(mppp::real &rop, T &&x, U &&y)#

Added in version 0.21.

Ternary positive difference.

This function will set rop to the positive difference of x and y. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first operand.
y – the second operand.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::dim(T &&x, U &&y)#

Added in version 0.21.

Binary positive difference.

This function will compute and return the positive difference of x and y. The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first operand.
y – the second operand.

Returns:

the positive difference of x and y.

Comparison#

bool mppp::nan_p(const mppp::real &r)#

bool mppp::isnan(const mppp::real &r)#

bool mppp::inf_p(const mppp::real &r)#

bool mppp::isinf(const mppp::real &r)#

bool mppp::number_p(const mppp::real &r)#

bool mppp::isfinite(const mppp::real &r)#

bool mppp::zero_p(const mppp::real &r)#

bool mppp::regular_p(const mppp::real &r)#

bool mppp::integer_p(const mppp::real &r)#

bool mppp::is_one(const mppp::real &r)#

Detect special values.

These functions will return true if r is, respectively:

NaN (nan_p() and isnan()),
an infinity (inf_p() and isinf()),
a finite number (number_p() and isfinite()),
zero (zero_p()),
a regular number (i.e., not NaN, infinity or zero) (regular_p()),
an integral value (integer_p()),
one (is_one()),

false otherwise.

Added in version 0.27: The isnan(), isinf() and isfinite() overloads.

Parameters:: r – the input argument.
Returns:: the result of the detection.

int mppp::sgn(const mppp::real &r)#

bool mppp::signbit(const mppp::real &r)#

Detect sign or sign bit.

The sign is returned as a positive value if r is positive, zero if r is zero, a negative value if r is negative.

The sign bit is true if r is negative, -0, or a NaN whose representation has its sign bit set, false otherwise.

Parameters:: r – the input argument.
Returns:: the sign or sign bit of r.
Throws:: unspecified – any exception raised by mppp::real::sgn().

int mppp::cmp(const mppp::real &a, const mppp::real &b)#

Three-way comparison.

This function will compare a and b, returning:

zero if \(a=b\),
a negative value if \(a<b\),
a positive value if \(a>b\).

If at least one NaN value is involved in the comparison, an error will be raised.

This function is useful to distinguish the three possible cases. The comparison operators are recommended instead if it is needed to distinguish only two cases.

Parameters:

a – the first operand.
b – the second operand.

Returns:

an integral value expressing how a compares to b.

Throws:

std::domain_error – if at least one of the operands is NaN.

int mppp::cmpabs(const mppp::real &a, const mppp::real &b)#

Added in version 0.20.

Three-way comparison of absolute values.

This function will compare a and b, returning:

zero if \(\left|a\right|=\left|b\right|\),
a negative value if \(\left|a\right|<\left|b\right|\),
a positive value if \(\left|a\right|>\left|b\right|\).

If at least one NaN value is involved in the comparison, an error will be raised.

Parameters:

a – the first operand.
b – the second operand.

Returns:

an integral value expressing how the absolute values of a and b compare.

Throws:

std::domain_error – if at least one of the operands is NaN.

int mppp::cmp_ui_2exp(const mppp::real &a, unsigned long n, mpfr_exp_t e)#

int mppp::cmp_si_2exp(const mppp::real &a, long n, mpfr_exp_t e)#

Added in version 0.20.

Comparison with integral multiples of powers of 2.

This function will compare a to \(n\times 2^e\), returning:

zero if \(a=n\times 2^e\),
a negative value if \(a<n\times 2^e\),
a positive value if \(a>n\times 2^e\).

If a is NaN, an error will be raised.

Parameters:

a – the first operand.
n – the integral multiplier.
e – the power of 2.

Returns:

an integral value expressing how a compares to \(n\times 2^e\).

Throws:

std::domain_error – if a is NaN.

bool mppp::real_equal_to(const mppp::real &a, const mppp::real &b)#

Equality predicate with special handling for NaN.

If both a and b are not NaN, this function is identical to the equality operator for real. If at least one operand is NaN, this function will return true if both operands are NaN, false otherwise.

In other words, this function behaves like an equality operator which considers all NaN values equal to each other.

Parameters:

a – the first operand.
b – the second operand.

Returns:

true if \(a = b\) (including the case in which both operands are NaN), false otherwise.

bool mppp::real_lt(const mppp::real &a, const mppp::real &b)#

bool mppp::real_gt(const mppp::real &a, const mppp::real &b)#

Comparison predicates with special handling for NaN and moved-from real.

These functions behave like less/greater-than operators which consider NaN values greater than non-NaN values, and moved-from objects greater than both NaN and non-NaN values. These functions can be used as comparators in various facilities of the standard library (e.g., std::sort(), std::set, etc.).

Parameters:

a – the first operand.
b – the second operand.

Returns:

true if \(a < b\) (respectively, \(a > b\)), following the rules detailed above regarding NaN values and moved-from objects, false otherwise.

Roots#

template<mppp::cvr_real T> mppp::real &mppp::sqrt(mppp::real &rop, T &&op)#

Binary real square root.

This function will compute the square root of op and store it into rop. The precision of the result will be equal to the precision of op.

If op is -0, rop will be set to -0. If op is negative, rop will be set to NaN.

Parameters:

rop – the return value.
op – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::sqrt(T &&r)#

Unary real square root.

This function will compute and return the square root of r. The precision of the result will be equal to the precision of r.

If r is -0, the result will be -0. If r is negative, the result will be NaN.

Parameters:: r – the operand.
Returns:: the square root of r.

template<mppp::cvr_real T> mppp::real &mppp::sqrt1pm1(mppp::real &rop, T &&op)#

Added in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Binary real sqrt1pm1.

This function will compute \(\sqrt{1+x}-1\), where \(x\) is the value of op, and store the result into rop. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the operand.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real mppp::sqrt1pm1(T &&r)#

Added in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Unary real sqrt1pm1.

This function will compute and return \(\sqrt{1+x}-1\), where \(x\) is the value of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the operand.
Returns:: the sqrt1pm1 of r.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real &mppp::rec_sqrt(mppp::real &rop, T &&op)#

Added in version 0.12.

Binary real reciprocal square root.

This function will compute the reciprocal square root of op and store it into rop. The precision of the result will be equal to the precision of op.

If op is zero, rop will be set to a positive infinity (regardless of the sign of op). If op is a positive infinity, rop will be set to +0. If op is negative, rop will be set to NaN.

Parameters:

rop – the return value.
op – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::rec_sqrt(T &&r)#

Added in version 0.12.

Unary real reciprocal square root.

This function will compute and return the reciprocal square root of r. The precision of the result will be equal to the precision of r.

If r is zero, a positive infinity will be returned (regardless of the sign of r). If r is a positive infinity, +0 will be returned. If r is negative, NaN will be returned.

Parameters:: r – the operand.
Returns:: the reciprocal square root of r.

template<mppp::cvr_real T> mppp::real &mppp::cbrt(mppp::real &rop, T &&op)#

Added in version 0.12.

Binary real cubic root.

This function will compute the cubic root of op and store it into rop. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the operand.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::cbrt(T &&r)#

Added in version 0.12.

Unary real cubic root.

This function will compute and return the cubic root of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the operand.
Returns:: the cubic root of r.

template<mppp::cvr_real T> mppp::real &mppp::rootn_ui(mppp::real &rop, T &&op, unsigned long k)#

Added in version 0.12.

Note

This function is available from MPFR 4 onwards.

Binary real k-th root.

This function will compute the k-th root of op and store it into rop. The precision of the result will be equal to the precision of op.

If k is zero, the result will be NaN. If k is odd (resp. even) and op negative (including negative infinity), the result will be a negative number (resp. NaN). If op is zero, the result will be zero with the sign obtained by the usual limit rules, i.e., the same sign as op if k is odd, and positive if k is even.

Parameters:

rop – the return value.
op – the operand.
k – the degree of the root.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::rootn_ui(T &&r, unsigned long k)#

Added in version 0.12.

Note

This function is available from MPFR 4 onwards.

Unary real k-th root.

This function will compute and return the k-th root of r. The precision of the result will be equal to the precision of r.

If k is zero, the result will be NaN. If k is odd (resp. even) and r negative (including negative infinity), the result will be a negative number (resp. NaN). If r is zero, the result will be zero with the sign obtained by the usual limit rules, i.e., the same sign as r if k is odd, and positive if k is even.

Parameters:

r – the operand.
k – the degree of the root.

Returns:

the k-th root of r.

Exponentiation#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::pow(mppp::real &rop, T &&op1, U &&op2)#

Ternary exponentiation.

This function will set rop to op1 raised to the power of op2. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
op1 – the base.
op2 – the exponent.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::pow(T &&op1, U &&op2)#

Binary exponentiation.

This function will compute and return op1 raised to the power of op2. The precision of the result will be set to the largest precision among the operands.

Parameters:

op1 – the base.
op2 – the exponent.

Returns:

op1 raised to the power of op2.

Trigonometry#

template<mppp::cvr_real T> mppp::real &mppp::sin(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::cos(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::tan(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::sec(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::csc(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::cot(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::sin_pi(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::cos_pi(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::tan_pi(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::cot_pi(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::sinc(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::sinc_pi(mppp::real &rop, T &&x)#

Note

The functions sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi() are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Binary basic trigonometric functions.

These functions will set rop to, respectively:

\(\sin\left( x \right)\),
\(\cos\left( x \right)\),
\(\tan\left( x \right)\),
\(\sec\left( x \right)\),
\(\csc\left( x \right)\),
\(\cot\left( x \right)\),
\(\sin\left( \pi x \right)\),
\(\cos\left( \pi x \right)\),
\(\tan\left( \pi x \right)\),
\(\cot\left( \pi x \right)\),
\(\frac{\sin\left( x \right)}{x}\),
\(\frac{\sin\left( \pi x \right)}{\pi x}\).

The precision of the result will be equal to the precision of x.

Added in version 0.19: The functions sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi().

Parameters:

rop – the return value.
x – the argument.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real mppp::sin(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::cos(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::tan(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::sec(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::csc(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::cot(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::sin_pi(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::cos_pi(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::tan_pi(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::cot_pi(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::sinc(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::sinc_pi(T &&x)#

Note

The functions sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi() are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Unary basic trigonometric functions.

These functions will return, respectively:

\(\sin\left( x \right)\),
\(\cos\left( x \right)\),
\(\tan\left( x \right)\),
\(\sec\left( x \right)\),
\(\csc\left( x \right)\),
\(\cot\left( x \right)\),
\(\sin\left( \pi x \right)\),
\(\cos\left( \pi x \right)\),
\(\tan\left( \pi x \right)\),
\(\cot\left( \pi x \right)\),
\(\frac{\sin\left( x \right)}{x}\),
\(\frac{\sin\left( \pi x \right)}{\pi x}\).

The precision of the result will be equal to the precision of x.

Added in version 0.19: The functions sin_pi(), cos_pi(), tan_pi(), cot_pi(), sinc() and sinc_pi().

Parameters:: x – the argument.
Returns:: the trigonometric function of x.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> void mppp::sin_cos(mppp::real &sop, mppp::real &cop, T &&op)#

Simultaneous sine and cosine.

This function will set sop and cop respectively to the sine and cosine of op. sop and cop must be distinct objects. The precision of sop and rop will be set to the precision of op.

Parameters:

sop – the sine return value.
cop – the cosine return value.
op – the operand.

Throws:

std::invalid_argument – if sop and cop are the same object.

template<mppp::cvr_real T> mppp::real &mppp::asin(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::acos(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::atan(mppp::real &rop, T &&op)#

Binary basic inverse trigonometric functions.

These functions will set rop to, respectively, the arcsine, arccosine and arctangent of op. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::asin(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::acos(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::atan(T &&r)#

Unary basic inverse trigonometric functions.

These functions will return, respectively, the arcsine, arccosine and arctangent of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the argument.
Returns:: the arcsine, arccosine or arctangent of r.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::atan2(mppp::real &rop, T &&y, U &&x)#

Ternary arctangent-2.

This function will set rop to the arctangent-2 of y and x. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
y – the sine argument.
x – the cosine argument.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::atan2(T &&y, U &&x)#

Binary arctangent-2.

This function will compute and return the arctangent-2 of y and x. The precision of the result will be set to the largest precision among the operands.

Parameters:

y – the sine argument.
x – the cosine argument.

Returns:

the arctangent-2 of y and x.

Hyperbolic functions#

template<mppp::cvr_real T> mppp::real &mppp::sinh(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::cosh(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::tanh(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::sech(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::csch(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::coth(mppp::real &rop, T &&op)#

Binary basic hyperbolic functions.

These functions will set rop to, respectively, the hyperbolic sine, cosine, tangent, secant, cosecant and cotangent of op. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::sinh(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::cosh(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::tanh(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::sech(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::csch(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::coth(T &&r)#

Unary basic hyperbolic functions.

These functions will return, respectively, the hyperbolic sine, cosine, tangent, secant, cosecant and cotangent of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the argument.
Returns:: the hyperbolic sine, cosine, tangent, secant, cosecant or cotangent of r.

template<mppp::cvr_real T> void mppp::sinh_cosh(mppp::real &sop, mppp::real &cop, T &&op)#

Simultaneous hyperbolic sine and cosine.

This function will set sop and cop respectively to the hyperbolic sine and cosine of op. sop and cop must be distinct objects. The precision of sop and rop will be set to the precision of op.

Parameters:

sop – the hyperbolic sine return value.
cop – the hyperbolic cosine return value.
op – the operand.

Throws:

std::invalid_argument – if sop and cop are the same object.

template<mppp::cvr_real T> mppp::real &mppp::asinh(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::acosh(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::atanh(mppp::real &rop, T &&op)#

Binary basic inverse hyperbolic functions.

These functions will set rop to, respectively, the inverse hyperbolic sine, cosine and tangent of op. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::asinh(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::acosh(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::atanh(T &&r)#

Unary basic inverse hyperbolic functions.

These functions will return, respectively, the inverse hyperbolic sine, cosine and tangent of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the argument.
Returns:: the inverse hyperbolic sine, cosine or tangent of r.

Logarithms and exponentials#

template<mppp::cvr_real T> mppp::real &mppp::exp(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::exp2(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::exp10(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::expm1(mppp::real &rop, T &&x)#

Binary exponentials.

These functions will set rop to, respectively,

\(e^x\),
\(2^x\),
\(10^x\),
\(e^x - 1\).

The precision of the result will be equal to the precision of x.

Parameters:

rop – the return value.
x – the exponent.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::exp(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::exp2(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::exp10(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::expm1(T &&x)#

Unary exponentials.

These functions will return, respectively,

\(e^x\),
\(2^x\),
\(10^x\),
\(e^x - 1\).

The precision of the result will be equal to the precision of x.

Parameters:: x – the exponent.
Returns:: the exponential of x.

template<mppp::cvr_real T> mppp::real &mppp::log(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::log2(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::log10(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::log1p(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::log_base_ui(mppp::real &rop, T &&x, unsigned long b)#

Note

The log_base_ui() function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Binary logarithms.

These functions will set rop to, respectively,

\(\log x\),
\(\log_2 x\),
\(\log_{10} x\),
\(\log\left( 1+x \right)\),
\(\log_b x\).

The precision of the result will be equal to the precision of x.

Added in version 0.21: The log_base_ui() function.

Parameters:

rop – the return value.
x – the operand.
b – the base of the logarithm.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real mppp::log(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::log2(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::log10(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::log1p(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::log_base_ui(T &&x, unsigned long b)#

Note

The log_base_ui() function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Unary logarithms.

These functions will return, respectively,

\(\log x\),
\(\log_2 x\),
\(\log_{10} x\),
\(\log\left( 1+x \right)\),
\(\log_b x\).

The precision of the result will be equal to the precision of x.

Added in version 0.21: The log_base_ui() function.

Parameters:

x – the operand.
b – the base of the logarithm.

Returns:

the logarithm of x.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::log_hypot(mppp::real &rop, T &&x, U &&y)#

Added in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Ternary log hypot function.

This function will set rop to \(\log\left(\sqrt{x^2+y^2}\right)\). The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first argument.
y – the second argument.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::log_hypot(T &&x, U &&y)#

Added in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Binary log hypot function.

This function will compute and return \(\log\left(\sqrt{x^2+y^2}\right)\). The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first argument.
y – the second argument.

Returns:

the log hypot function of x and y.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

Polylogarithms#

template<mppp::cvr_real T> mppp::real &mppp::li2(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::polylog_si(mppp::real &rop, long s, T &&x)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::polylog(mppp::real &rop, T &&s, U &&x)#

Note

The polylog_si() and polylog() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Polylogarithms.

These functions will set rop to, respectively:

the dilogarithm \(\operatorname{Li}_2\left( x \right)\),
the polylogarithm of integer order \(s\) \(\operatorname{Li}_s\left( x \right)\),
the polylogarithm of real order \(s\) \(\operatorname{Li}_s\left( x \right)\).

The precision of the result will be equal to the precision of x (for li2() and polylog_si()) or to the largest precision among s and x (for polylog()).

Added in version 0.24: The polylog_si() and polylog() functions.

Parameters:

rop – the return value.
s – the order of the polylogarithm.
x – the argument.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real mppp::li2(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::polylog_si(long s, T &&x)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::polylog(T &&s, U &&x)#

Note

The polylog_si() and polylog() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Polylogarithms.

These functions will return, respectively:

the dilogarithm \(\operatorname{Li}_2\left( x \right)\),
the polylogarithm of integer order \(s\) \(\operatorname{Li}_s\left( x \right)\),
the polylogarithm of real order \(s\) \(\operatorname{Li}_s\left( x \right)\).

The precision of the result will be equal to the precision of x (for li2() and polylog_si()) or to the largest precision among s and x (for polylog()).

Added in version 0.24: The polylog_si() and polylog() functions.

Parameters:

s – the order of the polylogarithm.
x – the argument.

Returns:

the polylogarithm of x.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

Gamma functions#

template<mppp::cvr_real T> mppp::real &mppp::gamma(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::lngamma(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::lgamma(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::digamma(mppp::real &rop, T &&op)#

Binary gamma functions.

These functions will set rop to, respectively,

\(\Gamma\left(op\right)\),
\(\ln\Gamma\left(op\right)\),
\(\ln\left|\Gamma\left(op\right)\right|\),
\(\psi\left(op\right)\).

The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::gamma(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::lngamma(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::lgamma(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::digamma(T &&r)#

Unary gamma functions.

These functions will return, respectively,

\(\Gamma\left(r\right)\),
\(\ln\Gamma\left(r\right)\),
\(\ln\left|\Gamma\left(r\right)\right|\),
\(\psi\left(r\right)\).

The precision of the result will be equal to the precision of r.

Parameters:: r – the argument.
Returns:: the Gamma function, logarithm of the Gamma function, logarithm of the absolute value of the Gamma function, or the Digamma function of r.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::gamma_inc(mppp::real &rop, T &&x, U &&y)#

Added in version 0.17.

Note

This function is available from MPFR 4 onwards.

Ternary incomplete Gamma function.

This function will set rop to the upper incomplete Gamma function of x and y. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first argument.
y – the second argument.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::gamma_inc(T &&x, U &&y)#

Added in version 0.17.

Note

This function is available from MPFR 4 onwards.

Binary incomplete Gamma function.

This function will compute and return the upper incomplete Gamma function of x and y. The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first argument.
y – the second argument.

Returns:

the upper incomplete Gamma function of x and y

Bessel functions#

Added in version 0.17.

template<mppp::cvr_real T> mppp::real &mppp::j0(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::j1(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::jn(mppp::real &rop, long n, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::y0(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::y1(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::yn(mppp::real &rop, long n, T &&x)#

Bessel functions of the first and second kind of integral order.

These functions will set rop to, respectively,

\(J_0\left( x \right)\),
\(J_1\left( x \right)\),
\(J_n\left( x \right)\),
\(Y_0\left( x \right)\),
\(Y_1\left( x \right)\),
\(Y_n\left( x \right)\).

The precision of the result will be equal to the precision of x.

Parameters:

rop – the return value.
n – the order of the Bessel function.
x – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::j0(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::j1(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::jn(long n, T &&x)#

template<mppp::cvr_real T> mppp::real mppp::y0(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::y1(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::yn(long n, T &&x)#

Bessel functions of the first and second kind of integral order.

These functions will return, respectively,

\(J_0\left( x \right)\),
\(J_1\left( x \right)\),
\(J_n\left( x \right)\),
\(Y_0\left( x \right)\),
\(Y_1\left( x \right)\),
\(Y_n\left( x \right)\).

The precision of the result will be equal to the precision of x.

Parameters:

n – the order of the Bessel function.
r – the argument.

Returns:

the Bessel function of r.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::jx(mppp::real &rop, T &&nu, U &&x)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::yx(mppp::real &rop, T &&nu, U &&x)#

Added in version 0.20.

Note

These functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Bessel functions of the first and second kind of real order.

These functions will set rop to, respectively,

\(J_\nu\left( x \right)\),
\(Y_\nu\left( x \right)\),

where \(\nu \in \mathbb{R}\). The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
nu – the order of the Bessel function.
x – the argument.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::jx(T &&nu, U &&x)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::yx(T &&nu, U &&x)#

Added in version 0.20.

Note

These functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Bessel functions of the first and second kind of real order.

These functions will return, respectively,

\(J_\nu\left( x \right)\),
\(Y_\nu\left( x \right)\),

where \(\nu \in \mathbb{R}\). The precision of the result will be set to the largest precision among the operands.

Parameters:

nu – the order of the Bessel function.
x – the argument.

Returns:

the Bessel function of x.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

Error functions#

template<mppp::cvr_real T> mppp::real &mppp::erf(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::erfc(mppp::real &rop, T &&op)#

Binary error functions.

These functions will set rop to, respectively, the error function and the complementary error function of op. The precision of the result will be equal to the precision of op.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real mppp::erf(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::erfc(T &&r)#

Unary error functions.

These functions will return, respectively, the error function and the complementary error function of r. The precision of the result will be equal to the precision of r.

Parameters:: r – the argument.
Returns:: the error function or the complementary error function of r.

Other special functions#

template<mppp::cvr_real T> mppp::real &mppp::eint(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::zeta(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::ai(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::lambert_w0(mppp::real &rop, T &&op)#

template<mppp::cvr_real T> mppp::real &mppp::lambert_wm1(mppp::real &rop, T &&op)#

Note

The lambert_w0() and lambert_wm1() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Other binary special functions.

These functions will set rop to, respectively,

the exponential integral,
the Riemann Zeta function,
the Airy function,
the Lambert W functions \(W_0\) and \(W_{-1}\),

of op. The precision of the result will be equal to the precision of op.

Added in version 0.24: The lambert_w0() and lambert_wm1() functions.

Parameters:

rop – the return value.
op – the argument.

Returns:

a reference to rop.

Throws:

std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T> mppp::real mppp::eint(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::zeta(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::ai(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::lambert_w0(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::lambert_wm1(T &&r)#

Note

The lambert_w0() and lambert_wm1() functions are available only if mp++ was configured with the MPPP_WITH_FLINT option enabled.

Other unary special functions.

These functions will return, respectively,

the exponential integral,
the Riemann Zeta function,
the Airy function,
the Lambert W functions \(W_0\) and \(W_{-1}\),

of r. The precision of the result will be equal to the precision of r.

Added in version 0.24: The lambert_w0() and lambert_wm1() functions.

Parameters:: r – the argument.
Returns:: the exponential integral, Riemann Zeta function, Airy function or Lambert W function of r.
Throws:: std::invalid_argument – if the conversion between FLINT and MPFR types fails because of (unlikely) overflow conditions.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::beta(mppp::real &rop, T &&x, U &&y)#

Added in version 0.17.

Note

This function is available from MPFR 4 onwards.

Ternary beta function.

This function will set rop to the beta function of x and y. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first argument.
y – the second argument.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::beta(T &&x, U &&y)#

Added in version 0.17.

Note

This function is available from MPFR 4 onwards.

Binary beta function.

This function will compute and return the beta function of x and y. The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first argument.
y – the second argument.

Returns:

the beta function of x and y.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::hypot(mppp::real &rop, T &&x, U &&y)#

Ternary hypot function.

This function will set rop to \(\sqrt{x^2+y^2}\). The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first argument.
y – the second argument.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::hypot(T &&x, U &&y)#

Binary hypot function.

This function will compute and return \(\sqrt{x^2+y^2}\). The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first argument.
y – the second argument.

Returns:

the hypot function of x and y.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::agm(mppp::real &rop, T &&x, U &&y)#

Ternary AGM.

This function will set rop to the arithmetic-geometric mean of x and y. The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the first argument.
y – the second argument.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::agm(T &&x, U &&y)#

Binary AGM.

This function will compute and return the arithmetic-geometric mean of x and y. The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the first argument.
y – the second argument.

Returns:

the AGM of x and y.

Integer and remainder related functions#

template<mppp::cvr_real T> mppp::real &mppp::ceil(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::floor(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::round(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::roundeven(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::trunc(mppp::real &rop, T &&x)#

template<mppp::cvr_real T> mppp::real &mppp::frac(mppp::real &rop, T &&x)#

Note

The roundeven() function is available from MPFR 4 onwards.

Binary integer and remainder-related functions.

These functions will set rop to, respectively:

\(\left\lceil x \right\rceil\),
\(\left\lfloor x \right\rfloor\),
x rounded to nearest (IEEE roundTiesToAway mode),
x rounded to nearest (IEEE roundTiesToEven mode),
\(\operatorname{trunc}\left( x \right)\),
the fractional part of x.

The precision of the result will be equal to the precision of x.

Added in version 0.21: The ceil(), floor(), round(), roundeven() and frac() functions.

Parameters:

rop – the return value.
x – the operand.

Returns:

a reference to rop.

Throws:

std::domain_error – if x is NaN.

template<mppp::cvr_real T> mppp::real mppp::ceil(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::floor(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::round(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::roundeven(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::trunc(T &&x)#

template<mppp::cvr_real T> mppp::real mppp::frac(T &&x)#

Note

The roundeven() function is available from MPFR 4 onwards.

Unary integer and remainder-related functions.

These functions will return, respectively:

\(\left\lceil x \right\rceil\),
\(\left\lfloor x \right\rfloor\),
x rounded to nearest (IEEE roundTiesToAway mode),
x rounded to nearest (IEEE roundTiesToEven mode),
\(\operatorname{trunc}\left( x \right)\),
the fractional part of x.

The precision of the result will be equal to the precision of x.

Added in version 0.21: The ceil(), floor(), round(), roundeven() and frac() functions.

Parameters:: x – the operand.
Returns:: the result of the operation.
Throws:: std::domain_error – if x is NaN.

template<mppp::cvr_real T> void mppp::modf(mppp::real &iop, mppp::real &fop, T &&op)#

Added in version 0.21.

Simultaneous integral and fractional parts.

This function will set iop and fop respectively to the integral and fractional parts of op. iop and fop must be distinct objects. The precision of iop and fop will be set to the precision of op.

Parameters:

iop – the integral part return value.
fop – the fractional part return value.
op – the operand.

Throws:

std::invalid_argument – if iop and fop are the same object.
std::domain_error – if op is NaN.

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::fmod(mppp::real &rop, T &&x, U &&y)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::remainder(mppp::real &rop, T &&x, U &&y)#

Added in version 0.21.

Ternary floating modulus and remainder.

These functions will set rop to, respectively, the floating modulus and the remainder of the division \(x/y\).

The floating modulus is \(x - n\times y\), where \(n\) is \(x/y\) with its fractional part truncated.

The remainder is \(x - m\times y\), where \(m\) is the integral value nearest the exact value \(x/y\).

Special values are handled as described in the C99 standard.

The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
x – the numerator.
y – the denominator.

Returns:

a reference to rop.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::fmod(T &&x, U &&y)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::remainder(T &&x, U &&y)#

Added in version 0.21.

Binary floating modulus and remainder.

These functions will return, respectively, the floating modulus and the remainder of the division \(x/y\).

The floating modulus is \(x - n\times y\), where \(n\) is \(x/y\) with its fractional part truncated.

The remainder is \(x - m\times y\), where \(m\) is the integral value nearest the exact value \(x/y\).

Special values are handled as described in the C99 standard.

The precision of the result will be set to the largest precision among the operands.

Parameters:

x – the numerator.
y – the denominator.

Returns:

the floating modulus or remainder of \(x/y\).

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::fmodquo(mppp::real &rop, long *q, T &&x, U &&y)#

template<mppp::cvr_real T, mppp::cvr_real U> mppp::real &mppp::remquo(mppp::real &rop, long *q, T &&x, U &&y)#

Note

The fmodquo() function is available from MPFR 4 onwards.

Added in version 0.21.

Floating modulus and remainder with quotient.

These functions will set rop to, respectively, the floating modulus and the remainder of the division \(x/y\). Additionally, they will also store the low significant bits from the quotient in the value pointed to by q (more precisely the number of bits in a long minus one), with the sign of x divided by y (except if those low bits are all zero, in which case zero is returned).

The precision of rop will be set to the largest precision among the operands.

Parameters:

rop – the return value.
q – a pointer to the quotient return value.
x – the numerator.
y – the denominator.

Returns:

a reference to rop.

template<mppp::cvr_real T> mppp::real &mppp::nexttoward(mppp::real &rop, T &&x, const mppp::real &y)#

template<mppp::cvr_real T> mppp::real &mppp::nextafter(mppp::real &rop, T &&x, const mppp::real &y)#

Added in version 0.27.

Returns the next representable value of x in the direction of y (ternary version).

These functions will set rop to the next representable value of x in the direction of y. Note that in these functions the precision of y is ignored, and the precision of rop will always be set to the precision of x. If x equals y, rop will be set to x. If any operand is NaN, rop will also be set to NaN.

Parameters:

rop – the return value.
x – the source value.
y – the direction value.

Returns:

a reference to rop.

Throws:

unspecified – any exception raised by the copy assignment operator of real.

template<mppp::cvr_real T> mppp::real mppp::nexttoward(T &&x, const mppp::real &y)#

template<mppp::cvr_real T> mppp::real mppp::nextafter(T &&x, const mppp::real &y)#

Added in version 0.27.

Returns the next representable value of x in the direction of y (binary version).

These functions will return the next representable value of x in the direction of y. Note that in these functions the precision of y is ignored, and the precision of the result will always be set to the precision of x. If x equals y, x will be returned. If any operand is NaN, the return value will also be NaN.

Parameters:

x – the source value.
y – the direction value.

Returns:

the next representable value of x in the direction of y.

Throws:

unspecified – any exception raised by the copy assignment operator or the copy constructor of real.

Input/Output#

std::ostream &mppp::operator<<(std::ostream &os, const mppp::real &r)#

Output stream operator.

This function will direct to the output stream os the input real r.

Parameters:

os – the target stream.
r – the input argument.

Returns:

a reference to os.

Throws:

std::overflow_error – in case of (unlikely) overflow errors.
std::invalid_argument – if the MPFR printing primitive mpfr_asprintf() returns an error code.
unspecified – any exception raised by the public interface of std::ostream or by memory allocation errors.

Serialisation#

Added in version 0.22.

std::size_t mppp::binary_size(const mppp::real &x)#

Binary size.

This function is the free function equivalent of the mppp::real::binary_size() member function.

Parameters:: x – the input argument.
Returns:: the output of mppp::real::binary_size() called on x.
Throws:: unspecified – any exception thrown by mppp::real::binary_size().

template<typename T> std::size_t mppp::binary_save(const mppp::real &x, T &&dest)#

Binary serialisation.

Note

This function participates in overload resolution only if the expression

return x.binary_save(std::forward<T>(dest));

is well-formed.

This function is the free function equivalent of the mppp::real::binary_save() overloads.

Parameters:

x – the input argument.
dest – the object into which x will be serialised.

Returns:

the output of the invoked mppp::real::binary_save() overload called on x with dest as argument.

Throws:

unspecified – any exception thrown by the invoked mppp::real::binary_save() overload.

template<typename T> std::size_t mppp::binary_load(mppp::real &x, T &&src)#

Binary deserialisation.

Note

This function participates in overload resolution only if the expression

return x.binary_load(std::forward<T>(src));

is well-formed.

This function is the free function equivalent of the mppp::real::binary_load() overloads.

Parameters:

x – the output argument.
src – the object containing the serialised real that will be loaded into x.

Returns:

the output of the invoked mppp::real::binary_load() overload called on x with src as argument.

Throws:

unspecified – any exception thrown by the invoked mppp::real::binary_load() overload.

Other#

std::size_t mppp::hash(const mppp::real &x)#

Added in version 0.27.

Hash function for real.

This function guarantees that x == y implies hash(x) == hash(y).

Parameters:: x – the argument.
Returns:: a hash value for x.

Mathematical operators#

template<mppp::cvr_real T> mppp::real mppp::operator+(T &&r)#

template<mppp::cvr_real T> mppp::real mppp::operator-(T &&r)#

Identity and negation operators.

Parameters:: r – the input argument.
Returns:: \(r\) and \(-r\) respectively.

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::operator+(T &&a, U &&b)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::operator-(T &&a, U &&b)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::operator*(T &&a, U &&b)#

template<typename T, mppp::real_op_types<T> U> mppp::real mppp::operator/(T &&a, U &&b)#

Binary arithmetic operators.

The precision of the result will be set to the largest precision among the operands.

Parameters:

a – the first operand.
b – the second operand.

Returns:

the result of the binary operation.

template<typename U, mppp::real_in_place_op_types<U> T> T &mppp::operator+=(T &a, U &&b)#

template<typename U, mppp::real_in_place_op_types<U> T> T &mppp::operator-=(T &a, U &&b)#

template<typename U, mppp::real_in_place_op_types<U> T> T &mppp::operator*=(T &a, U &&b)#

template<typename U, mppp::real_in_place_op_types<U> T> T &mppp::operator/=(T &a, U &&b)#

In-place arithmetic operators.

If a is a real, then these operators are equivalent, respectively, to the expressions:

a = a + b;
a = a - b;
a = a * b;
a = a / b;

Otherwise, these operators are equivalent to the expressions:

a = static_cast<T>(a + b);
a = static_cast<T>(a - b);
a = static_cast<T>(a * b);
a = static_cast<T>(a / b);

Parameters:

a – the first operand.
b – the second operand.

Returns:

a reference to a.

Throws:

unspecified – any exception thrown by the generic conversion operator of real.

mppp::real &mppp::operator++(mppp::real &x)#

mppp::real &mppp::operator--(mppp::real &x)#

Prefix increment/decrement.

Parameters:: x – the input argument.
Returns:: a reference to x after the increment/decrement.

mppp::real mppp::operator++(mppp::real &x, int)#

mppp::real mppp::operator--(mppp::real &x, int)#

Suffix increment/decrement.

Parameters:: x – the input argument.
Returns:: a copy of x before the increment/decrement.

template<typename T, mppp::real_eq_op_types<T> U> bool mppp::operator==(const T &a, const U &b)#

template<typename T, mppp::real_eq_op_types<T> U> bool mppp::operator!=(const T &a, const U &b)#

template<typename T, mppp::real_op_types<T> U> bool mppp::operator<(const T &a, const U &b)#

template<typename T, mppp::real_op_types<T> U> bool mppp::operator<=(const T &a, const U &b)#

template<typename T, mppp::real_op_types<T> U> bool mppp::operator>(const T &a, const U &b)#

template<typename T, mppp::real_op_types<T> U> bool mppp::operator>=(const T &a, const U &b)#

Comparison operators.

These operators will compare a and b, returning true if, respectively:

\(a=b\),
\(a \neq b\),
\(a<b\),
\(a \leq b\),
\(a>b\),
\(a \geq b\),

and false otherwise.

The comparisons are always exact (i.e., no rounding is involved).

These operators handle NaN in the same way specified by the IEEE floating-point standard. Alternative comparison functions treating NaN specially are available.

Parameters:

a – the first operand.
b – the second operand.

Returns:

the result of the comparison.

Constants#

mppp::real mppp::real_pi(mpfr_prec_t p)#

mppp::real mppp::real_log2(mpfr_prec_t p)#

mppp::real mppp::real_euler(mpfr_prec_t p)#

mppp::real mppp::real_catalan(mpfr_prec_t p)#

These functions will return, respectively:

the \(\pi\) constant,
the \(\log 2\) constant,
the Euler-Mascheroni constant (0.577…),
Catalan’s constant (0.915…),

with a precision of p.

Added in version 0.21: The real_log2(), real_euler() and real_catalan() functions.

Parameters:: p – the desired precision.
Returns:: an approximation of a constant.
Throws:: std::invalid_argument – if p is outside the range established by mppp::real_prec_min() and mppp::real_prec_max().

mppp::real &mppp::real_pi(mppp::real &rop)#

mppp::real &mppp::real_log2(mppp::real &rop)#

mppp::real &mppp::real_euler(mppp::real &rop)#

mppp::real &mppp::real_catalan(mppp::real &rop)#

These functions will set rop to, respectively:

the \(\pi\) constant,
the \(\log 2\) constant,
the Euler-Mascheroni constant (0.577…),
Catalan’s constant (0.915…).

The precision of rop will not be altered.

Added in version 0.21: The real_log2(), real_euler() and real_catalan() functions.

Parameters:: rop – the return value.
Returns:: a reference to rop.

Standard library specialisations#

template<> class std::hash<mppp::real>#

Added in version 0.27.

Specialisation of std::hash for mppp::real.

The hash is computed via std::size_t mppp::hash(const mppp::real &).

using argument_type = mppp::real #

using result_type = std::size_t#

Note

The argument_type and result_type type aliases are defined only until C++14.

std::size_t operator()(const mppp::real &x) const#

Parameters:: x – the input mppp::real.
Returns:: a hash value for x.

User-defined literals#

Added in version 0.19.

template<char... Chars> mppp::real mppp::literals::operator""_r128()#

template<char... Chars> mppp::real mppp::literals::operator""_r256()#

template<char... Chars> mppp::real mppp::literals::operator""_r512()#

template<char... Chars> mppp::real mppp::literals::operator""_r1024()#

User-defined real literals.

These numeric literal operator templates can be used to construct real instances with, respectively, 128, 256, 512 and 1024 bits of precision. Floating-point literals in decimal and hexadecimal format are supported.

Throws:: std::invalid_argument – if the input sequence of characters is not a valid floating-point literal (as defined by the C++ standard).

Multiprecision floats

Contents

Multiprecision floats#

The real class#

Types#

Concepts#

Functions#

Precision handling#

Assignment#

Conversion#

Arithmetic#

Comparison#

Roots#

Exponentiation#

Trigonometry#

Hyperbolic functions#

Logarithms and exponentials#

Polylogarithms#

Gamma functions#

Bessel functions#

Error functions#

Other special functions#

Integer and remainder related functions#

Input/Output#

Serialisation#

Other#

Mathematical operators#

Constants#

Standard library specialisations#

User-defined literals#