@micro-os-plus/micro-test-plus 3.3.1 → 4.1.0

package/include/micro-os-plus/micro-test-plus/inlines/{test-reporter-inlines.h → expression-formatter-inlines.h}

@@ -17,37 +17,32 @@
 
 /**
  * @file
- * @brief C++ header file with inline implementations for the µTest++ test
- * reporter.
+ * @brief C++ header file with inline implementations for the µTest++
+ * expression formatter.
  *
  * @details
- * This header provides the inline implementations for the test reporting
- * facilities used within the µTest++ framework. It defines the logic for
- * formatting and outputting test results, including operator overloads for
- * various value types, containers, and comparison expressions, as well as
- * structured output for logical and exception-related assertions.
+ * This header provides the inline and template method implementations for
+ * `expression_formatter`. The buffer accessors (`str()`, `c_str()`,
+ * `clear()`, `empty()`, `append()`, `reserve()`) are defined as inline
+ * functions for zero-overhead access. The template operators —
+ * `operator<<(T*)`, `operator<<(is_op<T>)`,
+ * `operator<<(genuine_integral_value<T>)`, and `operator<<(container)` —
+ * are instantiated per concrete type at each call site.
  *
- * The implementations ensure that test outcomes are presented in a clear,
- * consistent, and expressive manner, supporting both value and pointer
- * semantics, and providing detailed diagnostics for both successful and failed
- * test cases. Special attention is given to formatting, colour highlighting,
- * and extensibility, enabling professional and readable test reports suitable
- * for embedded and general C++ development.
+ * The `append_number_()` helper is also a template, selecting between a
+ * `std::to_chars` path for standard numeric types and an `snprintf` fallback
+ * for `long double` on platforms where `std::to_chars` lacks support for
+ * 80-bit extended precision.
  *
- * 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.
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace.
  *
  * This file is intended solely for internal use within the framework and
  * should not be included directly by user code.
  */
 
-#ifndef MICRO_TEST_PLUS_TEST_REPORTER_INLINES_H_
-#define MICRO_TEST_PLUS_TEST_REPORTER_INLINES_H_
+#ifndef MICRO_TEST_PLUS_EXPRESSION_FORMATTER_INLINES_H_
+#define MICRO_TEST_PLUS_EXPRESSION_FORMATTER_INLINES_H_
 
 // ----------------------------------------------------------------------------
 
@@ -55,8 +50,9 @@
 
 // ----------------------------------------------------------------------------
 
-#include <stdio.h>
-#include <cstring>
+#include <cstdio>
+
+#include "micro-os-plus/micro-test-plus/reflection.h"
 
 // ----------------------------------------------------------------------------
 
@@ -69,94 +65,184 @@
 #endif
 #endif
 
-namespace micro_os_plus::micro_test_plus
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus::detail
 {
   // --------------------------------------------------------------------------
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output pointer
-   * values in a consistent and readable hexadecimal format.
-   *
-   * The pointer is formatted as a string using `snprintf` with the `%p` format
-   * specifier, ensuring portability across platforms. The resulting string is
-   * appended to the internal output buffer, allowing pointer values to be
-   * included in test reports and diagnostics.
-   *
-   * This approach provides clear and unambiguous representation of pointer
-   * addresses, which is particularly useful for debugging and verifying
-   * pointer-related test cases.
+   * Initializes the `colours_` reference with the provided `colours` instance.
+   * The internal buffer is default-initialized to an empty string.
+   */
+  inline expression_formatter::expression_formatter (colours& colours) noexcept
+      : colours_ (colours)
+  {
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * @details
+   * Returns the ANSI colour code for pass or fail, depending on the boolean
+   * condition provided.
+   */
+  inline auto
+  expression_formatter::colour_ (const bool cond) const
+  {
+    return cond ? colours_.pass : colours_.fail;
+  }
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * @details
+   * Returns a const reference to the internal `buffer_` string.
+   */
+  inline const std::string&
+  expression_formatter::str () const noexcept
+  {
+    return buffer_;
+  }
+
+  /**
+   * @details
+   * Returns `buffer_.c_str()`, providing a pointer to the
+   * null-terminated contents of the internal buffer.
+   */
+  inline const char*
+  expression_formatter::c_str () const noexcept
+  {
+    return buffer_.c_str ();
+  }
+
+  /**
+   * @details
+   * Calls `buffer_.clear()`, resetting the buffer length to zero
+   * without releasing the allocated storage.
+   */
+  inline void
+  expression_formatter::clear () noexcept
+  {
+    buffer_.clear ();
+  }
+
+  /**
+   * @details
+   * Returns `buffer_.empty()`, indicating whether the accumulated
+   * string has zero length.
+   */
+  inline bool
+  expression_formatter::empty () const noexcept
+  {
+    return buffer_.empty ();
+  }
+
+  /**
+   * @details
+   * Appends @p count repetitions of @p ch to the internal buffer by
+   * delegating to `buffer_.append(count, ch)`.
+   */
+  inline void
+  expression_formatter::append (size_t count, char ch)
+  {
+    buffer_.append (count, ch);
+  }
+
+  /**
+   * @details
+   * Calls `buffer_.reserve(capacity)` to pre-allocate storage,
+   * reducing subsequent dynamic allocations.
+   */
+  inline void
+  expression_formatter::reserve (size_t capacity)
+  {
+    buffer_.reserve (capacity);
+  }
+
+  // --------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage"
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
+
+  // --------------------------------------------------------------------------
+
+  /**
+   * @details
+   * Null pointers are rendered as `"0x0"` to avoid platform-specific
+   * representations such as `"(nil)"` on Linux/glibc. Non-null pointers
+   * are formatted as a hexadecimal address using `snprintf` with the
+   * `%p` specifier.
    */
   template <typename T>
-  test_reporter&
-  test_reporter::operator<< (T* v)
+  expression_formatter&
+  expression_formatter::operator<< (T* v)
   {
+    if (v == nullptr)
+      {
+        buffer_.append ("0x0");
+        return *this;
+      }
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
+#endif
+#endif
     char buff[20];
     snprintf (buff, sizeof (buff), "%p", reinterpret_cast<void*> (v));
-    out_.append (buff);
-
+    buffer_.append (buff);
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
     return *this;
   }
 
-#if 0
-/**
-  * @details
-  * This operator overload enables the `test_reporter` to output any type that is supported by the `detail::get` mechanism, ensuring consistent formatting and extensibility.
-  *
-  * By delegating to `detail::get`, the operator allows for custom formatting and extraction of values, supporting a wide range of types including user-defined and framework-specific types. The resulting value is then forwarded to the appropriate output handler, ensuring seamless integration into test reports and diagnostics.
-  *
-  * This approach promotes flexibility and maintainability, allowing new types to be supported with minimal changes to the reporting infrastructure.
-  */
-   template <class T>
-  test_reporter&
-  test_reporter::operator<< (const T& t)
+  /**
+   * @details
+   * Delegates to `detail::get(t)` to obtain the displayable value
+   * of an op expression, then streams it through `operator<<` to
+   * format it into the buffer.
+   */
+  template <class T>
+    requires type_traits::is_op<T>
+  expression_formatter&
+  expression_formatter::operator<< (const T& t)
   {
     *this << detail::get (t);
     return *this;
   }
-#endif
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output
-   * strongly-typed integral values in a clear and consistent decimal format.
-   *
-   * The value is converted to a string using `std::to_string` after being cast
-   * to `long long`, ensuring accurate formatting and compatibility across
-   * platforms. The resulting string is appended to the internal output buffer,
-   * allowing integral values to be included in test reports and diagnostics.
-   *
-   * This approach ensures precise and unambiguous representation of integral
-   * values, which is particularly advantageous for verifying test results and
-   * facilitating debugging.
+   * Casts the underlying integral value to `long long` and formats
+   * it without a type suffix, appending the result to the buffer.
    */
   template <class T>
-  test_reporter&
-  test_reporter::operator<< (const type_traits::genuine_integral_value<T>& v)
+  expression_formatter&
+  expression_formatter::operator<< (
+      const type_traits::genuine_integral_value<T>& v)
   {
-    out_.append (std::to_string (static_cast<long long> (v.get ())));
+    detail::append_number_ (buffer_, static_cast<long long> (v.get ()));
     return *this;
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output container
-   * types in a structured and readable format.
-   *
-   * The contents of the container are enclosed in curly braces and each
-   * element is separated by a comma and a space. The operator iterates over
-   * the container, formatting each element in sequence, which ensures clarity
-   * and consistency in test reports and diagnostics.
-   *
-   * This approach provides a clear visual representation of container
-   * contents, making it easier to interpret test results and debug issues
-   * involving collections of values.
+   * Iterates the container and formats each element separated by
+   * `", "`, surrounded by `{` and `}`. Each element is streamed
+   * through `operator<<`, which recurses as needed for nested types.
    */
-  template <class T,
-            type_traits::requires_t<type_traits::is_container_v<T>
-                                    and not type_traits::has_npos_v<T>>>
-  test_reporter&
-  test_reporter::operator<< (T&& t)
+  template <class T>
+    requires (type_traits::container_like<T> and not type_traits::has_npos<T>)
+  expression_formatter&
+  expression_formatter::operator<< (const T& t)
   {
     *this << '{';
     auto first = true;
@@ -169,9 +255,12 @@ namespace micro_os_plus::micro_test_plus
     return *this;
   }
 
+  // --------------------------------------------------------------------------
+  // Compound expression operators (without colour codes).
+
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output equality
+   * This operator overload enables the `reporter` to output equality
    * comparison expressions in a clear and expressive format.
    *
    * The left-hand side and right-hand side values are formatted and separated
@@ -181,16 +270,16 @@ namespace micro_os_plus::micro_test_plus
    * equality assertions and facilitates efficient debugging of test failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::eq_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::eq_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " == " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " == " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output inequality
+   * This operator overload enables the `reporter` to output inequality
    * comparison expressions in a clear and expressive format.
    *
    * The left-hand side and right-hand side values are formatted and separated
@@ -201,16 +290,16 @@ namespace micro_os_plus::micro_test_plus
    * failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::ne_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::ne_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " != " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " != " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output greater-than
+   * This operator overload enables the `reporter` to output greater-than
    * comparison expressions in a clear and expressive format.
    *
    * The left-hand side and right-hand side values are formatted and separated
@@ -221,16 +310,16 @@ namespace micro_os_plus::micro_test_plus
    * failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::gt_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::gt_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " > " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " > " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output
+   * This operator overload enables the `reporter` to output
    * greater-than-or-equal-to comparison expressions in a clear and expressive
    * format.
    *
@@ -242,16 +331,16 @@ namespace micro_os_plus::micro_test_plus
    * efficient debugging of test failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::ge_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::ge_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " >= " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " >= " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output less-than
+   * This operator overload enables the `reporter` to output less-than
    * comparison expressions in a clear and expressive format.
    *
    * The left-hand side and right-hand side values are formatted and separated
@@ -261,16 +350,16 @@ namespace micro_os_plus::micro_test_plus
    * less-than assertions and facilitates efficient debugging of test failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::lt_<Rhs_T, Lhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::lt_<Rhs_T, Lhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " < " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " < " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output
+   * This operator overload enables the `reporter` to output
    * less-than-or-equal-to comparison expressions in a clear and expressive
    * format.
    *
@@ -282,16 +371,16 @@ namespace micro_os_plus::micro_test_plus
    * efficient debugging of test failures.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::le_<Rhs_T, Lhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::le_<Rhs_T, Lhs_T>& op)
   {
-    return (*this << color (op) << op.lhs () << " <= " << op.rhs ()
-                  << colors_.none);
+    return (*this << colour_ (op) << op.lhs () << " <= " << op.rhs ()
+                  << colours_.none);
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output logical
+   * This operator overload enables the `reporter` to output logical
    * conjunction (AND) expressions in a clear and structured format.
    *
    * The left-hand side and right-hand side expressions are enclosed in
@@ -302,16 +391,16 @@ namespace micro_os_plus::micro_test_plus
    * test failures involving compound conditions.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::and_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::and_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << '(' << op.lhs () << color (op) << " and " << colors_.none
-                  << op.rhs () << ')');
+    return (*this << '(' << op.lhs () << colour_ (op) << " and "
+                  << colours_.none << op.rhs () << ')');
   }
 
   /**
    * @details
-   * This operator overload enables the `test_reporter` to output logical
+   * This operator overload enables the `reporter` to output logical
    * disjunction (OR) expressions in a clear and structured format.
    *
    * The left-hand side and right-hand side expressions are enclosed in
@@ -322,11 +411,11 @@ namespace micro_os_plus::micro_test_plus
    * test failures involving compound conditions.
    */
   template <class Lhs_T, class Rhs_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::or_<Lhs_T, Rhs_T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::or_<Lhs_T, Rhs_T>& op)
   {
-    return (*this << '(' << op.lhs () << color (op) << " or " << colors_.none
-                  << op.rhs () << ')');
+    return (*this << '(' << op.lhs () << colour_ (op) << " or "
+                  << colours_.none << op.rhs () << ')');
   }
 
   /**
@@ -338,10 +427,10 @@ namespace micro_os_plus::micro_test_plus
    * diagnostics.
    */
   template <class T>
-  test_reporter&
-  test_reporter::operator<< (const detail::not_<T>& op)
+  expression_formatter&
+  expression_formatter::operator<< (const detail::not_<T>& op)
   {
-    return (*this << color (op) << "not " << op.value () << colors_.none);
+    return (*this << colour_ (op) << "not " << op.operand () << colours_.none);
   }
 
 #if defined(__cpp_exceptions)
@@ -357,13 +446,14 @@ namespace micro_os_plus::micro_test_plus
    * reports, and assists in the precise identification and debugging of
    * exception-related test cases.
    */
-  template <class Expr_T, class Exception_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::throws_<Expr_T, Exception_T>& op)
+  template <class Callable_T, class Exception_T>
+  expression_formatter&
+  expression_formatter::operator<< (
+      const detail::throws_<Callable_T, Exception_T>& op)
   {
-    return (*this << color (op) << "throws<"
+    return (*this << colour_ (op) << "throws<"
                   << reflection::type_name<Exception_T> () << ">"
-                  << colors_.none);
+                  << colours_.none);
   }
 
   /**
@@ -376,11 +466,12 @@ namespace micro_os_plus::micro_test_plus
    * immediately apparent when an expression is expected to throw, thereby
    * improving the readability and professionalism of the test output.
    */
-  template <class Expr_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::throws_<Expr_T, void>& op)
+  template <class Callable_T>
+  expression_formatter&
+  expression_formatter::operator<< (
+      const detail::throws_<Callable_T, void>& op)
   {
-    return (*this << color (op) << "throws" << colors_.none);
+    return (*this << colour_ (op) << "throws" << colours_.none);
   }
 
   /**
@@ -393,73 +484,16 @@ namespace micro_os_plus::micro_test_plus
    * apparent when an expression is guaranteed not to throw, thereby improving
    * the readability and professionalism of the test output.
    */
-  template <class Expr_T>
-  test_reporter&
-  test_reporter::operator<< (const detail::nothrow_<Expr_T>& op)
+  template <class Callable_T>
+  expression_formatter&
+  expression_formatter::operator<< (const detail::nothrow_<Callable_T>& op)
   {
-    return (*this << color (op) << "nothrow" << colors_.none);
+    return (*this << colour_ (op) << "nothrow" << colours_.none);
   }
 #endif
 
-  /**
-   * @details
-   * This operator overload formats output for expressions that do not throw
-   * exceptions. It applies colour styling for clarity and ensures a structured
-   * representation of exception safety.
-   *
-   * When invoked, the function outputs a pass prefix, followed by either the
-   * provided message or, if the message is empty, the evaluated expression
-   * itself. It then appends a pass suffix to complete the output. This
-   * approach guarantees that successful test outcomes are presented in a clear
-   * and consistent manner, enhancing the readability and professionalism of
-   * test reports.
-   */
-  template <class Expr_T>
-  void
-  test_reporter::pass (Expr_T& expr, std::string& message)
-  {
-    current_test_suite->current_test_case.index++;
-
-    output_pass_prefix_ (message);
-
-    if (message.empty ())
-      {
-        // If there is no message, display the evaluated expression.
-        *this << expr;
-      }
-
-    output_pass_suffix_ ();
-  }
-
-  /**
-   * @details
-   * This function reports a test failure and formats the output in a clear and
-   * consistent manner. It provides contextual information, including the
-   * precise source location, and appends the evaluated expression when
-   * applicable. The failure handling process ensures uniformity in the
-   * presentation of unsuccessful test cases, aiding in the rapid
-   * identification and diagnosis of issues within test reports.
-   */
-  template <class Expr_T>
-  void
-  test_reporter::fail (Expr_T& expr, bool abort, std::string& message,
-                       const reflection::source_location& location)
-  {
-    current_test_suite->current_test_case.index++;
-
-    const bool hasExpression = type_traits::is_op_v<Expr_T>;
-    output_fail_prefix_ (message, hasExpression, location);
-
-    if constexpr (type_traits::is_op_v<Expr_T>)
-      {
-        *this << expr;
-      }
-
-    output_fail_suffix_ (location, abort);
-  }
-
   // --------------------------------------------------------------------------
-} // namespace micro_os_plus::micro_test_plus
+} // namespace micro_os_plus::micro_test_plus::detail
 
 #if defined(__GNUC__)
 #pragma GCC diagnostic pop
@@ -471,6 +505,6 @@ namespace micro_os_plus::micro_test_plus
 
 // ----------------------------------------------------------------------------
 
-#endif // MICRO_TEST_PLUS_TEST_REPORTER_INLINES_H_
+#endif // MICRO_TEST_PLUS_EXPRESSION_FORMATTER_INLINES_H_
 
 // ----------------------------------------------------------------------------