Cantera  2.4.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  {
83  if (sizeof...(args) == 0) {
84  msg_ = msg;
85  } else {
86  msg_ = fmt::format(msg, args...);
87  }
88  }
89 
90  //! Destructor for base class does nothing
91  virtual ~CanteraError() throw() {};
92 
93  //! Get a description of the error
94  const char* what() const throw();
95 
96  //! Method overridden by derived classes to format the error message
97  virtual std::string getMessage() const;
98 
99  //! Method overridden by derived classes to indicate their type
100  virtual std::string getClass() const {
101  return "CanteraError";
102  }
103 
104 protected:
105  //! Protected default constructor discourages throwing errors containing no
106  //! information.
108 
109  //! Constructor used by derived classes that override getMessage()
110  explicit CanteraError(const std::string& procedure);
111 
112  //! The name of the procedure where the exception occurred
113  std::string procedure_;
114  mutable std::string formattedMessage_; //!< Formatted message returned by what()
115 
116 private:
117  std::string msg_; //!< Message associated with the exception
118 };
119 
120 
121 //! Array size error.
122 /*!
123  * This error is thrown if a supplied length to a vector supplied to Cantera is
124  * too small.
125  *
126  * @ingroup errorhandling
127  */
129 {
130 public:
131  //! Constructor
132  /*!
133  * The length needed is supplied by the argument, reqd, and the
134  * length supplied is given by the argument sz.
135  *
136  * @param procedure String name for the function within which the error was
137  * generated.
138  * @param sz This is the length supplied to Cantera.
139  * @param reqd This is the required length needed by Cantera
140  */
141  ArraySizeError(const std::string& procedure, size_t sz, size_t reqd) :
142  CanteraError(procedure), sz_(sz), reqd_(reqd) {}
143 
144  virtual std::string getMessage() const;
145  virtual std::string getClass() const {
146  return "ArraySizeError";
147  }
148 
149 private:
150  size_t sz_, reqd_;
151 };
152 
153 
154 //! An array index is out of range.
155 /*!
156  * @ingroup errorhandling
157  */
158 class IndexError : public CanteraError
159 {
160 public:
161  //! Constructor
162  /*!
163  * This class indicates an out-of-bounds array index.
164  *
165  * @param func String name for the function within which the error was
166  * generated.
167  * @param arrayName name of the corresponding array
168  * @param m This is the value of the out-of-bounds index.
169  * @param mmax This is the maximum allowed value of the index. The
170  * minimum allowed value is assumed to be 0.
171  */
172  IndexError(const std::string& func, const std::string& arrayName, size_t m, size_t mmax) :
173  CanteraError(func), arrayName_(arrayName), m_(m), mmax_(mmax) {}
174 
175  virtual ~IndexError() throw() {};
176  virtual std::string getMessage() const;
177  virtual std::string getClass() const {
178  return "IndexError";
179  }
180 
181 private:
182  std::string arrayName_;
183  size_t m_, mmax_;
184 };
185 
186 //! An error indicating that an unimplemented function has been called
188 {
189 public:
190  NotImplementedError(const std::string& func) :
191  CanteraError(func, "Not implemented.") {}
192 
193  virtual std::string getClass() const {
194  return "NotImplementedError";
195  }
196 };
197 
198 //! Provides a line number
199 #define XSTR_TRACE_LINE(s) STR_TRACE_LINE(s)
200 
201 //! Provides a line number
202 #define STR_TRACE_LINE(s) #s
203 
204 //! Provides a std::string variable containing the file and line number
205 /*!
206  * This is a std:string containing the file name and the line number
207  */
208 #define STR_TRACE (std::string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__))
209 
210 #ifdef NDEBUG
211 #ifndef AssertTrace
212 # define AssertTrace(expr) ((void) (0))
213 #endif
214 #ifndef AssertThrow
215 # define AssertThrow(expr, procedure) ((void) (0))
216 #endif
217 #ifndef AssertThrowMsg
218 # define AssertThrowMsg(expr,procedure, ...) ((void) (0))
219 #endif
220 #else
221 
222 //! Assertion must be true or an error is thrown
223 /*!
224  * Assertion must be true or else a CanteraError is thrown. A diagnostic string
225  * containing the file and line number, indicating where the error occurred is
226  * added to the thrown object.
227  *
228  * @param expr Boolean expression that must be true
229  *
230  * @ingroup errorhandling
231  */
232 #ifndef AssertTrace
233 # define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, std::string("failed assert: ") + #expr))
234 #endif
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  * indicating where the error occurred is added to the thrown object.
240  *
241  * @param expr Boolean expression that must be true
242  * @param procedure Character string or std:string expression indicating the
243  * procedure where the assertion failed
244  * @ingroup errorhandling
245  */
246 #ifndef AssertThrow
247 # define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, std::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
257  * the procedure where the assertion failed
258  * Additional arguments are passed on to the constructor for CanteraError to
259  * generate a formatted error message.
260  *
261  * @ingroup errorhandling
262  */
263 #ifndef AssertThrowMsg
264 # define AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + std::string(":\nfailed assert: \"") + std::string(#expr) + std::string("\""), __VA_ARGS__))
265 #endif
266 
267 #endif
268 
269 //! Throw an exception if the specified exception is not a finite number.
270 #ifndef AssertFinite
271 # define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
272 #endif
273 
274 }
275 
276 #endif
IndexError(const std::string &func, const std::string &arrayName, size_t m, size_t mmax)
Constructor.
Definition: ctexceptions.h:172
Wrapper for either system-installed or local headers for fmt.
std::string formattedMessage_
Formatted message returned by what()
Definition: ctexceptions.h:114
Array size error.
Definition: ctexceptions.h:128
An error indicating that an unimplemented function has been called.
Definition: ctexceptions.h:187
std::string msg_
Message associated with the exception.
Definition: ctexceptions.h:117
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:113
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:107
ArraySizeError(const std::string &procedure, size_t sz, size_t reqd)
Constructor.
Definition: ctexceptions.h:141
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:145
An array index is out of range.
Definition: ctexceptions.h:158
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:8
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:100
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:177
virtual std::string getClass() const
Method overridden by derived classes to indicate their type.
Definition: ctexceptions.h:193
virtual ~CanteraError()
Destructor for base class does nothing.
Definition: ctexceptions.h:91