Cantera  3.1.0a1
ctexceptions.h
Go to the documentation of this file.
1 /**
2  * @file ctexceptions.h
3  * Definitions for the classes that are
4  * thrown when %Cantera experiences an error condition
5  * (also contains errorhandling module text - see @ref errGroup).
6  */
7 
8 // This file is part of Cantera. See License.txt in the top-level directory or
9 // at https://cantera.org/license.txt for license and copyright information.
10 
11 #ifndef CT_CTEXCEPTIONS_H
12 #define CT_CTEXCEPTIONS_H
13 
14 #include "ct_defs.h"
15 #include "cantera/base/fmt.h"
16 #include <exception>
17 
18 namespace Cantera
19 {
20 
21 /**
22  * @defgroup debugGroup Errors and Diagnostics
23 */
24 
25 /**
26  * @defgroup errGroup Errors
27  *
28  * @brief Handling of errors and unknown events within %Cantera.
29  *
30  * The general idea is that exceptions are thrown using the common base class
31  * called CanteraError. Derived types of CanteraError characterize what type of
32  * error is thrown. A list of all of the thrown errors is kept in the
33  * Application class.
34  *
35  * Any exceptions which are not caught cause a fatal error exit from the
36  * program.
37  *
38  * A group of defines may be used during debugging to assert conditions which
39  * should be true. These are named AssertTrace(), AssertThrow(), and
40  * AssertThrowMsg(). Examples of their usage is given below.
41  *
42  * @code
43  * AssertTrace(p == OneAtm);
44  * AssertThrow(p == OneAtm, "Kinetics::update");
45  * AssertThrowMsg(p == OneAtm, "Kinetics::update",
46  * "Algorithm limited to atmospheric pressure");
47  * @endcode
48  *
49  * Their first argument is a boolean. If the boolean is not true, a CanteraError
50  * is thrown, with descriptive information indicating where the error occurred.
51  * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined,
52  * for example with the compiler option -DNDEBUG.
53  * @ingroup debugGroup
54  */
55 
56 
57 //! Base class for exceptions thrown by %Cantera classes.
58 /*!
59  * This class is the base class for exceptions thrown by Cantera. It inherits
60  * from std::exception so that normal error handling operations from
61  * applications may automatically handle the errors in their own way.
62  *
63  * @ingroup errGroup
64  */
65 class CanteraError : public std::exception
66 {
67 public:
68  //! Normal Constructor for the CanteraError base class
69  /*!
70  * @param procedure Name of the function within which the error was
71  * generated. For member functions, this should be written as
72  * `ClassName::functionName`. For constructors, this should be
73  * `ClassName::ClassName`. Arguments can be specified to
74  * disambiguate overloaded functions, such as
75  * `ClassName::functionName(int, int)`.
76  * @param msg Descriptive string describing the type of error message. This
77  * can be a fmt-style format string (that is, using curly braces to indicate
78  * fields), which will be used with additional arguments to generate a
79  * formatted error message
80  * @param args Arguments which will be used to interpolate the format string
81  */
82  template <typename... Args>
83  CanteraError(const string& procedure, const string& msg, const Args&... args)
84  : procedure_(procedure)
85  {
86  if (sizeof...(args) == 0) {
87  msg_ = msg;
88  } else {
89  msg_ = fmt::format(msg, args...);
90  }
91  }
92 
93  //! Destructor for base class does nothing
94  virtual ~CanteraError() throw() {};
95 
96  //! Get a description of the error
97  const char* what() const throw() override;
98 
99  //! Method overridden by derived classes to format the error message
100  virtual string getMessage() const;
101 
102  //! Get the name of the method that threw the exception
103  virtual string getMethod() const;
104 
105  //! Method overridden by derived classes to indicate their type
106  virtual string getClass() const {
107  return "CanteraError";
108  }
109 
110 protected:
111  //! Protected default constructor discourages throwing errors containing no
112  //! information.
114 
115  //! Constructor used by derived classes that override getMessage()
116  explicit CanteraError(const string& procedure);
117 
118  //! The name of the procedure where the exception occurred
119  string procedure_;
120  mutable string formattedMessage_; //!< Formatted message returned by what()
121 
122 private:
123  string msg_; //!< Message associated with the exception
124 };
125 
126 
127 //! Array size error.
128 /*!
129  * This error is thrown if a supplied length to a vector supplied to %Cantera is
130  * too small.
131  *
132  * @ingroup errGroup
133  */
135 {
136 public:
137  //! Constructor
138  /*!
139  * The length needed is supplied by the argument, reqd, and the
140  * length supplied is given by the argument sz.
141  *
142  * @param procedure String name for the function within which the error was
143  * generated.
144  * @param sz This is the length supplied to Cantera.
145  * @param reqd This is the required length needed by Cantera
146  */
147  ArraySizeError(const string& procedure, size_t sz, size_t reqd) :
148  CanteraError(procedure), sz_(sz), reqd_(reqd) {}
149 
150  string getMessage() const override;
151  string getClass() const override {
152  return "ArraySizeError";
153  }
154 
155 private:
156  size_t sz_, reqd_;
157 };
158 
159 
160 //! An array index is out of range.
161 /*!
162  * @ingroup errGroup
163  */
164 class IndexError : public CanteraError
165 {
166 public:
167  //! Constructor
168  /*!
169  * This class indicates an out-of-bounds array index.
170  *
171  * @param func String name for the function within which the error was
172  * generated.
173  * @param arrayName name of the corresponding array
174  * @param m This is the value of the out-of-bounds index.
175  * @param mmax This is the maximum allowed value of the index. The
176  * minimum allowed value is assumed to be 0.
177  */
178  IndexError(const string& func, const string& arrayName, size_t m, size_t mmax) :
179  CanteraError(func), arrayName_(arrayName), m_(m), mmax_(mmax) {}
180 
181  ~IndexError() throw() override {};
182  string getMessage() const override;
183  string getClass() const override {
184  return "IndexError";
185  }
186 
187 private:
188  string arrayName_;
189  size_t m_, mmax_;
190 };
191 
192 //! An error indicating that an unimplemented function has been called
193 //! @ingroup errGroup
195 {
196 public:
197  //! @param func Name of the unimplemented function, such as
198  //! `ClassName::functionName`
199  NotImplementedError(const string& func) :
200  CanteraError(func, "Not implemented.") {}
201 
202  //! Alternative constructor taking same arguments as CanteraError
203  template <typename... Args>
204  NotImplementedError(const string& func, const string& msg, const Args&... args) :
205  CanteraError(func, msg, args...) {}
206 
207  string getClass() const override {
208  return "NotImplementedError";
209  }
210 };
211 
212 //! Provides a line number
213 #define XSTR_TRACE_LINE(s) STR_TRACE_LINE(s)
214 
215 //! Provides a line number
216 #define STR_TRACE_LINE(s) #s
217 
218 //! Provides a string variable containing the file and line number
219 /*!
220  * This is a std:string containing the file name and the line number
221  */
222 #define STR_TRACE (string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__))
223 
224 #ifdef NDEBUG
225 #ifndef AssertTrace
226 # define AssertTrace(expr) ((void) (0))
227 #endif
228 #ifndef AssertThrow
229 # define AssertThrow(expr, procedure) ((void) (0))
230 #endif
231 #ifndef AssertThrowMsg
232 # define AssertThrowMsg(expr,procedure, ...) ((void) (0))
233 #endif
234 #else
235 
236 //! Assertion must be true or an error is thrown
237 /*!
238  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
239  * containing the file and line number, indicating where the error occurred is
240  * added to the thrown object.
241  *
242  * @param expr Boolean expression that must be true
243  *
244  * @ingroup errGroup
245  */
246 #ifndef AssertTrace
247 # define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, string("failed assert: ") + #expr))
248 #endif
249 
250 //! Assertion must be true or an error is thrown
251 /*!
252  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
253  * indicating where the error occurred is added to the thrown object.
254  *
255  * @param expr Boolean expression that must be true
256  * @param procedure Character string or std:string expression indicating the
257  * procedure where the assertion failed
258  * @ingroup errGroup
259  */
260 #ifndef AssertThrow
261 # define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, string("failed assert: ") + #expr))
262 #endif
263 
264 //! Assertion must be true or an error is thrown
265 /*!
266  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
267  * indicating where the error occurred is added to the thrown object.
268  *
269  * @param expr Boolean expression that must be true
270  * @param procedure Character string or std:string expression indicating
271  * the procedure where the assertion failed
272  * Additional arguments are passed on to the constructor for CanteraError to
273  * generate a formatted error message.
274  *
275  * @ingroup errGroup
276  */
277 #ifndef AssertThrowMsg
278 # define AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + string(":\nfailed assert: \"") + string(#expr) + string("\""), __VA_ARGS__))
279 #endif
280 
281 #endif
282 
283 //! Throw an exception if the specified exception is not a finite number.
284 //! @ingroup errGroup
285 #ifndef AssertFinite
286 # define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
287 #endif
288 
289 }
290 
291 #endif
Array size error.
Definition: ctexceptions.h:135
ArraySizeError(const string &procedure, size_t sz, size_t reqd)
Constructor.
Definition: ctexceptions.h:147
string getMessage() const override
Method overridden by derived classes to format the error message.
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:151
Base class for exceptions thrown by Cantera classes.
Definition: ctexceptions.h:66
const char * what() const override
Get a description of the error.
virtual string getMessage() const
Method overridden by derived classes to format the error message.
string formattedMessage_
Formatted message returned by what()
Definition: ctexceptions.h:120
string procedure_
The name of the procedure where the exception occurred.
Definition: ctexceptions.h:119
virtual ~CanteraError()
Destructor for base class does nothing.
Definition: ctexceptions.h:94
CanteraError()
Protected default constructor discourages throwing errors containing no information.
Definition: ctexceptions.h:113
string msg_
Message associated with the exception.
Definition: ctexceptions.h:123
virtual string getMethod() const
Get the name of the method that threw the exception.
CanteraError(const string &procedure, const string &msg, const Args &... args)
Normal Constructor for the CanteraError base class.
Definition: ctexceptions.h:83
virtual string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:106
An array index is out of range.
Definition: ctexceptions.h:165
string getMessage() const override
Method overridden by derived classes to format the error message.
IndexError(const string &func, const string &arrayName, size_t m, size_t mmax)
Constructor.
Definition: ctexceptions.h:178
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:183
An error indicating that an unimplemented function has been called.
Definition: ctexceptions.h:195
NotImplementedError(const string &func, const string &msg, const Args &... args)
Alternative constructor taking same arguments as CanteraError.
Definition: ctexceptions.h:204
NotImplementedError(const string &func)
Definition: ctexceptions.h:199
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:207
This file contains definitions of constants, types and terms that are used in internal routines and a...
Wrapper for either system-installed or local headers for fmt.
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:564