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

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

@@ -0,0 +1,315 @@
+/*
+ * 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++
+ * mathematical utilities.
+ *
+ * @details
+ * This header provides the inline implementations for the mathematical utility
+ * templates used within the µTest++ framework. It defines constexpr logic for
+ * common mathematical operations, including absolute value, minimum value
+ * selection, exponentiation, and compile-time parsing of numeric values from
+ * character sequences.
+ *
+ * These utilities are designed to be lightweight and suitable for embedded
+ * environments, supporting both integral and floating-point types, and
+ * enabling expressive, type-safe, and efficient compile-time computations.
+ * Special attention is given to constexpr compatibility and minimal reliance
+ * on the standard library, ensuring portability and performance.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus::math`
+ * 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_MATH_INLINES_H_
+#define MICRO_TEST_PLUS_MATH_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <cstdint>
+
+// #include "type-traits.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 math
+  {
+
+    /**
+     * @details
+     * This function template provides a generic, constexpr implementation for
+     * obtaining the absolute value of any type that supports comparison and
+     * unary negation.
+     *
+     * The function returns the non-negative value of the input. If the input
+     * is less than the default-constructed value of its type (typically zero),
+     * the negated value is returned; otherwise, the original value is
+     * returned.
+     *
+     * This utility is designed to be lightweight and suitable for embedded
+     * environments, where standard library alternatives may be unavailable,
+     * less efficient, or not constexpr.
+     */
+    template <class T>
+    [[nodiscard]] constexpr auto
+    abs (const T t) -> T
+    {
+      return t < T{} ? -t : t;
+    }
+
+    /**
+     * @details
+     * This function template provides a generic, constexpr implementation for
+     * determining the minimum of two values of any type that supports
+     * comparison.
+     *
+     * The function returns a reference to the lesser of the two input values,
+     * as determined by the `<` operator. If the second argument is less than
+     * the first, it is returned; otherwise, the first argument is returned.
+     *
+     * This utility is designed to be lightweight and suitable for embedded
+     * environments, where standard library alternatives may be unavailable,
+     * less efficient, or not constexpr.
+     */
+    template <class T>
+    [[nodiscard]] constexpr auto
+    min_value (const T& lhs, const T& rhs) -> const T&
+    {
+      return (rhs < lhs) ? rhs : lhs;
+    }
+
+    /**
+     * @details
+     * This function template provides a constexpr implementation for raising a
+     * base value to a given exponent, supporting any types that allow
+     * multiplication and subtraction.
+     *
+     * The function recursively multiplies the base by itself exponent times.
+     * If the exponent is zero, the function returns one (the multiplicative
+     * identity for the type).
+     *
+     * This utility is designed to be lightweight and suitable for embedded
+     * environments, where standard library alternatives may be unavailable,
+     * less efficient, or not constexpr.
+     */
+    template <class T, class Exp_T>
+    [[nodiscard]] constexpr auto
+    pow (const T base, const Exp_T exp) -> T
+    {
+      // If the exponent is 0, return 1, otherwise recurse.
+      return exp ? T (base * pow (base, exp - Exp_T (1))) : T (1);
+    }
+
+    /**
+     * @details
+     * This function template performs compile-time parsing of a numeric value
+     * from a sequence of characters, typically provided as a template
+     * parameter pack.
+     *
+     * The function assumes that all characters are either digits, a dot (`.`),
+     * or an apostrophe (`'`). Parsing stops at the first dot, allowing the
+     * function to extract only the integral part of the number.
+     *
+     * This utility is particularly useful for user-defined literals and other
+     * compile-time constant expressions, enabling efficient and type-safe
+     * conversion from character sequences to integral values.
+     */
+    template <class T, char... Cs>
+    [[nodiscard]] constexpr auto
+    num (void) -> T
+    {
+      // Assume all are digits or dot or apostrophe.
+      static_assert (
+          ((Cs == '.' or Cs == '\'' or (Cs >= '0' and Cs <= '9')) and ...));
+      T result{};
+      for (const char c : { Cs... })
+        {
+          if (c == '.')
+            {
+              break;
+            }
+          if (c >= '0' and c <= '9')
+            {
+              result = static_cast<T> (result * static_cast<T> (10)
+                                       + static_cast<T> (c - '0'));
+            }
+        }
+      return result;
+    }
+
+    /**
+     * @details
+     * This function template performs compile-time extraction of the decimal
+     * (fractional) part from a sequence of characters, typically provided as a
+     * template parameter pack.
+     *
+     * The function expects the character sequence to represent a numeric
+     * value, where all characters are either digits, a dot (`.`), or an
+     * apostrophe (`'`). Parsing begins after the first dot, accumulating the
+     * decimal digits as an integer value, each weighted by its decimal
+     * position.
+     *
+     * This utility is particularly useful for user-defined literals and other
+     * compile-time constant expressions, enabling efficient and type-safe
+     * conversion from character sequences to the decimal part of numeric
+     * values.
+     */
+    template <class T, char... Cs>
+    [[nodiscard]] constexpr auto
+    den (void) -> T
+    {
+      constexpr const std::array cs{ Cs... };
+      T result{};
+      auto i = 0u;
+      while (cs[i++] != '.')
+        {
+        }
+
+      for (auto j = i; j < sizeof...(Cs); ++j)
+        {
+          result += pow (T (10), sizeof...(Cs) - j) * T (cs[j] - '0');
+        }
+      return result;
+    }
+
+    /**
+     * @details
+     * This function template determines, at compile time, the number of
+     * decimal (fractional) digits present in a numeric value represented by a
+     * character sequence, typically provided as a template parameter pack.
+     *
+     * The function expects the character sequence to represent a numeric
+     * value, where all characters are either digits, a dot (`.`), or an
+     * apostrophe (`'`). It locates the first dot and counts the number of
+     * digits that follow, returning the count as the number of decimal places.
+     *
+     * This utility is particularly useful for user-defined literals and other
+     * compile-time constant expressions, enabling efficient and type-safe
+     * determination of decimal precision from character sequences.
+     */
+    template <class T, char... Cs>
+    [[nodiscard]] constexpr auto
+    den_size (void) -> T
+    {
+      constexpr const std::array cs{ Cs... };
+      T i{};
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wconversion"
+#endif
+      while (cs[i++] != '.')
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+        {
+        }
+
+      return T (sizeof...(Cs)) - i + T (1);
+    }
+
+    /**
+     * @details
+     * This function template determines, at compile time, the number of
+     * decimal (fractional) digits present in a floating-point value, up to a
+     * maximum of seven digits of precision.
+     *
+     * The function repeatedly multiplies the input value by ten, incrementing
+     * a counter until the fractional part is less than a defined precision
+     * threshold (1e-7). This approach provides a robust means of estimating
+     * decimal precision for values where exact representation is not possible
+     * due to floating-point limitations.
+     *
+     * This utility is particularly useful for user-defined literals and
+     * compile-time constant expressions, enabling efficient and type-safe
+     * determination of decimal precision from floating-point values.
+     */
+    template <class T, class Value_T>
+    [[nodiscard]] constexpr auto
+    den_size (Value_T value) -> T
+    {
+      constexpr auto precision = Value_T (1e-7);
+      T result{};
+      Value_T tmp{};
+      do
+        {
+          value *= 10;
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if !defined(__clang__) // GCC only
+#pragma GCC diagnostic ignored "-Warith-conversion"
+#endif
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wimplicit-int-float-conversion"
+#endif
+#endif
+          tmp = value - T (value);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+          ++result;
+        }
+      while (tmp > precision);
+
+      return result;
+    }
+
+    // ------------------------------------------------------------------------
+  } // namespace math
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_MATH_INLINES_H_
+
+// ----------------------------------------------------------------------------

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

@@ -0,0 +1,313 @@
+/*
+ * 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++ Testing
+ * Framework.
+ *
+ * @details
+ * This header provides the inline implementations for the principal public API
+ * functions and utilities of the µTest++ framework, including test case
+ * registration, expectation and assumption evaluation, exception verification,
+ * and utility helpers for string processing in tests.
+ *
+ * It defines the logic for registering and executing test cases, evaluating
+ * logical conditions and custom comparators, and reporting test results with
+ * detailed diagnostics. The exception verification functions enable robust
+ * testing of error handling and exception safety, while utility functions such
+ * as string splitting support flexible validation of string processing logic.
+ *
+ * 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_INLINES_H_
+#define MICRO_TEST_PLUS_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#pragma GCC diagnostic ignored "-Wpadded"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wc++98-c++11-c++14-c++17-compat-pedantic"
+#endif
+#endif
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+#if defined(__clang__)
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdocumentation"
+#endif
+  /**
+   * @details
+   * The `test_case` function template registers and executes a test case
+   * within the µTest++ framework. It accepts a descriptive name, a callable
+   * object (such as a lambda or function pointer), and an optional list of
+   * arguments to be passed to the callable. The test case is reported using
+   * the provided name, and its execution is managed by the framework's test
+   * runner.
+   *
+   * Each test case typically involves evaluating a logical expression, such as
+   * comparing a computed result to an expected value. For C++ projects, it is
+   * also possible to verify whether evaluating an expression throws
+   * exceptions. Each test either succeeds or fails, and for expectations, the
+   * test runner maintains counts of successful and failed checks.
+   *
+   * This function template enables flexible and expressive test case
+   * definitions, supporting both parameterised and non-parameterised tests. It
+   * is typically invoked at global scope or within test suite definitions to
+   * ensure automatic registration and execution.
+   *
+   * A test case is characterised by a name, a function that performs the
+   * checks, and optionally, arguments to be passed to that function. The
+   * implementation of `test_case` invokes the provided function with the given
+   * arguments and reports the results to the test runner.
+   *
+   * @par Example
+   *
+   * @code{.cpp}
+   *   namespace mt = micro_os_plus::micro_test_plus;
+   *
+   *   mt::test_case ("Check answer with comparator", [] {
+   *     mt::expect (mt::eq (compute_answer (), 42)) << "answer is 42";
+   *   });
+   * @endcode
+   */
+#if defined(__clang__)
+#pragma clang diagnostic pop
+#endif
+  template <typename Callable_T, typename... Args_T>
+  void
+  test_case (const char* name, Callable_T&& callable, Args_T&&... arguments)
+  {
+#if 0 // defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS)
+    printf ("%s\n", __PRETTY_FUNCTION__);
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS
+
+    current_test_suite->begin_test_case (name);
+    std::invoke (std::forward<Callable_T> (callable),
+                 std::forward<Args_T> (arguments)...);
+    current_test_suite->end_test_case ();
+  }
+
+  /**
+   * @details
+   * The `expect` function template evaluates a logical condition or custom
+   * expression and reports the result within the µTest++ framework. It is
+   * designed to provide detailed diagnostics for test failures, including the
+   * actual and expected values, when using the provided comparators (`eq()`,
+   * `ne()`, `lt()`, `le()`, `gt()`, `ge()`) or custom operators.
+   *
+   * The function template can be used with any expression that evaluates to a
+   * boolean or with custom comparators/operators derived from the local
+   * `detail::op` type. For complex checks performed outside the `expect()`
+   * logical expression (such as within `if` or `try`/`catch` statements), the
+   * result can be reported by calling `expect(true)` or `expect(false)`.
+   *
+   * The function returns an output stream, allowing optional messages to be
+   * appended to the test report.
+   *
+   * **Example**
+   *
+   * @code{.cpp}
+   * namespace mt = micro_os_plus::micro_test_plus;
+   * mt::expect(compute_answer() == 42) << "answer is 42";
+   * @endcode
+   */
+
+  template <class Expr_T, type_traits::requires_t<
+                              type_traits::is_op_v<Expr_T>
+                              or type_traits::is_convertible_v<Expr_T, bool>>>
+  constexpr auto
+  expect (const Expr_T& expr, const reflection::source_location& sl)
+  {
+    return detail::deferred_reporter<Expr_T>{ expr, false, sl };
+  }
+
+  /**
+   * @details
+   * The `assume` function template evaluates a logical condition or custom
+   * expression and reports the result within the µTest++ framework. It is
+   * designed to provide detailed diagnostics for test failures, including the
+   * actual and expected values, when using the provided comparators (`eq()`,
+   * `ne()`, `lt()`, `le()`, `gt()`, `ge()`) or custom operators.
+   *
+   * The function template can be used with any expression that evaluates to a
+   * boolean or with custom comparators/operators derived from the local
+   * `detail::op` type. For complex checks performed outside the `expect()`
+   * logical expression (such as within `if` or `try`/`catch` statements), the
+   * result can be reported by calling `expect(true)` or `expect(false)`.
+   *
+   * The function returns an output stream, allowing optional messages to be
+   * appended to the test report.
+   *
+   * **Example**
+   *
+   * @code{.cpp}
+   * namespace mt = micro_os_plus::micro_test_plus;
+   * mt::assume(compute_answer() == 42) << "answer is 42";
+   * @endcode
+   */
+  template <class Expr_T, type_traits::requires_t<
+                              type_traits::is_op_v<Expr_T>
+                              or type_traits::is_convertible_v<Expr_T, bool>>>
+  constexpr auto
+  assume (const Expr_T& expr, const reflection::source_location& sl)
+  {
+    return detail::deferred_reporter<Expr_T>{ expr, true, sl };
+  }
+
+#if defined(__cpp_exceptions)
+
+  /**
+   * @details
+   * The `throws` function template verifies whether invoking the provided
+   * callable object results in the throwing of a specific exception type
+   * within the µTest++ framework. This is useful for testing error handling
+   * and exception safety in code under test.
+   *
+   * The function returns an output stream, allowing optional messages to be
+   * appended to the test report for diagnostic purposes.
+   */
+  template <class Exception_T, class Callable_T>
+  [[nodiscard]] constexpr auto
+  throws (const Callable_T& func)
+  {
+    return detail::throws_<Callable_T, Exception_T>{ func };
+  }
+
+  /**
+   * @details
+   * The `throws` function template verifies whether invoking the provided
+   * callable object results in the throwing of any exception within the
+   * µTest++ framework. This is useful for testing general exception safety and
+   * ensuring that code under test properly signals error conditions.
+   *
+   * The function returns an output stream, allowing optional messages to be
+   * appended to the test report for diagnostic purposes.
+   */
+  template <class Callable_T>
+  [[nodiscard]] constexpr auto
+  throws (const Callable_T& func)
+  {
+    return detail::throws_<Callable_T>{ func };
+  }
+
+  /**
+   * @details
+   * The `nothrow` function template verifies whether invoking the provided
+   * callable object does not result in the throwing of any exception within
+   * the µTest++ framework. This is useful for testing exception safety and
+   * ensuring that code under test does not unexpectedly signal error
+   * conditions.
+   *
+   * The function returns an output stream, allowing optional messages to be
+   * appended to the test report for diagnostic purposes.
+   */
+  template <class Callable_T>
+  [[nodiscard]] constexpr auto
+  nothrow (const Callable_T& func)
+  {
+    return detail::nothrow_<Callable_T>{ func };
+  }
+
+#endif // defined(__cpp_exceptions)
+
+  // --------------------------------------------------------------------------
+  namespace utility
+  {
+    /**
+     * @details
+     * This function template facilitates string handling in tests by splitting
+     * a string into a vector of substrings, using the specified delimiter.
+     *
+     * The function iterates through the input string, identifying delimiter
+     * positions and extracting substrings between them. Each resulting
+     * substring is added to the output vector. This approach supports flexible
+     * parsing of delimited data, which is particularly useful for validating
+     * string processing logic in test cases.
+     *
+     * **Example**
+     *
+     * @code{.cpp}
+     * namespace mt = micro_os_plus::micro_test_plus;
+     *
+     * mt::expect (std::vector<std::string_view>{ "a", "b" }
+     *             == mt::utility::split<std::string_view> ("a.b", "."))
+     *         << "a.b splits into [a,b]";
+     * @endcode
+     */
+    template <class T = std::string_view, class Delim_T>
+    [[nodiscard]] auto
+    split (T input, Delim_T delim) -> std::vector<T>
+    {
+      std::vector<T> output{};
+      std::size_t first{};
+      while (first < std::size (input))
+        {
+          const auto second = input.find_first_of (delim, first);
+          if (first != second)
+            {
+              output.emplace_back (input.substr (first, second - first));
+            }
+          if (second == T::npos)
+            {
+              break;
+            }
+          first = second + 1;
+        }
+      return output;
+    }
+
+    // ------------------------------------------------------------------------
+  } // namespace utility
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_INLINES_H_
+
+// ----------------------------------------------------------------------------