cantera/Cantera/src/ctexceptions.h

/**
 * @file ctexceptions.h
 *   Definitions for the classes that are
 *   thrown when %Cantera experiences an error condition 
 *   (also contains errorhandling module text - see \ref errorhandling).
 */

/*
 *  $Author$
 *  $Date$
 *  $Revision$
 */

// Copyright 2001  California Institute of Technology

#ifndef CT_CTEXCEPTIONS_H
#define CT_CTEXCEPTIONS_H

#include <string>

// See file misc.cpp for implementations of methods/functions declared
// here.

namespace Cantera {

  /*!
   * @defgroup errorhandling Error Handling
   *
   * \brief These classes and related functions are used to handle errors and 
   *        unknown events within Cantera.
   * 
   *  The general idea is that exceptions are thrown using the common
   *  base class called CanteraError. Derived types of CanteraError
   *  characterize what type of error is thrown. A list of all
   *  of the thrown errors is kept in the Application class. 
   *
   *  Any exceptions which are not caught cause a fatal error exit
   *  from the program.
   *
   *  Below is an example of how to catch errors that throw the CanteraError class.
   *  In general, all Cantera C++ programs will have this basic structure.
   * 
   *  \include edemo.cpp
   *
   *  The function showErrors() will print out the fatal error condition to standard output. 
   *
   *  A group of defines may be used during debugging to assert conditions which should
   *  be true. These are named AssertTrace(), AssertThrow(), and AssertThrowMsg().
   *  Examples of their usage is given below.
   *
   * @code
   *       AssertTrace(p == OneAtm);
   *       AssertThrow(p == OneAtm, "Kinetics::update");
   *       AssertThrowMsg(p == OneAtm, "Kinetics::update", "Algorithm limited to atmospheric pressure");
   * @endcode
   *
   *  Their first argument is a boolean. If the boolean is not true, a CanteraError is thrown, with 
   *  descriptive information indicating where the error occured. These functions may be eliminated
   *  from the source code, if the -DNDEBUG option is specified to the compiler.
   *
   */
  
    
  //! Base class for exceptions thrown by Cantera classes.
  /*!
   * This class is the base class for exceptions thrown by Cantera.
   *
   * @ingroup errorhandling
   */
  class CanteraError {
  public:
    //! Normal Constructor for the CanteraError base class
    /*!
     * This class doesn't have any storage associated with it. In its
     * constructor, a call to the Application class is made to store
     * the strings associated with the generated error condition.
     *
     * @param proc String name for the function within which the error was
     *             generated.
     * @param msg  Descriptive string describing the type of error message.
     */
    CanteraError(std::string proc, std::string msg);

    //! Destructor for base class does nothing
    virtual ~CanteraError(){}
  protected:
    //! Empty base constructor is made protected so that it may be used only by 
    //! inherited classes.
    /*!
     *  We want to discourage throwing an error containing no information.
     */
    CanteraError() {}
  };

  //! Array size error.
  /*!
   *  This error is thrown if a supplied length to a vector supplied
   *  to Cantera is too small.
   *
   * @ingroup errorhandling
   */
  class ArraySizeError : public CanteraError {
  public:
    //! Constructor
    /*!
     * The length needed is supplied by the argument, reqd, and the
     * length supplied is given by the argument sz.
     *
     * @param proc String name for the function within which the error was
     *             generated.
     * @param sz   This is the length supplied to Cantera.
     * @param reqd This is the required length needed by Cantera
     */
    ArraySizeError(std::string proc, int sz, int reqd);
  };

  //! An element index is out of range.
  /*!
   *
   * @ingroup errorhandling
   */
  class ElementRangeError : public CanteraError {
  public:
    //! Constructor
    /*!
     * This class indicates an out-of-bounds index.
     *
     * @param func String name for the function within which the error was
     *             generated.
     * @param m   This is the value of the out-of-bounds index.
     * @param mmax This is the maximum allowed value of the index. The
     *             minimum allowed value is assumed to be 0.
     */
    ElementRangeError(std::string func, int m, int mmax);
  };

  //! Print a warning when a deprecated method is called.
  /*!
   * These methods are slated to go away in future releases of Cantera.
   * The developer should work towards eliminating the use of these
   * methods in the near future.
   *
   * @param classnm Class the method belongs to
   * @param oldnm Name of the deprecated method
   * @param newnm Name of the method users should use instead
   *
   * @ingroup errorhandling
   */
  void deprecatedMethod(std::string classnm, std::string oldnm, std::string newnm);

  //! Throw an error condition for a procedure that has been removed.
  /*!
   *  
   * @param func String name for the function within which the error was
   *             generated.
   * @param version Version of Cantera that first removed this function.
   *
   * @ingroup errorhandling 
   */
  void removeAtVersion(std::string func, std::string version);

  //! Provides a line number
#define XSTR_TRACE_LINE(s) STR_TRACE_LINE(s)

  //! Provides a line number
#define STR_TRACE_LINE(s) #s  

  //! Provides a std::string variable containing the file and line number
  /*!
   *   This is a std:string containing the file name and the line number
   */
#define STR_TRACE   (std::string(__FILE__) +  ":" + XSTR_TRACE_LINE(__LINE__))

#ifdef NDEBUG
#  define AssertTrace(expr)                   ((void) (0))
#  define AssertThrow(expr, proc)             ((void) (0))
#  define AssertThrowMsg(expr,proc, message)  ((void) (0))
#else

  //! Assertion must be true or an error is thrown
  /*!
   * Assertion must be true or else a CanteraError is thrown. A diagnostic string containing the
   * file and line number,  indicating where the error 
   * occured is added to the thrown object.
   *
   * @param expr  Boolean expression that must be true
   *
   * @ingroup errorhandling
   */
#  define AssertTrace(expr)         ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr))

  //!  Assertion must be true or an error is thrown
  /*!
   * Assertion must be true or else a CanteraError is thrown. A diagnostic string indicating where the error 
   * occured is added to the thrown object.
   *
   * @param expr  Boolean expression that must be true
   * @param proc  Character string or std:string expression indicating the procedure where the assertion failed
   * @ingroup errorhandling
   */
#  define AssertThrow(expr, proc)   ((expr) ? (void) 0 : throw CanteraError(proc, std::string("failed assert: ") + #expr))

  //!  Assertion must be true or an error is thrown
  /*!
   * Assertion must be true or else a CanteraError is thrown. A diagnostic string indicating where the error 
   * occured is added to the thrown object.
   *
   * @param expr  Boolean expression that must be true
   * @param proc  Character string or std:string expression indicating the procedure where the assertion failed
   * @param message  Character string or std:string expression contaiing a  descriptive 
   *                 message is added to the thrown error condition.
   *
   * @ingroup errorhandling
   */
#  define AssertThrowMsg(expr, proc, message)  ((expr) ? (void) 0 : throw CanteraError(proc + std::string(": at failed assert: \"") + std::string(#expr) + std::string("\""), message))
#endif
 
}

#endif