Error Checking

Public header: #include "brookesia/lib_utils/check.hpp"

Overview

check provides unified check macros for invalid parameters, failed expressions, exceptions, error codes, and out-of-range values.

Features

Covers common cases: nullptr, booleans, std::exception, esp_err_t, ranges
Multiple failure modes: code blocks, return, exit, goto
Integrates with logging for context
Configurable failure policy (no-op, log, assert)

API Reference

Header File

utils/brookesia_lib_utils/include/brookesia/lib_utils/check.hpp

Macros

BROOKESIA_CHECK_NULL_EXECUTE(ptr, process_code, ...)

Execute a fallback code block when a pointer is null.

Parameters

ptr -- Pointer expression to test.
process_code -- Code block executed when ptr is nullptr.
... -- Compatibility arguments kept for legacy call sites and ignored in this mode.

BROOKESIA_CHECK_FALSE_EXECUTE(value, process_code, ...)

Execute a fallback code block when an expression evaluates to false.

Parameters

value -- Expression to test.
process_code -- Code block executed when value converts to false.
... -- Compatibility arguments kept for legacy call sites and ignored in this mode.

BROOKESIA_CHECK_EXCEPTION_EXECUTE(expression, process_code, ...)

Execute a fallback code block when an expression throws std::exception.

Parameters

expression -- Expression to evaluate inside a try block.
process_code -- Code block executed when expression throws std::exception.
... -- Compatibility arguments kept for legacy call sites and ignored in this mode.

BROOKESIA_CHECK_ESP_ERR_EXECUTE(esp_result, process_code, ...)

Execute a fallback code block when an ESP-IDF error code is not ESP_OK.

Parameters

esp_result -- Expression that yields an ESP-IDF error code.
process_code -- Code block executed when esp_result is not ESP_OK.
... -- Compatibility arguments kept for legacy call sites and ignored in this mode.

BROOKESIA_CHECK_OUT_RANGE_EXECUTE(value, min, max, process_code, ...)

Execute a fallback code block when a value is outside the inclusive range [min, max].

Parameters

value -- Expression to test.
min -- Inclusive lower bound.
max -- Inclusive upper bound.
process_code -- Code block executed when value is outside the range.
... -- Compatibility arguments kept for legacy call sites and ignored in this mode.

BROOKESIA_CHECK_NULL_RETURN(value, ret, fmt, ...)

Return a value when a pointer is null.

Parameters

value -- Pointer expression to test.
ret -- Value returned when value is nullptr.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_NULL_EXIT(value, fmt, ...)

Return from the current void function when a pointer is null.

Parameters

value -- Pointer expression to test.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_NULL_GOTO(value, goto_tag, fmt, ...)

Jump to a label when a pointer is null.

Parameters

value -- Pointer expression to test.
goto_tag -- Label jumped to when value is nullptr.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_FALSE_RETURN(value, ret, fmt, ...)

Return a value when an expression evaluates to false.

Parameters

value -- Expression to test.
ret -- Value returned when value converts to false.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_FALSE_EXIT(value, fmt, ...)

Return from the current void function when an expression evaluates to false.

Parameters

value -- Expression to test.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_FALSE_GOTO(value, goto_tag, fmt, ...)

Jump to a label when an expression evaluates to false.

Parameters

value -- Expression to test.
goto_tag -- Label jumped to when value converts to false.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_ESP_ERR_RETURN(value, ret, fmt, ...)

Return a value when an ESP-IDF error code is not ESP_OK.

Parameters

value -- Expression that yields an ESP-IDF error code.
ret -- Value returned when value is not ESP_OK.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_ESP_ERR_EXIT(value, fmt, ...)

Return from the current void function when an ESP-IDF error code is not ESP_OK.

Parameters

value -- Expression that yields an ESP-IDF error code.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_ESP_ERR_GOTO(value, goto_tag, fmt, ...)

Jump to a label when an ESP-IDF error code is not ESP_OK.

Parameters

value -- Expression that yields an ESP-IDF error code.
goto_tag -- Label jumped to when value is not ESP_OK.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_EXCEPTION_RETURN(expression, ret, fmt, ...)

Return a value when an expression throws std::exception.

Parameters

expression -- Expression to evaluate inside a try block.
ret -- Value returned when expression throws std::exception.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_EXCEPTION_EXIT(expression, fmt, ...)

Return from the current void function when an expression throws std::exception.

Parameters

expression -- Expression to evaluate inside a try block.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_EXCEPTION_GOTO(expression, goto_tag, fmt, ...)

Jump to a label when an expression throws std::exception.

Parameters

expression -- Expression to evaluate inside a try block.
goto_tag -- Label jumped to when expression throws std::exception.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_OUT_RANGE(value, min, max, fmt, ...)

Log when a value is outside the inclusive range [min, max].

Parameters

value -- Expression to test.
min -- Inclusive lower bound.
max -- Inclusive upper bound.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_OUT_RANGE_RETURN(value, min, max, ret, fmt, ...)

Return a value when a value is outside the inclusive range [min, max].

Parameters

value -- Expression to test.
min -- Inclusive lower bound.
max -- Inclusive upper bound.
ret -- Value returned when value is outside the range.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_OUT_RANGE_EXIT(value, min, max, fmt, ...)

Return from the current void function when a value is outside the inclusive range [min, max].

Parameters

value -- Expression to test.
min -- Inclusive lower bound.
max -- Inclusive upper bound.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.

BROOKESIA_CHECK_OUT_RANGE_GOTO(value, min, max, goto_tag, fmt, ...)

Jump to a label when a value is outside the inclusive range [min, max].

Parameters

value -- Expression to test.
min -- Inclusive lower bound.
max -- Inclusive upper bound.
goto_tag -- Label jumped to when value is outside the range.
fmt -- User log format string forwarded to BROOKESIA_LOGE.
... -- Optional format arguments for fmt.