错误检查

[English]

公共头文件： #include "brookesia/lib_utils/check.hpp"

概述

check 提供一组统一的检查宏，用于在参数非法、表达式失败、异常抛出、 错误码异常或数值越界时执行统一处理逻辑。

特性

• 覆盖常见检查场景：nullptr、布尔条件、std::exception、esp_err_t、范围检查

• 支持多种失败处理模式：执行代码块、return、exit、goto

• 与日志系统联动，可输出失败原因与上下文信息

• 可通过配置宏切换失败处理策略（无动作、错误日志、断言）

API 参考

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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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].

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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.

参数

• 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].

参数

• 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].

参数

• 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].

参数

• 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].

参数

• 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.