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