detail.h

Go to the documentation of this file.

/*
 * 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.
 */
 
// ----------------------------------------------------------------------------

 
#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_DETAIL_H_
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_DETAIL_H_
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#if __has_include("micro-os-plus/project-config.h")
#include "micro-os-plus/project-config.h"
#endif // __has_include("micro-os-plus/project-config.h")
 
#if __has_include("micro-os-plus/micro-test-plus-defines.h")
#include "micro-os-plus/micro-test-plus-defines.h"
#endif // __has_include("micro-os-plus/micro-test-plus-defines.h")
 
#include "extension.h"
#include "math.h"
 
#include <algorithm>
#include <compare>
#include <concepts>
#include <cstddef>
#include <cstdio>
#include <string>
#include <string_view>
#include <type_traits>
#include <utility>
 
// ----------------------------------------------------------------------------

#if defined(_WIN32) && defined(__clang__) && !defined(__MINGW32__)
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE "Iu"
#elif defined(_WIN32) && defined(__GNUC__) && !defined(__clang__)
#if defined(_WIN64)
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE "llu"
#else
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE "u"
#endif // defined(_WIN64)
#else
#define MICRO_OS_PLUS_MICRO_TEST_PLUS_PRI_SIZE "zu"
#endif // defined(_WIN32) && defined(__clang__) && !defined(__MINGW32__)
 
// ----------------------------------------------------------------------------
 
#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 "-Wdocumentation"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
// ============================================================================
 
namespace micro_os_plus::micro_test_plus
{
  namespace detail
  {
    // ========================================================================

    template <class T>
    // The specifier order works around a Doxygen (1.17, 1.18) mismatch
    // with the definition, reported as "no matching file member found".
    [[nodiscard]] decltype (auto) constexpr unwrap (const T& t);
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
    template <class Lhs_T, class Rhs_T>
      requires (extension::has_epsilon<Lhs_T> or extension::has_epsilon<Rhs_T>)
    [[nodiscard]] constexpr bool
    within_tolerance (const Lhs_T& lhs, const Rhs_T& rhs);
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
 
    // ========================================================================

    template <class T>
    using stored_operand_t = std::conditional_t<
        std::is_lvalue_reference_v<T>
            and not std::is_copy_constructible_v<std::remove_cvref_t<T>>,
        const std::remove_reference_t<T>&, std::remove_cvref_t<T>>;
 
    // ========================================================================

    template <class T>
    struct unary_op : op
    {
      template <class U>
      constexpr unary_op (U&& t, bool value);

      [[nodiscard]] constexpr
      operator bool () const;

      [[nodiscard]] constexpr decltype (auto)
      operand (void) const;
 
    private:
      T t_;

      const bool value_{};
    };
 
    // ========================================================================

    template <class Lhs_T, class Rhs_T>
    struct binary_op : op
    {
      template <class L, class R>
      constexpr binary_op (L&& lhs, R&& rhs, bool value);

      [[nodiscard]] constexpr
      operator bool () const;

      [[nodiscard]] constexpr decltype (auto)
      lhs (void) const;

      [[nodiscard]] constexpr decltype (auto)
      rhs (void) const;
 
    private:
      Lhs_T lhs_;

      Rhs_T rhs_;

      const bool value_{};
    };
 
    // ========================================================================

    struct equal_to
    {
      static constexpr const char* symbol = " == ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = true;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };

    struct not_equal_to
    {
      static constexpr const char* symbol = " != ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = false;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };

    struct greater
    {
      static constexpr const char* symbol = " > ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = false;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };

    struct greater_equal
    {
      static constexpr const char* symbol = " >= ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = true;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };

    struct less
    {
      static constexpr const char* symbol = " < ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = false;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };

    struct less_equal
    {
      static constexpr const char* symbol = " <= ";
 
#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)
      static constexpr bool within_tolerance_result = true;
#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

      template <class Lhs_T, class Rhs_T>
      [[nodiscard, gnu::always_inline]] static constexpr bool
      apply (const Lhs_T& lhs, const Rhs_T& rhs);
    };
 
    // ========================================================================

    template <class T>
    [[nodiscard]] constexpr auto
    as_operand (T&& t) noexcept -> decltype (auto);

    template <class T>
    using unwrapped_t = std::remove_cvref_t<decltype (detail::unwrap (
        std::declval<const std::remove_cvref_t<T>&> ()))>;
 
    // ========================================================================

    template <class Lhs_T, class Rhs_T, class Compare_T>
    struct compare_op : binary_op<Lhs_T, Rhs_T>
    {
      template <class L, class R>
        requires extension::compare_tag<Compare_T, unwrapped_t<L>,
                                        unwrapped_t<R>>
      constexpr compare_op (L&& lhs, R&& rhs, Compare_T);
 
#if !defined(__DOXYGEN__)
      template <class L, class R>
        requires (not extension::compare_tag<Compare_T, unwrapped_t<L>,
                                             unwrapped_t<R>>)
      constexpr compare_op (L&& lhs, R&& rhs, Compare_T);
#endif // !defined(__DOXYGEN__)
    };

    template <class Lhs_T, class Rhs_T, class Compare_T>
    compare_op (Lhs_T&&, Rhs_T&&, Compare_T)
        -> compare_op<stored_operand_t<decltype (detail::as_operand (
                          std::declval<Lhs_T> ()))>,
                      stored_operand_t<decltype (detail::as_operand (
                          std::declval<Rhs_T> ()))>,
                      Compare_T>;
 
    // ========================================================================

    template <class Lhs_T, class Rhs_T, class Epsilon_T>
    [[nodiscard]] constexpr bool
    differ_by_at_most (Lhs_T lhs, Rhs_T rhs, Epsilon_T epsilon);

    template <class Lhs_T, class Rhs_T, class Epsilon_T>
    struct approx_op : binary_op<Lhs_T, Rhs_T>
    {
      template <class L, class R, class E>
      constexpr approx_op (L&& lhs, R&& rhs, E&& epsilon);

      [[nodiscard]] constexpr decltype (auto)
      epsilon (void) const;
 
    private:
      Epsilon_T epsilon_;
    };

    template <class Lhs_T, class Rhs_T, class Epsilon_T>
    approx_op (Lhs_T&&, Rhs_T&&, Epsilon_T&&)
        -> approx_op<stored_operand_t<Lhs_T>, stored_operand_t<Rhs_T>,
                     stored_operand_t<Epsilon_T>>;
 
    // ========================================================================

    template <class Lhs_T, class Rhs_T>
    struct and_op : binary_op<Lhs_T, Rhs_T>
    {
      template <class L, class R>
      constexpr and_op (L&& lhs, R&& rhs);
    };

    template <typename Lhs_T, typename Rhs_T>
    and_op (Lhs_T&&, Rhs_T&&)
        -> and_op<stored_operand_t<Lhs_T>, stored_operand_t<Rhs_T>>;
 
    // ========================================================================

    template <class Lhs_T, class Rhs_T>
    struct or_op : binary_op<Lhs_T, Rhs_T>
    {
      template <class L, class R>
      constexpr or_op (L&& lhs, R&& rhs);
    };

    template <typename Lhs_T, typename Rhs_T>
    or_op (Lhs_T&&, Rhs_T&&)
        -> or_op<stored_operand_t<Lhs_T>, stored_operand_t<Rhs_T>>;
 
    // ========================================================================

    template <class T>
    struct not_op : unary_op<T>
    {
      template <class U>
        requires (not std::is_same_v<std::remove_cvref_t<U>, not_op<T>>)
      explicit constexpr not_op (U&& t);
    };
 
    // ========================================================================

    template <class T, class Predicate_T>
    struct predicate_op : unary_op<T>
    {
      template <class U>
        requires extension::predicate_tag<Predicate_T, unwrapped_t<U>>
      constexpr predicate_op (U&& t, Predicate_T);
 
#if !defined(__DOXYGEN__)
      template <class U>
        requires (not extension::predicate_tag<Predicate_T, unwrapped_t<U>>)
      constexpr predicate_op (U&& t, Predicate_T);
#endif // !defined(__DOXYGEN__)
    };

    template <class T, class Predicate_T>
    predicate_op (T&&, Predicate_T) -> predicate_op<
        stored_operand_t<decltype (detail::as_operand (std::declval<T> ()))>,
        Predicate_T>;
 
    // ========================================================================

    struct failed_requirement
    {
    };
 
    // ========================================================================
 
#if defined(__cpp_exceptions)

    enum class throw_outcome : unsigned char
    {
      none,

      std_exception,

      unknown_exception
    };

    struct callable_result
    {
      bool value;

      throw_outcome outcome;

      std::string what;
    };

    struct callable_op : op
    {
      explicit callable_op (callable_result&& result);

      [[nodiscard]] constexpr
      operator bool () const;

      [[nodiscard]] throw_outcome
      outcome (void) const noexcept;

      [[nodiscard]] const std::string&
      what (void) const noexcept;
 
    private:
      const bool value_{};

      throw_outcome outcome_{ throw_outcome::none };

      std::string what_{};
    };
 
    // ========================================================================

    template <class Exception_T = void>
    struct throws_op : callable_op
    {
      template <class Callable_T>
        requires std::invocable<Callable_T&>
      explicit throws_op (Callable_T&& func);
    };
 
    // ========================================================================

    template <>
    struct throws_op<void> : callable_op
    {
      template <class Callable_T>
        requires std::invocable<Callable_T&>
      explicit throws_op (Callable_T&& func);
    };
 
    // ========================================================================

    struct nothrow_op : callable_op
    {
      template <class Callable_T>
        requires std::invocable<Callable_T&>
      explicit nothrow_op (Callable_T&& func);
    };
 
#endif // defined(__cpp_exceptions)
 
    // ========================================================================

    template <class T>
      requires std::is_arithmetic_v<T>
    void
    append_number (std::string& buffer, T v);

    template <class T>
    void
    append_pointer (std::string& buffer, T* v);
 
    // ========================================================================

    template <class T>
    concept character = std::is_same_v<std::remove_cv_t<T>, char>
                        or std::is_same_v<std::remove_cv_t<T>, wchar_t>
                        or std::is_same_v<std::remove_cv_t<T>, char8_t>
                        or std::is_same_v<std::remove_cv_t<T>, char16_t>
                        or std::is_same_v<std::remove_cv_t<T>, char32_t>;

    template <class T>
    concept character_pointer
        = std::is_pointer_v<T> and character<std::remove_pointer_t<T>>
          and not std::is_volatile_v<std::remove_pointer_t<T>>;

    template <character Char_T>
    struct basic_c_string
    {
      constexpr explicit basic_c_string (const Char_T* str) noexcept;

      constexpr basic_c_string (const Char_T* str,
                                std::size_t capacity) noexcept;

      [[nodiscard]] constexpr std::basic_string_view<Char_T>
      view (void) const noexcept;

      [[nodiscard]] constexpr bool
      is_null (void) const noexcept;
 
    private:
      const Char_T* str_;

      std::size_t size_;
    };

    using c_string = basic_c_string<char>;

    template <character Char_T>
    [[nodiscard]] constexpr bool
    operator== (const basic_c_string<Char_T>& lhs,
                const basic_c_string<Char_T>& rhs) noexcept;

    template <character Char_T>
    [[nodiscard]] constexpr bool
    operator== (
        const basic_c_string<Char_T>& lhs,
        std::type_identity_t<std::basic_string_view<Char_T>> rhs) noexcept;

    template <character Char_T>
    [[nodiscard]] constexpr bool
    operator== (const basic_c_string<Char_T>& lhs, std::nullptr_t) noexcept;

    template <character Char_T>
    [[nodiscard]] constexpr std::strong_ordering
    operator<=> (const basic_c_string<Char_T>& lhs,
                 const basic_c_string<Char_T>& rhs) noexcept;

    template <character Char_T>
    [[nodiscard]] constexpr std::strong_ordering
    operator<=> (
        const basic_c_string<Char_T>& lhs,
        std::type_identity_t<std::basic_string_view<Char_T>> rhs) noexcept;

    template <class T>
    struct array_operand
    {
      constexpr array_operand (const T* first, std::size_t count) noexcept;

      [[nodiscard]] constexpr const T*
      begin (void) const noexcept;

      [[nodiscard]] constexpr const T*
      end (void) const noexcept;
 
    private:
      const T* first_;

      std::size_t count_;
    };

    template <class T, class R>
      requires (container_like<R>
                and std::equality_comparable_with<
                    T, typename range_element<R>::type>)
    [[nodiscard]] constexpr bool
    operator== (const array_operand<T>& lhs, const R& rhs);

    template <class T, class R>
      requires (container_like<R>
                and std::three_way_comparable_with<
                    T, typename range_element<R>::type>)
    [[nodiscard]] constexpr auto
    operator<=> (const array_operand<T>& lhs, const R& rhs);
 
    // ------------------------------------------------------------------------
  } // namespace detail
 
  // --------------------------------------------------------------------------
 
  namespace extension
  {
    // ------------------------------------------------------------------------
    // The expressions of the custom comparators, predicates, and operators.
 
    // The definitions are in `detail`, with the built-in expressions that
    // share them; the using-declarations name the same templates, so the
    // class template argument deduction applies, and the formatter
    // reports them as the built-in ones.
 
    using detail::compare_op;
    using detail::predicate_op;
 
    // ------------------------------------------------------------------------

    template <class T>
    concept approx_operand
        = std::is_arithmetic_v<detail::unwrapped_t<T>>
          and not std::is_same_v<detail::unwrapped_t<T>, bool>
          and not std::is_same_v<detail::unwrapped_t<T>, char>
          and not std::is_same_v<detail::unwrapped_t<T>, wchar_t>
          and not std::is_same_v<detail::unwrapped_t<T>, char8_t>
          and not std::is_same_v<detail::unwrapped_t<T>, char16_t>
          and not std::is_same_v<detail::unwrapped_t<T>, char32_t>;
 
    // ------------------------------------------------------------------------
  } // namespace extension
 
  // --------------------------------------------------------------------------
} // namespace micro_os_plus::micro_test_plus
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
// ----------------------------------------------------------------------------
 
#endif // defined(__cplusplus)
 
// ============================================================================
// Templates, inlines & constexpr implementations.
 
#include "inlines/detail-inlines.h"
 
// ----------------------------------------------------------------------------
 
#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_DETAIL_H_
 
// ----------------------------------------------------------------------------