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).

New 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 C++ floating-point 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 (and the precision at which the addition is computed) 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 represents exactly the value used for initialisation. 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.

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)

Copy constructor with custom precision.

This constructor will set this to a copy 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.

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.

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().

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

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 a C++ integral type I, then the precision is set to the bit width of I;
  • if x is a C++ floating-point 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<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.

Parameters
x – the mpfr_t that will be moved.
~real()

Destructor.

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.
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.

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<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().
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 a C++ integral 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 C++ floating-point 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<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.
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.
real &neg()
real &abs()

In-place negation and absolute value.

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_ARB 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.

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

New in version 0.19: The sqrt1pm1() function.

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

New in version 0.19.

Square this in place.

Returns
a reference to this.
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_ARB 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.

New 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 Arb 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()

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)\),

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

Returns
a reference to this.
real &trunc()

In-place truncation.

This member function will set this to its truncated counterpart.

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

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.

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

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::real_interoperable

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

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 ...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:

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.

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.

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.

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\).

This function 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.

Parameters
  • r – the return value.
  • n – input integer.
  • 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.

:param rop :the variable which will store the result of the conversion. :param 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<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.

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)

Binary real absolute value.

This function will set rop to \(\left| x \right|\). 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::abs(T &&x)

Unary real absolute value.

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

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)

New in version 0.19.

Ternary real primitives for exact 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. The computation will be exact (that is, no rounding takes place).

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)

New in version 0.19.

Binary real primitives for exact 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. The computation will be exact (that is, no rounding takes place).

Parameters
  • x – the operand.
  • n – the power of 2.
Returns

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

Comparison

bool mppp::nan_p(const mppp::real &r)
bool mppp::inf_p(const mppp::real &r)
bool mppp::number_p(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,
  • an infinity,
  • a finite number,
  • zero,
  • a regular number (i.e., not NaN, infinity or zero),
  • an integral value,
  • one,

false otherwise.

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.

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)

New in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_ARB option enabled (see the installation instructions).

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 Arb and MPFR types fails because of (unlikely) overflow conditions.

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

New in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_ARB option enabled (see the installation instructions).

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 Arb and MPFR types fails because of (unlikely) overflow conditions.
template<mppp::cvr_real T>
mppp::real &mppp::rec_sqrt(mppp::real &rop, T &&op)

New 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)

New 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)

New 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)

New 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)

New 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)

New 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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • op1 – the base.
  • op2 – the exponent.
Returns

op1 raised to the power of op2.

Throws

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

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

New 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)

New 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.

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_ARB option enabled (see the installation instructions).

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.

New 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 Arb 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_ARB option enabled (see the installation instructions).

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.

New 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 Arb 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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • y – the sine argument.
  • x – the cosine argument.
Returns

the arctangent-2 of y and x.

Throws

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

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)

Binary logarithms.

These functions will set rop to, respectively,

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

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::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)

Unary logarithms.

These functions will return, respectively,

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

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

Parameters
x – the operand.
Returns
the logarithm of x.
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::log_hypot(mppp::real &rop, T &&x, U &&y)

New in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_ARB option enabled (see the installation instructions).

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 Arb 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)

New in version 0.19.

Note

This function is available only if mp++ was configured with the MPPP_WITH_ARB option enabled (see the installation instructions).

Binary log hypot function.

This function will compute and return \(\log\left(\sqrt{x^2+y^2}\right)\).

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • x – the first argument.
  • y – the second argument.
Returns

the log hypot function of x and y.

Throws
  • unspecified – any exception thrown by the generic assignment operator of real.
  • std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.

Polylogarithms

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

Binary dilogarithm.

This function will set rop to \(\operatorname{Li}_2\left( x \right)\). The precision of the result will be equal to the precision of x. If \(x \geq 1\), rop will be set to NaN.

Parameters
  • rop – the return value.
  • x – the argument.
Returns

a reference to rop.

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

Unary dilogarithm.

This function will return \(\operatorname{Li}_2\left( x \right)\). The precision of the result will be equal to the precision of x. If \(x \geq 1\), NaN will be returned.

Parameters
x – the argument.
Returns
the dilogarithm of x.

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)

New 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)

New 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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • x – the first argument.
  • y – the second argument.
Returns

the upper incomplete Gamma function of x and y

Throws

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

Bessel functions

New in version 0.17.

template<mppp::cvr_real T>
mppp::real &mppp::j0(mppp::real &rop, T &&op)
template<mppp::cvr_real T>
mppp::real &mppp::j1(mppp::real &rop, T &&op)
template<mppp::cvr_real T>
mppp::real &mppp::jn(mppp::real &rop, long n, T &&op)
template<mppp::cvr_real T>
mppp::real &mppp::y0(mppp::real &rop, T &&op)
template<mppp::cvr_real T>
mppp::real &mppp::y1(mppp::real &rop, T &&op)
template<mppp::cvr_real T>
mppp::real &mppp::yn(mppp::real &rop, long n, T &&op)

Bessel functions.

These functions will set rop to, respectively,

  • the Bessel function of the first kind of order 0 \(\left(J_0\right)\) of op,
  • the Bessel function of the first kind of order 1 \(\left(J_1\right)\) of op,
  • the Bessel function of the first kind of order n \(\left(J_n\right)\) of op,
  • the Bessel function of the second kind of order 0 \(\left(Y_0\right)\) of op,
  • the Bessel function of the second kind of order 1 \(\left(Y_1\right)\) of op,
  • the Bessel function of the second kind of order n \(\left(Y_n\right)\) 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::j0(T &&r)
template<mppp::cvr_real T>
mppp::real mppp::j1(T &&r)
template<mppp::cvr_real T>
mppp::real mppp::jn(long n, T &&r)
template<mppp::cvr_real T>
mppp::real mppp::y0(T &&r)
template<mppp::cvr_real T>
mppp::real mppp::y1(T &&r)
template<mppp::cvr_real T>
mppp::real mppp::yn(long n, T &&r)

Bessel functions.

These functions will return, respectively,

  • the Bessel function of the first kind of order 0 \(\left(J_0\right)\) of r,
  • the Bessel function of the first kind of order 1 \(\left(J_1\right)\) of r,
  • the Bessel function of the first kind of order n \(\left(J_n\right)\) of r,
  • the Bessel function of the second kind of order 0 \(\left(Y_0\right)\) of r,
  • the Bessel function of the second kind of order 1 \(\left(Y_1\right)\) of r,
  • the Bessel function of the second kind of order n \(\left(Y_n\right)\) of r.

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

Parameters
r – the argument.
Returns
the Bessel function of r.

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)

Other binary special functions.

These functions will set rop to, respectively,

  • the exponential integral,
  • the Riemann Zeta function,
  • the Airy 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::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)

Other unary special functions.

These functions will return, respectively,

  • the exponential integral,
  • the Riemann Zeta function,
  • the Airy function,

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

Parameters
r – the argument.
Returns
the exponential integral, Riemann Zeta function or Airy function of r.
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::beta(mppp::real &rop, T &&x, U &&y)

New 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)

New 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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • x – the first argument.
  • y – the second argument.
Returns

the beta function of x and y.

Throws

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

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}\).

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • x – the first argument.
  • y – the second argument.
Returns

the hypot function of x and y.

Throws

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

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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • x – the first argument.
  • y – the second argument.
Returns

the AGM of x and y.

Throws

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

Input/Output

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

Output stream operator.

This operator will insert into the stream os a string representation of r in base 10 (as returned by mppp::real::to_string()).

Warning

In future versions of mp++, the behaviour of this operator will change to support the output stream’s formatting flags. For the time being, users are encouraged to use the mpfr_get_str() function from the MPFR library if precise and forward-compatible control on the printing format is needed.

Parameters
  • os – the target stream.
  • r – the input argument.
Returns

a reference to os.

Throws

unspecified – any exception thrown by :cpp:func`mppp::real::to_string()`.

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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Parameters
  • a – the first operand.
  • b – the second operand.
Returns

the result of the binary operation.

Throws

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

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);

That is, the operation is performed via the corresponding binary operator and the result is assigned back to a, after a conversion if necessary.

Parameters
  • a – the first operand.
  • b – the second operand.
Returns

a reference to a.

Throws

unspecified – any exception thrown by the corresponding binary operator, or 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_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)
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.

Non-real operands will be converted to real before performing the operation. The conversion of non-real operands to real follows the same heuristics described in the generic assignment operator of real.

Note

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.

Throws

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

Constants

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

\(\pi\) constant.

This function will return a real \(\pi\) with a precision of p.

Parameters
p – the desired precision.
Returns
an approximation of \(\pi\).
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)

Set to \(\pi\).

This function will set rop to \(\pi\). The precision of rop will not be altered.

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

User-defined literals

New 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).