@micro-os-plus/micro-test-plus 3.3.0 → 4.0.0

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

@@ -0,0 +1,126 @@
+/*
+ * 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 with declarations for the µTest++ exception-checking
+ * functions.
+ *
+ * @details
+ * This header provides the declarations for the exception-checking facilities
+ * of the µTest++ framework. It exposes three function templates —
+ * `throws<Exception_T>()`, `throws()`, and `nothrow()` — which allow test
+ * cases to verify that a callable throws a specific exception, throws any
+ * exception, or throws no exception, respectively.
+ *
+ * All declarations are conditionally compiled under `__cpp_exceptions` and
+ * reside within the `micro_os_plus::micro_test_plus` namespace, ensuring
+ * clear separation from user code and minimising the risk of naming conflicts.
+ *
+ * This header is located in the top-level `include/micro-os-plus` folder.
+ * Users should include `<micro-os-plus/micro-test-plus.h>` rather than this
+ * header directly.
+ */
+
+#ifndef MICRO_TEST_PLUS_EXCEPTIONS_H_
+#define MICRO_TEST_PLUS_EXCEPTIONS_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#if defined(MICRO_OS_PLUS_INCLUDE_CONFIG_H)
+#include <micro-os-plus/config.h>
+#endif // MICRO_OS_PLUS_INCLUDE_CONFIG_H
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+#if defined(__cpp_exceptions)
+
+  /**
+   * @ingroup micro-test-plus-exceptions
+   * @brief Check if a callable throws a specific exception.
+   *
+   * @tparam Exception_T The type of the exception expected to be thrown.
+   * @tparam Callable_T The type of the callable object to be invoked.
+   * @param [in] func The callable object to check for exception throwing
+   * behaviour.
+   * @return An output stream to write optional messages.
+   */
+  template <class Exception_T, class Callable_T>
+  [[nodiscard]] constexpr auto
+  throws (const Callable_T& func);
+
+  /**
+   * @ingroup micro-test-plus-exceptions
+   * @brief Check if a callable throws an exception (any exception).
+   *
+   * @tparam Callable_T The type of the callable object to be invoked.
+   * @param [in] func The callable object to check for exception throwing
+   * behaviour.
+   * @return An output stream to write optional messages.
+   */
+  template <class Callable_T>
+  [[nodiscard]] constexpr auto
+  throws (const Callable_T& func);
+
+  /**
+   * @ingroup micro-test-plus-exceptions
+   * @brief Check if a callable does not throw an exception.
+   *
+   * @tparam Callable_T The type of the callable object to be invoked.
+   * @param [in] func The callable object to check for exception safety.
+   * @return An output stream to write optional messages.
+   */
+  template <class Callable_T>
+  [[nodiscard]] constexpr auto
+  nothrow (const Callable_T& func);
+
+#endif
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_EXCEPTIONS_H_
+
+// ----------------------------------------------------------------------------

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

@@ -24,10 +24,10 @@
  * 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.
+ * equality, non-equality, greater than, less than, greater than or equal,
+ * and less than or equal. 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.
@@ -62,10 +62,13 @@
 #pragma GCC diagnostic ignored "-Waggregate-return"
 #if defined(__clang__)
 #pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wpre-c++17-compat"
 #pragma clang diagnostic ignored "-Wunknown-warning-option"
 #endif
 #endif
 
+// ===========================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -315,13 +318,13 @@ namespace micro_os_plus::micro_test_plus
   [[nodiscard]] constexpr auto
   mut (const T& t) noexcept -> T&;
 
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
 #if defined(__GNUC__)
 #pragma GCC diagnostic pop
 #endif
 
-  // --------------------------------------------------------------------------
-} // namespace micro_os_plus::micro_test_plus
-
 // ----------------------------------------------------------------------------
 
 #endif // __cplusplus

package/include/micro-os-plus/micro-test-plus/inlines/{details-inlines.h → deferred-reporter-inlines.h}

@@ -42,8 +42,8 @@
  * should not be included directly by user code.
  */
 
-#ifndef MICRO_TEST_PLUS_DETAILS_INLINES_H_
-#define MICRO_TEST_PLUS_DETAILS_INLINES_H_
+#ifndef MICRO_TEST_PLUS_DEFERRED_REPORTER_INLINES_H_
+#define MICRO_TEST_PLUS_DEFERRED_REPORTER_INLINES_H_
 
 // ----------------------------------------------------------------------------
 
@@ -51,9 +51,8 @@
 
 // ----------------------------------------------------------------------------
 
-#include <stdio.h>
-#include <cstring>
-// #include "test-reporter.h"
+#include <charconv>
+#include <cstdio>
 
 // ----------------------------------------------------------------------------
 
@@ -66,6 +65,8 @@
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -80,22 +81,45 @@ namespace micro_os_plus::micro_test_plus
      * 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.
+     * If the argument is a `char`, it is appended directly as a character.
+     * If the argument is of another arithmetic type, it is converted to a
+     * string using a fixed-size buffer and `std::to_chars` to avoid dynamic
+     * memory allocation. For all other types, the value is appended directly.
      */
     template <class T>
+      requires type_traits::printable<T>
     auto&
     deferred_reporter_base::operator<< (const T& msg)
     {
-      if constexpr (std::is_arithmetic_v<T>)
+      if constexpr (std::is_same_v<T, char>)
+        {
+          deferred_output_.push_back (msg);
+        }
+      else if constexpr (std::is_arithmetic_v<T>)
         {
-          message_.append (std::to_string (msg));
+          // Optimise to avoid dynamic memory allocation in std::to_string by
+          // using a fixed-size buffer and std::to_chars.
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#endif
+#endif
+          char buf[64];
+          // 64 bytes is sufficient for the longest decimal representation
+          // of any standard arithmetic type (long double ~45 chars).
+          static_assert (sizeof (buf) >= 50,
+                         "buf must be large enough for any arithmetic type");
+          auto [ptr, ec] = std::to_chars (buf, buf + sizeof (buf), msg);
+          if (ec == std::errc{})
+            deferred_output_.append (buf, ptr);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
         }
       else
         {
-          message_.append (msg);
+          deferred_output_.append (msg);
         }
       return *this;
     }
@@ -114,15 +138,17 @@ namespace micro_os_plus::micro_test_plus
      * contextual information for reporting purposes.
      */
     template <class Expr_T>
-    constexpr deferred_reporter<Expr_T>::deferred_reporter (
+    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 },
+        const reflection::source_location& location, subtest& subtest)
+        : deferred_reporter_base{ static_cast<bool> (expr), location,
+                                  subtest },
           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
+#if defined(MICRO_OS_PLUS_TRACE) \
+    && defined(MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS)
+      trace::printf ("%s\n", __PRETTY_FUNCTION__);
+#endif // MICRO_OS_PLUS_TRACE_MICRO_TEST_PLUS_CONSTRUCTORS
       abort_ = abort;
     }
 
@@ -141,13 +167,14 @@ namespace micro_os_plus::micro_test_plus
     template <class Expr_T>
     deferred_reporter<Expr_T>::~deferred_reporter ()
     {
-      if (value_)
+      if (value_) [[likely]]
         {
-          reporter->pass (expr_, message_);
+          subtest_.reporter ().pass (expr_, deferred_output_, subtest_);
         }
       else
         {
-          reporter->fail (expr_, abort_, message_, location_);
+          subtest_.reporter ().fail (expr_, abort_, deferred_output_,
+                                     location_, subtest_);
         }
     }
 
@@ -167,6 +194,6 @@ namespace micro_os_plus::micro_test_plus
 
 // ----------------------------------------------------------------------------
 
-#endif // MICRO_TEST_PLUS_DETAILS_INLINES_H_
+#endif // MICRO_TEST_PLUS_DEFERRED_REPORTER_INLINES_H_
 
 // ----------------------------------------------------------------------------

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

@@ -55,10 +55,6 @@
 
 // ----------------------------------------------------------------------------
 
-// #include "detail.h"
-
-// ----------------------------------------------------------------------------
-
 #if defined(__GNUC__)
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Waggregate-return"
@@ -68,6 +64,8 @@
 #endif
 #endif
 
+// ===========================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -254,6 +252,9 @@ namespace micro_os_plus::micro_test_plus
     return detail::le_<Lhs_T*, Rhs_T*>{ lhs, rhs };
   }
 
+  // --------------------------------------------------------------------------
+  // Logical operators.
+
   /**
    * @details
    * The `_not` function template provides a generic logical negation for any
@@ -308,6 +309,68 @@ namespace micro_os_plus::micro_test_plus
     return detail::or_<Lhs_T, Rhs_T>{ lhs, rhs };
   }
 
+  // --------------------------------------------------------------------------
+  // Exceptions related comparators.
+
+#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)
+
+  // --------------------------------------------------------------------------
+  // Utility functions.
+
   /**
    * @details
    * The `mut` function template provides a safe and generic mechanism to

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

@@ -58,8 +58,6 @@
 
 #include <cstdint>
 
-// #include "type-traits.h"
-
 // ----------------------------------------------------------------------------
 
 #if defined(__GNUC__)
@@ -71,6 +69,8 @@
 #endif
 #endif
 
+// ===========================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -509,9 +509,7 @@ namespace micro_os_plus::micro_test_plus
      *
      * The returned type is a lightweight wrapper that behaves as a `bool` and
      * supports equality comparison with both other named instances and boolean
-     * values.
-     *
-     * @note This operator is intended to facilitate expressive and type-safe
+     * values. This operator is intended to facilitate expressive and type-safe
      * test conditions.
      */
     constexpr auto
@@ -523,7 +521,6 @@ namespace micro_os_plus::micro_test_plus
        * @details
        * This structure inherits from `std::string_view` and a type trait base,
        * providing a strongly-typed boolean value for use in test expressions.
-       *
        * It defines conversion to `bool` and equality operators for comparison
        * with other named instances and boolean values.
        */

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

@@ -56,8 +56,6 @@
 
 #include <cstdint>
 
-// #include "type-traits.h"
-
 // ----------------------------------------------------------------------------
 
 #if defined(__GNUC__)
@@ -66,9 +64,12 @@
 #if defined(__clang__)
 #pragma clang diagnostic ignored "-Wc++98-compat"
 #pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
+#pragma clang diagnostic ignored "-Wc++20-compat"
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -93,7 +94,7 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T>
     [[nodiscard]] constexpr auto
-    abs (const T t) -> T
+    abs (const T t) noexcept -> T
     {
       return t < T{} ? -t : t;
     }
@@ -114,7 +115,7 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T>
     [[nodiscard]] constexpr auto
-    min_value (const T& lhs, const T& rhs) -> const T&
+    min_value (const T& lhs, const T& rhs) noexcept -> const T&
     {
       return (rhs < lhs) ? rhs : lhs;
     }
@@ -123,9 +124,9 @@ namespace micro_os_plus::micro_test_plus
      * @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.
+     * multiplication.
      *
-     * The function recursively multiplies the base by itself exponent times.
+     * The function iteratively multiplies the base by itself exponent times.
      * If the exponent is zero, the function returns one (the multiplicative
      * identity for the type).
      *
@@ -135,10 +136,12 @@ namespace micro_os_plus::micro_test_plus
      */
     template <class T, class Exp_T>
     [[nodiscard]] constexpr auto
-    pow (const T base, const Exp_T exp) -> T
+    pow (const T base, const Exp_T exp) noexcept -> T
     {
-      // If the exponent is 0, return 1, otherwise recurse.
-      return exp ? T (base * pow (base, exp - Exp_T (1))) : T (1);
+      T result{ 1 };
+      for (Exp_T i{}; i < exp; ++i)
+        result *= base;
+      return result;
     }
 
     /**
@@ -156,7 +159,7 @@ namespace micro_os_plus::micro_test_plus
      * conversion from character sequences to integral values.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     num (void) -> T
     {
       // Assume all are digits or dot or apostrophe.
@@ -196,9 +199,11 @@ namespace micro_os_plus::micro_test_plus
      * values.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     den (void) -> T
     {
+      static_assert ((... || (Cs == '.')),
+                     "den(): no decimal point in literal");
       constexpr const std::array cs{ Cs... };
       T result{};
       auto i = 0u;
@@ -229,9 +234,11 @@ namespace micro_os_plus::micro_test_plus
      * determination of decimal precision from character sequences.
      */
     template <class T, char... Cs>
-    [[nodiscard]] constexpr auto
+    [[nodiscard]] consteval auto
     den_size (void) -> T
     {
+      static_assert ((... || (Cs == '.')),
+                     "den_size(): no decimal point in literal");
       constexpr const std::array cs{ Cs... };
       T i{};
 #if defined(__GNUC__)
@@ -276,11 +283,10 @@ namespace micro_os_plus::micro_test_plus
           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"
+#else // GCC only
+#pragma GCC diagnostic ignored "-Warith-conversion"
 #endif
 #endif
           tmp = value - T (value);

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

@@ -56,8 +56,6 @@
 
 #include <cstdint>
 
-// #include "type-traits.h"
-
 // ----------------------------------------------------------------------------
 
 #if defined(__GNUC__)
@@ -69,6 +67,8 @@
 #endif
 #endif
 
+// ============================================================================
+
 namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
@@ -98,7 +98,8 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @details
-     * ... TBD
+     * Returns the file name captured at the time this `source_location`
+     * instance was created.
      */
     [[nodiscard]] constexpr auto
     source_location::file_name (void) const noexcept
@@ -108,7 +109,8 @@ namespace micro_os_plus::micro_test_plus
 
     /**
      * @details
-     * ... TBD
+     * Returns the line number captured at the time this `source_location`
+     * instance was created.
      */
     [[nodiscard]] constexpr auto
     source_location::line (void) const noexcept
@@ -124,29 +126,45 @@ namespace micro_os_plus::micro_test_plus
      * `__PRETTY_FUNCTION__` macro to extract a concise type name for the
      * template parameter \c T.
      *
-     * The implementation is compiler-dependent and may require adjustment for
-     * different toolchains. It is primarily intended for internal use within
-     * the µTest++ framework to support improved diagnostics and reporting.
+     * Rather than relying on fixed character offsets (which are fragile across
+     * compiler versions and namespace changes), the implementation searches
+     * for well-known marker characters in the function signature string:
+     *
+     * - Clang formats the signature as `"... [T = <typename>]"`, so the type
+     *   name lies between the last `'['` (skipping `"[T = "`) and the last
+     *   `']'`.
+     * - GCC formats the signature as `"... [with T = <typename>]"`, so the
+     *   type name lies between the last `'='` (skipping the trailing space)
+     *   and the last `']'`.
+     *
+     * This approach is resilient to namespace renaming, namespace nesting
+     * changes, and compiler format updates.
      */
     template <class T>
     [[nodiscard]] constexpr auto
     type_name (void) -> std::string_view
     {
+      const std::string_view sv = __PRETTY_FUNCTION__;
 #if defined(__clang__)
-#pragma GCC diagnostic push
-#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
-      // printf("|%s|%zu|\n", __PRETTY_FUNCTION__, sizeof
-      // (__PRETTY_FUNCTION__)); printf("|%s|\n", &__PRETTY_FUNCTION__[78]);
-      return { &__PRETTY_FUNCTION__[78], sizeof (__PRETTY_FUNCTION__) - 80 };
-#pragma GCC diagnostic pop
+      // Clang: "... [T = <typename>]"
+      // rfind('[') locates the opening bracket of "[T = ...]".
+      const auto start = sv.rfind ('[') + 5; // skip "[T = "
+      const auto end = sv.rfind (']');
 #elif defined(__GNUC__)
-      // printf("|%s|%zu|\n", __PRETTY_FUNCTION__, sizeof
-      // (__PRETTY_FUNCTION__)); printf("|%s|\n", &__PRETTY_FUNCTION__[93]);
-      return { &__PRETTY_FUNCTION__[93], sizeof (__PRETTY_FUNCTION__) - 144 };
+      // GCC: "... [with T = <typename>]" or, on some versions,
+      //      "... [with T = <typename>; std::string_view = ...]"
+      // Search for "T = " explicitly to avoid landing on a later '='.
+      const auto t_eq = sv.find ("T = ");
+      const auto start = t_eq + 4; // skip "T = "
+      const auto semi = sv.find (';', start);
+      const auto end
+          = (semi != std::string_view::npos) ? semi : sv.rfind (']');
 #else
+// Note: MSVC uses __FUNCSIG__ instead of __PRETTY_FUNCTION__.
+// MSVC is not a supported target for this framework.
 #error "Unsupported compiler"
-      return "Unsupported compiler";
 #endif
+      return sv.substr (start, end - start);
     }
 
     // ------------------------------------------------------------------------