# 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 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, $$\mathrm{max}\left(200,150\right)=200$$ bits.

The precision of a real can be set at construction, or it can be changed later via functions and methods 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 either by specifying explicitly the desired precision value, or by setting a global default precision via real_set_default_prec().

This class has the look and feel of a C++ builtin type: it can interact with all of C++’s integral and floating-point primitive types, integer, rational and real128 (see the RealInteroperable concept), and it provides overloaded operators. Differently from the builtin types, however, this class does not allow any implicit conversion to/from other types (apart from bool): construction from and conversion to primitive types must always be requested explicitly. As a side effect, syntax such as

real r = 5;
int m = r;


will not work, and direct initialization should be used instead:

real r{5};
int m{r};


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

Multiple overloads of the same functionality are often available. Binary functions in MPFR are usually implemented via three-operands functions, in which the first operand is a reference to the return value. The exponentiation function mpfr_pow(), for instance, takes three operands: the return value, the base and the exponent. There are two overloads of the corresponding exponentiation function for real:

• a ternary overload similar to mpfr_pow(),

• a binary overload taking as inputs the base and the exponent, and returning the result of the exponentiation.

This allows to avoid having to set up a return value for one-off invocations of pow() (the binary overload will do it for you). For example:

real r1, r2, r3{3}, r4{2};
pow(r1,r3,r4);   // Ternary pow(): computes 3**2 and stores
// the result in r1.
r2 = pow(r3,r4); // Binary pow(): returns 3**2, which is then
// assigned to r2.


In case of unary functions, there are often three overloads available:

• a binary overload taking as first parameter a reference to the return value (MPFR style),

• a unary overload returning the result of the operation,

• a nullary member function that modifies the calling object in-place.

For instance, here are three possible ways of computing the absolute value:

real r1, r2, r3{-5};
abs(r1,r3);   // Binary abs(): computes and stores the absolute value
// of r3 into r1.
r2 = abs(r3); // Unary abs(): returns the absolute value of r3, which is
// then assigned to r2.
r3.abs();     // Member function abs(): replaces the value of r3 with its
// absolute value.


Note that at this time a subset of the MPFR API has been wrapped by real.

Various overloaded operators are provided. The arithmetic operators always return a real result. The relational operators, ==, !=, <, >, <= and >= will promote non-real arguments to real before performing the comparison. 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.

Public Functions

real()

Default constructor.

The value will be initialised to positive zero. The precision of this will be either the default precision, if set, or the value returned by real_prec_min() otherwise.

real(const real &other)

Copy constructor.

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

Parameters
• other: the real that will be copied.

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 real that will be copied.

• p: the desired precision.

Exceptions

real(real &&other)

Move constructor.

Warning

Unless otherwise noted, the only valid operations on the moved-from other object are destruction and copy/move assignment. After re-assignment, other can be used normally again.

Parameters
• other: the real that will be moved.

real(real_kind k, int sign, mpfr_prec_t p)

Constructor from a special value, sign and precision.

This constructor will initialise this with one of the special values specified by the real_kind enum. The precision of this will be p. If p is zero, the precision will be set to the default precision (as indicated by real_get_default_prec()).

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

Parameters
• k: the desired special value.

• sign: the desired sign for this.

• p: the desired precision for this.

Exceptions
• std::invalid_argument: if p is not within the bounds established by real_prec_min() and real_prec_max(), or if p is zero but no default precision has been set.

real(real_kind k, mpfr_prec_t p)

Constructor from a special value and precision.

This constructor is equivalent to the constructor from a special value, sign and precision with a hard-coded sign of 0.

Parameters
• k: the desired special value.

• p: the desired precision for this.

Exceptions
• unspecified: any exception thrown by the constructor from a special value, sign and precision.

real(real_kind k)

Constructor from a special value.

This constructor is equivalent to the constructor from a special value, sign and precision with a hard-coded sign of 0 and hard-coded precision of 0.

Parameters
• k: the desired special value.

Exceptions
• unspecified: any exception thrown by the constructor from a special value, sign and precision.

template<RealInteroperable T>
real(const T &x, mpfr_prec_t p = 0)

Generic constructor.

The generic constructor will set this to the value of x with a precision of p.

If p is nonzero, then this will be initialised exactly to a precision of p, and a rounding operation might occurr.

If p is zero, the constructor will first fetch the default precision dp via real_get_default_prec(). If dp is nonzero, then dp will be used as precision for this and a rounding operation might occurr.

Otherwise, if dp is zero, the precision of this will be set 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 ensuring that, whatever the type of x, its value is preserved exactly 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.

Exceptions
• std::overflow_error: if an overflow occurs in the computation of the automatically-deduced precision.

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

template<StringType T>
real(const T &s, int base, mpfr_prec_t p)

Constructor from string, base and precision.

This constructor will set this to the value represented by the StringType 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 [2,62] 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 p if p is nonzero, the default precision otherwise. If p is zero and no default precision has been set, an error will be raised.

Parameters
• s: the input string.

• base: the base used in the string representation.

• p: the desired precision.

Exceptions
• std::invalid_argument: in the following cases:

• base is not zero and not in the [2,62] range,

• p is either outside the valid bounds for a precision value, or it is zero and no default precision value has been set,

• s cannot be interpreted as a floating-point number.

• unspecified: any exception thrown by memory errors in standard containers.

template<StringType T>
real(const T &s, mpfr_prec_t p)

Constructor from string and precision.

This constructor is equivalent to the constructor from string with a base value hard-coded to 10.

Parameters
• s: the input string.

• p: the desired precision.

Exceptions
• unspecified: any exception thrown by the constructor from string, base and precision.

template<StringType T>
real(const T &s)

Constructor from string.

This constructor is equivalent to the constructor from string with a base value hard-coded to 10 and a precision value hard-coded to zero (that is, the precision will be the default precision, if set).

Parameters
• s: the input string.

Exceptions
• unspecified: any exception thrown by the constructor from string, base and precision.

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

Constructor from range of characters, base and precision.

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

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.

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

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

Constructor from range of characters and precision.

This constructor is equivalent to the constructor from range of characters with a base value hard-coded to 10.

Parameters
• begin: the start of the input range.

• end: the end of the input range.

• p: the desired precision.

Exceptions
• unspecified: any exception thrown by the constructor from range of characters, base and precision.

real(const char *begin, const char *end)

Constructor from range of characters.

This constructor is equivalent to the constructor from range of characters with a base value hard-coded to 10 and a precision value hard-coded to zero (that is, the precision will be the default precision, if set).

Parameters
• begin: the start of the input range.

• end: the end of the input range.

Exceptions
• unspecified: any exception thrown by the constructor from range of characters, base and precision.

real(const mpfr_t x)

Copy constructor from 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 real_prec_min() and real_prec_max().

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

real(mpfr_t &&x)

Move constructor from 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 real_prec_min() and 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.

The destructor will free any resource held by the internal mpfr_t instance.

real &operator=(const real &other)

Copy assignment operator.

The operator will deep-copy other into this.

Return

a reference to this.

Parameters
• other: the real that will be copied into this.

real &operator=(real &&other)

Move assignment operator.

Return

a reference to this.

Parameters
• other: the real that will be moved into this.

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

Generic assignment operator.

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

The operator will first fetch the default precision dp via real_get_default_prec(). If dp is nonzero, then dp will be used as a new precision for this and a rounding operation might occurr during the assignment.

Otherwise, if dp is zero, the precision of this will be set according to the same heuristics described in the generic constructor.

Return

a reference to this.

Parameters
• x: the assignment argument.

Exceptions
• std::overflow_error: if an overflow occurs in the computation of the automatically-deduced precision.

template<StringType T>
real &operator=(const T &s)

Assignment from string.

This operator will set this to the value represented by the StringType s, which is interpreted as a floating-point number in base 10. The precision of this will be set to the value returned by real_get_default_prec(). If no default precision has been set, an error will be raised. If s is not a valid representation of a floating-point number in base 10, this will be set to NaN and an error will be raised.

Return

a reference to this.

Parameters
• s: the string that will be assigned to this.

Exceptions
• std::invalid_argument: if a default precision has not been set, or if s cannot be parsed as a floating-point value in base 10.

• unspecified: any exception thrown by memory allocation errors in standard containers.

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 real_prec_min() and real_prec_max().

Return

a reference to this.

Parameters
• x: the mpfr_t that will be copied.

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

Return

a reference to this.

Parameters
• x: the mpfr_t that will be moved.

real &set(const real &other)

Set to another real value.

This method 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 method is a thin wrapper around the mpfr_set() assignment function from the MPFR API.

Return

a reference to this.

Parameters
• other: the value to which this will be set.

template<RealInteroperable T>
real &set(const T &x)

Generic setter.

This method 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 method is a thin wrapper around various mpfr_set_*() assignment functions from the MPFR API.

Return

a reference to this.

Parameters
• x: the value to which this will be set.

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

Setter to string.

This method will set this to the value represented by the StringType 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 [2,62] range. Contrary to the assignment operator from string, the global default precision is ignored and the precision of the assignment is dictated by the precision of this. Consequently, the precision of this will not be altered by the assignment, and a rounding might occur, depending on the operands.

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 method is a thin wrapper around the mpfr_set_str() assignment function from the MPFR API.

Return

a reference to this.

Parameters
• s: the string to which this will be set.

• base: the base used in the string representation.

Exceptions
• std::invalid_argument: if s cannot be parsed as a floating-point value in base 10, 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.

Return

a reference to this.

Parameters
• begin: the start of the input range.

• end: the end of the input range.

• base: the base used in the string representation.

Exceptions
• 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 method 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 method 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.

Return

a reference to this.

Parameters
• x: the mpfr_t to which this will be set.

real &set_nan()

Set to NaN.

This setter will set this to NaN with an unspecified sign bit. The precision of this will not be altered.

Return

a reference to this.

real &set_inf(int sign = 0)

Set to infinity.

This setter will set this to infinity. The sign bit will be positive if sign is nonnegative, negative otherwise. The precision of this will not be altered.

Return

a reference to this.

Parameters
• sign: the sign of the infinity to which this will be set.

real &set_zero(int sign = 0)

Set to zero.

This setter will set this to zero. The sign bit will be positive if sign is nonnegative, negative otherwise. The precision of this will not be altered.

Return

a reference to this.

Parameters
• sign: the sign of the zero to which this will be set.

const mpfr_struct_t *get_mpfr_t() const

Const reference to the internal mpfr_t.

This method will return a const pointer to the internal MPFR structure used to represent the value of this. The returned object can be used as a const mpfr_t function parameter in the MPFR API.

Return

a const reference to the internal MPFR structure.

mpfr_struct_t *_get_mpfr_t()

Mutable reference to the internal mpfr_t.

This method will return a mutable pointer to the internal MPFR structure used to represent the value of this. The returned object can be used as an mpfr_t function parameter in the MPFR API.

Warning

When using this 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 real_prec_min() and real_prec_max(), and upon destruction a real object must contain a valid mpfr_t object.

Return

a mutable reference to the internal MPFR structure.

bool nan_p() const

Detect NaN.

Return

true if this is NaN, false otherwise.

bool inf_p() const

Detect infinity.

Return

true if this is an infinity, false otherwise.

bool number_p() const

Detect finite number.

Return

true if this is a finite number (i.e., not NaN or infinity), false otherwise.

bool zero_p() const

Detect zero.

Return

true if this is zero, false otherwise.

bool regular_p() const

Detect regular number.

Return

true if this is a regular number (i.e., not NaN, infinity or zero), false otherwise.

bool is_one() const

Detect one.

Return

true if this is exactly equal to 1, false otherwise.

int sgn() const

Detect sign.

Return

a positive value if this is positive, zero if this is zero, a negative value if this is negative.

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

Return

the sign bit of this.

mpfr_prec_t get_prec() const

Get the precision of this.

Return

the current precision (i.e., the number of binary digits in the significand) of this.

real &neg()

Negate in-place.

This method will set this to -this.

Return

a reference to this.

real &abs()

In-place absolute value.

This method will set this to its absolute value.

Return

a reference to this.

real &set_prec(mpfr_prec_t p)

Destructively set the precision.

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

Return

a reference to this.

Parameters
• p: the desired precision.

Exceptions

real &prec_round(mpfr_prec_t p)

Set the precision maintaining the current value.

This method 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 value will be preserved exactly.

Return

a reference to this.

Parameters
• p: the desired precision.

Exceptions

template<RealInteroperable T>
operator T() const

Generic conversion operator.

This operator will convert this to a RealInteroperable type. 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.

Return

this converted to T.

Exceptions
• 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<RealInteroperable T>
bool get(T &rop) const

Generic conversion method.

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

Return

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

Parameters
• rop: the variable which will store the result of the conversion.

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

Convert to string.

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

Return

this converted to a string.

Parameters
• base: the base to be used for the string representation.

Exceptions
• std::invalid_argument: if base is not in the [2,62] range.

• std::runtime_error: if the call to the mpfr_get_str() function of the MPFR API fails.

real &sqrt()

In-place square root.

This method will set this to its square root. The precision of this will not be altered.

Return

a reference to this.

real &rec_sqrt()

In-place reciprocal square root.

This method will set this to its reciprocal square root. The precision of this will not be altered.

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

Return

a reference to this.

real &cbrt()

In-place cubic root.

This method will set this to its cubic root. The precision of this will not be altered.

Return

a reference to this.

real &sin()

In-place sine.

This method will set this to its sine. The precision of this will not be altered.

Return

a reference to this.

real &cos()

In-place cosine.

This method will set this to its cosine. The precision of this will not be altered.

Return

a reference to this.

real &tan()

In-place tangent.

This method will set this to its tangent. The precision of this will not be altered.

Return

a reference to this.

real &sec()

In-place secant.

This method will set this to its secant. The precision of this will not be altered.

Return

a reference to this.

real &csc()

In-place cosecant.

This method will set this to its cosecant. The precision of this will not be altered.

Return

a reference to this.

real &cot()

In-place cotangent.

This method will set this to its cotangent. The precision of this will not be altered.

Return

a reference to this.

real &acos()

In-place arccosine.

This method will set this to its arccosine. The precision of this will not be altered.

Return

a reference to this.

real &asin()

In-place arcsine.

This method will set this to its arcsine. The precision of this will not be altered.

Return

a reference to this.

real &atan()

In-place arctangent.

This method will set this to its arctangent. The precision of this will not be altered.

Return

a reference to this.

real &cosh()

In-place hyperbolic cosine.

This method will set this to its hyperbolic cosine. The precision of this will not be altered.

Return

a reference to this.

real &sinh()

In-place hyperbolic sine.

This method will set this to its hyperbolic sine. The precision of this will not be altered.

Return

a reference to this.

real &tanh()

In-place hyperbolic tangent.

This method will set this to its hyperbolic tangent. The precision of this will not be altered.

Return

a reference to this.

real &sech()

In-place hyperbolic secant.

This method will set this to its hyperbolic secant. The precision of this will not be altered.

Return

a reference to this.

real &csch()

In-place hyperbolic cosecant.

This method will set this to its hyperbolic cosecant. The precision of this will not be altered.

Return

a reference to this.

real &coth()

In-place hyperbolic cotangent.

This method will set this to its hyperbolic cotangent. The precision of this will not be altered.

Return

a reference to this.

real &acosh()

In-place inverse hyperbolic cosine.

This method will set this to its inverse hyperbolic cosine. The precision of this will not be altered.

Return

a reference to this.

real &asinh()

In-place inverse hyperbolic sine.

This method will set this to its inverse hyperbolic sine. The precision of this will not be altered.

Return

a reference to this.

real &atanh()

In-place inverse hyperbolic tangent.

This method will set this to its inverse hyperbolic tangent. The precision of this will not be altered.

Return

a reference to this.

real &exp()

In-place exponential.

This method will set this to its exponential. The precision of this will not be altered.

Return

a reference to this.

real &exp2()

In-place base-2 exponential.

This method will set this to 2**this. The precision of this will not be altered.

Return

a reference to this.

real &exp10()

In-place base-10 exponential.

This method will set this to 10**this. The precision of this will not be altered.

Return

a reference to this.

real &expm1()

In-place exponential minus 1.

This method will set this to its exponential minus one. The precision of this will not be altered.

Return

a reference to this.

real &log()

In-place logarithm.

This method will set this to its logarithm. The precision of this will not be altered.

Return

a reference to this.

real &log2()

In-place base-2 logarithm.

This method will set this to its base-2 logarithm. The precision of this will not be altered.

Return

a reference to this.

real &log10()

In-place base-10 logarithm.

This method will set this to its base-10 logarithm. The precision of this will not be altered.

Return

a reference to this.

real &log1p()

In-place augmented logarithm.

This method will set this the logarithm of this + 1. The precision of this will not be altered.

Return

a reference to this.

real &gamma()

In-place Gamma function.

This method will set this to its Gamma function. The precision of this will not be altered.

Return

a reference to this.

real &lngamma()

In-place logarithm of the Gamma function.

This method will set this to the logarithm of its Gamma function. The precision of this will not be altered.

Return

a reference to this.

real &lgamma()

In-place logarithm of the absolute value of the Gamma function.

This method will set this to the logarithm of the absolute value of its Gamma function. The precision of this will not be altered.

Return

a reference to this.

real &digamma()

In-place Digamma function.

This method will set this to its Digamma function. The precision of this will not be altered.

Return

a reference to this.

real &j0()

In-place Bessel function of the first kind of order 0.

This method will set this to its Bessel function of the first kind of order 0. The precision of this will not be altered.

Return

a reference to this.

real &j1()

In-place Bessel function of the first kind of order 1.

This method will set this to its Bessel function of the first kind of order 1. The precision of this will not be altered.

Return

a reference to this.

real &y0()

In-place Bessel function of the second kind of order 0.

This method will set this to its Bessel function of the second kind of order 0. The precision of this will not be altered.

Return

a reference to this.

real &y1()

In-place Bessel function of the second kind of order 1.

This method will set this to its Bessel function of the second kind of order 1. The precision of this will not be altered.

Return

a reference to this.

real &eint()

In-place exponential integral.

This method will set this to its exponential integral. The precision of this will not be altered.

Return

a reference to this.

real &li2()

In-place dilogarithm.

This method will set this to its dilogarithm. The precision of this will not be altered.

Return

a reference to this.

real &zeta()

In-place Riemann Zeta function.

This method will set this to its Riemann Zeta function. The precision of this will not be altered.

Return

a reference to this.

real &erf()

In-place error function.

This method will set this to its error function. The precision of this will not be altered.

Return

a reference to this.

real &erfc()

In-place complementary error function.

This method will set this to its complementary error function. The precision of this will not be altered.

Return

a reference to this.

real &ai()

In-place Airy function.

This method will set this to its Airy function. The precision of this will not be altered.

Return

a reference to this.

bool integer_p() const

Check if the value is an integer.

Return

true if this represents an integer value, false otherwise.

real &trunc()

In-place truncation.

This method will set this to its truncated counterpart. The precision of this will not be altered.

Return

a reference to this.

Exceptions
• std::domain_error: if this represents a NaN value.

## Types¶

using mppp::mpfr_struct_t = std::remove_extent<mpfr_t>::type

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

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

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

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() method 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::RealOpTypes

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:

A corresponding boolean type trait called are_real_op_types is also available (even if the compiler does not support concepts).

template<typename T, typename U>
concept mppp::RealCompoundOpTypes

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 RealOpTypes and T, after the removal of reference, is not const.

## Functions¶

### Precision handling¶

constexpr mpfr_prec_t mppp::real_prec_min()

Minimum precision for a real.

This compile-time constant represents the minimum valid precision for a real. The returned value is guaranteed to be not less than the MPFR_PREC_MIN MPFR constant.

Return

the minimum valid precision for a real.

constexpr mpfr_prec_t mppp::real_prec_max()

Maximum precision for a real.

This compile-time constant represents the maximum valid precision for a real. The returned value is guaranteed to be not greater than the MPFR_PREC_MAX MPFR constant.

Return

the maximum valid precision for a real.

mpfr_prec_t mppp::real_get_default_prec()

Get the default precision for real objects.

This function returns the value of the precision used during the construction of real objects when an explicit precision value is not specified . On program startup, the value returned by this function is zero, meaning that the precision of a real object will be chosen automatically according to heuristics depending on the specific situation, if possible.

The default precision is stored in a global variable, and its value can be changed via real_set_default_prec(). It is safe to read and modify concurrently from multiple threads the default precision.

Return

the value of the default precision for real objects.

void mppp::real_set_default_prec(mpfr_prec_t p)

Set the default precision for real objects.

See real_get_default_prec() for an explanation of how the default precision value is used.

Parameters
• p: the desired value for the default precision for real objects.

Exceptions

void mppp::real_reset_default_prec()

Reset the default precision for real objects.

This function will reset the default precision value to zero (i.e., the same value assigned on program startup). See real_get_default_prec() for an explanation of how the default precision value is used.

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

Destructively set the precision of a real.

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

Parameters
• r: the real whose precision will be set.

• p: the desired precision.

Exceptions

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

Set the precision of a real maintaining the current value.

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

Parameters
• r: the real whose precision will be set.

• p: the desired precision.

Exceptions

mpfr_prec_t mppp::get_prec(const real &r)

Get the precision of a real.

Return

the precision of r.

Parameters
• r: the real whose precision will be returned.

### Assignment¶

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

Generic setter for real.

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

Return

a reference to r.

Parameters
• r: the real that will be set.

• args: the arguments that will be passed to mppp::real::set().

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

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

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

Return

a reference to r.

Parameters
• r: the real argument.

• n: the integer multiplier.

• e: the exponent.

real &mppp::set_nan(real &r)

Set real to NaN.

This function will set r to NaN with an unspecified sign bit. The precision of r will not be altered.

Return

a reference to r.

Parameters
• r: the real argument.

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

Set real to infinity.

This function will set r to infinity. The sign bit will be positive if sign is nonnegative, negative otherwise. The precision of r will not be altered.

Return

a reference to r.

Parameters
• r: the real argument.

• sign: the sign of the infinity to which r will be set.

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

Set real to zero.

This function will set r to zero. The sign bit will be positive if sign is nonnegative, negative otherwise. The precision of r will not be altered.

Return

a reference to r.

Parameters
• r: the real argument.

• sign: the sign of the zero to which r will be set.

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

Swap real objects.

This function will efficiently swap the content of a and b.

Parameters
• a: the first operand.

• b: the second operand.

### Conversion¶

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

Generic conversion function for real.

This function will convert the input real x to a RealInteroperable type, 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.

Return

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

Parameters
• rop: the variable which will store the result of the conversion.

• x: the input real.

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

Extract the significand and the exponent of a real.

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

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

Return

the exponent e such that r equals $$n\times 2^e$$.

Parameters
• n: the integer that will contain the scaled significand of r.

• r: the input real.

Exceptions
• std::domain_error: if r is not finite.

• std::overflow_error: if the output exponent is larger than an implementation-defined value.

### Arithmetic¶

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

This function will compute $$a+b$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

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

Ternary real subtraction.

This function will compute $$a-b$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

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

Ternary real multiplication.

This function will compute $$a \times b$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

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

Ternary real division.

This function will compute $$a / b$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

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

This function will compute $$a \times b + c$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

• c: the third operand.

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

This function will compute and return $$a \times b + c$$. The precision of the result will be set to the largest precision among the operands.

Return

$$a \times b + c$$.

Parameters
• a: the first operand.

• b: the second operand.

• c: the third operand.

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

Quaternary real fused multiply–sub.

This function will compute $$a \times b - c$$, storing the result in rop. The precision of the result will be set to the largest precision among the operands.

Return

a reference to rop.

Parameters
• rop: the return value.

• a: the first operand.

• b: the second operand.

• c: the third operand.

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

Ternary real fused multiply–sub.

This function will compute and return $$a \times b - c$$. The precision of the result will be set to the largest precision among the operands.

Return

$$a \times b - c$$.

Parameters
• a: the first operand.

• b: the second operand.

• c: the third operand.

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

Unary negation for real.

Return

the negative of x.

Parameters
• x: the real that will be negated.

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

Binary negation for real.

This function will set rop to the negation of x.

Return

a reference to rop.

Parameters
• rop: the real that will hold the result.

• x: the real that will be negated.

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

Unary absolute value for real.

Return

the absolute value of x.

Parameters
• x: the real whose absolute value will be computed.

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

Binary absolute value for real.

This function will set rop to the absolute value of x.

Return

a reference to rop.

Parameters
• rop: the real that will hold the result.

• x: the real whose absolute value will be computed.

### Comparison¶

bool mppp::nan_p(const real &r)

Detect if a real is NaN.

Return

true if r is NaN, false otherwise.

Parameters
• r: the real that will be examined.

bool mppp::inf_p(const real &r)

Detect if a real is infinity.

Return

true if r is an infinity, false otherwise.

Parameters
• r: the real that will be examined.

bool mppp::number_p(const real &r)

Detect if real is a finite number.

Return

true if r is a finite number (i.e., not NaN or infinity), false otherwise.

Parameters
• r: the real that will be examined.

bool mppp::zero_p(const real &r)

Detect if a real is zero.

Return

true if r is zero, false otherwise.

Parameters
• r: the real that will be examined.

bool mppp::regular_p(const real &r)

Detect if a real is a regular number.

Return

true if r is a regular number (i.e., not NaN, infinity or zero), false otherwise.

Parameters
• r: the real that will be examined.

bool mppp::is_one(const real &r)

Detect if a real is one.

Return

true if r is exactly 1, false otherwise.

Parameters
• r: the real to be checked.

int mppp::sgn(const real &r)

Detect the sign of a real.

Return

a positive value if r is positive, zero if r is zero, a negative value if this is negative.

Parameters
• r: the real that will be examined.

Exceptions

bool mppp::signbit(const real &r)

Get the sign bit of a real.

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

Return

the sign bit of r.

Parameters
• r: the real that will be examined.

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

Real comparison.

This function will compare a and b, returning:

• zero if a equals b,

• a negative value if a is less than b,

• a positive value if a is greater than 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.

Return

an integral value expressing how a compares to b.

Parameters
• a: the first operand.

• b: the second operand.

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

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

Equality predicate with special NaN handling for real.

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.

Return

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

Parameters
• a: the first operand.

• b: the second operand.

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

Less-than predicate with special NaN and moved-from handling for real.

This function behaves like a less-than operator which considers NaN values greater than non-NaN values, and moved-from objects greater than both NaN and non-NaN values. This function can be used as a comparator in various facilities of the standard library (e.g., std::sort(), std::set, etc.).

Return

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

Parameters
• a: the first operand.

• b: the second operand.

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

Greater-than predicate with special NaN and moved-from handling for real.

This function behaves like a greater-than operator which considers NaN values greater than non-NaN values, and moved-from objects greater than both NaN and non-NaN values. This function can be used as a comparator in various facilities of the standard library (e.g., std::sort(), std::set, etc.).

Return

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

Parameters
• a: the first operand.

• b: the second operand.

### Roots¶

template<mppp::CvrReal 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::CvrReal 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::CvrReal 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::CvrReal 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::CvrReal 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::CvrReal 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::CvrReal T>
mppp::real &mppp::rootn_ui(mppp::real &rop, T &&op, unsigned long k)

New in version 0.12.

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.

Note

This function is available from MPFR 4 onwards.

Parameters
• rop – the return value.

• op – the operand.

• k – the degree of the root.

Returns

a reference to rop.

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

New in version 0.12.

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.

Note

This function is available from MPFR 4 onwards.

Parameters
• r – the operand.

• k – the degree of the root.

Returns

the k-th root of r.

### Exponentiation¶

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

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

Return

a reference to rop.

Parameters
• rop: the return value.

• op1: the base.

• op2: the exponent.

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

Binary real exponentiation.

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Return

op1 raised to the power of op2.

Parameters
• op1: the base.

• op2: the exponent.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

### Trigonometry¶

template<mppp::CvrReal T>
mppp::real &mppp::sin(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::cos(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::tan(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::sec(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::csc(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::cot(mppp::real &rop, T &&op)

Binary basic trigonometric functions.

These functions will set rop to, respectively, the 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::CvrReal T>
mppp::real mppp::sin(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::cos(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::tan(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::sec(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::csc(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::cot(T &&r)

Unary basic trigonometric functions.

These functions will return, respectively, the 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 sine, cosine, tangent, secant, cosecant or cotangent of r.

template<mppp::CvrReal 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::CvrReal T>
mppp::real &mppp::asin(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::acos(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::asin(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::acos(T &&r)
template<mppp::CvrReal 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::CvrReal T, mppp::CvrReal 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::RealOpTypes<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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

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::CvrReal T>
mppp::real &mppp::sinh(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::cosh(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::tanh(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::sech(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::csch(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::sinh(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::cosh(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::tanh(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::sech(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::csch(T &&r)
template<mppp::CvrReal 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::CvrReal 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::CvrReal T>
mppp::real &mppp::asinh(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::acosh(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::asinh(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::acosh(T &&r)
template<mppp::CvrReal 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::CvrReal T>
mppp::real &mppp::exp(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::exp2(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::exp10(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::expm1(mppp::real &rop, T &&op)

Binary exponentials.

These functions will set rop to, respectively,

• e**op,

• 2**op,

• 10**op,

• e**op-1.

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

Parameters
• rop – the return value.

• op – the exponent.

Returns

a reference to rop.

template<mppp::CvrReal T>
mppp::real mppp::exp(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::exp2(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::exp10(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::expm1(T &&r)

Unary exponentials.

These functions will return, respectively,

• e**r,

• 2**r,

• 10**r,

• e**r-1.

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

Parameters

r – the exponent.

Returns

the exponential of r.

template<mppp::CvrReal T>
mppp::real &mppp::log(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::log2(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::log10(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::log1p(mppp::real &rop, T &&op)

Binary logarithms.

These functions will set rop to, respectively,

• log(op),

• log2(op),

• log10(op),

• log(1+op).

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::CvrReal T>
mppp::real mppp::log(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::log2(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::log10(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::log1p(T &&r)

Unary logarithms.

These functions will return, respectively,

• log(r),

• log2(r),

• log10(r),

• log(1+op).

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

Parameters

r – the operand.

Returns

the logarithm of r.

### Gamma functions¶

template<mppp::CvrReal T>
mppp::real &mppp::gamma(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::lngamma(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::lgamma(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::gamma(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::lngamma(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::lgamma(T &&r)
template<mppp::CvrReal 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::CvrReal T, mppp::CvrReal U>
mppp::real &mppp::gamma_inc(mppp::real &rop, T &&x, U &&y)

New in version 0.17.

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.

Note

This function is available from MPFR 4 onwards.

Parameters
• rop – the return value.

• x – the first argument.

• y – the second argument.

Returns

a reference to rop.

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

New in version 0.17.

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This function is available from MPFR 4 onwards.

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::CvrReal T>
mppp::real &mppp::j0(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::j1(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::jn(mppp::real &rop, long n, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::y0(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::y1(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::j0(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::j1(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::jn(long n, T &&r)
template<mppp::CvrReal T>
mppp::real mppp::y0(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::y1(T &&r)
template<mppp::CvrReal 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::CvrReal T>
mppp::real &mppp::erf(mppp::real &rop, T &&op)
template<mppp::CvrReal 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::CvrReal T>
mppp::real mppp::erf(T &&r)
template<mppp::CvrReal 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::CvrReal T>
mppp::real &mppp::eint(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::li2(mppp::real &rop, T &&op)
template<mppp::CvrReal T>
mppp::real &mppp::zeta(mppp::real &rop, T &&op)
template<mppp::CvrReal 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 dilogarithm,

• 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::CvrReal T>
mppp::real mppp::eint(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::li2(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::zeta(T &&r)
template<mppp::CvrReal T>
mppp::real mppp::ai(T &&r)

Other unary special functions.

These functions will return, respectively,

• the exponential integral,

• the dilogarithm,

• 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, dilogarithm, Riemann Zeta function or Airy function of r.

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

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.

Note

This function is available from MPFR 4 onwards.

Parameters
• rop – the return value.

• x – the first argument.

• y – the second argument.

Returns

a reference to rop.

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

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This function is available from MPFR 4 onwards.

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::CvrReal T, mppp::CvrReal 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::RealOpTypes<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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

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::CvrReal T, mppp::CvrReal 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::RealOpTypes<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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

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 real &r)

Output stream operator for real objects.

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.

Return

a reference to os.

Parameters
• os: the target stream.

• r: the real that will be directed to os.

Exceptions

## Mathematical operators¶

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

Identity operator for real.

This operator will return a copy of the input real r.

Return

a copy of r.

Parameters
• r: the real that will be copied.

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

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Return

$$a+b$$.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

If a is a real, then this operator is equivalent to the expression:

a = a + b;


Otherwise, this operator is equivalent to the expression:

a = static_cast<T>(a + b);


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

Return

a reference to a.

Parameters
• a: the augend.

• b: the addend.

Exceptions
• unspecified: any exception thrown by the corresponding binary operator, or by the generic conversion operator of real.

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

Prefix increment for real.

This operator will increment x by one.

Return

a reference to x after the increment.

Parameters
• x: the real that will be increased.

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

Suffix increment for real.

This operator will increment x by one and return a copy of x as it was before the increment.

Return

a copy of x before the increment.

Parameters
• x: the real that will be increased.

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

Negated copy for real.

This operator will return a negated copy of the input real r.

Return

a negated copy of r.

Parameters
• r: the real that will be negated.

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

Binary subtraction involving real.

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Return

$$a-b$$.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

In-place subtraction involving real.

If a is a real, then this operator is equivalent to the expression:

a = a - b;


Otherwise, this operator is equivalent to the expression:

a = static_cast<T>(a - b);


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

Return

a reference to a.

Parameters
• a: the minuend.

• b: the subtrahend.

Exceptions
• unspecified: any exception thrown by the corresponding binary operator, or by the generic conversion operator of real.

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

Prefix decrement for real.

This operator will decrement x by one.

Return

a reference to x after the decrement.

Parameters
• x: the real that will be decreased.

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

Suffix decrement for real.

This operator will decrement x by one and return a copy of x as it was before the decrement.

Return

a copy of x before the decrement.

Parameters
• x: the real that will be decreased.

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

Binary multiplication involving real.

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Return

$$a\times b$$.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

In-place multiplication involving real.

If a is a real, then this operator is equivalent to the expression:

a = a * b;


Otherwise, this operator is equivalent to the expression:

a = static_cast<T>(a * b);


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

Return

a reference to a.

Parameters
• a: the multiplicand.

• b: the multiplicator.

Exceptions
• unspecified: any exception thrown by the corresponding binary operator, or by the generic conversion operator of real.

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

Binary division involving real.

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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Return

$$a / b$$.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

In-place division involving real.

If a is a real, then this operator is equivalent to the expression:

a = a / b;


Otherwise, this operator is equivalent to the expression:

a = static_cast<T>(a / b);


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

Return

a reference to a.

Parameters
• a: the dividend.

• b: the divisor.

Exceptions
• unspecified: any exception thrown by the corresponding binary operator, or by the generic conversion operator of real.

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

Equality operator involving real.

This operator will compare a and b, returning true if a is equal to b, false otherwise. The comparison is performed via the mpfr_equal_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN compares different from any value, including NaN itself). See mppp::real_equal_to() for an equality predicate that handles NaN specially.

Return

true if a is equal to b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

Inequality operator involving real.

This operator will compare a and b, returning true if a is different from b, false otherwise. The comparison is performed via the mpfr_equal_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN compares different from any value, including NaN itself). See mppp::real_equal_to() for an equality predicate that handles NaN specially.

Return

true if a is different from b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

Greater-than operator involving real.

This operator will compare a and b, returning true if a is greater than b, false otherwise. The comparison is performed via the mpfr_greater_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN is never greater than any value, and no value is greater than NaN). See mppp::real_gt() for a greater-than predicate that handles NaN specially.

Return

true if a is greater than b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

Greater-than or equal operator involving real.

This operator will compare a and b, returning true if a is greater than or equal to b, false otherwise. The comparison is performed via the mpfr_greaterequal_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN is never greater than or equal to any value, and no value is greater than or equal to NaN).

Return

true if a is greater than or equal to b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

Less-than operator involving real.

This operator will compare a and b, returning true if a is less than b, false otherwise. The comparison is performed via the mpfr_less_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN is never less than any value, and no value is less than NaN). See mppp::real_lt() for a less-than predicate that handles NaN specially.

Return

true if a is less than b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

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

Less-than or equal operator involving real.

This operator will compare a and b, returning true if a is less than or equal to b, false otherwise. The comparison is performed via the mpfr_lessequal_p() function from the MPFR API. 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. Specifically, the precision of the conversion is either the default precision, if set, or it is automatically deduced depending on the type and value of the operand to be converted.

Note

This operator does not handle NaN in a special way (that is, NaN is never less than or equal to any value, and no value is less than or equal to NaN).

Return

true if a is less than or equal to b, false otherwise.

Parameters
• a: the first operand.

• b: the second operand.

Exceptions
• unspecified: any exception thrown by the generic assignment operator of real.

## Constants¶

real mppp::real_pi(mpfr_prec_t p = 0)

Real $$\pi$$ constant.

This function will return a real $$\pi$$ with a precision of p. If p is zero, the precision will be set to the value returned by real_get_default_prec(). If p is zero and no default precision has been set, an error will be raised.

Return

a real $$\pi$$.

Parameters
• p: the desired precision.

Exceptions
• std::invalid_argument: if p is not within the bounds established by real_prec_min() and real_prec_max(), or if p is zero but no default precision has been set.

real &mppp::real_pi(real &rop)

Set real to $$\pi$$.

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

Return

a reference to rop.

Parameters
• rop: the real that will be set to $$\pi$$.