Error Handling » CnxError module

typedef struct CnxError CnxError

#include <include/Cnx/Error.h>

CnxError provides an extensible, configurable type for communicating recoverable errors via error codes and error message strings

Example

CnxError do_thing(i64 input, i64* restrict out) {
    // do things ...
    if(errno) {
        return cnx_error_new(errno, CNX_POSIX_ERROR_CATEGORY);
    }
    else {
        *out = 42;
        return cnx_error_new(0, CNX_POSIX_ERROR_CATEGORY);
    }
}

void func(void) {
    i64 i = 0;
    let maybe_err = do_thing(10, &i);
    if(cnx_error_code(&maybe_err) != 0) {
        // handle error ...
    }
    // do other things...
}

In most cases, CnxError would be used in tandem with CnxResult(T) to enable concise error handling without having to use "out" parameters.

Trait(CnxErrorCategory, const_cstring(*)(const CnxErrorCategory*restrict self, i64 code) message;i64(*)(const CnxErrorCategory*restrict self) get_last_error;)

#include <include/Cnx/Error.h>

CnxErrorCategory is a Trait that provides the mechanism to convert an arbitrary error code into a corresponding message associated with a specific class of errors, and to get the last error that occurred in a particular category (if supported by the category. For example, global categories like CNX_WIN32_ERROR_CATEGORY and CNX_POSIX_ERROR_CATEGORY support this, but categories local to specific modules probably won't).

CnxErrorCategory is what allows a CnxError to communicate error messages unique to the module the error originated from.

CnxError cnx_error_new(i64 error_code, CnxErrorCategory error_category)

#include <include/Cnx/Error.h>

Creates a CnxError with the given error code and category.

i64 cnx_error_code(const CnxError*restrict self)

#include <include/Cnx/Error.h>

Returns the error code associated with the given error.

const_cstring cnx_error_message(const CnxError*restrict self)

#include <include/Cnx/Error.h>

Returns the error message associated with the given error, as a cstring

const_cstring cnx_error_category_get_message(CnxErrorCategory self, i64 error_code)

#include <include/Cnx/Error.h>

Returns the error message associated with the given error code, as a cstring

i64 cnx_error_category_get_last_error(CnxErrorCategory self)

#include <include/Cnx/Error.h>

Returns the error code for the last reported error.

const_cstring cnx_posix_category_get_message(const CnxErrorCategory*restrict self, i64 error_code)

#include <include/Cnx/Error.h>

Returns the POSIX error message associated with the given error code, as a cstring

i64 cnx_posix_category_get_last_error(const CnxErrorCategory*restrict self)

#include <include/Cnx/Error.h>

Returns the error code for the last reported POSIX error.

static ImplTraitFor(CnxFormat, CnxError, cnx_error_is_specifier_valid, cnx_error_format, cnx_error_format_with_allocator)

#include <include/Cnx/Error.h>

Implement CnxFormat for CnxError

#define CNX_POSIX_ERROR_CATEGORY

#include <include/Cnx/Error.h>

The CnxErrorCategory to map POSIX error codes.

CNX_POSIX_ERROR_CATEGORY is the error category to map POSIX error codes to their associated error messages. It will produce equivalent results to strerror in standard C

#define CNX_DEFAULT_ERROR_CATEGORY

#include <include/Cnx/Error.h>

the default CnxErrorCategory. By default, this is CNX_POSIX_ERROR_CATEGORY

This can be overridden by defining CNX_DEFAULT_ERROR_CATEGORY to a compound literal of your chosen CnxErrorCategory prior to including <C2nxt/Error.h>