1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2002-2012, Industrial Light & Magic, a division of Lucas
4 // Digital Ltd. LLC
5 //
6 // All rights reserved.
7 //
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
10 // met:
11 // *       Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // *       Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
16 // distribution.
17 // *       Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
20 //
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 //
33 ///////////////////////////////////////////////////////////////////////////
34 
35 
36 #ifndef INCLUDED_IEXBASEEXC_H
37 #define INCLUDED_IEXBASEEXC_H
38 
39 #include "IexNamespace.h"
40 #include "IexExport.h"
41 
42 //----------------------------------------------------------
43 //
44 //	A general exception base class, and a few
45 //	useful exceptions derived from the base class.
46 //
47 //----------------------------------------------------------
48 
49 #include <string>
50 #include <exception>
51 #include <sstream>
52 
53 IEX_INTERNAL_NAMESPACE_HEADER_ENTER
54 
55 
56 //-------------------------------
57 // Our most basic exception class
58 //-------------------------------
59 
60 class BaseExc: public std::exception
61 {
62   public:
63 
64     //----------------------------
65     // Constructors and destructor
66     //----------------------------
67 
68     IEX_EXPORT BaseExc (const char *s = 0) throw();     // std::string (s)
69     IEX_EXPORT BaseExc (const std::string &s) throw();  // std::string (s)
70     IEX_EXPORT BaseExc (std::stringstream &s) throw();  // std::string (s.str())
71 
72     IEX_EXPORT BaseExc (const BaseExc &be) throw();
73     IEX_EXPORT virtual ~BaseExc () throw ();
74 
75     //---------------------------------------------------
76     // what() method -- e.what() returns _message.c_str()
77     //---------------------------------------------------
78 
79     IEX_EXPORT virtual const char * what () const throw ();
80 
81 
82     //--------------------------------------------------
83     // Convenient methods to change the exception's text
84     //--------------------------------------------------
85 
86     IEX_EXPORT BaseExc &            assign (std::stringstream &s);	// assign (s.str())
87     IEX_EXPORT BaseExc &            operator = (std::stringstream &s);
88 
89     IEX_EXPORT BaseExc &            append (std::stringstream &s);	// append (s.str())
90     IEX_EXPORT BaseExc &            operator += (std::stringstream &s);
91 
92 
93     //--------------------------------------------------
94     // These methods from the base class get obscured by
95     // the definitions above.
96     //--------------------------------------------------
97 
98     IEX_EXPORT BaseExc &            assign (const char *s);
99     IEX_EXPORT BaseExc &            operator = (const char *s);
100 
101     IEX_EXPORT BaseExc &            append (const char *s);
102     IEX_EXPORT BaseExc &            operator += (const char *s);
103 
104     //---------------------------------------------------
105     // Access to the string representation of the message
106     //---------------------------------------------------
107 
108     IEX_EXPORT const std::string &  message () const;
109 
110     //--------------------------------------------------
111     // Stack trace for the point at which the exception
112     // was thrown.  The stack trace will be an empty
113     // string unless a working stack-tracing routine
114     // has been installed (see below, setStackTracer()).
115     //--------------------------------------------------
116 
117     IEX_EXPORT const std::string &  stackTrace () const;
118 
119   private:
120 
121     std::string                     _message;
122     std::string                     _stackTrace;
123 };
124 
125 
126 //-----------------------------------------------------
127 // A macro to save typing when declararing an exception
128 // class derived directly or indirectly from BaseExc:
129 //-----------------------------------------------------
130 
131 #define DEFINE_EXC_EXP(exp, name, base)                             \
132     class name: public base                                         \
133     {                                                               \
134       public:                                                       \
135         exp name()                         throw(): base (0)    {}  \
136         exp name (const char* text)        throw(): base (text) {}  \
137         exp name (const std::string &text) throw(): base (text) {}  \
138         exp name (std::stringstream &text) throw(): base (text) {}  \
139         exp ~name() throw() { }                                     \
140     };
141 
142 // For backward compatibility.
143 #define DEFINE_EXC(name, base) DEFINE_EXC_EXP(, name, base)
144 
145 
146 //--------------------------------------------------------
147 // Some exceptions which should be useful in most programs
148 //--------------------------------------------------------
149 DEFINE_EXC_EXP (IEX_EXPORT, ArgExc, BaseExc)    // Invalid arguments to a function call
150 
151 DEFINE_EXC_EXP (IEX_EXPORT, LogicExc, BaseExc)  // General error in a program's logic,
152                                                 // for example, a function was called
153                                                 // in a context where the call does
154                                                 // not make sense.
155 
156 DEFINE_EXC_EXP (IEX_EXPORT, InputExc, BaseExc)  // Invalid input data, e.g. from a file
157 
158 DEFINE_EXC_EXP (IEX_EXPORT, IoExc, BaseExc)     // Input or output operation failed
159 
160 DEFINE_EXC_EXP (IEX_EXPORT, MathExc, BaseExc) 	// Arithmetic exception; more specific
161                                                 // exceptions derived from this class
162                                                 // are defined in ExcMath.h
163 
164 DEFINE_EXC_EXP (IEX_EXPORT, ErrnoExc, BaseExc)  // Base class for exceptions corresponding
165                                                 // to errno values (see errno.h); more
166                                                 // specific exceptions derived from this
167                                                 // class are defined in ExcErrno.h
168 
169 DEFINE_EXC_EXP (IEX_EXPORT, NoImplExc, BaseExc) // Missing method exception e.g. from a
170                                                 // call to a method that is only partially
171                                                 // or not at all implemented. A reminder
172                                                 // to lazy software people to get back
173                                                 // to work.
174 
175 DEFINE_EXC_EXP (IEX_EXPORT, NullExc, BaseExc)   // A pointer is inappropriately null.
176 
177 DEFINE_EXC_EXP (IEX_EXPORT, TypeExc, BaseExc)   // An object is an inappropriate type,
178                                                 // i.e. a dynamnic_cast failed.
179 
180 
181 //----------------------------------------------------------------------
182 // Stack-tracing support:
183 //
184 // setStackTracer(st)
185 //
186 //	installs a stack-tracing routine, st, which will be called from
187 //	class BaseExc's constructor every time an exception derived from
188 //	BaseExc is thrown.  The stack-tracing routine should return a
189 //	string that contains a printable representation of the program's
190 //	current call stack.  This string will be stored in the BaseExc
191 //	object; the string is accesible via the BaseExc::stackTrace()
192 //	method.
193 //
194 // setStackTracer(0)
195 //
196 //	removes the current stack tracing routine.  When an exception
197 //	derived from BaseExc is thrown, the stack trace string stored
198 //	in the BaseExc object will be empty.
199 //
200 // stackTracer()
201 //
202 //	returns a pointer to the current stack-tracing routine, or 0
203 //	if there is no current stack stack-tracing routine.
204 //
205 //----------------------------------------------------------------------
206 
207 typedef std::string (* StackTracer) ();
208 
209 IEX_EXPORT void        setStackTracer (StackTracer stackTracer);
210 IEX_EXPORT StackTracer stackTracer ();
211 
212 
213 IEX_INTERNAL_NAMESPACE_HEADER_EXIT
214 
215 #endif // INCLUDED_IEXBASEEXC_H
216