CGAL 4.13  Number Types

#include <CGAL/Gmpfr.h>
An object of the class Gmpfr
is a fixed precision floatingpoint number, based on the Mpfr library.
This type is inexact, due to the fact that the mantissa of each number is represented by a fixed amount of bits (this amount is called precision). If an operation needs more bits than the precision of the result number, the results are rounded following different possible criteria (called rounding modes).
Currently, the Gmpfr
interface supports four rounding modes: round to nearest, round toward zero, round down (or toward \( (\infty)\)) and round up (or toward \( (+\infty)\)). When not specified explicitly, the operations use the default rounding mode, which is in practice a variable local to each execution thread. The default rounding mode can be set to any of the four rounding modes (initially, it is set to nearest). To specify rounding modes for operations, the type used is std::float_round_style
.
This type is ImplicitInteroperable
with Gmpz
, long
, unsigned long
, int
, double
and long double
.
Comparisons
Comparison operators ==
, !=
, >
, <
, >=
and <=
are also overloaded. A Gmpfr
can be compared with other Gmpfr
, as well as with a Gmpz
, long
, unsigned long
, int
, double
or long double
. It is worth noting that the numbers are never converted nor rounded before comparison. In the case where one of the compared numbers is NaN
, the erange
flag is set.
Implementation
Since the Mpfr library can be compiled to be threadsafe, this interface is designed to keep the threadsafety.
Gmpfr
s are reference counted. This behavior may be changed, by setting the flag CGAL_GMPFR_NO_REFCOUNT
. A nonreferencecounted class is slightly more efficient in case the implementation does not need to copy numbers (this is not usually the case). Nevertheless, setting this flag may be useful for debugging purposes.
RealEmbeddable
FieldWithKthRoot
Related Functions  
(Note that these are not member functions.)  
std::istream &  operator>> (std::istream &in, Gmpfr &f) 
Reads a floatingpoint number from in . More...  
std::ostream &  operator<< (std::ostream &out, const Gmpfr &f) 
If the ostream out is in prettyprint mode, writes a decimal approximation of f to out . More...  
Types  
typedef unspecified_type  Precision_type 
Type representing the precision (number of bits used to represent the mantissa) of a number.  
Creation  
Note that all constructors can be called with two optional parameters. One can specify as second parameter the rounding mode desired for the conversion from the source number and as a third parameter the precision with which this These optional parameters, along with other functions which will be explained below, allow users to control the rounding and precision. For example, being  
Gmpfr ()  
Creates an uninitialized Gmpfr f .  
Gmpfr (const Gmpfr &n)  
Copy constructor. More...  
Gmpfr (long si)  
Creates a Gmpfr , initialized with the value of si .  
Gmpfr (unsigned long ui)  
Creates a Gmpfr , initialized with the value of ui .  
Gmpfr (int i)  
Creates a Gmpfr , initialized with the value of i .  
Gmpfr (double d)  
Creates a Gmpfr , initialized with the value of d .  
Gmpfr (long double ld)  
Creates a Gmpfr , initialized with the value of ld .  
Gmpfr (const Gmpz &z)  
Creates a Gmpfr , initialized with the value of z .  
Gmpfr (const Gmpzf &zf)  
Creates a Gmpfr , initialized with the value of zf .  
Gmpfr (const std::pair< Gmpz, long > &ie)  
Creates a Gmpfr , initialized with the value of ie.first \( \times2^{\mathrm{ie.second}} \) .  
static Precision_type  get_default_precision () 
This returns the current precision used in Gmpfr creation by default.  
static Precision_type  set_default_precision (Precision_type p) 
This function sets the default Mpfr precision to p, and returns the old one.  
Controlling the Precision  
Each Gmpfr object has a precision associated to it. The precision is the amount of bits needed to represent the mantissa. Mpfr has a default precision value, which can be controlled by static functions of the Gmpfr class (in practice, this default value is a variable local to each execution thread). There are also functions to get and set the precision of each Gmpfr object.  
Precision_type  get_precision () const 
Returns the precision of f .  
Gmpfr  round (Precision_type p, std::float_round_style r) const 
Returns the value of f , rounded with precision p in the direction r .  
static std::float_round_style  get_default_rndmode () 
This function returns the current rounding mode used by Mpfr.  
static std::float_round_style  set_default_rndmode (std::float_round_style r) 
This function sets the Mpfr rounding mode to r and returns the old one.  
Flags  
Mpfr provides some flags to know whether performed operations were exact or not, or they incurred in overflow or underflow, if the exponent is out of range, or the result was One can clear the flags before a set of operations and inspect them afterward, in order to see if something unexpected happened during the operations. The static functions used to handle flags are:  
static void  clear_flags () 
Clears all the flags set by Mpfr(they are not cleared automatically).  
static bool  underflow_flag () 
Shows whether an operation incurred in underflow.  
static bool  overflow_flag () 
Shows whether an operation incurred in overflow.  
static bool  nan_flag () 
Shows whether the result of an operation was NaN .  
static bool  inex_flag () 
Shows whether an operation was inexact.  
static bool  erange_flag () 
Returns true iff a range error occurred. More...  
Arithmetic Operations  
Arithmetic operators The precision of an operation between two  
Gmpfr  abs (Precision_type p, std::float_round_style r=get_default_rndmode()) const 
Returns the absolute value of f , rounded with precision p in the direction r . More...  
Gmpfr  sqrt (Precision_type p, std::float_round_style r=get_default_rndmode()) const 
Returns the square root of f , rounded with precision p in the direction r . More...  
Gmpfr  kthroot (int k, Precision_type p, std::float_round_style r=get_default_rndmode()) const 
Returns the kth root of f , rounded with precision p in the direction r . More...  
Gmpfr  square (Precision_type p, std::float_round_style r=get_default_rndmode()) const 
Returns the square of f , rounded with precision p in the direction r . More...  
double  to_double (std::float_round_style r=get_default_rndmode()) 
Returns a double precision approximation of f using the rounding mode r .  
std::pair< double, double >  to_interval () 
Returns an interval of doubles which contains f . More...  
std::pair< double, long >  to_double_exp (std::float_round_style r=get_default_rndmode()) 
Returns the pair \( (d,e) \) such that \( 0.5 \led < 1 \) and \( d \times2^e \) equals f rounded to double precision, using the rounding mode r . More...  
std::pair< std::pair< double, double >, long >  to_interval_exp () 
Returns \( ((m,M),e) \) such that \( m \times2^e \le f \le M \times2^e \). More...  
std::pair< Gmpz, long >  to_integer_exp () 
Returns a pair of integers \( (m,e) \), such that \( f = m \times2^e \). More...  
static Gmpfr  add (const Gmpfr &a, const Gmpfr &b) 
static Gmpfr  add (const Gmpfr &a, const Gmpfr &b, std::float_round_style r) 
static Gmpfr  add (const Gmpfr &a, const Gmpfr &b, Precision_type p) 
static Gmpfr  add (const Gmpfr &a, const Gmpfr &b, Precision_type p, std::float_round_style r) 
Query Functions  
Sign  sign () 
Returns the sign of f .  
bool  is_zero () 
Returns true iff f is zero.  
bool  is_one () 
Returns true iff f is one.  
bool  is_nan () 
Returns true iff f is NaN (notanumber).  
bool  is_inf () 
Returns true iff f is plus or minus infinity.  
bool  is_number () 
Returns true iff f is a valid number.  
bool  is_square () 
Returns true iff f is the square of a number representable by an object of this type.  
bool  is_square (const Gmpfr &y) 
Returns true iff f is the square of a number representable by an object of this type, computing and storing it in y .  
CGAL::Gmpfr::Gmpfr  (  const Gmpfr &  n  ) 
Copy constructor.
The copied object inherits the precision of n
, and thus it is not rounded.
Gmpfr CGAL::Gmpfr::abs  (  Precision_type  p, 
std::float_round_style  r = get_default_rndmode() 

)  const 
Returns the absolute value of f
, rounded with precision p
in the direction r
.
If p
is not specified, the precision used is the maximum between f
's precision and the default.

static 
Returns true
iff a range error occurred.
Such an exception occurs when some function which does not return a Gmpfr
has an invalid result. For example, this flag will be set if one of the operands of a comparison is NaN
.
Gmpfr CGAL::Gmpfr::kthroot  (  int  k, 
Precision_type  p,  
std::float_round_style  r = get_default_rndmode() 

)  const 
Returns the kth root of f
, rounded with precision p
in the direction r
.
If p
is not specified, the precision used is the maximum between f
's precision and the default.
Gmpfr CGAL::Gmpfr::sqrt  (  Precision_type  p, 
std::float_round_style  r = get_default_rndmode() 

)  const 
Returns the square root of f
, rounded with precision p
in the direction r
.
If p
is not specified, the precision used is the maximum between f
's precision and the default.
Gmpfr CGAL::Gmpfr::square  (  Precision_type  p, 
std::float_round_style  r = get_default_rndmode() 

)  const 
Returns the square of f
, rounded with precision p
in the direction r
.
If p
is not specified, the precision used is the maximum between f
's precision and the default.
std::pair<double,long> CGAL::Gmpfr::to_double_exp  (  std::float_round_style  r = get_default_rndmode()  ) 
Returns the pair \( (d,e) \) such that \( 0.5 \led < 1 \) and \( d \times2^e \) equals f
rounded to double precision, using the rounding mode r
.
If f
is NaN
or infinity, then the corresponding double is returned, leaving the exponent undefined and setting the appropriate error flag.
std::pair<Gmpz,long> CGAL::Gmpfr::to_integer_exp  (  ) 
Returns a pair of integers \( (m,e) \), such that \( f = m \times2^e \).
Note that the returned value of \( m\) is not necessarily the smallest possible value of \( m\) (that is, it might be that \( 2m\)).
std::pair<double,double> CGAL::Gmpfr::to_interval  (  ) 
Returns an interval of doubles which contains f
.
If a rounded endpoint does not fit in a double, the double is set to plus or minus infinity and the overflow
or underflow
flag.
std::pair<std::pair<double,double>,long> CGAL::Gmpfr::to_interval_exp  (  ) 
Returns \( ((m,M),e) \) such that \( m \times2^e \le f \le M \times2^e \).
If f
is NaN
or infinity, then the corresponding doubles are returned, leaving the exponent undefined and setting the appropriate error flag.

related 
If the ostream out
is in prettyprint mode, writes a decimal approximation of f
to out
.
Otherwise, writes f
to out
in the form \( MeE\), where \( M\) is its mantissa and \( E\) is its exponent, both in base 10.

related 
Reads a floatingpoint number from in
.
The number \( M \times2^E\) must be in the form \( MeE\), where the mantissa \( M\) and the exponent \( E\) are integers in base 10.