StdCompat.h

Go to the documentation of this file.

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Foundation_Common_StdCompat_h_
#define _Stroika_Foundation_Common_StdCompat_h_ 1
 
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include <bit>
#include <chrono>
#include <cmath>
#include <compare>
#include <concepts>
#include <cstdarg>
#include <ranges>
 
#if defined(__cpp_lib_expected)
#include <expected>
#else
#include <variant>
#endif
 
// Various kooky constraints
//      (1) clang++15/16 don't set __cpp_lib_format, so cannot check __cpp_lib_format >= 201907 instead check __has_include(<format>)
//      (2) has_include <format> false positives on some versions of XCode, and no reason to even build qStroika_HasComponent_fmtlib unless
//          its needed, so check it first
 
#if qStroika_HasComponent_fmtlib
#include <fmt/chrono.h>
#include <fmt/format.h>
#include <fmt/xchar.h>
#elif __has_include(<format>)
#include <format>
#endif
 
/**
 *  \file
 * 
 *  The purpose of this module is to define any std c++ functions/classes etc - which may not be provided by the
 *  current std c++ library (often because not compiled with appropriate --std=... flag) - and/or because its
 *  an old compiler.
 * 
 *  This also includes 'named requirements' - rendered as concepts (probably SHOULD be part of CPP standard but are not).
 *
 *  This doesn't strictly violate any rules about sticking stuff into namespace std - cuz we don't. That's why we use a
 *  separate namespace (that often just indirects to the namespace std - where the function/class is defined already).
 *
 *  A thin layer over the standard library: it includes nothing of Stroika's (beyond StroikaPreComp.h), so it is usable
 *  wherever std is.
 *
 *  \note Code-Status:  <a href="Code-Status.md#Beta">Beta</a>
 *
 */
 
namespace Stroika::Foundation::Common::StdCompat {
 
    /**
     *  By default include all of std, but throw in selected missing things from some implementations.
     */
    using namespace std;
 
    /**
     * \brief Logically the C++ standard BasicLockable named requirement, but that was not included in std c++ library
     *
     *  Must be satisfied by:       std::mutex, std::recursive_mutex, std::timed_mutex, std::shared_mutex,
     *                              std::unique_lock<std::mutex>
     *  NOT satisfied by:           std::lock_guard<std::mutex> - it is a scope guard, and exposes no
     *                              lock ()/unlock () of its own
     *
     *  \note   The examples above, and that this concept is not vacuously true, are asserted in
     *          StdCompat.cpp. They live in a .cpp so the <mutex>/<shared_mutex> needed to name the types
     *          costs one translation unit rather than every one that includes this header.
     *
     * \see https://en.cppreference.com/w/cpp/named_req/BasicLockable.html
     */
    template <typename T>
    concept BasicLockable = requires (T lo) {
        // Requires a public lock() member function
        { lo.lock () } -> std::same_as<void>;
        // Requires a public unlock() member function
        { lo.unlock () } -> std::same_as<void>;
    };
 
    /**
     * \brief Logically the C++ standard Lockable named requirement, but that was not included in std c++ library
     *
     *  Must be satisfied by:       std::mutex, std::recursive_mutex, std::timed_mutex, std::shared_mutex
     *
     *  \note   Asserted in StdCompat.cpp - including the check that matters most, that this concept is
     *          STRICTLY STRONGER than BasicLockable. That needs a purpose-built type: every std lockable
     *          type offers try_lock () too, so no standard type could ever tell the two apart.
     *
     * \see https://en.cppreference.com/w/cpp/named_req/Lockable.html
     */
    template <typename T>
    concept Lockable = BasicLockable<T> and requires (T lo) {
        { lo.try_lock () } -> std::same_as<bool>;
    };
 
    /**
     * \brief Logically the C++ standard TimedLockable named requirement, but that was not included in std c++ library
     * 
     * The TimedMutex requirements extend the TimedLockable requirements to include inter-thread synchronization
     *
     *  Must be satisfied by:       std::timed_mutex, std::recursive_timed_mutex
     *  NOT satisfied by:           std::mutex - it has no try_lock_for ()/try_lock_until ()
     *
     *  \note   Asserted in StdCompat.cpp, along with the check that this is strictly stronger than
     *          Lockable. @see the note on BasicLockable for why those live in a .cpp.
     *
     * \see https://en.cppreference.com/w/cpp/named_req/TimedLockable.html
     */
    template <typename T>
    concept TimedLockable = Lockable<T> and requires (T lo, const chrono::milliseconds& d, const chrono::time_point<chrono::steady_clock>& tp) {
        // Requires a public try_lock_for() taking a duration
        { lo.try_lock_for (d) } -> std::same_as<bool>;
        // Requires a public try_lock_until() taking a time_point
        { lo.try_lock_until (tp) } -> std::same_as<bool>;
    };
 
    /**
     * \brief Logically the C++ standard TimedMutex named requirement, but that was not included in std c++ library
     *
     *  A TimedMutex is a Mutex which also satisfies TimedLockable - it adds to TimedLockable that the type
     *  is default-constructible and neither copyable nor movable, as every std mutex type is.
     *
     *  Must be satisfied by:       std::timed_mutex, std::recursive_timed_mutex
     *  NOT satisfied by:           std::mutex (it is not TimedLockable)
     *
     *  \note   Asserted in StdCompat.cpp, together with 'not TimedMutex<int>' - which is there to prove
     *          the concept is not vacuously true, the way a botched requires-clause silently would be.
     *
     * \see https://en.cppreference.com/w/cpp/named_req/TimedMutex.html
     */
    template <typename T>
    concept TimedMutex =
        TimedLockable<T> and default_initializable<T> and destructible<T> and not copy_constructible<T> and not move_constructible<T>;
 
    namespace Private_ {
        template <class _Ty>
        concept _Boolean_testable_impl = convertible_to<_Ty, bool>;
    }
 
    /**
     *  \brief handy re-usable concept, with the obvious meaning, and strangely omitted from std-c++ (though used in exposition).
     * 
     *  \see https://en.cppreference.com/w/cpp/concepts/boolean-testable.html
     */
    template <class _Ty>
    concept Boolean_testable = Private_::_Boolean_testable_impl<_Ty> && requires (_Ty&& __t) {
        { !static_cast<_Ty&&> (__t) } -> Private_::_Boolean_testable_impl;
    };
 
    /**
     *  \brief like convertible_to, but also handling cases where T has an explicit CTOR taking From
     * 
     *  \see https://stackoverflow.com/questions/76547398/stdconvertible-to-failing-to-recognize-explicitly-convertible-types
     */
    template <class FROM, class TO>
    concept explicitly_convertible_to = requires { static_cast<TO> (declval<FROM> ()); };
 
#if qStroika_HasComponent_fmtlib
#define qStroika_Foundation_Characters_FMT_PREFIX_ fmt
#elif __has_include(<format>)
#define qStroika_Foundation_Characters_FMT_PREFIX_ std
#else
    static_assert (false, "Stroika v3 requires some std::format compatible library - if building with one lacking builtin std::format, "
                          "configure --fmtlib use");
#endif
 
    /**
     *  To allow interop between std::format and fmt(fmtlib)::format, publish the names into the namespace 'Stroika::Foundation::Common::StdCompat' and use those.
     *  Lose this once I can fully depend upon std::format... --LGP 2024-03-12
     */
    using qStroika_Foundation_Characters_FMT_PREFIX_::basic_format_parse_context;
    using qStroika_Foundation_Characters_FMT_PREFIX_::format;
    using qStroika_Foundation_Characters_FMT_PREFIX_::format_args;
    using qStroika_Foundation_Characters_FMT_PREFIX_::format_error;
    using qStroika_Foundation_Characters_FMT_PREFIX_::format_string;
    using qStroika_Foundation_Characters_FMT_PREFIX_::format_to;
    using qStroika_Foundation_Characters_FMT_PREFIX_::make_format_args;
    using qStroika_Foundation_Characters_FMT_PREFIX_::make_wformat_args;
    using qStroika_Foundation_Characters_FMT_PREFIX_::vformat;
    using qStroika_Foundation_Characters_FMT_PREFIX_::wformat_args;
    using qStroika_Foundation_Characters_FMT_PREFIX_::wformat_string;
 
#if qStroika_Foundation_Common_cplusplus >= qStroika_Foundation_Common_cplusplus_23
    template <class T, class CharT>
    concept formattable = std::formattable<T, CharT>;
#else
    namespace Private_ {
        template <class _CharT>
        struct _Phony_fmt_iter_for {
            using difference_type = ptrdiff_t;
            _CharT&              operator* () const;
            _Phony_fmt_iter_for& operator++ ();
            _Phony_fmt_iter_for  operator++ (int);
        };
        // _Formatter a defaulted template parameter, not named in the requires: needed for clang++-15 (compiler bug but no BWA declaration
        // for now...BWA in middle of BWA ;-)). And formatter<T, char_type> - which a context's formatter_type<T> is by definition - as
        // fmtlib's context (as of fmtlib 11) has no formatter_type.
        template <class _Ty, class _Context, class _Formatter = qStroika_Foundation_Characters_FMT_PREFIX_::formatter<remove_const_t<_Ty>, typename _Context::char_type>>
        concept _Formattable_with = semiregular<_Formatter> && requires (_Formatter& __f, const _Formatter& __cf, _Ty&& __t, _Context __fc,
                                                                         basic_format_parse_context<typename _Context::char_type> __pc) {
            { __f.parse (__pc) } -> same_as<typename decltype (__pc)::iterator>;
            { __cf.format (__t, __fc) } -> same_as<typename _Context::iterator>;
        };
    }
    template <class T, class CharT>
    concept formattable =
        Private_::_Formattable_with<remove_reference_t<T>, qStroika_Foundation_Characters_FMT_PREFIX_::basic_format_context<Private_::_Phony_fmt_iter_for<CharT>, CharT>>;
#endif
 
    /**
     *  Kept so existing callers of StdCompat::bit_cast still compile; every supported standard library now has std::bit_cast
     *  (the fallback was for XCode 14).
     */
    using std::bit_cast;
 
    /**
     *  std::byteswap where the standard library has it (it is C++23), else an equivalent - so every C++20 build uses
     *  the version below.
     */
#if defined(__cpp_lib_byteswap)
    using std::byteswap;
#else
    template <class T>
    inline T byteswap (T n) noexcept
    {
        static_assert (std::has_unique_object_representations_v<T>, "T may not have padding bits");
        auto value_representation = bit_cast<array<byte, sizeof (T)>> (n);
        for (size_t i = 0; i < value_representation.size () / 2; ++i) {
            swap (value_representation[i], value_representation[value_representation.size () - 1 - i]);
        }
        return bit_cast<T> (value_representation);
    }
#endif
 
    /**
     *  std::isinf, but constexpr where the standard library allows it (C++23)
     */
    template <typename T>
#if qStroika_Foundation_Common_cplusplus >= qStroika_Foundation_Common_cplusplus_23
    constexpr
#else
    inline
#endif
        bool isinf (T v) noexcept
    {
        return std::isinf (v);
    }
 
    /**
     *  std::isnan, but constexpr where the standard library allows it (C++23)
     */
    template <typename T>
#if qStroika_Foundation_Common_cplusplus >= qStroika_Foundation_Common_cplusplus_23
    constexpr
#else
    inline
#endif
        bool isnan (T v) noexcept
    {
        return std::isnan (v);
    }
 
#if qCompilerAndStdLib_stdlib_compare_three_way_present_but_Buggy
    struct compare_three_way {
        // NOTE - this workaround is GENERALLY INADEQUATE, but is adequate for my current use in Stroika -- LGP 2022-11-01
        template <typename LT, typename RT>
        constexpr auto operator() (LT&& lhs, RT&& rhs) const
        {
            using CT = common_type_t<LT, RT>;
            if (equal_to<CT>{}(forward<LT> (lhs), forward<RT> (rhs))) {
                return strong_ordering::equal;
            }
            return less<CT>{}(forward<LT> (lhs), forward<RT> (rhs)) ? strong_ordering::less : strong_ordering::greater;
        }
        using is_transparent = void;
    };
#else
    using compare_three_way = std::compare_three_way;
#endif
 
    /**
     *  Wrap a simplified version of std::unexpected, cuz handy even if c++23 not present
     */
#if defined(__cpp_lib_expected)
    template <typename T>
    using unexpected = std::unexpected<T>;
    template <typename T, typename E>
    using expected = std::expected<T, E>;
#else
    template <typename T>
    class unexpected {
    public:
        template <typename _UError = T>
            requires (!is_same_v<remove_cvref_t<_UError>, unexpected> && !is_same_v<remove_cvref_t<_UError>, in_place_t> && is_constructible_v<T, _UError>)
        constexpr explicit unexpected (_UError&& _Unex)
            : _Unexpected (forward<_UError> (_Unex))
        {
        }
        template <typename... _Args>
            requires is_constructible_v<T, _Args...>
        constexpr explicit unexpected (in_place_t, _Args&&... _Vals)
            : _Unexpected (forward<_Args> (_Vals)...)
        {
        }
        template <typename _Uty, typename... _Args>
            requires is_constructible_v<T, initializer_list<_Uty>&, _Args...>
        constexpr explicit unexpected (in_place_t, initializer_list<_Uty> _Ilist, _Args&&... _Vals)
            : _Unexpected (_Ilist, forward<_Args> (_Vals)...)
        {
        }
 
        constexpr const T& error () const& noexcept
        {
            return _Unexpected;
        }
        constexpr T& error () & noexcept
        {
            return _Unexpected;
        }
        constexpr const T&& error () const&& noexcept
        {
            return std::move (_Unexpected);
        }
        constexpr T&& error () && noexcept
        {
            return std::move (_Unexpected);
        }
 
        constexpr void swap (unexpected& _Other)
        {
            using std::swap;
            swap (_Unexpected, _Other._Unexpected); // intentional ADL
        }
 
        friend constexpr void swap (unexpected& _Left, unexpected& _Right)
            requires is_swappable<T>::value // TRANSITION, /permissive needs ::value
        {
            _Left.swap (_Right);
        }
 
        template <class _UErr>
        friend constexpr bool operator== (const unexpected& _Left, const unexpected<_UErr>& _Right)
        {
            return _Left._Unexpected == _Right.error ();
        }
 
    private:
        T _Unexpected;
    };
    template <typename T>
    unexpected (T) -> unexpected<T>;
 
    /**
     *  Wrap a simplified version of std::expected, cuz handy even if c++23 not present
     * 
     *      \note STILL VERY ROUGH DRAFT - IN USE - BUT NOT SURE ITS RIGHT (cuz mine works but delegating to
     *            MSFT one not working, so maybe mine wrong).
     */
    template <typename T, typename E>
    class expected;
    template <typename T, typename E>
    class expected {
    public:
        using value_type      = T;
        using error_type      = E;
        using unexpected_type = unexpected<E>;
 
        constexpr expected () noexcept                = default;
        constexpr expected (const expected&) noexcept = default;
        constexpr expected (T v)
            : fData_{v}
        {
        }
        constexpr expected (const unexpected_type& e)
            : fData_{e.error ()}
        {
        }
        template <typename T1, typename E1>
        constexpr expected (const expected<T1, E1>& e)
        {
            if (e) {
                fData_ = e.value ();
            }
            else {
                fData_ = e.error ();
            }
        }
        explicit operator bool () const noexcept
        {
            return std::get_if<T> (&fData_) != nullptr;
        }
        T operator* () const
        {
            return value ();
        }
        T value () const
        {
            return get<T> (fData_);
        }
        E error () const
        {
            return get<E> (fData_);
        }
 
    private:
        variant<T, E> fData_;
    };
#endif
 
    /**
     * \brief Stroika_ATTRIBUTE_INDETERMINATE is used where you would use a C++ attribute for a variable that is intentionally uninitialized
     * 
     * [[indeterminate]]
     * https://en.cppreference.com/w/cpp/language/attributes/indeterminate.html
     * 
     *  \par Example Usage
     *      \code
     *         Stroika_ATTRIBUTE_INDETERMINATE byte r[1024]; // don't initialize explicitly cuz filled in below before used (performance)
     *      \endcode
     */
#if __has_cpp_attribute(indeterminate)
#define Stroika_ATTRIBUTE_INDETERMINATE [[indeterminate]]
#else
#define Stroika_ATTRIBUTE_INDETERMINATE
#endif
 
    /**
     * \brief Stroika_ATTRIBUTE_ASSUME(C) is used where you would put a C++ attribute assume expression, to assume a condition is true for a given block.
     *
     *  The assume attribute was introduced in c++23, and Stroika OPTIONALLY supports this, but doesn't require it as of Stroika v3.
     *  So use Stroika_ATTRIBUTE_ASSUME () to conditionally use [[assume(X)]]
     */
#if __has_cpp_attribute(assume) && defined(__clang__)
    // clang warns by default (-Wassume) whenever it ignores an assumption whose expression might have side effects, such as
    // a function call. That helps someone who wrote [[assume]] by hand for its effect; for the Assert/Require/Ensure that
    // expand to this - conditions written as documentation first - it is only noise. So silence it for these expansions
    // only, not for other code's own [[assume]]s.
#define Stroika_ATTRIBUTE_ASSUME(X)                                                                                                        \
    _Pragma ("clang diagnostic push") _Pragma ("clang diagnostic ignored \"-Wassume\"") [[assume (X)]];                                    \
    _Pragma ("clang diagnostic pop")
#elif __has_cpp_attribute(assume)
#define Stroika_ATTRIBUTE_ASSUME(X) [[assume (X)]];
#elif _MSC_VER
    // Docs not clear.
    // https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1774r4.pdf suggests this hack. BUT...
    // https://github.com/MicrosoftDocs/cpp-docs/blob/main/docs/build/optimization-best-practices.md seems to hint __assume doesn't evaluate X, except to pay attention to simple a>constant compares so this should be OK
#define Stroika_ATTRIBUTE_ASSUME(X) __assume (X);
#else
#define Stroika_ATTRIBUTE_ASSUME(X)
#endif
 
    /**
     * \brief Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS - used for the attribute [[no_unique_address]]
     * 
     *  MSVC accepts [[no_unique_address]] but ignores it, to keep its ABI, and supports [[msvc::no_unique_address]] instead
     *  (see qCompilerAndStdLib_NO_UNIQUE_ADDR_IgnoredAndMustUseMSVCNOUNIQUE_Buggy)
     */
#if qCompilerAndStdLib_NO_UNIQUE_ADDR_IgnoredAndMustUseMSVCNOUNIQUE_Buggy && defined(_MSC_VER)
#if qCompilerAndStdLib_NO_UNIQUE_ADDR_REALLYREALLY_Buggy
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
#else
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS [[msvc::no_unique_address]]
#endif
#elif __has_cpp_attribute(no_unique_address)
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS [[no_unique_address]]
#else
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
#endif
 
    /**
     * \brief [[msvc::no_unique_address]] isn't always broken in MSVC. Annotate with this
     *        on things where its not broken.
     */
#if qCompilerAndStdLib_NO_UNIQUE_ADDR_REALLYREALLY_Buggy
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE [[msvc::no_unique_address]]
#else
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
#endif
 
    /**
     * \brief Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCBUGGY same as Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
     * 
     * EMPHASIZE that this is Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
     * and not Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE cuz its known buggy
     */
#define Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCBUGGY Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
 
// DEPRECATED NAMES - since 3.0d25 (to be removed in v3.0a1): these expand to attributes, not values, so by
// Design-Overview.md "Macro names" they take the Stroika_ prefix, not q
#define qStroika_ATTRIBUTE_INDETERMINATE Stroika_ATTRIBUTE_INDETERMINATE
#define qStroika_ATTRIBUTE_ASSUME Stroika_ATTRIBUTE_ASSUME
#define qStroika_ATTRIBUTE_NO_UNIQUE_ADDRESS Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS
#define qStroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE
#define qStroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCBUGGY Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCBUGGY
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "StdCompat.inl"
 
#endif /*_Stroika_Foundation_Common_StdCompat_h_*/