Cantera  2.3.0
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 errorhandling).
6  */
7 
8 // This file is part of Cantera. See License.txt in the top-level directory or
9 // at http://www.cantera.org/license.txt for license and copyright information.
10 
11 #ifndef CT_CTEXCEPTIONS_H
12 #define CT_CTEXCEPTIONS_H
13 
14 #include "cantera/base/fmt.h"
15 #include <exception>
16 
17 namespace Cantera
18 {
19 
20 /*!
21  * @defgroup errorhandling Error Handling
22  *
23  * \brief These classes and related functions are used to handle errors and
24  * unknown events within Cantera.
25  *
26  * The general idea is that exceptions are thrown using the common base class
27  * called CanteraError. Derived types of CanteraError characterize what type of
28  * error is thrown. A list of all of the thrown errors is kept in the
29  * Application class.
30  *
31  * Any exceptions which are not caught cause a fatal error exit from the
32  * program.
33  *
34  * Below is an example of how to catch errors that throw the CanteraError class.
35  * In general, all Cantera C++ programs will have this basic structure.
36  *
37  * \include demo1a.cpp
38  *
39  * A group of defines may be used during debugging to assert conditions which
40  * should be true. These are named AssertTrace(), AssertThrow(), and
41  * AssertThrowMsg(). Examples of their usage is given below.
42  *
43  * @code
44  * AssertTrace(p == OneAtm);
45  * AssertThrow(p == OneAtm, "Kinetics::update");
46  * AssertThrowMsg(p == OneAtm, "Kinetics::update",
47  * "Algorithm limited to atmospheric pressure");
48  * @endcode
49  *
50  * Their first argument is a boolean. If the boolean is not true, a CanteraError
51  * is thrown, with descriptive information indicating where the error occurred.
52  * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined,
53  * e.g. with the compiler option -DNDEBUG.
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 errorhandling
64  */
65 class CanteraError : public std::exception
66 {
67 public:
68  //! Normal Constructor for the CanteraError base class
69  /*!
70  * @param procedure String name for the function within which the error was
71  * generated.
72  * @param msg Descriptive string describing the type of error message. This
73  * can be a fmt-style format string (i.e. using curly braces to indicate
74  * fields), which will be used with additional arguments to generate a
75  * formatted error message
76  * @param args Arguments which will be used to interpolate the format string
77  */
78  template <typename... Args>
79  CanteraError(const std::string& procedure, const std::string& msg,
80  const Args&... args)
81  : procedure_(procedure)
82  , saved_(false)
83  {
84  if (sizeof...(args) == 0) {
85  msg_ = msg;
86  } else {
87  msg_ = fmt::format(msg, args...);
88  }
89  }
90 
91  //! Destructor for base class does nothing
92  virtual ~CanteraError() throw() {};
93 
94  //! Get a description of the error
95  const char* what() const throw();
96 
97  //! Function to put this error onto Cantera's error stack
98  //! @deprecated Unused. To be removed after Cantera 2.3.
99  void save();
100 
101  //! Method overridden by derived classes to format the error message
102  virtual std::string getMessage() const;
103 
104  //! Method overridden by derived classes to indicate their type
105  virtual std::string getClass() const {
106  return "CanteraError";
107  }
108 
109 protected:
110  //! Protected default constructor discourages throwing errors containing no
111  //! information.
112  CanteraError() : saved_(false) {};
113 
114  //! Constructor used by derived classes that override getMessage()
115  explicit CanteraError(const std::string& procedure);
116 
117  //! The name of the procedure where the exception occurred
118  std::string procedure_;
119  mutable std::string formattedMessage_; //!< Formatted message returned by what()
120 
121 private:
122  std::string msg_; //!< Message associated with the exception
123  bool saved_; //!< Exception has already been saved to Cantera's error stack
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 errorhandling
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 std::string& procedure, size_t sz, size_t reqd) :
148  CanteraError(procedure), sz_(sz), reqd_(reqd) {}
149 
150  virtual std::string getMessage() const;
151  virtual std::string getClass() const {
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 errorhandling
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 std::string& func, const std::string& arrayName, size_t m, size_t mmax) :
179  CanteraError(func), arrayName_(arrayName), m_(m), mmax_(mmax) {}
180 
181  virtual ~IndexError() throw() {};
182  virtual std::string getMessage() const;
183  virtual std::string getClass() const {
184  return "IndexError";
185  }
186 
187 private:
188  std::string arrayName_;
189  size_t m_, mmax_;
190 };
191 
192 //! An error indicating that an unimplemented function has been called
194 {
195 public:
196  NotImplementedError(const std::string& func) :
197  CanteraError(func, "Not implemented.") {}
198 
199  virtual std::string getClass() const {
200  return "NotImplementedError";
201  }
202 };
203 
204 //! Provides a line number
205 #define XSTR_TRACE_LINE(s) STR_TRACE_LINE(s)
206 
207 //! Provides a line number
208 #define STR_TRACE_LINE(s) #s
209 
210 //! Provides a std::string variable containing the file and line number
211 /*!
212  * This is a std:string containing the file name and the line number
213  */
214 #define STR_TRACE (std::string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__))
215 
216 #ifdef NDEBUG
217 #ifndef AssertTrace
218 # define AssertTrace(expr) ((void) (0))
219 #endif
220 #ifndef AssertThrow
221 # define AssertThrow(expr, procedure) ((void) (0))
222 #endif
223 #ifndef AssertThrowMsg
224 # define AssertThrowMsg(expr,procedure, ...) ((void) (0))
225 #endif
226 #else
227 
228 //! Assertion must be true or an error is thrown
229 /*!
230  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
231  * containing the file and line number, indicating where the error occurred is
232  * added to the thrown object.
233  *
234  * @param expr Boolean expression that must be true
235  *
236  * @ingroup errorhandling
237  */
238 #ifndef AssertTrace
239 # define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr))
240 #endif
241 
242 //! Assertion must be true or an error is thrown
243 /*!
244  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
245  * indicating where the error occurred is added to the thrown object.
246  *
247  * @param expr Boolean expression that must be true
248  * @param procedure Character string or std:string expression indicating the
249  * procedure where the assertion failed
250  * @ingroup errorhandling
251  */
252 #ifndef AssertThrow
253 # define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, std::string("failed assert: ") + #expr))
254 #endif
255 
256 //! Assertion must be true or an error is thrown
257 /*!
258  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
259  * indicating where the error occurred is added to the thrown object.
260  *
261  * @param expr Boolean expression that must be true
262  * @param procedure Character string or std:string expression indicating
263  * the procedure where the assertion failed
264  * Additional arguments are passed on to the constructor for CanteraError to
265  * generate a formatted error message.
266  *
267  * @ingroup errorhandling
268  */
269 #ifndef AssertThrowMsg
270 # define AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + std::string(":\nfailed assert: \"") + std::string(#expr) + std::string("\""), __VA_ARGS__))
271 #endif
272 
273 #endif
274 
275 //! Throw an exception if the specified exception is not a finite number.
276 #ifndef AssertFinite
277 # define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
278 #endif
279 
280 }
281 
282 #endif
IndexError(const std::string &func, const std::string &arrayName, size_t m, size_t mmax)
Constructor.
Definition: ctexceptions.h:178
Wrapper for either system-installed or local headers for fmt.
std::string formattedMessage_
Formatted message returned by what()
Definition: ctexceptions.h:119
bool saved_
Exception has already been saved to Cantera&#39;s error stack.
Definition: ctexceptions.h:123
Array size error.
Definition: ctexceptions.h:134
An error indicating that an unimplemented function has been called.
Definition: ctexceptions.h:193
std::string msg_
Message associated with the exception.
Definition: ctexceptions.h:122
virtual std::string getMessage() const
Method overridden by derived classes to format the error message.
const char * what() const
Get a description of the error.
STL namespace.
virtual std::string getMessage() const
Method overridden by derived classes to format the error message.
virtual std::string getMessage() const
Method overridden by derived classes to format the error message.
std::string procedure_
The name of the procedure where the exception occurred.
Definition: ctexceptions.h:118
Base class for exceptions thrown by Cantera classes.
Definition: ctexceptions.h:65
CanteraError()
Protected default constructor discourages throwing errors containing no information.
Definition: ctexceptions.h:112
ArraySizeError(const std::string &procedure, size_t sz, size_t reqd)
Constructor.
Definition: ctexceptions.h:147
CanteraError(const std::string &procedure, const std::string &msg, const Args &... args)
Normal Constructor for the CanteraError base class.
Definition: ctexceptions.h:79
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:151
An array index is out of range.
Definition: ctexceptions.h:164
Namespace for the Cantera kernel.
Definition: application.cpp:29
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:105
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:183
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:199
void save()
Function to put this error onto Cantera&#39;s error stack.
virtual ~CanteraError()
Destructor for base class does nothing.
Definition: ctexceptions.h:92