.. _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 <https://github.com/jeremy-rifkin/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.