1 /****************************************************************************
2  * Copyright (C) 2012 by Matteo Franchin                                    *
3  *                                                                          *
4  * This file is part of Box.                                                *
5  *                                                                          *
6  *   Box is free software: you can redistribute it and/or modify it         *
7  *   under the terms of the GNU Lesser General Public License as published  *
8  *   by the Free Software Foundation, either version 3 of the License, or   *
9  *   (at your option) any later version.                                    *
10  *                                                                          *
11  *   Box is distributed in the hope that it will be useful,                 *
12  *   but WITHOUT ANY WARRANTY; without even the implied warranty of         *
13  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
14  *   GNU Lesser General Public License for more details.                    *
15  *                                                                          *
16  *   You should have received a copy of the GNU Lesser General Public       *
17  *   License along with Box.  If not, see <http://www.gnu.org/licenses/>.   *
18  ****************************************************************************/
19 
20 /**
21  * @file exception.h
22  * @brief Declaration of BoxException and related functionality.
23  *
24  * This header defines the BoxException, an object used to describe error
25  * conditions.
26  */
27 
28 #ifndef _BOX_EXCEPTION_H
29 #  define _BOX_EXCEPTION_H
30 
31 #  include <box/types.h>
32 #  include <box/print.h>
33 
34 /**
35  * Exception object.
36  */
37 typedef struct BoxException_struct BoxException;
38 
39 /**
40  * Create a new exception object.
41  */
42 BOXEXPORT BoxException *
43 BoxException_Create_Raw(char *msg);
44 
45 #define BoxException_Create(...) \
46   BoxException_Create_Raw(Box_SPrintF(__VA_ARGS__))
47 
48 /**
49  * Destroy an exception object.
50  */
51 BOXEXPORT void
52 BoxException_Destroy(BoxException *excp);
53 
54 /**
55  * @brief Show the exception to the console and destroy it.
56  *
57  * @param excp The exception.
58  * @return Whether @p excp was not NULL.
59  *
60  * If the provided exception is not NULL, then print the exception to the
61  * screen (stderr) and destroy the exception.
62  * @note This function can be used to check for an error condition and abort.
63  * See the example below.
64  *
65  * @code
66  * BoxException *exception = My_Function_Returning_Exception();
67  * if (BoxException_Check(exception))
68  *   abort();
69  * @endcode
70  */
71 BOXEXPORT BoxBool
72 BoxException_Check(BoxException *excp);
73 
74 BOXEXPORT char *
75 BoxException_Get_Str(BoxException *excp);
76 
77 #endif /* _BOX_EXCEPTION_H */
78