#include <cpl.h>
#include <string.h>

Functions
void	_clipm_priv_error_sprint_messages (char outstr, const char msg1, const char *msg2, size_t maxlen)

#define	_CLIPM_ERROR_SET_WHERE_()

#define	_CLIPM_ERROR_SET_MSG_(code, object, msg)

#define	CLIPM_TRY
	Beginning of a TRY-block. More...

#define	CLIPM_CATCH
	End of a TRY-block, beginning of a CATCH-block. More...

#define	CLIPM_ERROR_GET_NEW_SINCE_TRY(void)
	Return new CPL error code. More...

#define	CLIPM_ERROR_RECOVER_TRYSTATE(void)
	Recover the error state which was present during CLIPM_TRY (at the beginning of the try-block). More...

#define	CLIPM_ERROR_SET(code)
	Set a new error code. More...

#define	CLIPM_ERROR_SET_MSG(code, object, msg)
	Set a new error code together with a custom error message. More...

#define	CLIPM_ERROR_SET_MSG_IF_CODE(code, object, msg)
	Set a new custom error message if a certain error code is already set. More...

#define	CLIPM_ERROR_IS_SET(void)
	Return if a new CPL error is set. More...

#define	CLIPM_ERROR_IS_NONE(void)
	Return if no new CPL error is set. More...

#define	CLIPM_TRY_CHECK(condition, code, object, msg)
	Assure the condition is true, else set the respective error code, exit the TRY block, and set an error message using the object name (can be empty string) and a message. More...

#define	CLIPM_TRY_CHECK_AUTOMSG(condition, code)
	Assure the condition is true, else set the respective error code, exit the TRY block, and auto-generate an error message (re-using the condition). More...

#define	CLIPM_TRY_CHECK_ERROR_STATE(void)
	Check the CPL error state, and exit the try-block if not CPL_ERROR_NONE. More...

#define	CLIPM_TRY_ASSERT(condition)
	Assert that the given condition is fulfilled, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED. More...

#define	CLIPM_TRY_ASSERT_ERROR_STATE(void)
	Assert that the CPL error state is CPL_ERROR_NONE, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED. More...

#define	CLIPM_TRY_EXIT_WITH_ERROR(code)
	Set a new CPL error, and exit the try-block. More...

#define	CLIPM_TRY_EXIT_WITH_ERROR_MSG(code, object, msg)
	Set a new CPL error together with a custom error message, and exit the try-block. More...

#define	CLIPM_TRY_EXIT_IFN(condition)
	If condition == 0, then the try-block is exited. More...

#define	CLIPM_TRY_EXIT(void)
	The try-block is exited. More...

enum	_clipm_error_code_ { CLIPM_ERROR_UNEXPECTED = CPL_ERROR_EOL + 0 }
	Extension to CPL error codes. More...

typedef enum _clipm_error_code_	clipm_error_code
	Extension to CPL error codes. More...

const char	_CLIPM_MSG_ERR_UNEXPECTED []
	Internal error. More...

const char	_CLIPM_MSG_ERR_HANDLING []
	Internal error handling bug. More...

const char	CLIPM_MSG_ERR_2ROWXY []
	Location matrix must contain 2 rows. More...

const char	CLIPM_MSG_ERR_DIFFSIZES []
	Location matrices differ in size. More...

const char	CLIPM_MSG_ERR_DIFFTYPES []
	Location matrices differ in size. More...

Macro Definition Documentation

#define _CLIPM_ERROR_SET_MSG_	(	code,
		object,
		msg
	)

Value:

do { \
    char _clipm_error_msg[256]; \
    _clipm_priv_error_sprint_messages(      _clipm_error_msg, \
                                            object, \
                                            msg, \
                                            255); \
    cpl_error_set_message(                  __func__, \
                                            code, \
                                            "%s", _clipm_error_msg); \
    clipm_error_is_set_where = 1; \
} while (0)

#define _CLIPM_ERROR_SET_WHERE_ ( )

Value:

do { \
    if (CLIPM_ERROR_IS_SET()) \
    { \
        const char      *_msg; \
        int             _n = 0; \
        \
        _msg = cpl_error_get_message(); \
        /* search the beginning of the last custom message */ \
        while (_msg[_n] != '\0' && _msg[_n] != ':') \
            _n++; \
        while (_msg[_n] == ':' || _msg[_n] == ' ') \
            _n++; \
        cpl_error_set_message(              __func__, \
                                            cpl_error_get_code(), \
                                            "%s", _msg+_n); \
        clipm_error_is_set_where = 1; \
    } \
} while (0)

#define CLIPM_CATCH

End of a TRY-block, beginning of a CATCH-block.

Please refer to CLIPM_TRY.

#define CLIPM_ERROR_GET_NEW_SINCE_TRY ( void )

Return new CPL error code.

Returns: If the CPL error state has changed since CLIPM_TRY, the latest error code is returned, otherwise CPL_ERROR_NONE.

May be called outside TRY-block.

#define CLIPM_ERROR_IS_NONE ( void )

Return if no new CPL error is set.

Returns: If the CPL error state has changed since CLIPM_TRY, 0 returned, otherwise 1.

May be called outside TRY-block.

#define CLIPM_ERROR_IS_SET ( void )

Return if a new CPL error is set.

Returns: If the CPL error state has changed since CLIPM_TRY, 1 returned, otherwise 0.

May be called outside TRY-block.

#define CLIPM_ERROR_RECOVER_TRYSTATE ( void )

Recover the error state which was present during CLIPM_TRY (at the beginning of the try-block).

May be called outside TRY-block.

#define CLIPM_ERROR_SET ( code )

Set a new error code.

code must not be CPL_ERROR_NONE.
May be called outside TRY-block.

#define CLIPM_ERROR_SET_MSG	(	code,
		object,
		msg
	)

Set a new error code together with a custom error message.

code must not be CPL_ERROR_NONE.
May be called outside TRY-block.

#define CLIPM_ERROR_SET_MSG_IF_CODE	(	code,
		object,
		msg
	)

Set a new custom error message if a certain error code is already set.

code must not be CPL_ERROR_NONE.
May be called outside TRY-block.

#define CLIPM_TRY

Beginning of a TRY-block.

The macro CLIPM_TRY is to be used like a keyword in front of a deeper scope. This scope has to be followed by the macro CLIPM_CATCH. This means that CLIPM_TRY and CLIPM_CATCH build a frame around a code statement or a code scope, called the try-block.

The CLIPM_CATCH macro is to be followed by a statement or scope, which is only executed if a CPL error is set while reaching the CLIPM_CATCH macro, called the catch-block.

The try-block can be exited by using one of the macros below, for example with CLIPM_TRY_EXIT_WITH_ERROR(). In this case, a jump to CLIPM_CATCH is performed, and the catch-block executed if an error is set.

Note

The following constraints have to be fulfilled:

A "return" or "goto" statement inside the try-block is forbidden, because leaving the try-block without processing the CLIPM_CATCH macro will mess up the error state information. In the catch-block (which comes after the CLIPM_CATCH macro), it is allowed.
The macros require some variables, which are declared at the beginning of the CLIPM_TRY macro. Therefore it is not possible in ANSI-C to have code statements (except declarations) before the CLIPM_TRY macro. If it is required, this can be solved by putting a scope around the try-catch construct.
Only one CLIPM_TRY - CLIPM_CATCH - construct can be inside one function.

Example 1:

cpl_error_code my_func()
{
    cpl_object      *obj = NULL;
    
    CLIPM_TRY
    {
        CLIPM_TRY_EXIT_IFN(
            obj = cpl_object_new());
        
        CLIPM_TRY_EXIT_IFN(
            cpl_function(obj) == CPL_ERROR_NONE);
        
        cpl_function(obj);
        CLIPM_TRY_CHECK_ERROR_STATE();
    }
    CLIPM_CATCH
    {
    }
    cpl_object_delete(obj);
    
    return CLIPM_ERROR_GET_NEW_SINCE_TRY;
}
 * 

Example 2:

cpl_object  *my_func()
{
    cpl_object      *obj = NULL;
    
    CLIPM_TRY
    {
        CLIPM_TRY_EXIT_IFN(
            obj = cpl_object_new());
        
        CLIPM_TRY_EXIT_IFN(
            cpl_function(obj) == CPL_ERROR_NONE);
        
        cpl_function(obj);
        CLIPM_TRY_CHECK_ERROR_STATE();
    }
    CLIPM_CATCH
    {
        cpl_object_delete(obj);
        obj = NULL;
    }
    
    return obj;
}
 * 

#define CLIPM_TRY_ASSERT ( condition )

Assert that the given condition is fulfilled, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.

Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_ASSERT_ERROR_STATE ( void )

Assert that the CPL error state is CPL_ERROR_NONE, otherwise set a custom bugreport message and exit the TRY-block with error code CLIPM_ERROR_UNEXPECTED.

Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_CHECK	(	condition,
		code,
		object,
		msg
	)

Assure the condition is true, else set the respective error code, exit the TRY block, and set an error message using the object name (can be empty string) and a message.

Parameters

condition	Condition
code	Error code to be set
object	Object name (can be empty or NULL)
msg	Message (can be empty or NULL)

Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_CHECK_AUTOMSG	(	condition,
		code
	)

Assure the condition is true, else set the respective error code, exit the TRY block, and auto-generate an error message (re-using the condition).

Parameters

condition	Condition
code	Error code to be set

Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_CHECK_ERROR_STATE ( void )

Check the CPL error state, and exit the try-block if not CPL_ERROR_NONE.

Does not overwrite locally set messages.
Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_EXIT ( void )

The try-block is exited.

It is not necessary that a new error state is already set. In this case, the try-block is just exited.
Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_EXIT_IFN ( condition )

If condition == 0, then the try-block is exited.

It is assumed, that a new error state is already set if condition is 0, otherwise a custom bugreport message is set and the TRY-block is exited with error code CLIPM_ERROR_UNEXPECTED. If it is desired to instead eventually set an error here, consider using CLIPM_TRY_CHECK[_AUTOMSG] instead.
Does not overwrite locally set messages.
Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_EXIT_WITH_ERROR ( code )

Set a new CPL error, and exit the try-block.

code must not be CPL_ERROR_NONE!
Only allowed in TRY-block, forbidden in CATCH-block!

#define CLIPM_TRY_EXIT_WITH_ERROR_MSG	(	code,
		object,
		msg
	)

Set a new CPL error together with a custom error message, and exit the try-block.

code must not be CPL_ERROR_NONE!
Overwrites any message!
Only allowed in TRY-block, forbidden in CATCH-block!

Typedef Documentation

typedef enum _clipm_error_code_ clipm_error_code

Extension to CPL error codes.

Enumeration Type Documentation

enum _clipm_error_code_

Extension to CPL error codes.

Enumerator
CLIPM_ERROR_UNEXPECTED	Unexpected internal error

Function Documentation

void _clipm_priv_error_sprint_messages	(	char *	outstr,
		const char *	msg1,
		const char *	msg2,
		size_t	maxlen
	)

Variable Documentation

const char _CLIPM_MSG_ERR_HANDLING[]

Internal error handling bug.

const char _CLIPM_MSG_ERR_UNEXPECTED[]

Internal error.

const char CLIPM_MSG_ERR_2ROWXY[]

Location matrix must contain 2 rows.

const char CLIPM_MSG_ERR_DIFFSIZES[]

Location matrices differ in size.

const char CLIPM_MSG_ERR_DIFFTYPES[]