%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  exceptions.tex        LiDIA documentation
%%
%%  This file contains the documentation of the exceptions
%%  thrown by LiDIA.
%%
%%  Copyright (c) 2002 by the LiDIA Group
%%
%%  Authors: Christoph Ludwig
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME

\CLASS{precondition_error} \dotfill exception indicating that a precondition
was not met


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT

Some \LiDIA routines enforce their preconditions. If they detect a failed
precondition check they throw a \code{precondition_error}, typically via a
call of \code{precondition_error_handler()}. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION

Class \code{precondition_error} is publicly derived from \code{basic_error} as
well as \code{std::logic_error}. It stores a textual representation of the
prototype of the function that detected the failed precondition as well as the
class or source file the function belongs to and an error message.

Furthermore, one can add arbitrary data objects together with strings
describing their name and their requirements at runtime. There are no relevant
restrictions with respect to number or type of the data objects. The added
objects can be accessed through a rudimentary vector-like interface.  

Let \code{e} be an object of type \code{precondition_error}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\TYPES

\begin{typedef}{precondition_error::size_type}
  An integral type that can hold the number of added data objects.
\end{typedef}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS

\begin{fcode}{ct}{precondition_error}{const std::string& proto,
                                      const std::string& where,
                                      const std::string& what_msg}
  Constructs a new precondition error object. The semantic of \code{where} and
  \code{what_msg} is the same as in \code{lidia_error_handler()}. When the
  constructor returns the postconditions \code{proto == e.prototype()},
  \code{where == e.offendingClass()}, \code{what_msg == e.what()},
  and \code{0 == e.noParams()} hold.
\end{fcode}

\begin{fcode}{ct}{precondition_error}{const precondition_error& pce}
  Constructs a copy of \code{pce}. The copy strategy is \emph{deep-copy},
  i.\,e.\ all added data objects will be copied, too.
\end{fcode}

\begin{fcode}{dt}{virtual ~cast_error}{}
  Frees all resources hold by this object. All added data objects will be
  destroyed. 
\end{fcode}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ASGN

\begin{fcode}{precondition_error&}{e.operator=}{
                                          const precondition_error& pce}
  Makes \code{e} a copy of \code{pce}. The copy strategy is
  \emph{deep-copy}, i.\,e.\ all added data objects will be copied, too.
  All data objects previously held by \code{e} will be freed.

  This operator offers the strong exception safety guarantee, i.\,e.\
  the state of \code{e} will only be changed if the copy succeeds. 
\end{fcode}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS

\begin{cfcode}{virtual const std::string&}{e.prototype}{}
  Returns the prototype of the function that detected the failed
  precondition.
\end{cfcode}

\begin{cfcode}{virtual const std::string&}{e.offendingClass}{}
  Returns a textual description where the error occured. Corresponds to the
  first parameter of \code{lidia_error_handler}.
\end{cfcode}

\begin{cfcode}{virtual const char*}{e.what}{}
  Returns a textual description of the error. Corresponds to the second
  parameter of \code{lidia_error_handler}.

  This method overrides \code{basic_error::what()} as well as
  \code{std::logic_error::what()} and thereby resolves any ambiguity.
\end{cfcode}

\begin{cfcode}{size_type}{e.noParams}{}
  The number of data objects added to \code{e}.
\end{cfcode}

\begin{cfcode}{std::string&}{e.paramNameStr}{size_type $n$}
  The name of the parameter added at position $n$.

  \code{paramNameStr} throws an \code{index_out_of_bounds_error} if
  $0 \leq n < \code{e.noParams()}$ does not hold.
\end{cfcode}

\begin{cfcode}{std::string&}{e.paramValueStr}{size_type $n$}
  A textual representation of the value of the parameter added at position
  $n$. If the parameter is of type \code{T}, then the representation is
  generated by a call to \code{std::ostream& operator<<(std::ostream&, const
  T& t)}.

  \code{paramValueStr} throws an \code{index_out_of_bounds_error} if
  $0 \leq n < \code{e.noParams()}$ does not hold.
\end{cfcode}

\begin{cfcode}{std::string&}{e.paramConditionStr}{size_type $n$}
  A description of the requirement on the parameter added at position
  $n$.

  \code{paramConditionStr} throws an \code{index_out_of_bounds_error} if
  $0 \leq n < \code{e.noParams()}$ does not hold.
\end{cfcode}

\begin{cfcode}{const T&}{e.paramValueStr< T >}{size_type $n$}
  The value of the parameter added at position
  $n$..

  \code{paramValueStr} throws an \code{index_out_of_bounds_error} if
  $0 \leq n < \code{e.noParams()}$ does not hold and a \code{cast_error} if
  the parameter cannot be casted to the type \code{const T}.
\end{cfcode}

\begin{cfcode}{size_type}{e.indexOf}{const std::string& paramName}
  Returns the smalles nonnegative index $n$ such that
  \code{paramName == e.paramNameStr($n$)} holds. If no such index exists,
  \code{indexOf} returns \code{e.noParams()}.
\end{cfcode}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\BASIC

\begin{cfcode}{virtual void}{e.traditional_error_handler_implementation}{
    std::string& classname, std::string& msg}
  Prints the prototype and all added parameters with their values, names, and
  requirements to \code{std::cerr}. \code{classname} and \code{msg} are set to
  \code{e.offendigClass()} and \code{e.what()}, respectively.

  The effect is that a call to \code{e.traditional_error_handler()} will yield
  the same side effects as a call to the (undocumented) function templates
  \code{lidia_error_handler< T1, \ldots, Tn >} in \LiDIA 2.0.
\end{cfcode}

\begin{fcode}{void}{precondition_error_handler< T1, \dots, Tn >}{
    const T1& para_1, const char* name_1, const char* cond_1,
    \dots,
    const Tn& para_n, const char* name_n, const char* cond_n,
    const char* proto, const char* where, const char* what_msg}
  A function template that creates a \code{precondition_error}, adds the
  parameters and their description to it and passes it on to
  \code{error_handler}. 

  \code{precondition_error_handler} is defined for up to twelve template
  arguments. If you need a spezialization that \LiDIA does not provide yet you
  can include the function template definitions from
  \code{LiDIA/precondition_error.cc}. 
\end{fcode}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
\code{lidia_error_handler, basic_error, std::bad_cast}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\WARNINGS

\LiDIA's exception hierarchy is still experimental. We may change it without
prior notice.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR

Christoph Ludwig


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: t
%%% End: 
