CGAL 6.2 - Number Types: CGAL::Gmpfi Class Reference

CGAL 6.2 - Number Types

Loading...
Searching...
No Matches
List of all members | Related Functions
CGAL::Gmpfi Class Reference
Reference Manual » GMP

`#include <CGAL/Gmpfi.h>`

## Definition

An object of the class `Gmpfi` is a closed interval, with endpoints represented as `Gmpfr` 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`.

Is model of
  `FieldWithKthRoot`
  `RealEmbeddable`

Implementation

All interval operations are performed by the MPFI library. The class `Gmpfi` is not reference counted, but its members are.

The default precision of `Gmpfi` is local to each thread and independent of the default precision of `Gmpfr` (in contrast to the behavior of the MPFI and MPFR libraries, which share a default precision).

See also
  `CGAL::Gmpfr`
  `CGAL::Interval_nt`
  `CGAL::Uncertain`
  `RealEmbeddable`
  `FieldWithKthRoot`

## Related Functions
(Note that these are not member functions.)
std::istream & | operator>> (std::istream &is, Gmpfi i)
| Reads `i` from `is`.
std::ostream & | operator<< (std::ostream &os, const Gmpfi &i)
| Writes `i` to `os`, in the form `[i.inf(),i.sup()]`.

## Types
typedef unspecified_type | Precision_type
| Type representing the precision (number of bits used to represent the mantissa) of a number.

## Creation
All constructors accept as an optional last argument a precision, 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 (Precision_type p=get_default_precision())
| creates an uninitialized `Gmpfi` interval `i`.
template<class T >
| Gmpfi (const T &t, Precision_type p=get_default_precision())
| creates a `Gmpfi` initialized with the value of `t`.
| Gmpfi (const Gmpfr &left, const Gmpfr &right, Precision_type p=get_default_precision())
| creates a `Gmpfi` initialized with endpoints `left` and `right`.
template<class L , class R >
| Gmpfi (const std::pair< L, R > &endpoints, Precision_type p=get_default_precision())
| creates a `Gmpfi` initialized with endpoints `endpoints.first` and `endpoints.second`.

## Operations
Gmpfr | inf () const
| Returns the smallest (or inferior) `Gmpfr` endpoint of `i`.
Gmpfr | sup () const
| Returns the largest (or superior) `Gmpfr` endpoint of `i`.
Precision_type | get_precision () const
| Returns the precision of `i`.
Gmpfi | round (Precision_type p) const
| Returns the value of the number, rounded with precision `p`.
static Precision_type | get_default_precision ()
| Returns the default precision.
static Precision_type | set_default_precision (Precision_type prec)
| Sets the default precision to `prec` and returns the old value.

## Arithmetic Operations
Arithmetic operators `+`, `-`, and `/` are overloaded, but special care must be taken when applying them. The precision of an operation between two `Gmpfi`s 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: When the precision is not specified in this family of functions, it is defined as in the overloaded operators.
Gmpfi | abs (Precision_type p) const
| Returns the absolute value of `i`, with precision `p`.
Gmpfi | sqrt (Precision_type p) const
| Returns the square root of `i`, with precision `p`.
Gmpfi | kthroot (int k, Precision_type p) const
| Returns the k-th root of `i`, with precision `p`.
Gmpfi | square (Precision_type p) const
| Returns the square of `i`, with precision `p`.
std::pair< double, double > | to_interval () const
| Returns an interval of doubles which contains `i`.
std::pair< double, long > | to_double_exp () const
| Returns \( (m,e)\) such that \( m \times2^e\) is the center of `i`, rounded to nearest.
std::pair< std::pair< double, double >, long > | to_interval_exp () const
| Returns \( ((m_1,m_2),e)\), such that \( [m_1 \times2^e,m_2 \times2^e]\) contains `i`.
static Gmpfi | add (const Gmpfi &a, const Gmpfi &b, Precision_type p=0)

## 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::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 | is_same (const Gmpfi &j) const
| Returns `true` iff left endpoints of `i` and `j` are equal and right endpoints of them are also equal.
bool | do_overlap (const Gmpfi &j) const
| Returns `true` iff `i` and `j` overlap, i.e., iff they have points in common.
Uncertain< Comparison_result > | compare (const Gmpfi &j) const
| If `i` and `j` do not overlap, this function returns the result of the comparison.

## Query Functions
bool | is_point () const
| Returns `true` iff both endpoints are equal.
bool | is_nan () const
| Returns `true` iff at least one of the endpoints is `NaN`.
bool | is_inf () const
| Returns `true` iff at least one of the endpoints is plus or minus infinity.
bool | is_number () const
| Returns `true` iff `i` is a bounded interval, i.e., its endpoints are neither invalid nor infinite.
Uncertain< bool > | is_zero () const
| Returns `true` if both endpoints are zero, `false` if the interval does not contain zero and `indeterminate` otherwise.
Uncertain< bool > | is_one () const
| Returns `true` if both endpoints are one, `false` if the interval does not contain one and `indeterminate` otherwise.
Uncertain< Sign > | sign () const
| If all numbers contained in the interval have the same sign, this function returns it.
Uncertain< bool > | is_positive () const
| 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 > | is_negative () const
| Returns `true` if all numbers contained in the interval are negative, false if all of them are positive or zero and `indeterminate` otherwise.

## Constructor & Destructor Documentation

## ◆ Gmpfi() [1/3]

template<class T >

CGAL::Gmpfi::Gmpfi | ( | const T & | t,
|  | Precision_type | p = `get_default_precision()`
| ) |  |

creates a `Gmpfi` initialized with the value of `t`.

`T` is `Gmpfr`, `Gmpq`, or any type from which `Gmpfr` can be constructed from. The rounding of the endpoints will guarantee that `t` is included in `i`.

## ◆ Gmpfi() [2/3]

CGAL::Gmpfi::Gmpfi | ( | const Gmpfr & | left,
|  | const 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`.

## ◆ Gmpfi() [3/3]

template<class L , class R >

CGAL::Gmpfi::Gmpfi | ( | const std::pair< L, R > & | endpoints,
|  | Precision_type | p = `get_default_precision()`
| ) |  |

creates a `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 ([`endpoints.first`,`endpoints.second`]) is included in `i`.

## Member Function Documentation

## ◆ abs()

Gmpfi CGAL::Gmpfi::abs | ( | Precision_type | p | ) | const

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.

## ◆ compare()

Uncertain< Comparison_result > CGAL::Gmpfi::compare | ( | const Gmpfi & | j | ) | const

If `i` and `j` do not overlap, this function returns the result of the comparison.

Otherwise, it returns `indeterminate`.

## ◆ is_same()

bool CGAL::Gmpfi::is_same | ( | const Gmpfi & | j | ) | const

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

## ◆ kthroot()

Gmpfi CGAL::Gmpfi::kthroot | ( | int | k,
|  | Precision_type | p
| ) |  | const

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.

## ◆ sign()

Uncertain< Sign > CGAL::Gmpfi::sign | ( |  | ) | const

If all numbers contained in the interval have the same sign, this function returns it.

Otherwise it returns `indeterminate`.

## ◆ sqrt()

Gmpfi CGAL::Gmpfi::sqrt | ( | Precision_type | p | ) | const

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.

## ◆ square()

Gmpfi CGAL::Gmpfi::square | ( | Precision_type | p | ) | const

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.

## ◆ to_double_exp()

std::pair< double, long > CGAL::Gmpfi::to_double_exp | ( |  | ) | const

Returns \( (m,e)\) such that \( m \times2^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.

## ◆ to_interval()

std::pair< double, double > CGAL::Gmpfi::to_interval | ( |  | ) | const

Returns an interval of doubles which contains `i`.

If a rounded endpoint does not fit in a double, sets its value to plus or minus infinity and the `overflow` or `underflow` flag.

## ◆ to_interval_exp()

std::pair< std::pair< double, double >, long > CGAL::Gmpfi::to_interval_exp | ( |  | ) | const

Returns \( ((m_1,m_2),e)\), such that \( [m_1 \times2^e,m_2 \times2^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.

## Friends And Related Function Documentation

## ◆ operator<<()

std::ostream & operator<< | ( | std::ostream & | os,
|  | const Gmpfi & | i
| ) |  |
| related

Writes `i` to `os`, in the form `[i.inf(),i.sup()]`.

The endpoints are written according to the `Gmpfr` formatting.

## ◆ operator>>()

std::istream & operator>> | ( | std::istream & | is,
|  | Gmpfi | i
| ) |  |
| related

Reads `i` from `is`.

`is` must have the form `[inf,sup]`, where `inf` and `sup` have valid `Gmpfr` input formats.