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 floating-point C++ type whose precision is a runtime property of the class instances rather than a compile-time property of the type. Because of this, the way precision is handled inreal
differs from the way it is managed in MPFR. The most important difference is that in operations involvingreal
the precision of the result is usually determined by the precision of the operands, whereas in MPFR the precision of the operation is determined by the precision of the return value (which is always passed as the first function parameter in the MPFR API). For instance, in the following code,auto x = real{5, 200} + real{6, 150};
the first operand has a value of 5 and precision of 200 bits, while the second operand has a value of 6 and precision 150 bits. The precision of the result
x
will be the maximum precision among the two operands, that is, 200 bits.The precision of a
real
can be set at construction, or it can be changed later via functions such asmppp::real::set_prec()
,mppp::real::prec_round()
, etc. By default, the precision of areal
is automatically deduced upon construction following a set of heuristics aimed at ensuring that the constructedreal
preserves the value used for initialisation, if possible. For instance, by default the construction of areal
from a 32 bit integer will yield areal
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 callmpfr_add(rop, a, b, MPFR_RNDN);
that writes the result of
a + b
, rounded to nearest, intorop
, becomes simplyadd(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, thereal
API always rounds to nearest (that is, theMPFR_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 (seemppp::real::get_mpfr_t()
andmppp::real::_get_mpfr_t()
), so that it is possible to use transparently the MPFR API withreal
objects.The
real
class supports a simple binary serialisation API, through member functions such asbinary_save()
andbinary_load()
, and the corresponding free function overloads.A tutorial showcasing various features of
real
is available.-
real()#
Default constructor.
The value will be initialised to positive zero, the precision will be the value returned by
mppp::real_prec_min()
.
-
real(real &&other) noexcept#
Copy and move constructors.
The copy constructor performs an exact deep copy of the input object.
After move construction, the only valid operations on other are destruction, copy/move assignment and the invocation of the
is_valid()
member function. After re-assignment, other can be used normally again.- Parameters:
other – the construction argument.
-
explicit real(const real &other, mpfr_prec_t p)#
-
explicit real(real &&other, mpfr_prec_t p)#
Copy/move constructors with custom precision.
These constructors will set
this
to the value of other with precision p. If p is smaller than the precision of other, a rounding operation will be performed, otherwise the value will be copied exactly.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.New in version 0.20: The move overload.
- Parameters:
other – the construction argument.
p – the desired precision.
- Throws:
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::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 themppp::real_kind
enum. The precision ofthis
will be p.If k is not NaN, the sign bit will be set to positive if sign is nonnegative, negative otherwise.
The second overload invokes the first one with a sign of zero.
If k is not one of
nan
,inf
orzero
, an error will be raised.- Parameters:
k – the desired special value.
sign – the desired sign for
this
.p – the desired precision for
this
.
- Throws:
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::real_prec_max()
, or k is an invalid enumerator.
-
template<std::size_t SSize>
explicit real(const integer<SSize> &n, mpfr_exp_t e, mpfr_prec_t p)#
-
explicit real(unsigned long n, mpfr_exp_t e, mpfr_prec_t p)#
-
explicit real(long n, mpfr_exp_t e, mpfr_prec_t p)#
New in version 0.20.
Constructors from an integral multiple of a power of two.
These constructors will set
this
to \(n\times 2^e\) with a precision of p.- Parameters:
n – the integral multiple.
e – the power of 2.
p – the desired precision.
- Throws:
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::real_prec_max()
.
-
template<real_interoperable T>
real(const T &x)#
-
template<real_interoperable T>
explicit real(const T &x, mpfr_prec_t p)# Generic constructors.
The generic constructors will set
this
to the value of x.The variant with the p argument will set the precision of
this
exactly to p.The variant without the p argument will set the precision of
this
according to the following heuristics:if x is an integral C++ type
I
, then the precision is set to the bit width ofI
;if x is a floating-point C++ type
F
, then the precision is set to the number of binary digits in the significand ofF
;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 forinteger
);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 initialisethis
to 1 fortrue
, and 0 forfalse
.- 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()
andmppp::real_prec_max()
.
-
template<cpp_complex T>
explicit real(const T &c)#
-
template<cpp_complex T>
explicit real(const T &c, mpfr_prec_t p)# New in version 0.20.
Constructors from complex C++ types.
These constructors will set
this
to the real part of c. If the imaginary part of c is not zero, an error will be raised.The precision of
this
will be set exactly to p, if provided. Otherwise, the precision will be set following the same heuristics explained in the generic constructor for the real-valued floating-point type underlyingT
.- Parameters:
c – the construction argument.
p – the desired precision.
- Throws:
std::domain_error – if the imaginary part of c is not zero.
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::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 thestring_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 functionmpfr_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 basebase
.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()
andmppp::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()
andmppp::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 bythis
, which will take care of releasing them when the destructor is called.Note
Due to a compiler bug, this constructor is not available on Microsoft Visual Studio.
- Parameters:
x – the
mpfr_t
that will be moved.
-
~real()#
Destructor.
The destructor will run sanity checks in debug mode.
-
real &operator=(real &&other) noexcept#
Copy and move assignment operators.
- Parameters:
other – the assignment argument.
- Returns:
a reference to
this
.
-
template<real_interoperable T>
real &operator=(const T &x)# The generic assignment operator will set
this
to the value of x.The precision of
this
will be set according to the same heuristics described in the generic constructor.- Parameters:
x – the assignment argument.
- Returns:
a reference to
this
.- Throws:
std::overflow_error – if an overflow occurs in the computation of the automatically-deduced precision.
-
template<cpp_complex T>
real &operator=(const T &c)# New in version 0.20.
Assignment from complex C++ types.
This operator will first attempt to convert c to
real
, and it will then assign the result of the conversion tothis
.- Parameters:
c – the assignment argument.
- Returns:
a reference to
this
.- Throws:
unspecified – any exception thrown by the conversion of c to
real
.
-
real &operator=(const complex128 &x)#
-
real &operator=(const complex &x)#
Note
The
complex128
overload is available only if mp++ was configured with theMPPP_WITH_QUADMATH
option enabled. Thecomplex
overload is available only if mp++ was configured with theMPPP_WITH_MPC
option enabled.New in version 0.20.
Assignment operators from other mp++ classes.
These operators are formally equivalent to converting x to
real
and then move-assigning the result tothis
.- Parameters:
x – the assignment argument.
- Returns:
a reference to
this
.- Throws:
unspecified – any exception raised by the conversion of x to
real
.
-
real &operator=(const mpfr_t x)#
Copy assignment from
mpfr_t
.This operator will set
this
to a deep copy of x.Warning
It is the user’s responsibility to ensure that x has been correctly initialised with a precision within the bounds established by
mppp::real_prec_min()
andmppp::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()
andmppp::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 bythis
, which will take care of releasing them when the destructor is called.Note
Due to a compiler bug, this operator is not available on Microsoft Visual Studio.
- Parameters:
x – the assignment argument.
- Returns:
a reference to
this
.
-
bool is_valid() const noexcept#
Check validity.
A
real
becomes invalid after it is used as an argument to the move constructor.- Returns:
true
ifthis
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 ofthis
, rather than the precision of other. Consequently, the precision ofthis
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 ofthis
, rather than being deduced from the type and value of x. Consequently, the precision ofthis
will not be altered by the assignment, and a rounding might occur, depending on the operands.This function is a thin wrapper around various
mpfr_set_*()
assignment functions from the MPFR API.- Parameters:
x – the value to which
this
will be set.- Returns:
a reference to
this
.
-
template<cpp_complex T>
real &set(const T &c)# New in version 0.20.
Setter to complex C++ types.
This member function will set
this
to the value of c. Contrary to the generic assignment operator, the precision of the assignment is dictated by the precision ofthis
, rather than being deduced from the type and value of c. Consequently, the precision ofthis
will not be altered by the assignment, and a rounding might occur, depending on the operands.If the imaginary part of c is not zero, an error will be raised.
- Parameters:
c – the value to which
this
will be set.- Returns:
a reference to
this
.- Throws:
std::domain_error – if the imaginary part of c is not zero.
-
template<string_type T>
real &set(const T &s, int base = 10)# Setter to string.
This member function will set
this
to the value represented by s, which will be interpreted as a floating-point number in base base. base must be either 0 (in which case the base is automatically deduced), or a value in the \(\left[ 2,62 \right]\) range. The precision of the assignment is dictated by the precision ofthis
, 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 ofthis
, rather than the precision of x. Consequently, the precision ofthis
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_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 bymppp::real_prec_min()
andmppp::real_prec_max()
, and upon destruction areal
object must contain a validmpfr_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
ifthis
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 ifthis
is zero, a negative value ifthis
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 ofthis
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()
andmppp::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 ofthis
, 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()
andmppp::real_prec_max()
.
-
std::size_t get_nlimbs() const#
New in version 0.27.
Get the number of limbs.
- Returns:
the number of multiprecision limbs (of type
mp_limb_t
) necessary to represent the significand ofthis
.
-
template<real_interoperable T>
explicit operator T() const# Generic conversion operator.
This operator will convert
this
toT
. The conversion proceeds as follows:if
T
isbool
, then the conversion returnsfalse
ifthis
is zero,true
otherwise (including ifthis
is NaN);if
T
is an integral C++ type other thanbool
, the conversion will yield the truncated counterpart ofthis
(i.e., the conversion rounds to zero). The conversion may fail due to overflow or domain errors (i.e., when trying to convert non-finite values);if
T
if a floating-point C++ type, the conversion calls directly the low-level MPFR functions (e.g.,mpfr_get_d()
), and might yield infinities for finite input values;if
T
isinteger
, the conversion rounds to zero and might fail due to domain errors, but it will never overflow;if
T
isrational
, the conversion may fail ifthis
is not finite or if the conversion produces an overflow in the manipulation of the exponent ofthis
(that is, if the absolute value ofthis
is very large or very small). If the conversion succeeds, it will be exact;if
T
isreal128
, the conversion might yield infinities for finite input values.
- Returns:
this
converted toT
.- Throws:
std::domain_error – if
this
is not finite and the target type cannot represent non-finite numbers.std::overflow_error – if the conversion results in overflow.
-
template<cpp_complex T>
explicit operator T() const# New in version 0.20.
Conversion to complex C++ types.
The real part of the return value is constructed by converting
this
to the value type ofT
. The imaginary part of the return value is set to zero.- Returns:
this
converted toT
.
-
template<real_interoperable T>
bool get(T &rop) const# Generic conversion function.
This member function, similarly to the conversion operator, will convert
this
toT
, 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 returntrue
, otherwise the function will returnfalse
. If the conversion fails, rop will not be altered.- Parameters:
rop – the variable which will store the result of the conversion.
- Returns:
true
if the conversion succeeded,false
otherwise. The conversion can fail in the ways specified in the documentation of the conversion operator.
-
template<cpp_complex T>
bool get(T &rop) const# New in version 0.20.
Conversion function to complex C++ types.
The conversion is always successful.
- Parameters:
rop – the variable which will store the result of the conversion.
- Returns:
true
.
-
std::string to_string(int base = 10) const#
Conversion to string.
This member function will convert
this
to a string representation in base base. The returned string is guaranteed to produce exactly the original value when used in one of the constructors from string ofreal
(provided that the original precision and base are used in the construction).- Parameters:
base – the base to be used for the string representation.
- Returns:
this
converted to a string.- Throws:
std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.
std::runtime_error – if the call to the
mpfr_get_str()
function of the MPFR API fails.
-
std::size_t get_str_ndigits(int base = 10) const#
New in version 0.25.
Note
This function is available from MPFR 4.1 onwards.
Minimum number of digits necessary for round-tripping.
This member function will return the minimum number of digits necessary to ensure that the current value of
this
can be recovered exactly from a string representation in the given base.- Parameters:
base – the base to be used for the string representation.
- Returns:
the minimum number of digits necessary for round-tripping.
- Throws:
std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.
-
real &cbrt()#
Note
The
sqrt1pm1()
function is available only if mp++ was configured with theMPPP_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()
andcbrt()
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 &sinc_pi()#
Note
The
sin_pi()
,cos_pi()
,tan_pi()
,cot_pi()
,sinc()
andsinc_pi()
functions are available only if mp++ was configured with theMPPP_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
.- Returns:
a reference to
this
.- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
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 &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 &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 &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 &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 &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 &lambert_wm1()#
Note
The
lambert_w0()
andlambert_wm1()
functions are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Other special functions, in-place variants.
These member functions will set
this
to, respectively:\(\operatorname{Ei}\left( x \right)\),
\(\operatorname{Li}_2\left( x \right)\),
\(\zeta\left( x \right)\),
\(\operatorname{erf}\left( x \right)\),
\(\operatorname{erfc}\left( x \right)\),
\(\operatorname{Ai}\left( x \right)\),
the Lambert W functions \(W_0\left( x \right)\) and \(W_{-1}\left( x \right)\),
where \(x\) is the current value of
this
.New in version 0.24: The
lambert_w0()
andlambert_wm1()
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 &frac()#
Note
The
roundeven()
function is available from MPFR 4 onwards.In-place integer and remainder-related functions.
These member functions will set
this
to, respectively:\(\left\lceil x \right\rceil\),
\(\left\lfloor x \right\rfloor\),
x rounded to nearest (IEEE
roundTiesToAway
mode),x rounded to nearest (IEEE
roundTiesToEven
mode),\(\operatorname{trunc}\left( x \right)\),
the fractional part of x,
where \(x\) is the current value of
this
.New in version 0.21: The
ceil()
,floor()
,round()
,roundeven()
andfrac()
functions.- Returns:
a reference to
this
.- Throws:
std::domain_error – if
this
represents a NaN value.
-
std::size_t binary_size() const#
New in version 0.22.
Size of the serialised binary representation.
This member function will return a value representing the number of bytes necessary to serialise
this
into a memory buffer in binary format via one of the availablebinary_save()
overloads. The returned value is platform-dependent.- Returns:
the number of bytes needed for the binary serialisation of
this
.- Throws:
std::overflow_error – if the size in limbs of
this
is larger than an implementation-defined limit.
-
std::size_t binary_save(char *dest) const#
-
std::size_t binary_save(std::vector<char> &dest) const#
-
std::size_t binary_save(std::ostream &dest) const#
New in version 0.22.
Serialise into a memory buffer or an output stream.
These member functions will write into dest a binary representation of
this
. The serialised representation produced by these member functions can be read back with one of thebinary_load()
overloads.For the first overload, dest must point to a memory area whose size is at least equal to the value returned by
binary_size()
, otherwise the behaviour will be undefined. dest does not have any special alignment requirements.For the second overload, the size of dest must be at least equal to the value returned by
binary_size()
. If that is not the case, dest will be resized tobinary_size()
.For the third overload, the size of dest must be at least equal to the value returned by
binary_size()
. If that is not the case, no data will be written to dest and zero will be returned.For the fourth overload, if the serialisation is successful (that is, no stream error state is ever detected in dest after write operations), then the binary size of
this
(that is, the number of bytes written into dest) will be returned. Otherwise, zero will be returned. Note that a return value of zero does not necessarily imply that no bytes were written into dest, just that an error occurred at some point during the serialisation process.Warning
The binary representation produced by these member functions is compiler, platform and architecture specific, and it is subject to possible breaking changes in future versions of mp++. Thus, it should not be used as an exchange format or for long-term data storage.
- Parameters:
dest – the output buffer or stream.
- Returns:
the number of bytes written into
dest
(i.e., the output ofbinary_size()
, if the serialisation was successful).- Throws:
std::overflow_error – in case of (unlikely) overflow errors.
unspecified – any exception thrown by
binary_size()
, by memory errors in standard containers, or by the public interface ofstd::ostream
.
-
std::size_t binary_load(const char *src)#
-
std::size_t binary_load(const std::vector<char> &src)#
-
std::size_t binary_load(std::istream &src)#
New in version 0.22.
Deserialise from a memory buffer or an input stream.
These member functions will load into
this
the content of the memory buffer or input stream src, which must contain the serialised representation of areal
produced by one of thebinary_save()
overloads.For the first overload, src does not have any special alignment requirements.
For the second and third overloads, the serialised representation of the
real
must start at the beginning of src, but it can end before the end of src. Data past the end of the serialised representation of thereal
will be ignored.For the fourth overload, the serialised representation of the
real
must start at the current position of src, but src can contain other data before and after the serialisedreal
value. Data past the end of the serialised representation of thereal
will be ignored. If a stream error state is detected at any point of the deserialisation process after a read operation, zero will be returned andthis
will not have been modified. Note that a return value of zero does not necessarily imply that no bytes were read from src, just that an error occurred at some point during the serialisation process.Warning
Although these member functions perform a few consistency checks on the data in src, they cannot ensure complete safety against maliciously-crafted data. Users are advised to use these member functions only with trusted data.
- Parameters:
src – the source memory buffer or stream.
- Returns:
the number of bytes read from src (that is, the output of
binary_size()
after the deserialisation intothis
has successfully completed).- Throws:
std::overflow_error – in case of (unlikely) overflow errors.
std::invalid_argument – if invalid data is detected in src.
unspecified – any exception thrown by memory errors in standard containers, the public interface of
std::istream
,binary_size()
orset_prec()
.
-
real()#
Types#
-
type mpfr_t#
This is the type used by the MPFR library to represent multiprecision floats. It is defined as an array of size 1 of an unspecified structure (see
mpfr_struct_t
).
-
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.
Concepts#
-
template<typename T>
concept mppp::cvr_real# This concept is satisfied if the type
T
, after the removal of reference and cv qualifiers, is the same asmppp::real
.
-
template<typename T>
concept mppp::real_interoperable# This concept is satisfied if the type
T
can interoperate withreal
. Specifically, this concept will betrue
ifT
is either:a
cpp_arithmetic
type, oran
integer
, ora
rational
, or
-
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 themppp::real::set()
member function overloads. In other words, this concept is satisfied if the expressionr.set(x, y, z, ...);
is valid (where
r
is a non-constreal
andx
,y
,z
, etc. are const references to the types inArgs
).
-
template<typename T, typename U>
concept mppp::real_op_types# This concept is satisfied if the types
T
andU
are suitable for use in the generic binary operators and functions involvingreal
. Specifically, the concept will betrue
if either:T
andU
both satisfycvr_real
,one type satisfies
cvr_real
and the other type, after the removal of reference and cv qualifiers, satisfiesreal_interoperable
.
-
template<typename T, typename U>
concept mppp::real_in_place_op_types# This concept is satisfied if the types
T
andU
are suitable for use in the generic in-place operators involvingreal
. Specifically, the concept will betrue
ifT
andU
satisfyreal_op_types
andT
, after the removal of reference, is not const.
-
template<typename T, typename U>
concept mppp::real_eq_op_types# New in version 0.20.
This concept is satisfied if the types
T
andU
are suitable for use in the generic binary equality and inequality operators involvingreal
and other types. Specifically, the concept will betrue
if either:T
andU
satisfyreal_op_types
, orone type is
real
and the other is acpp_complex
type.
Functions#
Precision handling#
-
mpfr_prec_t mppp::get_prec(const mppp::real &r)#
Get the precision of a
real
.- Parameters:
r – the input argument.
- Returns:
the precision of r.
-
void mppp::set_prec(mppp::real &r, mpfr_prec_t p)#
-
void mppp::prec_round(mppp::real &r, mpfr_prec_t p)#
Set the precision of a
real
.The first variant will set the precision of r to exactly p bits. The value of r will be set to NaN.
The second variant will preserve the current value of r, performing a rounding operation if p is less than the current precision of r.
- Parameters:
r – the input argument.
p – the desired precision.
- Throws:
unspecified – any exception thrown by
mppp::real::set_prec()
ormppp::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 theMPFR_PREC_MIN
MPFR constant and not greater than theMPFR_PREC_MAX
MPFR constant.- Returns:
the minimum/maximum valid precisions for a
real
.
-
std::size_t mppp::get_nlimbs(const mppp::real &r)#
New in version 0.27.
Get the number of limbs of a
real
.- Parameters:
r – the input argument.
- Returns:
the number of multiprecision limbs (of type
mp_limb_t
) necessary to represent the significand of r.
-
std::size_t mppp::prec_to_nlimbs(mpfr_prec_t p)#
New in version 0.27.
Convert a precision value into a number of limbs.
- Parameters:
p – the input precision value.
- Returns:
the number of multiprecision limbs (of type
mp_limb_t
) necessary to represent the significand of areal
with p bits of precision.- Throws:
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::real_prec_max()
.
Assignment#
-
template<mppp::real_set_args... Args>
mppp::real &mppp::set(mppp::real &r, const Args&... args)# Generic setter.
This function will use the arguments args to set the value of the
real
r, using one of the availablemppp::real::set()
overloads. That is, the body of this function is equivalent toreturn r.set(args...);
The input arguments must satisfy the
mppp::real_set_args
concept.- Parameters:
r – the return value.
args – the arguments that will be passed to
mppp::real::set()
.
- Returns:
a reference to r.
- Throws:
unspecified – any exception thrown by the invoked
mppp::real::set()
overload.
-
mppp::real &mppp::set_ui_2exp(mppp::real &r, unsigned long n, mpfr_exp_t e)#
-
mppp::real &mppp::set_si_2exp(mppp::real &r, long n, mpfr_exp_t e)#
-
template<std::size_t SSize>
mppp::real &mppp::set_z_2exp(mppp::real &r, const mppp::integer<SSize> &n, mpfr_exp_t e)# Set to \(n\times 2^e\).
These functions will set r to \(n\times 2^e\). The precision of r will not be altered. If n is zero, the result will be positive zero.
New in version 0.20: The
set_ui_2exp()
andset_si_2exp()
functions.- Parameters:
r – the return value.
n – the input integer multiplier.
e – the exponent.
- Returns:
a reference to r.
-
mppp::real &mppp::set_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.
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 toT
, storing the result of the conversion into rop. If the conversion is successful, the function will returntrue
, otherwise the function will returnfalse
. If the conversion fails, rop will not be altered.- Parameters:
rop – the variable which will store the result of the conversion.
x – the input argument.
- Returns:
true
if the conversion succeeded,false
otherwise. The conversion can fail in the ways specified in the documentation of the conversion operator forreal
.
-
template<mppp::cpp_complex T>
bool mppp::get(T &rop, const mppp::real &x)# New in version 0.20.
Conversion to complex C++ types.
The conversion is always successful.
- Parameters:
rop – the variable which will store the result of the conversion.
x – the input argument.
- Returns:
true
.
-
template<std::size_t SSize>
mpfr_exp_t mppp::get_z_2exp(mppp::integer<SSize> &n, const mppp::real &r)# Extract significand and exponent.
This function will extract the scaled significand of r into n, and return the exponent e such that \(r = n\times 2^e\).
If r is not finite, an error will be raised.
- Parameters:
n – the
integer
that will contain the scaled significand of r.r – the input argument.
- Returns:
the exponent e such that \(r = n\times 2^e\).
- Throws:
std::domain_error – if r is not finite.
std::overflow_error – if the output exponent is larger than an implementation-defined value.
-
std::size_t mppp::get_str_ndigits(const mppp::real &r, int base = 10)#
New in version 0.25.
Note
This function is available from MPFR 4.1 onwards.
Minimum number of digits necessary for round-tripping.
This member function will return the minimum number of digits necessary to ensure that the current value of r can be recovered exactly from a string representation in the given base.
- Parameters:
r – the input value.
base – the base to be used for the string representation.
- Returns:
the minimum number of digits necessary for round-tripping.
- Throws:
std::invalid_argument – if base is not in the \(\left[ 2,62 \right]\) range.
Arithmetic#
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::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::fabs(mppp::real &rop, T &&x)# Binary
real
absolute value.These functions will set rop to \(\left| x \right|\). The precision of the result will be equal to the precision of x.
New in version 0.27: The
fabs()
overload.- Parameters:
rop – the return value.
x – the operand.
- Returns:
a reference to rop.
-
template<mppp::cvr_real T>
mppp::real mppp::fabs(T &&x)# Unary
real
absolute value.These functions will return \(\left| x \right|\). The precision of the result will be equal to the precision of x.
New in version 0.27: The
fabs()
overload.- Parameters:
x – the operand.
- Returns:
\(\left| x \right|\).
-
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 multiplication/division by powers of 2.These functions will set rop to, respectively:
\(x \times 2^n\) (
mul_2
variants),\(\frac{x}{2^n}\) (
div_2
variants).
The precision of the result will be equal to the precision of x.
- Parameters:
rop – the return value.
x – the operand.
n – the power of 2.
- Returns:
a reference to rop.
-
template<mppp::cvr_real T>
mppp::real mppp::div_2si(T &&x, long n)# New in version 0.19.
Binary
real
primitives for multiplication/division by powers of 2.These functions will return, respectively:
\(x \times 2^n\) (
mul_2
variants),\(\frac{x}{2^n}\) (
div_2
variants).
The precision of the result will be equal to the precision of x.
- Parameters:
x – the operand.
n – the power of 2.
- Returns:
x multiplied/divided by \(2^n\).
-
template<mppp::cvr_real T>
mppp::real &mppp::sqr(mppp::real &rop, T &&op)# 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.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::dim(mppp::real &rop, T &&x, U &&y)# New in version 0.21.
Ternary positive difference.
This function will set rop to the positive difference of x and y. The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
x – the first operand.
y – the second operand.
- Returns:
a reference to rop.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::dim(T &&x, U &&y)# New in version 0.21.
Binary positive difference.
This function will compute and return the positive difference of x and y. The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first operand.
y – the second operand.
- Returns:
the positive difference of x and y.
Comparison#
-
bool mppp::is_one(const mppp::real &r)#
Detect special values.
These functions will return
true
if r is, respectively:NaN (
nan_p()
andisnan()
),an infinity (
inf_p()
andisinf()
),a finite number (
number_p()
andisfinite()
),zero (
zero_p()
),a regular number (i.e., not NaN, infinity or zero) (
regular_p()
),an integral value (
integer_p()
),one (
is_one()
),
false
otherwise.New in version 0.27: The
isnan()
,isinf()
andisfinite()
overloads.- Parameters:
r – the input argument.
- Returns:
the result of the detection.
-
bool mppp::signbit(const mppp::real &r)#
Detect sign or sign bit.
The sign is returned as a positive value if r is positive, zero if r is zero, a negative value if r is negative.
The sign bit is
true
if r is negative, -0, or a NaN whose representation has its sign bit set,false
otherwise.- Parameters:
r – the input argument.
- Returns:
the sign or sign bit of r.
- Throws:
unspecified – any exception raised by
mppp::real::sgn()
.
-
int mppp::cmp(const mppp::real &a, const mppp::real &b)#
Three-way comparison.
This function will compare a and b, returning:
zero if \(a=b\),
a negative value if \(a<b\),
a positive value if \(a>b\).
If at least one NaN value is involved in the comparison, an error will be raised.
This function is useful to distinguish the three possible cases. The comparison operators are recommended instead if it is needed to distinguish only two cases.
- Parameters:
a – the first operand.
b – the second operand.
- Returns:
an integral value expressing how a compares to b.
- Throws:
std::domain_error – if at least one of the operands is NaN.
-
int mppp::cmpabs(const mppp::real &a, const mppp::real &b)#
New in version 0.20.
Three-way comparison of absolute values.
This function will compare a and b, returning:
zero if \(\left|a\right|=\left|b\right|\),
a negative value if \(\left|a\right|<\left|b\right|\),
a positive value if \(\left|a\right|>\left|b\right|\).
If at least one NaN value is involved in the comparison, an error will be raised.
- Parameters:
a – the first operand.
b – the second operand.
- Returns:
an integral value expressing how the absolute values of a and b compare.
- Throws:
std::domain_error – if at least one of the operands is NaN.
-
int mppp::cmp_ui_2exp(const mppp::real &a, unsigned long n, mpfr_exp_t e)#
-
int mppp::cmp_si_2exp(const mppp::real &a, long n, mpfr_exp_t e)#
New in version 0.20.
Comparison with integral multiples of powers of 2.
This function will compare a to \(n\times 2^e\), returning:
zero if \(a=n\times 2^e\),
a negative value if \(a<n\times 2^e\),
a positive value if \(a>n\times 2^e\).
If a is NaN, an error will be raised.
- Parameters:
a – the first operand.
n – the integral multiplier.
e – the power of 2.
- Returns:
an integral value expressing how a compares to \(n\times 2^e\).
- Throws:
std::domain_error – if a is NaN.
-
bool mppp::real_equal_to(const mppp::real &a, const mppp::real &b)#
Equality predicate with special handling for NaN.
If both a and b are not NaN, this function is identical to the equality operator for
real
. If at least one operand is NaN, this function will returntrue
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_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.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.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.
- Parameters:
op1 – the base.
op2 – the exponent.
- Returns:
op1 raised to the power of op2.
Trigonometry#
-
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()
andsinc_pi()
are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Binary basic trigonometric functions.
These functions will set rop to, respectively:
\(\sin\left( x \right)\),
\(\cos\left( x \right)\),
\(\tan\left( x \right)\),
\(\sec\left( x \right)\),
\(\csc\left( x \right)\),
\(\cot\left( x \right)\),
\(\sin\left( \pi x \right)\),
\(\cos\left( \pi x \right)\),
\(\tan\left( \pi x \right)\),
\(\cot\left( \pi x \right)\),
\(\frac{\sin\left( x \right)}{x}\),
\(\frac{\sin\left( \pi x \right)}{\pi x}\).
The precision of the result will be equal to the precision of x.
New in version 0.19: The functions
sin_pi()
,cos_pi()
,tan_pi()
,cot_pi()
,sinc()
andsinc_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::sinc_pi(T &&x)# Note
The functions
sin_pi()
,cos_pi()
,tan_pi()
,cot_pi()
,sinc()
andsinc_pi()
are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Unary basic trigonometric functions.
These functions will return, respectively:
\(\sin\left( x \right)\),
\(\cos\left( x \right)\),
\(\tan\left( x \right)\),
\(\sec\left( x \right)\),
\(\csc\left( x \right)\),
\(\cot\left( x \right)\),
\(\sin\left( \pi x \right)\),
\(\cos\left( \pi x \right)\),
\(\tan\left( \pi x \right)\),
\(\cot\left( \pi x \right)\),
\(\frac{\sin\left( x \right)}{x}\),
\(\frac{\sin\left( \pi x \right)}{\pi x}\).
The precision of the result will be equal to the precision of x.
New in version 0.19: The functions
sin_pi()
,cos_pi()
,tan_pi()
,cot_pi()
,sinc()
andsinc_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::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::atan(T &&r)# Unary basic inverse trigonometric functions.
These functions will return, respectively, the arcsine, arccosine and arctangent of r. The precision of the result will be equal to the precision of r.
- Parameters:
r – the argument.
- Returns:
the arcsine, arccosine or arctangent of r.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::atan2(mppp::real &rop, T &&y, U &&x)# Ternary arctangent-2.
This function will set rop to the arctangent-2 of y and x. The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
y – the sine argument.
x – the cosine argument.
- Returns:
a reference to rop.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::atan2(T &&y, U &&x)# Binary arctangent-2.
This function will compute and return the arctangent-2 of y and x. The precision of the result will be set to the largest precision among the operands.
- Parameters:
y – the sine argument.
x – the cosine argument.
- Returns:
the arctangent-2 of y and x.
Hyperbolic functions#
-
template<mppp::cvr_real T>
mppp::real &mppp::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::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::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::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::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::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_base_ui(mppp::real &rop, T &&x, unsigned long b)# Note
The
log_base_ui()
function is available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Binary logarithms.
These functions will set rop to, respectively,
\(\log x\),
\(\log_2 x\),
\(\log_{10} x\),
\(\log\left( 1+x \right)\),
\(\log_b x\).
The precision of the result will be equal to the precision of x.
New in version 0.21: The
log_base_ui()
function.- Parameters:
rop – the return value.
x – the operand.
b – the base of the logarithm.
- Returns:
a reference to rop.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
template<mppp::cvr_real T>
mppp::real mppp::log_base_ui(T &&x, unsigned long b)# Note
The
log_base_ui()
function is available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Unary logarithms.
These functions will return, respectively,
\(\log x\),
\(\log_2 x\),
\(\log_{10} x\),
\(\log\left( 1+x \right)\),
\(\log_b x\).
The precision of the result will be equal to the precision of x.
New in version 0.21: The
log_base_ui()
function.- Parameters:
x – the operand.
b – the base of the logarithm.
- Returns:
the logarithm of x.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::log_hypot(mppp::real &rop, T &&x, U &&y)# New in version 0.19.
Note
This function is available only if mp++ was configured with the
MPPP_WITH_ARB
option enabled.Ternary log hypot function.
This function will set rop to \(\log\left(\sqrt{x^2+y^2}\right)\). The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
x – the first argument.
y – the second argument.
- Returns:
a reference to rop.
- Throws:
std::invalid_argument – if the conversion between 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.Binary log hypot function.
This function will compute and return \(\log\left(\sqrt{x^2+y^2}\right)\). The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first argument.
y – the second argument.
- Returns:
the log hypot function of x and y.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
Polylogarithms#
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::polylog(mppp::real &rop, T &&s, U &&x)# Note
The
polylog_si()
andpolylog()
functions are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Polylogarithms.
These functions will set rop to, respectively:
the dilogarithm \(\operatorname{Li}_2\left( x \right)\),
the polylogarithm of integer order \(s\) \(\operatorname{Li}_s\left( x \right)\),
the polylogarithm of real order \(s\) \(\operatorname{Li}_s\left( x \right)\).
The precision of the result will be equal to the precision of x (for
li2()
andpolylog_si()
) or to the largest precision among s and x (forpolylog()
).New in version 0.24: The
polylog_si()
andpolylog()
functions.- Parameters:
rop – the return value.
s – the order of the polylogarithm.
x – the argument.
- Returns:
a reference to rop.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::polylog(T &&s, U &&x)# Note
The
polylog_si()
andpolylog()
functions are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Polylogarithms.
These functions will return, respectively:
the dilogarithm \(\operatorname{Li}_2\left( x \right)\),
the polylogarithm of integer order \(s\) \(\operatorname{Li}_s\left( x \right)\),
the polylogarithm of real order \(s\) \(\operatorname{Li}_s\left( x \right)\).
The precision of the result will be equal to the precision of x (for
li2()
andpolylog_si()
) or to the largest precision among s and x (forpolylog()
).New in version 0.24: The
polylog_si()
andpolylog()
functions.- Parameters:
s – the order of the polylogarithm.
x – the argument.
- Returns:
the polylogarithm of x.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
Gamma functions#
-
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::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. The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first argument.
y – the second argument.
- Returns:
the upper incomplete Gamma function of x and y
Bessel functions#
New in version 0.17.
-
template<mppp::cvr_real T>
mppp::real &mppp::yn(mppp::real &rop, long n, T &&x)# Bessel functions of the first and second kind of integral order.
These functions will set rop to, respectively,
\(J_0\left( x \right)\),
\(J_1\left( x \right)\),
\(J_n\left( x \right)\),
\(Y_0\left( x \right)\),
\(Y_1\left( x \right)\),
\(Y_n\left( x \right)\).
The precision of the result will be equal to the precision of x.
- Parameters:
rop – the return value.
n – the order of the Bessel function.
x – the argument.
- Returns:
a reference to rop.
-
template<mppp::cvr_real T>
mppp::real mppp::yn(long n, T &&x)# Bessel functions of the first and second kind of integral order.
These functions will return, respectively,
\(J_0\left( x \right)\),
\(J_1\left( x \right)\),
\(J_n\left( x \right)\),
\(Y_0\left( x \right)\),
\(Y_1\left( x \right)\),
\(Y_n\left( x \right)\).
The precision of the result will be equal to the precision of x.
- Parameters:
n – the order of the Bessel function.
r – the argument.
- Returns:
the Bessel function of r.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::yx(mppp::real &rop, T &&nu, U &&x)# New in version 0.20.
Note
These functions are available only if mp++ was configured with the
MPPP_WITH_ARB
option enabled.Bessel functions of the first and second kind of real order.
These functions will set rop to, respectively,
\(J_\nu\left( x \right)\),
\(Y_\nu\left( x \right)\),
where \(\nu \in \mathbb{R}\). The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
nu – the order of the Bessel function.
x – the argument.
- Returns:
a reference to rop.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::yx(T &&nu, U &&x)# New in version 0.20.
Note
These functions are available only if mp++ was configured with the
MPPP_WITH_ARB
option enabled.Bessel functions of the first and second kind of real order.
These functions will return, respectively,
\(J_\nu\left( x \right)\),
\(Y_\nu\left( x \right)\),
where \(\nu \in \mathbb{R}\). The precision of the result will be set to the largest precision among the operands.
- Parameters:
nu – the order of the Bessel function.
x – the argument.
- Returns:
the Bessel function of x.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
Error functions#
-
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::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::lambert_wm1(mppp::real &rop, T &&op)# Note
The
lambert_w0()
andlambert_wm1()
functions are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Other binary special functions.
These functions will set rop to, respectively,
the exponential integral,
the Riemann Zeta function,
the Airy function,
the Lambert W functions \(W_0\) and \(W_{-1}\),
of op. The precision of the result will be equal to the precision of op.
New in version 0.24: The
lambert_w0()
andlambert_wm1()
functions.- Parameters:
rop – the return value.
op – 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::lambert_wm1(T &&r)# Note
The
lambert_w0()
andlambert_wm1()
functions are available only if mp++ was configured with theMPPP_WITH_ARB
option enabled.Other unary special functions.
These functions will return, respectively,
the exponential integral,
the Riemann Zeta function,
the Airy function,
the Lambert W functions \(W_0\) and \(W_{-1}\),
of r. The precision of the result will be equal to the precision of r.
New in version 0.24: The
lambert_w0()
andlambert_wm1()
functions.- Parameters:
r – the argument.
- Returns:
the exponential integral, Riemann Zeta function, Airy function or Lambert W function of r.
- Throws:
std::invalid_argument – if the conversion between Arb and MPFR types fails because of (unlikely) overflow conditions.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::beta(mppp::real &rop, T &&x, U &&y)# 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. The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first argument.
y – the second argument.
- Returns:
the beta function of x and y.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::hypot(mppp::real &rop, T &&x, U &&y)# Ternary hypot function.
This function will set rop to \(\sqrt{x^2+y^2}\). The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
x – the first argument.
y – the second argument.
- Returns:
a reference to rop.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::hypot(T &&x, U &&y)# Binary hypot function.
This function will compute and return \(\sqrt{x^2+y^2}\). The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first argument.
y – the second argument.
- Returns:
the hypot function of x and y.
-
template<mppp::cvr_real T, mppp::cvr_real U>
mppp::real &mppp::agm(mppp::real &rop, T &&x, U &&y)# Ternary AGM.
This function will set rop to the arithmetic-geometric mean of x and y. The precision of rop will be set to the largest precision among the operands.
- Parameters:
rop – the return value.
x – the first argument.
y – the second argument.
- Returns:
a reference to rop.
-
template<typename T, mppp::real_op_types<T> U>
mppp::real mppp::agm(T &&x, U &&y)# Binary AGM.
This function will compute and return the arithmetic-geometric mean of x and y. The precision of the result will be set to the largest precision among the operands.
- Parameters:
x – the first argument.
y – the second argument.
- Returns:
the AGM of x and y.
Input/Output#
-
std::ostream &mppp::operator<<(std::ostream &os, const mppp::real &r)#
Output stream operator.
This function will direct to the output stream os the input
real
r.- Parameters:
os – the target stream.
r – the input argument.
- Returns:
a reference to os.
- Throws:
std::overflow_error – in case of (unlikely) overflow errors.
std::invalid_argument – if the MPFR printing primitive
mpfr_asprintf()
returns an error code.unspecified – any exception raised by the public interface of
std::ostream
or by memory allocation errors.
Serialisation#
New in version 0.22.
-
std::size_t mppp::binary_size(const mppp::real &x)#
Binary size.
This function is the free function equivalent of the
mppp::real::binary_size()
member function.- Parameters:
x – the input argument.
- Returns:
the output of
mppp::real::binary_size()
called on x.- Throws:
unspecified – any exception thrown by
mppp::real::binary_size()
.
-
template<typename T>
std::size_t mppp::binary_save(const mppp::real &x, T &&dest)# Binary serialisation.
Note
This function participates in overload resolution only if the expression
return x.binary_save(std::forward<T>(dest));
is well-formed.
This function is the free function equivalent of the
mppp::real::binary_save()
overloads.- Parameters:
x – the input argument.
dest – the object into which x will be serialised.
- Returns:
the output of the invoked
mppp::real::binary_save()
overload called on x with dest as argument.- Throws:
unspecified – any exception thrown by the invoked
mppp::real::binary_save()
overload.
-
template<typename T>
std::size_t mppp::binary_load(mppp::real &x, T &&src)# Binary deserialisation.
Note
This function participates in overload resolution only if the expression
return x.binary_load(std::forward<T>(src));
is well-formed.
This function is the free function equivalent of the
mppp::real::binary_load()
overloads.- Parameters:
x – the output argument.
src – the object containing the serialised
real
that will be loaded into x.
- Returns:
the output of the invoked
mppp::real::binary_load()
overload called on x with src as argument.- Throws:
unspecified – any exception thrown by the invoked
mppp::real::binary_load()
overload.
Other#
Mathematical operators#
-
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)# Binary arithmetic operators.
The precision of the result will be set to the largest precision among the operands.
- Parameters:
a – the first operand.
b – the second operand.
- Returns:
the result of the binary operation.
-
template<typename U, mppp::real_in_place_op_types<U> T>
T &mppp::operator/=(T &a, U &&b)# In-place arithmetic operators.
If a is a
real
, then these operators are equivalent, respectively, to the expressions:a = a + b; a = a - b; a = a * b; a = a / b;
Otherwise, these operators are equivalent to the expressions:
a = static_cast<T>(a + b); a = static_cast<T>(a - b); a = static_cast<T>(a * b); a = static_cast<T>(a / b);
- Parameters:
a – the first operand.
b – the second operand.
- Returns:
a reference to a.
- Throws:
unspecified – any exception thrown by the generic conversion operator of
real
.
-
mppp::real &mppp::operator--(mppp::real &x)#
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)#
Suffix increment/decrement.
- Parameters:
x – the input argument.
- Returns:
a copy of x before the increment/decrement.
-
template<typename T, mppp::real_eq_op_types<T> U>
bool mppp::operator==(const T &a, const U &b)#
-
template<typename T, mppp::real_eq_op_types<T> U>
bool mppp::operator!=(const T &a, const U &b)#
-
template<typename T, mppp::real_op_types<T> U>
bool mppp::operator<(const T &a, const U &b)#
-
template<typename T, mppp::real_op_types<T> U>
bool mppp::operator<=(const T &a, const U &b)#
-
template<typename T, mppp::real_op_types<T> U>
bool mppp::operator>(const T &a, const U &b)#
-
template<typename T, mppp::real_op_types<T> U>
bool mppp::operator>=(const T &a, const U &b)# Comparison operators.
These operators will compare a and b, returning
true
if, respectively:\(a=b\),
\(a \neq b\),
\(a<b\),
\(a \leq b\),
\(a>b\),
\(a \geq b\),
and
false
otherwise.The comparisons are always exact (i.e., no rounding is involved).
These operators handle NaN in the same way specified by the IEEE floating-point standard. Alternative comparison functions treating NaN specially are available.
- Parameters:
a – the first operand.
b – the second operand.
- Returns:
the result of the comparison.
Constants#
-
mppp::real mppp::real_pi(mpfr_prec_t p)#
-
mppp::real mppp::real_log2(mpfr_prec_t p)#
-
mppp::real mppp::real_euler(mpfr_prec_t p)#
-
mppp::real mppp::real_catalan(mpfr_prec_t p)#
These functions will return, respectively:
the \(\pi\) constant,
the \(\log 2\) constant,
the Euler-Mascheroni constant (0.577…),
Catalan’s constant (0.915…),
with a precision of p.
New in version 0.21: The
real_log2()
,real_euler()
andreal_catalan()
functions.- Parameters:
p – the desired precision.
- Returns:
an approximation of a constant.
- Throws:
std::invalid_argument – if p is outside the range established by
mppp::real_prec_min()
andmppp::real_prec_max()
.
-
mppp::real &mppp::real_catalan(mppp::real &rop)#
These functions will set rop to, respectively:
the \(\pi\) constant,
the \(\log 2\) constant,
the Euler-Mascheroni constant (0.577…),
Catalan’s constant (0.915…).
The precision of rop will not be altered.
New in version 0.21: The
real_log2()
,real_euler()
andreal_catalan()
functions.- Parameters:
rop – the return value.
- Returns:
a reference to rop.
Standard library specialisations#
-
template<>
class std::hash<mppp::real># New in version 0.27.
Specialisation of
std::hash
formppp::real
.The hash is computed via
std::size_t mppp::hash(const mppp::real &)
.-
using result_type = std::size_t#
Note
The
argument_type
andresult_type
type aliases are defined only until C++14.-
std::size_t operator()(const mppp::real &x) const#
- Parameters:
x – the input
mppp::real
.- Returns:
a hash value for x.
-
using result_type = std::size_t#
User-defined literals#
New in version 0.19.
-
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).