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

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

@@ -65,290 +65,282 @@
 #endif
 #endif
 
-// ===========================================================================
+// ============================================================================
 
 namespace micro_os_plus::micro_test_plus
 {
+  // --------------------------------------------------------------------------
 
-  // ==========================================================================
-
-  /**
-   * @brief A single point-in-time measurement, wrapping a `timespec` value.
-   *
-   * @details
-   * `timestamp` stores one `timespec` sample obtained from the system clock.
-   * It is default-constructible (zero-initialises the `timespec`),
-   * copy-constructible, and move-constructible, so that it can be used
-   * efficiently in `std::optional<timestamp>` containers.
-   *
-   * The `has_clock()` predicate allows callers to determine whether a
-   * real-time clock is available on the target platform before relying on
-   * the stored value.
-   *
-   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
-   */
-  class timestamp
+  namespace detail
   {
-  public:
-    /**
-     * @brief Default constructor. Zero-initialises the internal `timespec`.
-     */
-    timestamp () noexcept;
-
-    /**
-     * @brief Constructs a timestamp from an existing `timespec` value.
-     *
-     * @param ts The `timespec` value to store.
-     */
-    timestamp (const timespec& ts) noexcept : value_{ ts }
-    {
-    }
-
-    // `timespec` is trivially copyable, so copy and move are safe to default.
-    // Defaulting these operations allows `timestamp` to be used in contexts
-    // that require copyability or movability (e.g. containers, algorithms).
-    /**
-     * @brief Defaulted copy constructor.
-     */
-    timestamp (const timestamp&) = default;
-
-    /**
-     * @brief Defaulted move constructor.
-     */
-    timestamp (timestamp&&) = default;
-
-    /**
-     * @brief Defaulted copy assignment operator.
-     */
-    timestamp&
-    operator= (const timestamp&) = default;
-
-    /**
-     * @brief Defaulted move assignment operator.
-     */
-    timestamp&
-    operator= (timestamp&&) = default;
-
-    /**
-     * @brief Defaulted destructor.
-     */
-    ~timestamp () = default;
+    // ========================================================================
 
     /**
-     * @brief Returns true if a monotonic clock is available on this target.
+     * @brief A single point-in-time measurement, wrapping a `timespec` value.
      *
-     * @par Parameters
-     *   None.
-     * @retval true  A real-time clock is available and timestamps are valid.
-     * @retval false No clock is available; timing data should be ignored.
-     */
-    bool
-    has_clock (void) const noexcept;
-
-    /**
-     * @brief Returns a mutable reference to the underlying `timespec` value.
+     * @details
+     * `timestamp` stores one `timespec` sample obtained from the system clock.
+     * It is default-constructible (zero-initialises the `timespec`),
+     * copy-constructible, and move-constructible, so that it can be used
+     * efficiently in `std::optional<timestamp>` containers.
      *
-     * @par Parameters
-     *   None.
-     * @return A reference to the stored `timespec`.
-     */
-    [[nodiscard]] timespec&
-    value () noexcept
-    {
-      return value_;
-    }
-
-    /**
-     * @brief Returns a const reference to the underlying `timespec` value.
+     * The `has_clock()` predicate allows callers to determine whether a
+     * real-time clock is available on the target platform before relying on
+     * the stored value.
      *
-     * @par Parameters
-     *   None.
-     * @return A const reference to the stored `timespec`.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
-    [[nodiscard]] const timespec&
-    value () const noexcept
+    class timestamp
     {
-      return value_;
-    }
-
-  protected:
-    /**
-     * @brief The underlying `timespec` value.
-     */
-    timespec value_{};
-  };
-
-  // ==========================================================================
-
-  /**
-   * @brief A begin/end timestamp pair used to measure elapsed time.
-   *
-   * @details
-   * `timestamps` stores an optional begin `timestamp` and an optional end
-   * `timestamp`. When both are available, `compute_elapsed_time()` derives
-   * the elapsed interval in milliseconds and microseconds.
-   *
-   * Typical usage in the framework:
-   * 1. Call `timestamp_begin()` just before the test suite or session
-   *    body executes.
-   * 2. Call `timestamp_end()` immediately after it completes.
-   * 3. Pass the elapsed values to the reporter.
-   *
-   * If the platform does not provide a monotonic clock, the `std::optional`
-   * members remain empty and `has_timestamps()` returns `false`, so that the
-   * reporter can skip timing output.
-   *
-   * The class is non-copyable and non-movable to prevent accidental sharing
-   * of live timing state.
-   *
-   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
-   */
-  class timestamps
-  {
-  public:
-    /**
-     * @brief Default constructor. Both timestamps are uninitialised.
-     */
-    timestamps () = default;
-
-    /**
-     * @brief Deleted copy constructor to prevent copying.
-     */
-    timestamps (const timestamps&) = delete;
-
-    /**
-     * @brief Deleted move constructor to prevent moving.
-     */
-    timestamps (timestamps&&) = delete;
+    public:
+      /**
+       * @brief Default constructor. Zero-initialises the internal `timespec`.
+       */
+      timestamp () noexcept;
+
+      /**
+       * @brief Constructs a timestamp from an existing `timespec` value.
+       *
+       * @param ts The `timespec` value to store.
+       */
+      timestamp (const timespec& ts) noexcept;
+
+      // `timespec` is trivially copyable, so copy and move are safe to
+      // default. Defaulting these operations allows `timestamp` to be used in
+      // contexts that require copyability or movability (e.g. containers,
+      // algorithms).
+      /**
+       * @brief Defaulted copy constructor.
+       */
+      timestamp (const timestamp&) = default;
+
+      /**
+       * @brief Defaulted move constructor.
+       */
+      timestamp (timestamp&&) = default;
+
+      /**
+       * @brief Defaulted copy assignment operator.
+       */
+      timestamp&
+      operator= (const timestamp&)
+          = default;
+
+      /**
+       * @brief Defaulted move assignment operator.
+       */
+      timestamp&
+      operator= (timestamp&&)
+          = default;
+
+      /**
+       * @brief Defaulted destructor.
+       */
+      ~timestamp () = default;
+
+      /**
+       * @brief Returns true if a monotonic clock is available on this target.
+       *
+       * @par Parameters
+       *   None.
+       * @retval true  A real-time clock is available and timestamps are valid.
+       * @retval false No clock is available; timing data should be ignored.
+       */
+      bool
+      has_clock (void) const noexcept;
+
+      /**
+       * @brief Returns a mutable reference to the underlying `timespec` value.
+       *
+       * @par Parameters
+       *   None.
+       * @return A reference to the stored `timespec`.
+       */
+      [[nodiscard]] timespec&
+      value () noexcept;
+
+      /**
+       * @brief Returns a const reference to the underlying `timespec` value.
+       *
+       * @par Parameters
+       *   None.
+       * @return A const reference to the stored `timespec`.
+       */
+      [[nodiscard]] const timespec&
+      value () const noexcept;
+
+    protected:
+      /**
+       * @brief The underlying `timespec` value.
+       */
+      timespec value_{};
+    };
+
+    // ========================================================================
 
     /**
-     * @brief Deleted copy assignment operator to prevent copying.
-     */
-    timestamps&
-    operator= (const timestamps&) = delete;
-
-    /**
-     * @brief Deleted move assignment operator to prevent moving.
-     */
-    timestamps&
-    operator= (timestamps&&) = delete;
-
-    /**
-     * @brief Defaulted destructor.
-     */
-    ~timestamps () = default;
-
-    /**
-     * @brief Records the begin timestamp using the current system clock.
+     * @brief A begin/end timestamp pair used to measure elapsed time.
      *
-     * @par Parameters
-     *   None.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    timestamp_begin (void) noexcept;
-
-    /**
-     * @brief Records the begin timestamp from a caller-supplied value.
+     * @details
+     * `timestamps` stores an optional begin `timestamp` and an optional end
+     * `timestamp`. When both are available, `compute_elapsed_time()` derives
+     * the elapsed interval in milliseconds and microseconds.
      *
-     * @param ts The `timespec` value to use as the begin timestamp.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    timestamp_begin (const timespec& ts) noexcept;
-
-    /**
-     * @brief Records the end timestamp using the current system clock.
+     * Typical usage in the framework:
+     * 1. Call `timestamp_begin()` just before the test suite or session
+     *    body executes.
+     * 2. Call `timestamp_end()` immediately after it completes.
+     * 3. Pass the elapsed values to the reporter.
      *
-     * @par Parameters
-     *   None.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    timestamp_end (void) noexcept;
-
-    /**
-     * @brief Records the end timestamp from a caller-supplied value.
+     * If the platform does not provide a monotonic clock, the `std::optional`
+     * members remain empty and `has_timestamps()` returns `false`, so that the
+     * reporter can skip timing output.
      *
-     * @param ts The `timespec` value to use as the end timestamp.
-     * @par Returns
-     *   Nothing.
-     */
-    void
-    timestamp_end (const timespec& ts) noexcept;
-
-    /**
-     * @brief Returns true if the begin timestamp has been recorded.
+     * The class is non-copyable and non-movable to prevent accidental sharing
+     * of live timing state.
      *
-     * @par Parameters
-     *   None.
-     * @retval true  `timestamp_begin()` has been called.
-     * @retval false `timestamp_begin()` has not been called.
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
      */
-    bool
-    has_begin () const noexcept
+    class timestamps
     {
-      return begin_time_.has_value ();
-    }
-
-    /**
-     * @brief Returns true if the end timestamp has been recorded.
-     *
-     * @par Parameters
-     *   None.
-     * @retval true  `timestamp_end()` has been called.
-     * @retval false `timestamp_end()` has not been called.
-     */
-    bool
-    has_end () const noexcept
-    {
-      return end_time_.has_value ();
-    }
-
-    /**
-     * @brief Returns true if both begin and end timestamps are available.
-     *
-     * @par Parameters
-     *   None.
-     * @retval true  Both timestamps are present and elapsed time can be
-     *               computed.
-     * @retval false At least one timestamp is absent; elapsed time is not
-     *               available.
-     */
-    bool
-    has_timestamps (void) const noexcept;
-
-    /**
-     * @brief Computes the elapsed time between begin and end timestamps.
-     *
-     * @param[out] milliseconds The elapsed time in whole milliseconds.
-     * @param[out] microseconds The sub-millisecond remainder in microseconds.
-     *
-     * @details
-     * Both output parameters are only valid when `has_timestamps()` returns
-     * `true`. The caller is responsible for checking this precondition.
-     */
-    void
-    compute_elapsed_time (uint32_t& milliseconds,
-                          uint32_t& microseconds) const;
-
-  protected:
-    /**
-     * @brief The timestamp recorded at the beginning of the test suite.
-     */
-    std::optional<timestamp> begin_time_;
-
-    /**
-     * @brief The timestamp recorded at the end of the test suite.
-     */
-    std::optional<timestamp> end_time_;
-  };
-
+    public:
+      /**
+       * @brief Default constructor. Both timestamps are uninitialised.
+       */
+      timestamps () = default;
+
+      /**
+       * @brief Deleted copy constructor to prevent copying.
+       */
+      timestamps (const timestamps&) = delete;
+
+      /**
+       * @brief Deleted move constructor to prevent moving.
+       */
+      timestamps (timestamps&&) = delete;
+
+      /**
+       * @brief Deleted copy assignment operator to prevent copying.
+       */
+      timestamps&
+      operator= (const timestamps&)
+          = delete;
+
+      /**
+       * @brief Deleted move assignment operator to prevent moving.
+       */
+      timestamps&
+      operator= (timestamps&&)
+          = delete;
+
+      /**
+       * @brief Defaulted destructor.
+       */
+      ~timestamps () = default;
+
+      /**
+       * @brief Records the begin timestamp using the current system clock.
+       *
+       * @par Parameters
+       *   None.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      timestamp_begin (void) noexcept;
+
+      /**
+       * @brief Records the begin timestamp from a caller-supplied value.
+       *
+       * @param ts The `timespec` value to use as the begin timestamp.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      timestamp_begin (const timespec& ts) noexcept;
+
+      /**
+       * @brief Records the end timestamp using the current system clock.
+       *
+       * @par Parameters
+       *   None.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      timestamp_end (void) noexcept;
+
+      /**
+       * @brief Records the end timestamp from a caller-supplied value.
+       *
+       * @param ts The `timespec` value to use as the end timestamp.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      timestamp_end (const timespec& ts) noexcept;
+
+      /**
+       * @brief Returns true if the begin timestamp has been recorded.
+       *
+       * @par Parameters
+       *   None.
+       * @retval true  `timestamp_begin()` has been called.
+       * @retval false `timestamp_begin()` has not been called.
+       */
+      bool
+      has_begin () const noexcept;
+
+      /**
+       * @brief Returns true if the end timestamp has been recorded.
+       *
+       * @par Parameters
+       *   None.
+       * @retval true  `timestamp_end()` has been called.
+       * @retval false `timestamp_end()` has not been called.
+       */
+      bool
+      has_end () const noexcept;
+
+      /**
+       * @brief Returns true if both begin and end timestamps are available.
+       *
+       * @par Parameters
+       *   None.
+       * @retval true  Both timestamps are present and elapsed time can be
+       *               computed.
+       * @retval false At least one timestamp is absent; elapsed time is not
+       *               available.
+       */
+      bool
+      has_timestamps (void) const noexcept;
+
+      /**
+       * @brief Computes the elapsed time between begin and end timestamps.
+       *
+       * @param[out] milliseconds The elapsed time in whole milliseconds.
+       * @param[out] microseconds The sub-millisecond remainder in
+       * microseconds.
+       */
+      void
+      compute_elapsed_time (uint32_t& milliseconds,
+                            uint32_t& microseconds) const;
+
+    protected:
+      /**
+       * @brief The timestamp recorded at the beginning of the test suite.
+       */
+      std::optional<timestamp> begin_time_;
+
+      /**
+       * @brief The timestamp recorded at the end of the test suite.
+       */
+      std::optional<timestamp> end_time_;
+    };
+
+    // ------------------------------------------------------------------------
+  } // namespace detail
   // ==========================================================================
-
 } // namespace micro_os_plus::micro_test_plus
 
 #if defined(__GNUC__)
@@ -359,6 +351,11 @@ namespace micro_os_plus::micro_test_plus
 
 #endif // __cplusplus
 
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/timings-inlines.h"
+
 // ----------------------------------------------------------------------------
 
 #endif // MICRO_TEST_PLUS_TIMINGS_H_