6.11 The invalid argument exceptional–condition object

The invalid argument exceptional–condition object–type has the purpose of describing an exceptional condition caused by a wrong function argument. This condition object is meant to be used to describe unexpected exceptions: we do not really expect the argument to be invalid, but we want a fall–back just in case.

The function is meant to be used as follows:

void
do_something (cce_destination_t L, unsigned N)
{
  cce_check_argument(L, (0 == N), 1);

  /* do something with N */
}

All the following definitions are accessible from the header file ccexceptions.h.

Struct Typedef: cce_descriptor_invalid_argument_t

Structure type representing the exceptional–condition object–type descriptor. This descriptor has the descriptor cce_descriptor_logic_error_t as parent. It has the following public fields:

cce_descriptor_t descriptor

Core values of the exceptional–condition object–type descriptor.

Struct Typedef: cce_condition_invalid_argument_t

Structure type representing the exceptional–condition object. It has the following public fields:

cce_condition_logic_error_t logic_error

Core values of the exceptional–condition object.

char const * funcname

Pointer to a statically allocated ASCIIZ string representing the name of the function that raised the exception. It is usually generated with the preprocessor symbol __func__.

unsigned index

One–based index of the offending argument.

Function: cce_condition_t const * cce_condition_new_invalid_argument (cce_destination_t L, char const * func, unsigned index)

Return a pointer to a newly built exceptional–condition object of type cce_condition_invalid_argument_t. If an error occurs: raise an exception by performing a non–local exit to L.

Preprocessor Macro: void cce_check_argument (cce_destination_t L, bool EXPR, unsigned ARGNUM)

Expand to the following:

if (! (EXPR)) {
  cce_raise((L),
    cce_condition_new_invalid_argument((L), __func__, (ARGNUM)));
}

where EXPR is an expression evaluating to true if the argument is valid.

Function: bool cce_condition_is_invalid_argument (cce_condition_t const * C)

Return true if the exceptional–condition object referenced by C is of type cce_condition_invalid_argument_t or it is derived from it; otherwise return false.

Facilities to derive an exceptional–condition object subtype

When deriving a subtype from cce_condition_invalid_argument_t we need the following functions.

Function: void cce_descriptor_set_parent_to(cce_descriptor_invalid_argument_t) (cce_descriptor_t * D)

Mutate the exceptional–condition object–type descriptor referenced by D so that its parent is the descriptor of cce_descriptor_invalid_argument_t. We should call this function in the initialisation module of the derived type.

Function: void cce_condition_init_invalid_argument (cce_condition_invalid_argument_t * C, char const * func, unsigned index)

Initialise an already allocated exceptional–condition object. We should call this function from the initialisation function of the derived type.

Subtyping example

To define a subtype of cce_condition_invalid_argument_t we can copy the code in the files:

condition-subtyping-invalid-arg.c
condition-subtyping-invalid-arg-header.h
condition-subtyping-invalid-arg-body.c

under the tests directory of the source distribution; the code defines a new exceptional–condition object–type my_condition_invalid_argument_subtype_t.

This document describes version 0.9.0-devel.3 of CCExceptions.