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

When `NF_DEBUG_MESSAGING` is enabled a stack trace generated by [`cpptrace`](https://github.com/gabime/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.