cgal/STL_Extension/doc_tex/STL_Extension_ref/Uncertain.tex

%% =============================================================================
%% The CGAL Reference Manual
%% Chapter: STL Extensions - The Reference Part
%% -----------------------------------------------------------------------------
%% author: Sylvain Pion
%% -----------------------------------------------------------------------------
%% $Id$
%% $URL$
%% =============================================================================

%% +=========================================================================+

\begin{ccRefClass}{Uncertain<T>}

\ccDefinition

An object of the class \ccClassTemplateName\ represents an uncertainty on the
value of type \ccc{T}.  This uncertainty is represented by a non-empty range of
values of type \ccc{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.  \ccc{Uncertain<T>} allows
just that.

\ccc{Uncertain<T>} is also meant to be used as a drop-in replacement for
\ccc{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 \ccc{Uncertain<bool>} for example, or the operations on
enumeration types.

\ccc{Uncertain<T>} is used in CGAL as the return type of geometric predicates
when the number type used is interval arithmetic like \ccc{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
\ccc{Filtered_predicate}, know about it.

Note concerning \cgal\ assertions: assertions checking an expression of type
\ccc{Uncertain<bool>} will trigger an assertion failure only if the assertion
is certainly \ccc{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 \ccc{boost::tribool}.

  \ccInclude{CGAL/Uncertain.h}

  %% +-----------------------------------+
  \ccParameters

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

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

% TODO : the internal::Minmax_traits should be documented (and renamed before that).

  %% +-----------------------------------+
  \ccTypes
  \ccSetThreeColumns{static Uncertain<T>}{l.swap( l1)xxxxxxxxxxxx;}{}
  \ccPropagateThreeToTwoColumns

  \ccNestedType{value_type}{The type \ccc{T}.}

  \ccNestedType{Uncertain_conversion_exception}{The type of the exception
  thrown for uncertain conversions.  It is a typedef to the type
  \ccc{CGAL::Uncertain_conversion_exception} which derives from \ccc{std::range_error}.}

  %% +-----------------------------------+
  \ccCreation
  \ccCreationVariable{u}

  \ccConstructor{Uncertain();}
  {introduces a certain object with value \ccc{T()}.}

  \ccConstructor{Uncertain(T t);}
  {introduces a certain object with value \ccc{t}.}

  \ccMethod{Uncertain& operator=(T t);}
  {assigns the certain value \ccc{t} to \ccVar.}

  \ccConstructor{Uncertain(T i, T s);}
  {introduces an object representing the range with lower bound \ccc{i} and
  upper bound \ccc{s}. \ccPrecond $ i<= s$. }

  %% +-----------------------------------+
  \ccHeading{Access Functions}

  The following functions are meant to be used very rarely, they provide ways to inspect
  the content of an \ccc{Uncertain<T>} object.

  % \def\ccTagRmTrailingConst{\ccFalse}
  \ccMethod{T inf() const;}
  {returns the lower bound of the range represented by~\ccVar.}

  \ccGlue\ccMethod{T sup() const;}
  {returns the upper bound of the range represented by~\ccVar.}

  \ccGlue\ccMethod{bool is_same(Uncertain u) const;}
  {returns true whether \ccVar\ and \ccc{u} are the same range (equality as sets).}

  %% +-----------------------------------+
  \ccHeading{Uncertainty testing and conversion}

  There are several ways to extract the content of an \ccc{Uncertain} object.  The simplest way is to
  rely on the implicit conversion from \ccc{Uncertain<T>} to \ccc{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:

\begin{ccExampleCode}
  Uncertain<bool> b = ...;
  if (is_certain(b))
    bool cert_b = get_certain(b); // Extract the certain bool it contains
    ...
  else
    ... // b is indeterminate
\end{ccExampleCode}

Another option is :

\begin{ccExampleCode}
  Uncertain<bool> b = ...;
  if (certainly(b))
    ... // b is certainly true
  else if (certainly_not(b))
    ... // b is certainly false
  else
    ... // b is indeterminate
\end{ccExampleCode}

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

  \ccMethod{bool is_certain() const;}
  {returns \ccc{true} iff the value is certain, that is, it is unique, the range
   is a singleton. That is, \ccc{u.inf() == u.sup()}.}

  \ccMethod{T make_certain() const;}
  {if \ccVar.\ccc{is_certain()}, then returns the certain value which is represented.
   Otherwise, throws an exception of type \ccc{Uncertain_conversion_exception}.
   A profile counter of the number of such exceptions thrown during the execution of
   the program is available with \ccc{CGAL_PROFILE}.}

  \ccMethod{operator T() const;}
  {conversion operator to \ccc{T}.  It does and returns the same thing as
   \ccVar.\ccc{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
   \ccc{&&} and $||$ operators for \ccc{bool} (see below).}

  %% +-----------------------------------+
  \ccHeading{Static member function}

  \def\ccTagRmEigenClassName{\ccFalse}
  \ccFunction{static Uncertain<T> Uncertain<T>::indeterminate();}
  {returns an indeterminate range.}

  %% +-----------------------------------+
  \ccHeading{Free functions}

  \ccFunction{template <class T> T inf(Uncertain<T> u);}
  {returns \ccc{u.inf()}.}

  \ccFunction{template <class T> T sup(Uncertain<T> u);}
  {returns \ccc{u.sup()}.}

  \ccFunction{template <class T> bool is_certain(T t);}
  {returns \ccc{true}.}

  \ccFunction{template <class T> bool is_certain(Uncertain<T> u);}
  {returns \ccc{u}.\ccc{is_certain}().}

  \ccFunction{template <class U> U indeterminate();}
  {returns \ccc{U::indeterminate()} if \ccc{U} is \ccc{Uncertain<T>},
   and \ccc{U()} otherwise.}

  \ccFunction{template <class T> bool is_indeterminate(T u);}
  {returns \ccc{false}.}

  \ccFunction{template <class T> bool is_indeterminate(Uncertain<T> u);}
  {returns \ccc{!is_certain(u)}.}

  \ccFunction{template <class T> T get_certain(T t);}
  {returns \ccc{t}.}

  \ccFunction{template <class T> T get_certain(Uncertain<T> u);}
  {returns \ccc{u}.\ccc{make_certain}().  \ccPrecond \ccc{u}.\ccc{is_certain}().}

  \ccFunction{template <class T> T make_certain(T t);}
  {returns \ccc{t}.}

  \ccFunction{template <class T> T make_certain(Uncertain<T> u);}
  {returns \ccc{u}.\ccc{make_certain}().}

  \ccFunction{template <class T> Uncertain<T> make_uncertain(T t);}
  {returns \ccc{Uncertain<T>(u)}.}

  \ccFunction{template <class T> Uncertain<T> make_uncertain(Uncertain<T> u);}
  {returns \ccc{u}.}

  %% +-----------------------------------+
  \ccHeading{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 \ccc{T}.

  \ccFunction{template <class T>
              Uncertain<bool> operator==(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the equality operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator==(Uncertain<T> u, T v);}
  {returns \ccc{u == make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator==(T u, Uncertain<T> v);}
  {returns \ccc{v == u}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator!=(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the inequality operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator!=(Uncertain<T> u, T v);}
  {returns \ccc{u != make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator!=(T u, Uncertain<T> v);}
  {returns \ccc{v != u}.}

  %% +-----------------------------------+
  \ccHeading{Overloaded operators for \ccc{Uncertain<bool>} only}

  \ccFunction{Uncertain<bool> operator!(Uncertain<bool> u);}
  {returns the range containing the negated values of \ccc{u}.}

  \ccFunction{Uncertain<bool> operator|(Uncertain<bool> u, Uncertain<bool> v);}
  {returns the range containing the values computed as logical or from \ccc{u} and \ccc{v}.}

  \ccFunction{Uncertain<bool> operator|(Uncertain<bool> u, bool v);}
  {returns \ccc{u | make_uncertain(v)}.}

  \ccFunction{Uncertain<bool> operator|(bool u, Uncertain<bool> v);}
  {returns \ccc{v | u}.}

  \ccFunction{Uncertain<bool> operator&(Uncertain<bool> u, Uncertain<bool> v);}
  {returns the range containing the values computed as logical and from \ccc{u} and \ccc{v}.}

  \ccFunction{Uncertain<bool> operator&(Uncertain<bool> u, bool v);}
  {returns \ccc{u & make_uncertain(v)}.}

  \ccFunction{Uncertain<bool> operator&(bool u, Uncertain<bool> v);}
  {returns \ccc{v & u}.}

  Note : the logical operators $\&\&$ and $||$ are not overloaded on purpose.  The reason
  is that, when \ccc{f() && g()} is evaluated and they return \ccc{bool}, then \ccc{g()}
  is only evaluated when \ccc{f()} returns \ccc{true}.  One could have a dependency so
  that \ccc{g()} has an internal precondition that required that \ccc{f()} had returned \ccc{true}.
  The overloaded operators for user-defined types can not provide this short-circuiting
  property, and so, if the overloaded operators where provided, then \ccc{g()} would
  be evaluated, no matter the result of \ccc{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 :

\begin{ccExampleCode}
  // Logical AND
  if ( (p.x() == 0) && (p.y() == 0) )
    ...
  else
    ...

  // Logical OR
  if ( (q.x() == 0) || (q.y() == 0) )
    ...
  else
    ...
\end{ccExampleCode}

  One can do, for example :

\begin{ccExampleCode}
  // 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
\end{ccExampleCode}

  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 \ccc{CGAL_AND} and \ccc{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).

\begin{ccExampleCode}
  // 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
\end{ccExampleCode}

  For convenience, the macros \ccc{CGAL_AND_3} and \ccc{CGAL_OR_3} are also
  provided to support boolean operations with 3 arguments instead of 2.


  %% +-----------------------------------+
  \ccHeading{Overloaded operators and functions for \ccc{Uncertain<enum T>} only}

  \ccFunction{template <class T>
              Uncertain<bool> operator<(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the less-than operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator<(Uncertain<T> u, T v);}
  {returns \ccc{u < make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator<(T u, Uncertain<T> v);}
  {returns \ccc{make_uncertain(u) < v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the greater-than operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>(Uncertain<T> u, T v);}
  {returns \ccc{u > make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>(T u, Uncertain<T> v);}
  {returns \ccc{make_uncertain(u) > v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator<=(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the less-than or equal operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator<=(Uncertain<T> u, T v);}
  {returns \ccc{u <= make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator<=(T u, Uncertain<T> v);}
  {returns \ccc{make_uncertain(u) <= v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>=(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the greater-than or equal operator over \ccc{u} and \ccc{v}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>=(Uncertain<T> u, T v);}
  {returns \ccc{u > make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<bool> operator>=(T u, Uncertain<T> v);}
  {returns \ccc{make_uncertain(u) >= v}.}

  \ccFunction{template <class T>
              Uncertain<T> operator*(Uncertain<T> u, Uncertain<T> v);}
  {returns the extension of the multiplication operator over \ccc{u} and \ccc{v}.
   This requires \ccc{T} to have a multiplication operator as well.}

  \ccFunction{template <class T>
              Uncertain<T> operator*(Uncertain<T> u, T v);}
  {returns \ccc{u * make_uncertain(v)}.}

  \ccFunction{template <class T>
              Uncertain<T> operator<(T u, Uncertain<T> v);}
  {returns \ccc{make_uncertain(u) * v}.}

  \ccFunction{template <class T>
              Uncertain<T> operator-(Uncertain<T> u);}
  {returns the extension of the unary minus operator over \ccc{u}.}

  \ccFunction{template <class T, class U>
              Uncertain<T> enum_cast(Uncertain<U> u);}
  {returns the extension of the \ccc{enum_cast<T>} function over \ccc{u}.}

  %% +-----------------------------------+
  \ccHeading{Other free functions for \ccc{Uncertain<bool>}}

  \ccFunction{bool certainly(Uncertain<bool> u);}
  {returns \ccc{true} iff \ccVar.\ccc{is_certain()}, and the \ccVar.\ccc{make_certain}()
   returns \ccc{true}.}

  \ccFunction{bool certainly(bool u);}
  {returns \ccc{u}.}

  \ccFunction{bool possibly(Uncertain<bool> u);}
  {returns \ccc{true} iff \ccVar.\ccc{is_certain()} returns \ccc{false}, or if
   \ccVar.\ccc{make_certain}() returns \ccc{true}.}

  \ccFunction{bool possibly(bool u);}
  {returns \ccc{u}.}

  \ccFunction{bool certainly_not(Uncertain<bool> u);}
  {returns \ccc{true} iff \ccVar.\ccc{is_certain()}, and the \ccVar.\ccc{make_certain}()
   returns \ccc{false}.}

  \ccFunction{bool certainly_not(bool u);}
  {returns \ccc{!u}.}

  \ccFunction{bool possibly_not(Uncertain<bool> u);}
  {returns \ccc{true} iff \ccVar.\ccc{is_certain()} returns \ccc{false}, or if
   \ccVar.\ccc{make_certain}() returns \ccc{false}.}

  \ccFunction{bool possibly_not(bool u);}
  {returns \ccc{!u}.}


\ccSeeAlso
\ccc{CGAL::Interval_nt<bool>}

\end{ccRefClass}

\ccParDims