CGAL 4.7 - STL Extensions for CGAL: CGAL::Uncertain< T > Class Template Reference

\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.7 - STL Extensions for CGAL

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
List of all members | Static Public Member Functions | Related Functions
CGAL::Uncertain< T > Class Template Reference
Utilities

`#include <CGAL/Uncertain.h>`

## Definition

An object of the class `Uncertain` represents an uncertainty on the value of type `T`.

This uncertainty is represented by a non-empty range of values of type `T`.

The idea is that sometimes you are not sure of the result of a function, and you would like to communicate that to the caller. `Uncertain<T>` allows just that.

`Uncertain<T>` is also meant to be used as a drop-in replacement for `T` in some template contexts, as much as possible. This is why it provides overloaded operators and functions to naturally extend the Boolean operations for `Uncertain<bool>` for example, or the operations on enumeration types.

`Uncertain<T>` is used in CGAL as the return type of geometric predicates when the number type used is interval arithmetic like `Interval_nt`. End users typically do not see it, as it is hidden in the implementation of the filtered predicates provided by the various filtered kernels, but it is important that providers of predicates that are meant to be filtered by `Filtered_predicate`, know about it.

Note concerning CGAL assertions: assertions checking an expression of type `Uncertain<bool>` will trigger an assertion failure only if the assertion is certainly `false`. In case of an indeterminate value, the assertion is not triggered. This means that we assume, in case of doubt, that there is no error.

It can also be used in other contexts as well, as it is a general tool. This can be seen as support for non-deterministic programming. Finally, note that this class has some common points with `boost::tribool`.

Parameters

The parameter `T` can either be `bool` or one of the three-valued (-1, 0, 1) enumeration types: `Sign`, `Comparison_result`, `Orientation`, `Oriented_side`, `Bounded_side` or `Angle`.

Some functions are defined only when `T` is `bool` or alternatively when it is one of the enumeration types listed previously.

See Also
  `CGAL::Interval_nt<bool>`

## Static Public Member Functions

static Uncertain< T > | indeterminate ()
| returns an indeterminate range.

## Related Functions

(Note that these are not member functions.)
template<class T >
T | inf (Uncertain< T > u)
| returns `u.inf()`.
template<class T >
T | sup (Uncertain< T > u)
| returns `u.sup()`.
template<class T >
bool | is_certain (T t)
| returns `true`.
template<class T >
bool | is_certain (Uncertain< T > u)
| returns `u.is_certain`().
template<class U >
U | indeterminate ()
| returns `U::indeterminate()` if `U` is `Uncertain<T>`, and `U()` otherwise.
template<class T >
bool | is_indeterminate (T u)
| returns `false`.
template<class T >
bool | is_indeterminate (Uncertain< T > u)
| returns `!is_certain(u)`.
template<class T >
T | get_certain (T t)
| returns `t`.
template<class T >
T | get_certain (Uncertain< T > u)
| returns `u.make_certain`(). More...
template<class T >
T | make_certain (T t)
| returns `t`.
template<class T >
T | make_certain (Uncertain< T > u)
| returns `u.make_certain`().
template<class T >
Uncertain< T > | make_uncertain (T t)
| returns `Uncertain<T>(u)`.
template<class T >
Uncertain< T > | make_uncertain (Uncertain< T > u)
| returns `u`.
#define | CGAL_AND_3
| Boolean operation with 3 arguments.
#define | CGAL_OR_3
| Boolean operation with 3 arguments.
bool | certainly (Uncertain< bool > u)
| returns `true` iff `u.is_certain()`, and the `u.make_certain`() returns `true`.
bool | certainly (bool u)
| returns `u`.
bool | possibly (Uncertain< bool > u)
| returns `true` iff `u.is_certain()` returns `false`, or if `u.make_certain`() returns `true`.
bool | possibly (bool u)
| returns `u`.
bool | certainly_not (Uncertain< bool > u)
| returns `true` iff `u.is_certain()`, and the `u.make_certain`() returns `false`.
bool | certainly_not (bool u)
| returns `!u`.
bool | possibly_not (Uncertain< bool > u)
| returns `true` iff `u.is_certain()` returns `false`, or if `u.make_certain`() returns `false`.
bool | possibly_not (bool u)
| returns `!u`.

## Types

typedef unspecified_type | value_type
| The type `T`.
typedef unspecified_type | Uncertain_conversion_exception
| The type of the exception thrown for uncertain conversions. More...

## Creation

| Uncertain ()
| introduces a certain object with value `T()`.
| Uncertain (T t)
| introduces a certain object with value `t`.
Uncertain & | operator= (T t)
| assigns the certain value `t` to `u`.
| Uncertain (T i, T s)
| introduces an object representing the range with lower bound `i` and upper bound `s`. More...

## Access Functions

The following functions are meant to be used very rarely, they provide ways to inspect the content of an `Uncertain<T>` object.
T | inf () const
| returns the lower bound of the range represented by `u`.
T | sup () const
| returns the upper bound of the range represented by `u`.
bool | is_same (Uncertain u) const
| returns true whether `u` and `u` are the same range (equality as sets).

## Uncertainty Testing and Conversion

There are several ways to extract the content of an `Uncertain` object.

The simplest way is to rely on the implicit conversion from `Uncertain<T>` to `T`. In this case, no special code has to be written, apart from an exception handler (anywhere higher in the call stack) to manage the uncertain case. The more involved one is more efficient, but requires manual treatment of the uncertain case, such as:

Uncertain<bool> b = ...;
if (is_certain(b))
bool cert_b = get_certain(b); // Extract the certain bool it contains
...
else
... // b is indeterminate

Another option is :

Uncertain<bool> b = ...;
if (certainly(b))
... // b is certainly true
else if (certainly_not(b))
... // b is certainly false
else
... // b is indeterminate

There are many other handy functions which can be used for easier usage depending on the context. They are listed in the sequel.

bool | is_certain () const
| returns `true` iff the value is certain, that is, it is unique, the range is a singleton, that is `u.inf() == u.sup()`.
T | make_certain () const
| if `u.is_certain()`, then returns the certain value which is represented. More...
| operator T () const
| conversion operator to `T`. More...

## Overloaded Operators

The overloaded operators and functions are defined as preserving the set-inclusion property. Similarly to interval arithmetic, the returned range is guaranteed to contain the result of the operation over all values of the input range(s). In the following documentation we express this as the extension of the corresponding function over the type `T`.
template<class T >
Uncertain< bool > | operator== (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the equality operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator== (Uncertain< T > u, T v)
| returns `u == make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator== (T u, Uncertain< T > v)
| returns `v == u`.
template<class T >
Uncertain< bool > | operator!= (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the inequality operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator!= (Uncertain< T > u, T v)
| returns `u != make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator!= (T u, Uncertain< T > v)
| returns `v != u`.

## Overloaded Operators for Uncertain<bool>

The overloaded operators and functions are defined as preserving the set-inclusion property.

Similarly to interval arithmetic, the returned range is guaranteed to contain the result of the operation over all values of the input range(s). In the following documentation we express this as the extension of the corresponding function over the type `T`.

Note
  The logical operators \( \&\&\) and \( ||\) are not overloaded on purpose. The reason is that, when `f() && g()` is evaluated and they return `bool`, then `g()` is only evaluated when `f()` returns `true`. One could have a dependency so that `g()` has an internal precondition that required that `f()` had returned `true`. The overloaded operators for user-defined types can not provide this short-circuiting property, and so, if the overloaded operators where provided, then `g()` would be evaluated, no matter the result of `f()`, which could lead to an unwanted situation, or a performance loss. The \( \&\) and \( |\) operators do not have this short-circuiting property, and are therefore overloaded safely.

When translating normal code to use and propagate uncertainty, such as :

// Logical AND
if ( (p.x() == 0) && (p.y() == 0) )
...
else
...
// Logical OR
if ( (q.x() == 0) || (q.y() == 0) )
...
else
...

One can do, for example :

// Logical AND
Uncertain<bool> tmp = (p.x() == 0);
Uncertain<bool> res = certainly_not(tmp) ? make_uncertain(false) : tmp & (p.y() == 0);
... // Use res
// Logical OR
Uncertain<bool> tmp = (q.x() == 0);
Uncertain<bool> res = certainly(tmp) ? make_uncertain(true) : tmp | (q.y() == 0);
... // Use res

This ensures that the first expression is not evaluated twice, and that the second is evaluated only if needed.

This behavior can also be emulated through the use of macros, but only using non-standard features ("statement expressions", such as provided by GCC). The macros `CGAL_AND` and `CGAL_OR` are provided that perform the lazy evaluation of these logical operations. On compilers that do not support statement expressions, the macros simply expand to the \( \&\&\) and \( ||\) operators (which will throw an exception instead of propagating the uncertainty).

// Logical AND
Uncertain<bool> res = CGAL_AND( p.x() == 0 , p.y() == 0 );
... // Use res
// Logical OR
Uncertain<bool> res = CGAL_OR( q.x() == 0 , q.y() == 0 );
... // Use res

Uncertain< bool > | operator! (Uncertain< bool > u)
| returns the range containing the negated values of `u`.
Uncertain< bool > | operator| (Uncertain< bool > u, Uncertain< bool > v)
| returns the range containing the values computed as logical or from `u` and `v`.
Uncertain< bool > | operator| (Uncertain< bool > u, bool v)
| returns `u | make_uncertain(v)`.
Uncertain< bool > | operator| (bool u, Uncertain< bool > v)
| returns `v | u`.
Uncertain< bool > | operator& (Uncertain< bool > u, Uncertain< bool > v)
| returns the range containing the values computed as logical and from `u` and `v`.
Uncertain< bool > | operator& (Uncertain< bool > u, bool v)
| returns `u & make_uncertain(v)`.
Uncertain< bool > | operator& (bool u, Uncertain< bool > v)
| returns `v & u`.

## Overloaded Operators and Functions for Uncertain<enum T> Only

template<class T >
Uncertain< bool > | operator< (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the less-than operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator< (Uncertain< T > u, T v)
| returns `u < make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator< (T u, Uncertain< T > v)
| returns `make_uncertain(u) < v`.
template<class T >
Uncertain< bool > | operator> (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the greater-than operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator> (Uncertain< T > u, T v)
| returns `u > make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator> (T u, Uncertain< T > v)
| returns `make_uncertain(u) > v`.
template<class T >
Uncertain< bool > | operator<= (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the less-than or equal operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator<= (Uncertain< T > u, T v)
| returns `u <= make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator<= (T u, Uncertain< T > v)
| returns `make_uncertain(u) <= v`.
template<class T >
Uncertain< bool > | operator>= (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the greater-than or equal operator over `u` and `v`.
template<class T >
Uncertain< bool > | operator>= (Uncertain< T > u, T v)
| returns `u > make_uncertain(v)`.
template<class T >
Uncertain< bool > | operator>= (T u, Uncertain< T > v)
| returns `make_uncertain(u) >= v`.
template<class T >
Uncertain< T > | operator* (Uncertain< T > u, Uncertain< T > v)
| returns the extension of the multiplication operator over `u` and `v`. More...
template<class T >
Uncertain< T > | operator* (Uncertain< T > u, T v)
| returns `u * make_uncertain(v)`.
template<class T >
Uncertain< T > | operator< (T u, Uncertain< T > v)
| returns `make_uncertain(u) * v`.
template<class T >
Uncertain< T > | operator- (Uncertain< T > u)
| returns the extension of the unary minus operator over `u`.
template<class T , class U >
Uncertain< T > | enum_cast (Uncertain< U > u)
| returns the extension of the `enum_cast<T>` function over `u`.

## Member Typedef Documentation

template<typename T >

typedef unspecified_type CGAL::Uncertain< T >::Uncertain_conversion_exception

The type of the exception thrown for uncertain conversions.

It is a typedef to the type `CGAL::Uncertain_conversion_exception` which derives from `std::range_error`.

## Constructor & Destructor Documentation

template<typename T >

CGAL::Uncertain< T >::Uncertain | ( | T | i,
|  | T | s
| ) |  |

introduces an object representing the range with lower bound `i` and upper bound `s`.

Precondition
  \( i<= s\).

## Member Function Documentation

template<typename T >

T CGAL::Uncertain< T >::make_certain | ( | ) |  | const

if `u.is_certain()`, then returns the certain value which is represented.

Otherwise, throws an exception of type `Uncertain_conversion_exception`. A profile counter of the number of such exceptions thrown during the execution of the program is available with `CGAL_PROFILE`.

template<typename T >

CGAL::Uncertain< T >::operator T | ( | ) |  | const

conversion operator to `T`.

It does and returns the same thing as `u`. `make_certain()`. Note that relying on the automatic conversion can throw exceptions, which defeats the purpose of propagating uncertainty. Nevertheless, in many cases, it is hard to avoid it, for example for the `&&` and \( ||\) operators for `bool` (see below).

template<typename T >
template<class T >

Uncertain<T> CGAL::Uncertain< T >::operator* | ( | Uncertain< T > | u,
|  | Uncertain< T > | v
| ) |  |

returns the extension of the multiplication operator over `u` and `v`.

This requires `T` to have a multiplication operator as well.

## Friends And Related Function Documentation

template<class T >

T get_certain | ( | Uncertain< T > | u) |  |

related

returns `u.make_certain`().

Precondition
  `u.is_certain`().