Gmpfi

Navigation: Up Table of Contents Package Overview Bibliography Index Title Acknowledging CGAL

CGAL::Gmpfi

Definition

An object of the class Gmpfi is a closed interval, whith endpoints represented as MPFR floating-point numbers. An interval can have finite or infinite endpoints and its meaning is straightforward. It can also have one (or both) NaN endpoint(s): this indicates that an invalid operation has been performed and that the resulting interval has no mathematical meaning.

All the operations of Gmpfi were designed in such a way that the mathematical correct result is always contained in the resulting interval.

This type is ImplicitInteroperable with Gmpfr, Gmpz, Gmpq, long, unsigned long, int, double and long double.

#include <CGAL/Gmpfi.h>

Is Model for the Concepts

FieldWithKthRoot
RealEmbeddable

Types

Gmpfi::Precision_type
	Type representing the precision (number of bits used to represent the mantissa) of a number.

Creation

All the constructors accept an optional last argument: a precision (a Precision_type, which can be used to specify the precision of the Gmpfr endpoints. If none is specified, the default precision will be used. As the endpoints are represented with a fixed number of bits, they may need to be rounded. In this case, the number from which the Gmpfi was constructed is guaranteed to be included in the constructed interval.

Gmpfi i ( Precision_type p=get_default_precision());
	creates an uninitialized Gmpfi interval i.

template <class T>
Gmpfi i ( T t, Precision_type p=get_default_precision());
	creates a Gmpfi initialized with the value of t. T is Gmpfr, Gmpz, Gmpq, or any other type from which Gmpfr can be constructed from. The rounding of the endpoints will guarantee that t is included in i.

Gmpfi i ( Gmpfr left, Gmpfr right, Precision_type p=get_default_precision());
	creates a Gmpfi initialized with endpoints left and right. The rounding of the endpoints will guarantee that [left,right] is included in i.

template<class L, class R>
Gmpfi i ( std::pair< L ,const R&> endpoints);
	creates Gmpfi initialized with endpoints endpoints.first and endpoints.second. L and R are types from which Gmpfr can be constructed from. The rounding of the endpoints will guarantee that [left,right] is included in i.

Operations

Gmpfr	i.inf ()	Returns the smallest (or inferior) Gmpfr endpoint of i.

Gmpfr	i.sup ()	Returns the largest (or superior) Gmpfr endpoint of i.

static Precision_type	i.get_default_precision ()	Returns the default precision.

static Precision_type	i.set_default_precision ( Precision_type prec)
		Sets the default precision to prec and returns the old value.

Precision_type	i.get_precision ()	Returns the precision of i.

Gmpfi	i.round ( Precision_type p)	Returns the value of the number, rounded with precision p.

Arithmetic operators +, -, * and / are overloaded, but special care must be taken when applying them. The precision of an operation between two Gmpfis is defined as the maximum of the operands precision and the default precision.

The second operand of the former operations can be a Gmpfi, Gmpfr, int, long, unsigned, unsigned long, Gmpz or Gmpq. The precision of an operation between a Gmpfi and a number of another type is defined as the Gmpfi's precision (even when operating with a Gmpfr).

To specify the rounding mode and/or the precision to perform an operation, this class provides the four static functions add, sub, mul and div. Only one of them is shown here, since their interfaces are similar:

static Gmpfi

add ( a, b, Precision_type p=0)

When the precision is not specified in this family of functions, it is defined as in the overloaded operators.

Other arithmetic functions provided by the class are:

Gmpfi	i.abs ( Precision_type p)	Returns the absolute value of i, with precision p. If p is not specified, the precision used is the maximum between i's precision and the default.

Gmpfi	i.sqrt ( Precision_type p)	Returns the square root of i, with precision p. If p is not specified, the precision used is the maximum between i's precision and the default.

Gmpfi	i.kthroot ( int k, Precision_type p)
		Returns the k-th root of i, with precision p. If p is not specified, the precision used is the maximum between i's precision and the default.

Gmpfi	i.square ( Precision_type p)	Returns the square of i, with precision p. If p is not specified, the precision used is the maximum between i's precision and the default.

std::pair<double,double>	i.to_interval ()	Returns an interval of doubles which contains i. If a rounded enpoint does not fit in a double, sets its value to plus or minus infinity and the overflow or underflow flag.

std::pair<double,long>	i.to_double_exp ()	Returns (m,e) such that m × 2^e is the center of i, rounded to nearest. If one of the endpoints of i is Nan or infinity, then the corresponding double is returned, leaving the exponent undefined and setting the appropriate error flag.

std::pair<std::pair<double,double>,long>
	i.to_interval_exp ()	Returns ((m₁,m₂),e), such that [m₁ × 2^e,m₂ × 2^e] contains i. If one of the endpoints of i is Nan or infinity, then the corresponding doubles are returned, leaving the exponent undefined and setting the appropriate error flag.

Comparisons

The semantics of the comparison operators is the same than on Interval_nt<Protected>. The result of the comparison is always an Uncertain<bool> (this type is convertible to bool, but may throw an exception). If compared intervals have no common points, the result is true or false; otherwise, Uncertain<bool>::indeterminate() will be returned.

In the same way, we can explain the semantics of Uncertain<Comparison_result> and Uncertain<Sign>.

With the semantics described above, this class provides comparisons between Gmpfi and Gmpfi, Gmpfr, long, unsigned long, int, double, Gmpz and Gmpq. Comparison operators ==, !=, >, <, >= and <= are overloaded.

The class provides also functions to test efficiently some special kinds of comparisons:

bool	i.is_same ( j)	Returns true iff left endpoints of i and j are equal and right endpoints of them are also equal. Note that this does not mean equality between i and j.

bool	i.do_overlap ( j)	Returns true iff i and j overlap, i.e., iff they have points in common.

Uncertain<Comparison_result>	i.compare ( j)	If i and j do not overlap, this function returns the result of the comparison. Otherwise, it returns indeterminate.

Query Functions

bool	i.is_point ()	Returns true iff both endpoints are equal.

bool	i.is_nan ()	Returns true iff at least one of the endpoints is NaN.

bool	i.is_inf ()	Returns true iff at least one of the endpoints is plus or minus infinity.

bool	i.is_number ()	Returns true iff i is a bounded interval, i.e. its endpoints are neither invalid nor infinite.

Uncertain<bool>	i.is_zero ()	Returns true if both endpoints are zero, false if the interval does not contain zero and indeterminate otherwise.

Uncertain<bool>	i.is_one ()	Returns true if both endpoints are one, false if the interval does not contain one and indeterminate otherwise.

Uncertain<Sign>	i.sign ()	If all numbers contained in the interval have the same sign, this function returns it. Otherwise it returns indeterminate.

Uncertain<bool>	i.is_positive ()	Returns true if all numbers contained in the interval are positive, false if all of them are negative or zero and indeterminate otherwise.

Uncertain<bool>	i.is_negative ()	Returns true if all numbers contained in the interval are negative, false if all of them are positive or zero and indeterminate otherwise.

Input/Output

std::istream&	std::istream &is >> i	Reads i from is. is has the form [inf,sup], where inf and sup have valid Gmpfr formats.

std::ostream&	std::ostream &os << i	Writes i to os, in the form [i.inf(),i.sup()].

Implementation

Gmpfis are reference counted.