.. _macro_definitions: Macro Definitions ================= Overview ^^^^^^^^ NeoFOAM provides a set of macros for handling debug messaging, error reporting, and assertions. These macros are defined in two header files: ``Info.hpp`` and ``Error.hpp``, and offer standardized mechanisms for logging information and handling errors across the library. ``NF_DEBUG`` is active when ``CMAKE_BUILD_TYPE`` is set to ``Debug``, and ``NF_DEBUG_INFO`` is active when ``CMAKE_BUILD_TYPE`` is set to ``RelWithDebInfo``. Info.hpp ^^^^^^^^ The ``Info.hpp`` header defines macros for debug and informational messaging: - ``NF_DEBUG_MESSAGING``: Enables debug messaging if either ``NF_DEBUG`` or ``NF_DEBUG_INFO`` is defined. - ``NF_INFO`(message)``: Prints the given message to the standard output stream. - ``NF_DINFO(message)``: Prints the given debug message to the standard output stream if ``NF_DEBUG_MESSAGING`` is enabled. Example usage: .. code-block:: cpp NF_INFO("This is an informational message."); NF_DINFO("This is a debug message."); // Only prints if NF_DEBUG_MESSAGING is enabled. Error.hpp ^^^^^^^^^ The ``Error.hpp`` header defines macros for error handling and assertions: - ``NF_ERROR_EXIT(message)``: Prints an error message and aborts the program. - ``NF_THROW(message)``: Throws a ``NeoFOAMException`` with the specified error message. - ``NF_ASSERT(condition, message)``: Checks a condition and, if false, prints an error message and aborts the program. - ``NF_ASSERT_THROW(condition, message)``: Checks a condition and, if false, throws a ``NeoFOAMException``. - ``NF_DEBUG_ASSERT(condition, message)`` and ``NF_DEBUG_ASSERT_THROW(condition, message)``: Debug versions of ``NF_ASSERT`` and ``NF_ASSERT_THROW`` that are no-ops in release builds. - ``NF_DEBUG_ASSERT_THROW(condition, message)``: Debug version of ``NF_ASSERT_THROW`` that throws a ``NeoFOAMException`` if the condition is false. - ``NF_ASSERT_EQUAL(a, b)``: Asserts that two values are equal and prints an error message if they are not. - ``NF_DEBUG_ASSERT_EQUAL(a, b)``: Debug version of ``NF_ASSERT_EQUAL`` that is a no-op in release builds. - ``NF_ASSERT_EQUAL_THROW(a, b)``: Asserts that two values are equal and throws a ``NeoFOAMException`` if they are not. - ``NF_DEBUG_ASSERT_EQUAL_THROW(a, b)``: Debug version of ``NF_ASSERT_EQUAL`` that throws a ``NeoFOAMException`` if the values are not equal. - ``NF_PING()``: Used (in debug only) for determining where if the code reaches a certain file and line, purely for convenience. >>>>>>> d3ff4792 (format code) When ``NF_DEBUG_MESSAGING`` is enabled, a stack trace is generated by `cpptrace `_. Example usage: .. code-block:: cpp // Error handling NF_ERROR_EXIT("A critical error occurred."); NF_THROW("An error occurred."); // Assertions NF_ASSERT(ptr != nullptr, "Pointer should not be null."); NF_ASSERT_THROW(ptr != nullptr, "Pointer should not be null."); // Debug assertions NF_DEBUG_ASSERT(x > 0, "x should be positive."); // Only checks the condition if CMAKE_BUILD_TYPE is Debug. NF_DEBUG_ASSERT_THROW(x > 0, "x should be positive."); // Only checks the condition if CMAKE_BUILD_TYPE is Debug.