CppAD: A C++ Algorithmic Differentiation Package 20110419
cppad_assert.hpp
Go to the documentation of this file.
00001 /* $Id$ */
00002 # ifndef CPPAD_ASSERT_INCLUDED
00003 # define CPPAD_ASSERT_INCLUDED
00004 
00005 /* --------------------------------------------------------------------------
00006 CppAD: C++ Algorithmic Differentiation: Copyright (C) 2003-09 Bradley M. Bell
00007 
00008 CppAD is distributed under multiple licenses. This distribution is under
00009 the terms of the 
00010                     Common Public License Version 1.0.
00011 
00012 A copy of this license is included in the COPYING file of this distribution.
00013 Please visit http://www.coin-or.org/CppAD/ for information on other licenses.
00014 -------------------------------------------------------------------------- */
00015 
00016 /*!
00017 \file cppad_assert.hpp
00018 Define the CppAD error checking macros (all of which begin with CPPAD_ASSERT_)
00019 */
00020 
00021 /*
00022 -------------------------------------------------------------------------------
00023 $begin cppad_assert$$
00024 $spell
00025         CppAD
00026         exp
00027         const
00028         bool
00029 $$
00030 
00031 $index assert, error macro $$
00032 $index error, assert macro$$
00033 $index macro, error assert$$
00034 
00035 $section CppAD Assertions During Execution$$
00036 
00037 $head Syntax$$
00038 $syntax%CPPAD_ASSERT_KNOWN(%exp%, %msg%)
00039 %$$
00040 $syntax%CPPAD_ASSERT_UNKNOWN(%exp%)%$$
00041 
00042 
00043 $head Purpose$$
00044 If the preprocessor symbol $code NDEBUG/$$ is not defined, 
00045 these CppAD macros are used to detect and report errors.
00046 They are documented here because they correspond to the C++
00047 source code that the error is reported at.
00048 
00049 $head Restriction$$
00050 The CppAD user should not uses these macros.
00051 You can however write your own macros that do not begin with $code CPPAD$$
00052 and that call the $cref/CppAD error handler/ErrorHandler/$$.
00053 
00054 $subhead Known$$
00055 $index CPPAD_ASSERT_KNOWN$$
00056 The $code CPPAD_ASSERT_KNOWN$$ macro is used to check for an error
00057 with a known cause.
00058 For example, many CppAD routines uses these macros
00059 to make sure their arguments conform to their specifications.
00060 
00061 $subhead Unknown$$
00062 $index CPPAD_ASSERT_UNKNOWN$$
00063 The $code CPPAD_ASSERT_UNKNOWN$$ macro is used to check that the 
00064 CppAD internal data structures conform as expected.
00065 If this is not the case, CppAD does not know why the error has 
00066 occurred; for example, the user may have written past the end
00067 of an allocated array.
00068 
00069 $head Exp$$
00070 The argument $italic exp$$ is a C++ source code expression
00071 that results in a $code bool$$ value that should be true.
00072 If it is false, an error has occurred.
00073 This expression may be execute any number of times 
00074 (including zero times) so it must have not side effects.
00075 
00076 $head Msg$$
00077 The argument $italic msg$$ has prototype
00078 $syntax%
00079         const char *%msg%
00080 %$$
00081 and contains a $code '\0'$$ terminated character string.
00082 This string is a description of the error 
00083 corresponding to $italic exp$$ being false.
00084 
00085 $head Error Handler$$
00086 These macros use the 
00087 $cref/CppAD error handler/ErrorHandler/$$ to report errors.
00088 This error handler can be replaced by the user.
00089 
00090 $end
00091 ------------------------------------------------------------------------------
00092 */
00093 
00094 # include <cassert>
00095 # include <iostream>
00096 # include <cppad/error_handler.hpp>
00097 
00098 
00099 /*!
00100 \def CPPAD_ASSERT_KNOWN(exp, msg)
00101 Check that \a exp is true, if not print \a msg and terminate execution.
00102 
00103 The C++ expression \a exp is expected to be true.
00104 If it is false,
00105 the CppAD use has made an error that is described by \a msg.
00106 If the preprocessor symbol \a NDEBUG is not defined,
00107 and \a exp is false,
00108 this macro will report the source code line number at
00109 which this expected result occurred.
00110 In addition, it will print the specified error message \a msg.
00111 */
00112 # ifdef NDEBUG
00113 # define CPPAD_ASSERT_KNOWN(exp, msg)  // do nothing
00114 # else
00115 # define CPPAD_ASSERT_KNOWN(exp, msg)           \
00116 {       if( ! ( exp ) )                         \
00117         CppAD::ErrorHandler::Call(              \
00118                 true       ,                    \
00119                 __LINE__   ,                    \
00120                 __FILE__   ,                    \
00121                 #exp       ,                    \
00122                 msg        );                   \
00123 }
00124 # endif
00125 
00126 /*!
00127 \def CPPAD_ASSERT_UNKNOWN(exp)
00128 Check that \a exp is true, if not terminate execution.
00129 
00130 The C++ expression \a exp is expected to be true.
00131 If it is false,
00132 CppAD has detected an error but does not know the cause of the error.
00133 If the preprocessor symbol \a NDEBUG is not defined,
00134 and \a exp is false,
00135 this macro will report the source code line number at
00136 which this expected result occurred.
00137 */
00138 # ifdef NDEBUG
00139 # define CPPAD_ASSERT_UNKNOWN(exp)      // do nothing
00140 # else
00141 # define CPPAD_ASSERT_UNKNOWN(exp)              \
00142 {       if( ! ( exp ) )                         \
00143         CppAD::ErrorHandler::Call(              \
00144                 false      ,                    \
00145                 __LINE__   ,                    \
00146                 __FILE__   ,                    \
00147                 #exp       ,                    \
00148                 ""         );                   \
00149 }
00150 # endif
00151 
00152 /*!
00153 \def CPPAD_ASSERT_NARG_NRES(op, n_arg, n_res)
00154 Check that operator \a op has the specified number of of arguments and results.
00155 
00156 If \a NDEBUG is not defined and either the number of arguments 
00157 or the number of results are not as expected,
00158 execution is terminated and the source code line number is reported.
00159 */
00160 # define CPPAD_ASSERT_NARG_NRES(op, n_arg, n_res)   \
00161         CPPAD_ASSERT_UNKNOWN( NumArg(op) == n_arg ) \
00162         CPPAD_ASSERT_UNKNOWN( NumRes(op) == n_res ) 
00163         
00164 
00165 # endif