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.