@micro-os-plus/micro-test-plus 3.2.2 → 3.2.3

package/include/micro-os-plus/micro-test-plus/function-comparators.h

@@ -0,0 +1,333 @@
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ *
+ * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
+ * released under the terms of the Boost Version 1.0 Software License,
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with declarations for the µTest++ function
+ * comparators.
+ *
+ * @details
+ * This header provides the declarations for the function comparator templates
+ * and logical operators used within the µTest++ framework. It defines the
+ * interfaces for generic and pointer-based comparison functions, including
+ * equality, non-equality, greater than, less than, and their respective
+ * logical variants. Additionally, it declares logical combinators such as
+ * conjunction (`_and`), disjunction (`_or`), and negation (`_not`), as well as
+ * a utility for safely removing constness from objects.
+ *
+ * These comparators and logical operators enable expressive and type-safe test
+ * expectations and assertions, supporting both value and pointer semantics.
+ * The underscore-prefixed logical operators are intentionally named to avoid
+ * conflicts with standard operators and provide clear, readable test
+ * expressions.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, ensuring clear separation from user code and minimising the risk
+ * of naming conflicts.
+ *
+ * The header files are organised within the
+ * `include/micro-os-plus/micro-test-plus` folder to maintain a structured and
+ * modular codebase.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_FUNCTION_COMPARATORS_H_
+#define MICRO_TEST_PLUS_FUNCTION_COMPARATORS_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpadded"
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wunknown-warning-option"
+#endif
+#endif
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic equality comparator for non-pointer types.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if the operands are
+   * equal.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  eq (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer equality comparator for any pointer types.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the pointers are
+   * equal.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  eq (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic non-equality comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if the operands are not
+   * equal.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  ne (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer non-equality comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the pointers are not
+   * equal.
+   *
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  ne (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic greater than comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if `lhs` is greater
+   * than `rhs`.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  gt (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer greater than comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the left hand side
+   * pointer is greater than the right hand side pointer.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  gt (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic greater than or equal comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   *
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if `lhs` is greater
+   * than or equal to `rhs`.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  ge (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer greater than or equal comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   *
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the left hand side
+   * pointer is greater than or equal to the right hand side pointer.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  ge (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic less than comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   *
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if `lhs` is less than
+   * `rhs`.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  lt (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer less than comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   *
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the left hand side
+   * pointer is less than the right hand side pointer.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  lt (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Generic less than or equal comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   *
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return A comparator object that evaluates to true if `lhs` is less than
+   * or equal to `rhs`.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  le (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-function-comparators
+   * @brief Pointer less than or equal comparator.
+   *
+   * @tparam Lhs_T Type of the left hand side pointer operand.
+   * @tparam Rhs_T Type of the right hand side pointer operand.
+   *
+   * @param [in] lhs Left hand side pointer operand.
+   * @param [in] rhs Right hand side pointer operand.
+   * @return A comparator object that evaluates to true if the left hand side
+   * pointer is less than or equal to the right hand side pointer.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  le (Lhs_T* lhs, Rhs_T* rhs);
+
+  /**
+   * @ingroup micro-test-plus-logical-functions
+   * @brief Generic logical **not** operation.
+   *
+   * @tparam Expr_T Type of the operand.
+   *
+   * @param [in] expr Logical expression to be negated.
+   * @return An object that evaluates to true if the operand is false.
+   */
+  template <class Expr_T>
+  [[nodiscard]] constexpr auto
+  _not (const Expr_T& expr);
+
+  /**
+   * @ingroup micro-test-plus-logical-functions
+   * @brief Generic logical **and** operation.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   *
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return An object that evaluates to true if both operand expressions are
+   * true.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  _and (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-logical-functions
+   * @brief Generic logical **or** operation.
+   *
+   * @tparam Lhs_T Type of the left hand side operand.
+   * @tparam Rhs_T Type of the right hand side operand.
+   *
+   * @param [in] lhs Left hand side operand.
+   * @param [in] rhs Right hand side operand.
+   * @return An object that evaluates to true if at least one of the operand
+   * expressions is true.
+   */
+  template <class Lhs_T, class Rhs_T>
+  [[nodiscard]] constexpr auto
+  _or (const Lhs_T& lhs, const Rhs_T& rhs);
+
+  /**
+   * @ingroup micro-test-plus-utility-functions
+   * @brief Generic mutator to remove const qualification from any type.
+   *
+   * @tparam T The type of the input object.
+   *
+   * @param [in] t The object from which to remove const qualification.
+   * @return A non-const reference to the input object.
+   */
+  template <class T>
+  [[nodiscard]] constexpr auto
+  mut (const T& t) noexcept -> T&;
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_FUNCTION_COMPARATORS_H_
+
+// ----------------------------------------------------------------------------

package/include/micro-os-plus/micro-test-plus/inlines/details-inlines.h

@@ -0,0 +1,172 @@
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ *
+ * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
+ * released under the terms of the Boost Version 1.0 Software License,
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with inline implementations for the µTest++
+ * internals.
+ *
+ * @details
+ * This header provides the inline implementations for internal components of
+ * the µTest++ framework, including operator overloads and constructors for
+ * deferred reporting mechanisms.
+ *
+ * It defines the logic for accumulating expectation messages, handling both
+ * arithmetic and string-like types, as well as the construction and
+ * destruction behaviour of deferred reporters, ensuring that test outcomes are
+ * accurately captured and reported.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus::detail`
+ * namespace, ensuring clear separation from user code and minimising the risk
+ * of naming conflicts.
+ *
+ * The header files are organised within the
+ * `include/micro-os-plus/micro-test-plus` folder to maintain a structured and
+ * modular codebase.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_DETAILS_INLINES_H_
+#define MICRO_TEST_PLUS_DETAILS_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <stdio.h>
+#include <cstring>
+// #include "test-reporter.h"
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
+#endif
+#endif
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  namespace detail
+  {
+    // ------------------------------------------------------------------------
+
+    /**
+     * @details
+     * This operator overload enables the deferred reporter to accumulate
+     * expectation messages by appending the provided value to the internal
+     * message string.
+     *
+     * If the argument is of an arithmetic type, it is first converted to a
+     * string using `std::to_string` before being appended. For all other
+     * types, the value is appended directly. This ensures that both numeric
+     * and string-like messages are handled appropriately and consistently.
+     */
+    template <class T>
+    auto&
+    deferred_reporter_base::operator<< (const T& msg)
+    {
+      if constexpr (std::is_arithmetic_v<T>)
+        {
+          message_.append (std::to_string (msg));
+        }
+      else
+        {
+          message_.append (msg);
+        }
+      return *this;
+    }
+
+    // ------------------------------------------------------------------------
+
+    /**
+     * @details
+     * This constructor initialises a deferred reporter for a specific
+     * expression, capturing the evaluation result, abort status, and source
+     * location.
+     *
+     * The expression is evaluated and its boolean result is passed to the base
+     * class. The abort flag determines whether further test execution should
+     * be halted if the expectation fails. The source location provides
+     * contextual information for reporting purposes.
+     */
+    template <class Expr_T>
+    constexpr deferred_reporter<Expr_T>::deferred_reporter (
+        const Expr_T& expr, bool abort,
+        const reflection::source_location& location)
+        : deferred_reporter_base{ static_cast<bool> (expr), location },
+          expr_{ expr }
+    {
+#if 0 // defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
+      printf ("%s\n", __PRETTY_FUNCTION__);
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
+      abort_ = abort;
+    }
+
+    /**
+     * @details
+     * The destructor finalises the deferred reporting process for a test
+     * expression. If the evaluated expression is true, the reporter records a
+     * successful outcome along with any accumulated message. If the expression
+     * is false, the reporter records a failure, including the abort status,
+     * message, and source location for comprehensive reporting.
+     *
+     * This mechanism ensures that all relevant information about the test
+     * outcome is captured and reported accurately when the deferred reporter
+     * goes out of scope.
+     */
+    template <class Expr_T>
+    deferred_reporter<Expr_T>::~deferred_reporter ()
+    {
+      if (value_)
+        {
+          reporter.pass (expr_, message_);
+        }
+      else
+        {
+          reporter.fail (expr_, abort_, message_, location_);
+        }
+    }
+
+    // ------------------------------------------------------------------------
+  } // namespace detail
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_DETAILS_INLINES_H_
+
+// ----------------------------------------------------------------------------