Iterable.inl

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#include <algorithm>
#include <execution>
#include <set>
 
#include "Stroika/Foundation/Containers/Adapters/Adder.h"
#include "Stroika/Foundation/Debug/Assertions.h"
#include "Stroika/Foundation/Debug/Cast.h"
#include "Stroika/Foundation/Math/Statistics.h"
#include "Stroika/Foundation/Memory/BlockAllocated.h"
#include "Stroika/Foundation/Traversal/Generator.h"
 
namespace Stroika::Foundation::Traversal {
 
    constexpr bool kIterableUsesStroikaSharedPtr [[deprecated ("Since Stroika v3.0d1 - not used")]] = false;
 
    struct [[deprecated ("Since Stroika v3.0d1")]] IterableBase {
        template <typename SHARED_T>
        using PtrImplementationTemplate [[deprecated ("Since Stroika v3.0d1 - use shared_ptr directly")]] = shared_ptr<SHARED_T>;
        template <typename SHARED_T, typename... ARGS_TYPE>
        [[deprecated ("Since Stroika v3.0d1 - use Memory::MakeSharedPtr directly")]] static shared_ptr<SHARED_T> MakeSmartPtr (ARGS_TYPE&&... args)
        {
            return Memory::MakeSharedPtr<SHARED_T> (forward<ARGS_TYPE> (args)...);
        }
        template <typename SHARED_T>
        using enable_shared_from_this_PtrImplementationTemplate [[deprecated ("Since Stroika v3.0d1")]] = std::enable_shared_from_this<SHARED_T>;
    };
 
    /*
     ********************************************************************************
     ***************************** Iterable<T>::_IRep *******************************
     ********************************************************************************
     */
    template <typename T>
    inline size_t Iterable<T>::_IRep::size () const
    {
        /*
         * Default slow/weak implementation.
         */
        size_t sz{};
        if constexpr (true) {
            // eSeq is REQUIRED here, not just the current default: '++sz' on a captured local is a data race
            // under any parallel policy. Do not 'simplify' this to the no-policy overload.
            this->Apply ([&sz] (const T&) { ++sz; }, Execution::SequencePolicy::eSeq);
        }
        else {
            for (Iterator<T> i = MakeIterator (); i != Iterator<T>::GetEmptyIterator (); ++i, ++sz)
                ;
        }
        return sz;
    }
    template <typename T>
    inline bool Iterable<T>::_IRep::empty () const
    {
        if (auto i = MakeIterator ()) {
            return false;
        }
        return true;
    }
    template <typename T>
    inline void Iterable<T>::_IRep::Apply (const function<void (ArgByValueType<T> item)>& doToElement, [[maybe_unused]] Execution::SequencePolicy seq) const
    {
        RequireNotNull (doToElement);
        for (Iterator<T> i = MakeIterator (); i != Iterator<T>::GetEmptyIterator (); ++i) {
            doToElement (*i);
        }
    }
    template <typename T>
    inline auto Iterable<T>::_IRep::Find ([[maybe_unused]] bool findFirst, const function<bool (ArgByValueType<T> item)>& that,
                                          [[maybe_unused]] Execution::SequencePolicy seq) const -> Iterator<value_type>
    {
        RequireNotNull (that);
        for (Iterator<T> i = MakeIterator (); i != Iterator<T>::GetEmptyIterator (); ++i) {
            if (that (*i)) {
                return i;
            }
        }
        return Iterator<T>::GetEmptyIterator ();
    }
    template <typename T>
    inline auto Iterable<T>::_IRep::Find_equal_to (const ArgByValueType<T>& v, [[maybe_unused]] Execution::SequencePolicy seq) const
        -> Iterator<value_type>
    {
        if constexpr (Common::IEqualToOptimizable<T>) {
            /*
             *  This is the default implementation. It is only ever if there is a valid equal_to<> around, and
             *  that valid equal_to<> is stateless (verified by Common::IEqualToOptimizable).
             */
            if constexpr (true) {
                // simpler but not sure if faster; better though cuz by default leverages seq, which might
                // help. In 'size' testing, on windows, this was slightly larger, so
                // not 100% sure this is the best default -- LGP 2023-02-06
                return Find (/*findFirst*/ true, [&v] (const T& rhs) { return equal_to<T>{}(v, rhs); }, seq);
            }
            else {
                for (Iterator<T> i = MakeIterator (); i != Iterator<T>::GetEmptyIterator (); ++i) {
                    if (equal_to<T>{}(v, *i)) {
                        return i;
                    }
                }
                return Iterator<T>::GetEmptyIterator ();
            }
        }
        else {
            RequireNotReached (); // cannot call if not IEqualToOptimizable
            return Iterator<T>::GetEmptyIterator ();
        }
    }
    template <typename T>
    inline auto Iterable<T>::_IRep::PeekContiguousStorage () const -> optional<span<const value_type>>
    {
        return nullopt; // ie no contiguous storage to offer; callers fall back to iterating
    }
 
    /*
     ********************************************************************************
     ******************* Iterable<T>::_SafeReadRepAccessor **************************
     ********************************************************************************
     */
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline Iterable<T>::_SafeReadRepAccessor<REP_SUB_TYPE>::_SafeReadRepAccessor (const Iterable<T>* it) noexcept
        : fConstRef_{Debug::UncheckedDynamicCast<const REP_SUB_TYPE*> (it->_fRep.cget ())}
        , fIterableEnvelope_{it}
#if qStroika_Foundation_Debug_AssertionsChecked
        , fAssertReadLock_{it->_fThisAssertExternallySynchronized}
#endif
    {
        RequireNotNull (it);
        EnsureMember (fConstRef_, REP_SUB_TYPE);
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline Iterable<T>::_SafeReadRepAccessor<REP_SUB_TYPE>::_SafeReadRepAccessor (_SafeReadRepAccessor&& src) noexcept
        : fConstRef_{src.fConstRef_}
        , fIterableEnvelope_{src.fIterableEnvelope_}
#if qStroika_Foundation_Debug_AssertionsChecked
        , fAssertReadLock_{move (src.fAssertReadLock_)}
#endif
    {
        RequireNotNull (fConstRef_);
        EnsureMember (fConstRef_, REP_SUB_TYPE);
        src.fConstRef_ = nullptr;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline auto Iterable<T>::_SafeReadRepAccessor<REP_SUB_TYPE>::operator= (_SafeReadRepAccessor&& rhs) noexcept -> _SafeReadRepAccessor&
    {
        fConstRef_               = rhs.fConstRef_;
        this->fIterableEnvelope_ = rhs.fIterableEnvelope_;
#if qStroika_Foundation_Debug_AssertionsChecked
        this->fAssertReadLock_ = move (rhs.fAssertReadLock_);
#endif
        return *this;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline const REP_SUB_TYPE& Iterable<T>::_SafeReadRepAccessor<REP_SUB_TYPE>::_ConstGetRep () const noexcept
    {
        EnsureMember (fConstRef_, REP_SUB_TYPE);
        return *fConstRef_;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline auto Iterable<T>::_SafeReadRepAccessor<REP_SUB_TYPE>::_ConstGetRepSharedPtr () const noexcept -> shared_ptr<REP_SUB_TYPE>
    {
        return Debug::UncheckedDynamicPointerCast<REP_SUB_TYPE> (this->fIterableEnvelope_->_fRep.cget_ptr ());
    }
 
    /*
     ********************************************************************************
     ************* Iterable<CONTAINER_OF_T, T>::_SafeReadWriteRepAccessor ***********
     ********************************************************************************
     */
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline Iterable<T>::_SafeReadWriteRepAccessor<REP_SUB_TYPE>::_SafeReadWriteRepAccessor (Iterable<T>* iterableEnvelope)
        : fRepReference_{Debug::UncheckedDynamicCast<REP_SUB_TYPE*> (iterableEnvelope->_fRep.rwget ())}
#if qStroika_Foundation_Debug_AssertionsChecked
        , fAssertWriteLock_{iterableEnvelope->_fThisAssertExternallySynchronized}
        , fIterableEnvelope_{iterableEnvelope}
#endif
    {
        RequireNotNull (iterableEnvelope);
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline Iterable<T>::_SafeReadWriteRepAccessor<REP_SUB_TYPE>::_SafeReadWriteRepAccessor (_SafeReadWriteRepAccessor&& from)
        : fRepReference_{from.fRepReference_}
#if qStroika_Foundation_Debug_AssertionsChecked
        , fAssertWriteLock_{move (from.fAssertWriteLock_)}
        , fIterableEnvelope_{from.fIterableEnvelope_}
#endif
    {
        RequireNotNull (fRepReference_);
        EnsureMember (fRepReference_, REP_SUB_TYPE);
#if qStroika_Foundation_Debug_AssertionsChecked
        from.fIterableEnvelope_ = nullptr;
#endif
        from.fRepReference_ = nullptr;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline auto Iterable<T>::_SafeReadWriteRepAccessor<REP_SUB_TYPE>::operator= (_SafeReadWriteRepAccessor&& rhs) noexcept -> _SafeReadWriteRepAccessor&
    {
        fRepReference_ = rhs.fRepReference_;
        EnsureMember (fRepReference_, REP_SUB_TYPE);
#if qStroika_Foundation_Debug_AssertionsChecked
        this->fAssertWriteLock_  = move (rhs.fAssertWriteLock_);
        this->fIterableEnvelope_ = rhs.fIterableEnvelope_;
        rhs.fIterableEnvelope_   = nullptr;
#endif
        return *this;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline const REP_SUB_TYPE& Iterable<T>::_SafeReadWriteRepAccessor<REP_SUB_TYPE>::_ConstGetRep () const
    {
        EnsureNotNull (fRepReference_);
        return *fRepReference_;
    }
    template <typename T>
    template <typename REP_SUB_TYPE>
    inline REP_SUB_TYPE& Iterable<T>::_SafeReadWriteRepAccessor<REP_SUB_TYPE>::_GetWriteableRep ()
    {
        EnsureNotNull (fRepReference_);
#if qStroika_Foundation_Debug_AssertionsChecked
        EnsureNotNull (fIterableEnvelope_);
        EnsureNotNull (fIterableEnvelope_->_fRep);
        Ensure (fIterableEnvelope_->_fRep.use_count () == 1);
#endif
        return *fRepReference_;
    }
 
    /*
     ********************************************************************************
     ********************************** Iterable<T> *********************************
     ********************************************************************************
     */
    template <typename T>
    inline Iterable<T>::Iterable (const shared_ptr<typename Iterable<T>::_IRep>& rep) noexcept
        : _fRep{(RequireExpression (rep != nullptr), rep)}
    {
        Require (_fRep.GetSharingState () != Memory::SharedByValueSupport::SharingState::eNull);
    }
    template <typename T>
    inline Iterable<T>::Iterable (shared_ptr<typename Iterable<T>::_IRep>&& rep) noexcept
        : _fRep{(RequireExpression (rep != nullptr), move (rep))}
    {
        Require (_fRep.GetSharingState () != Memory::SharedByValueSupport::SharingState::eNull);
        Require (rep == nullptr); // after move (see https://en.cppreference.com/w/cpp/memory/shared_ptr/shared_ptr "After the construction, ... r is empty and its stored pointer is null"
    }
#if !qCompilerAndStdLib_RequiresNotMatchInlineOutOfLineForTemplateClassBeingDefined_Buggy
    template <typename T>
    template <IIterableOfTo<T> CONTAINER_OF_T>
    Iterable<T>::Iterable (CONTAINER_OF_T&& from)
        requires (not derived_from<remove_cvref_t<CONTAINER_OF_T>, Iterable<T>> and
                  (copyable<remove_cvref_t<CONTAINER_OF_T>> or same_as<remove_cvref_t<CONTAINER_OF_T>, initializer_list<T>>))
        : _fRep{mk_ (forward<CONTAINER_OF_T> (from))._fRep}
    {
    }
#endif
    template <typename T>
    inline Iterable<T>::Iterable (const initializer_list<T>& from)
        : _fRep{mk_ (from)._fRep}
    {
    }
    template <typename T>
    inline Iterable<T>::operator bool () const
    {
        return not empty ();
    }
    template <typename T>
    inline shared_ptr<typename Iterable<T>::_IRep> Iterable<T>::Clone_ (const _IRep& rep)
    {
        return rep.Clone ();
    }
    template <typename T>
    template <typename CONTAINER_OF_T>
    Iterable<T> Iterable<T>::mk_ (CONTAINER_OF_T&& from)
        requires (copyable<remove_cvref_t<CONTAINER_OF_T>> or same_as<remove_cvref_t<CONTAINER_OF_T>, initializer_list<T>>)
    {
        using DECAYED_CONTAINER = remove_cvref_t<CONTAINER_OF_T>;
        // Most containers are safe to use copy-by-value, except not initializer_list<> - not sure how to check for that generically...
        using USE_CONTAINER_TYPE =
            conditional_t<copy_constructible<DECAYED_CONTAINER> and not same_as<DECAYED_CONTAINER, initializer_list<T>>, DECAYED_CONTAINER, vector<T>>;
        auto sharedCopyOfContainer = Memory::MakeSharedPtr<USE_CONTAINER_TYPE> (forward<CONTAINER_OF_T> (from));
        // shared copy so if/when getNext copied, the container itself isn't (so not invalidating any iterators)
        function<optional<T> ()> getNext = [sharedCopyOfContainer, i = sharedCopyOfContainer->begin ()] () mutable -> optional<T> {
            if (i != sharedCopyOfContainer->end ()) {
                return *i++; // intentionally increment AFTER returning value
            }
            return nullopt;
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    inline Memory::SharedByValueSupport::SharingState Iterable<T>::_GetSharingState () const
    {
        return _fRep.GetSharingState ();
    }
    template <typename T>
    inline Iterator<T> Iterable<T>::MakeIterator () const
    {
        _SafeReadRepAccessor<> accessor{this};
        return accessor._ConstGetRep ().MakeIterator ();
    }
    template <typename T>
    inline size_t Iterable<T>::size () const
    {
        _SafeReadRepAccessor<> accessor{this};
        return accessor._ConstGetRep ().size ();
    }
    template <typename T>
    inline bool Iterable<T>::empty () const
    {
        _SafeReadRepAccessor<> accessor{this};
        return accessor._ConstGetRep ().empty ();
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    bool Iterable<T>::Contains (ArgByValueType<T> element, EQUALS_COMPARER&& equalsComparer) const
    {
        /*
         *  FAST PATH - when this backend keeps its elements contiguously, scan that buffer directly.
         *
         *  This is worth more here than the span alone suggests, because the general path below is
         *  unusually expensive for what it computes: it wraps the comparison in a lambda, hands that to
         *  Find (), which type-erases it into a std::function, walks the container through Iterable<T>'s
         *  virtuals calling through that function per element, CONSTRUCTS an Iterator<T> at the match,
         *  and then throws the iterator away to yield a bool. The fast path does none of those.
         *
         *  Dropping the comparer where it is the default one lets the standard library pick its
         *  vectorized find for the types it can (the same reason SequentialEquals () does it).
         *
         *  \note   This does NOT displace a better algorithm anywhere. Set, MultiSet, SortedCollection,
         *          KeyedCollection and Collection all declare their own Contains () routing to their
         *          backend's keyed lookup, so they never reach this. What is left - Sequence<T> and a
         *          plain Iterable<T> - is linear either way, so a span is a pure win.
         */
        {
            _SafeReadRepAccessor<> accessor{this};
            if (auto s = accessor._ConstGetRep ().PeekContiguousStorage ()) {
                if constexpr (same_as<remove_cvref_t<EQUALS_COMPARER>, equal_to<T>> or same_as<remove_cvref_t<EQUALS_COMPARER>, equal_to<>>) {
                    return std::find (s->begin (), s->end (), element) != s->end ();
                }
                else {
                    return std::find_if (s->begin (), s->end (), [&] (const T& i) { return equalsComparer (i, element); }) != s->end ();
                }
            }
        }
        // grab iterator to first matching item, and contains if not at end; this is faster than using iterators
        return static_cast<bool> (
            this->Find ([&element, &equalsComparer] (ArgByValueType<T> i) -> bool { return equalsComparer (i, element); }));
    }
    template <typename T>
    template <ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    bool Iterable<T>::SetEquals (const LHS_CONTAINER_TYPE& lhs, const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer)
    {
        // @todo OPTIMIZATION - check if constexpr EQUALS_COMPARE == equal_to and if less<> defined - and if so - construct a std::set<> to lookup/compare (do on shorter side)
        /*
         *  An extremely inefficient but space-constant implementation. N^2 and check
         *  a contains b and b contains a
         */
        for (const auto& ti : lhs) {
            bool contained = false;
            for (const auto& ri : rhs) {
                if (equalsComparer (ti, ri)) {
                    contained = true;
                    break;
                }
            }
            if (not contained) {
                return false;
            }
        }
        for (const auto& ri : rhs) {
            bool contained = false;
            for (const auto& ti : lhs) {
                if (equalsComparer (ti, ri)) {
                    contained = true;
                    break;
                }
            }
            if (not contained) {
                return false;
            }
        }
        return true;
    }
    template <typename T>
    template <ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    inline bool Iterable<T>::SetEquals (const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer) const
    {
        return SetEquals (*this, rhs, forward<EQUALS_COMPARER> (equalsComparer));
    }
    template <typename T>
    template <ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    bool Iterable<T>::MultiSetEquals (const LHS_CONTAINER_TYPE& lhs, const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer)
    {
        auto tallyOf = [&equalsComparer] (const auto& c, ArgByValueType<T> item) -> size_t {
            size_t total = 0;
            for (const auto& ti : c) {
                if (equalsComparer (ti, item)) {
                    ++total;
                }
            }
            return total;
        };
        /*
         *  An extremely in-efficient but space-constant implementation. N^3 and check
         *  a contains b and b contains a
         */
        for (const auto& ti : lhs) {
            if (tallyOf (lhs, ti) != tallyOf (rhs, ti)) {
                return false;
            }
        }
        for (const auto& ti : rhs) {
            if (tallyOf (lhs, ti) != tallyOf (rhs, ti)) {
                return false;
            }
        }
        return true;
    }
    template <typename T>
    template <ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    inline bool Iterable<T>::MultiSetEquals (const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer) const
    {
        return MultiSetEquals (*this, rhs, equalsComparer);
    }
    template <typename T>
    template <ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    bool Iterable<T>::SequentialEquals (const LHS_CONTAINER_TYPE& lhs, const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer)
    {
        /*
         *  FAST PATH - when BOTH sides can be seen as contiguous runs of T, compare them as spans instead of
         *  advancing two Stroika iterators in lockstep. Per-element virtual iteration measures ~6ns for int
         *  and ~12ns for String ('Test52 --show --orderby-probe', the "non-copying consumer shape" entries);
         *  a span walk pays none of it, which is a 46x/13x saving on a comparison that copies nothing. And
         *  where T is trivially comparable, dropping the predicate lets the standard library collapse the
         *  whole thing to a memcmp.
         *
         *  A side qualifies two ways, and they are not the same mechanism:
         *      o   an Iterable<T> (or subclass) whose backend offers _IRep::PeekContiguousStorage ()
         *      o   any OTHER contiguous_range of T - vector<T>, array<T,N>, span<T>, and notably
         *          initializer_list<T>, which is the default RHS_CONTAINER_TYPE, so
         *          'c.SequentialEquals ({1, 2, 3})' takes this path
         *  Only the first needs a _SafeReadRepAccessor; a plain range's data () is not COW-managed. Each
         *  accessor is a named local in the scope that uses the span, per PeekContiguousStorage ()'s
         *  precondition - which is also why this cannot be factored into a helper returning just the span.
         *
         *  useIterableSize is irrelevant here: comparing span sizes is O(1) either way, and "same length and
         *  same elements" is exactly what the general path below computes. So this deliberately does NOT
         *  call size () on either container, which is what that flag exists to let callers avoid.
         */
        {
            using LHS_                     = remove_cvref_t<LHS_CONTAINER_TYPE>;
            using RHS_                     = remove_cvref_t<RHS_CONTAINER_TYPE>;
            constexpr bool kLHSIsIterable_ = derived_from<LHS_, Iterable<T>>;
            constexpr bool kRHSIsIterable_ = derived_from<RHS_, Iterable<T>>;
            constexpr bool kLHSIsContiguous_ =
                not kLHSIsIterable_ and ranges::contiguous_range<LHS_> and same_as<remove_cvref_t<ranges::range_value_t<LHS_>>, T>;
            constexpr bool kRHSIsContiguous_ =
                not kRHSIsIterable_ and ranges::contiguous_range<RHS_> and same_as<remove_cvref_t<ranges::range_value_t<RHS_>>, T>;
            if constexpr ((kLHSIsIterable_ or kLHSIsContiguous_) and (kRHSIsIterable_ or kRHSIsContiguous_)) {
                auto spansEqual_ = [&] (span<const T> l, span<const T> r) -> bool {
                    if (l.size () != r.size ()) {
                        return false;
                    }
                    // Passing NO predicate where the comparer is the default one is what licenses the
                    // library's memcmp specialization; equal_to<T> and operator== agree by definition.
                    if constexpr (same_as<remove_cvref_t<EQUALS_COMPARER>, equal_to<T>> or same_as<remove_cvref_t<EQUALS_COMPARER>, equal_to<>>) {
                        return std::equal (l.begin (), l.end (), r.begin ());
                    }
                    else {
                        return std::equal (l.begin (), l.end (), r.begin (), equalsComparer);
                    }
                };
                // Completes the comparison once the LHS span is in hand; nullopt = RHS had no storage to
                // offer, so fall through to the general path below.
                auto withLHSSpan_ = [&] (span<const T> l) -> optional<bool> {
                    if constexpr (kRHSIsIterable_) {
                        _SafeReadRepAccessor<> rhsAccessor{&rhs};
                        if (auto rs = rhsAccessor._ConstGetRep ().PeekContiguousStorage ()) {
                            return spansEqual_ (l, *rs);
                        }
                        return nullopt;
                    }
                    else {
                        return spansEqual_ (l, span<const T>{ranges::data (rhs), ranges::size (rhs)});
                    }
                };
                if constexpr (kLHSIsIterable_) {
                    _SafeReadRepAccessor<> lhsAccessor{&lhs};
                    if (auto ls = lhsAccessor._ConstGetRep ().PeekContiguousStorage ()) {
                        if (auto result = withLHSSpan_ (*ls)) {
                            return *result;
                        }
                    }
                }
                else {
                    if (auto result = withLHSSpan_ (span<const T>{ranges::data (lhs), ranges::size (lhs)})) {
                        return *result;
                    }
                }
            }
        }
        auto li{lhs.begin ()};
        auto ri{rhs.begin ()};
        auto le{lhs.end ()};
        auto re{rhs.end ()};
        for (; li != le and ri != re; ++ri, ++li) {
            if (not equalsComparer (*li, *ri)) {
                return false;
            }
        }
        // one caused us to end (or more likely both)
        Assert (li == le or ri == re);
        // only true if we get to end at the same time
        return li == le and ri == re;
    }
    template <typename T>
    template <ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    inline bool Iterable<T>::SequentialEquals (const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer) const
    {
        return SequentialEquals (*this, rhs, forward<EQUALS_COMPARER> (equalsComparer));
    }
    DISABLE_COMPILER_MSC_WARNING_START (4996)
    DISABLE_COMPILER_CLANG_WARNING_START ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_GCC_WARNING_START ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
    template <typename T>
    template <ranges::range LHS_CONTAINER_TYPE, ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    inline bool Iterable<T>::SequentialEquals (const LHS_CONTAINER_TYPE& lhs, const RHS_CONTAINER_TYPE& rhs,
                                               EQUALS_COMPARER&& equalsComparer, [[maybe_unused]] bool useIterableSize)
    {
        // useIterableSize deliberately ignored - it never changed the ANSWER, only the strategy, and the
        // strategy it selected is not worth having (see the \deprecated note in Iterable.h).
        return SequentialEquals (lhs, rhs, forward<EQUALS_COMPARER> (equalsComparer));
    }
    template <typename T>
    template <ranges::range RHS_CONTAINER_TYPE, Common::IEqualsComparer<T> EQUALS_COMPARER>
    inline bool Iterable<T>::SequentialEquals (const RHS_CONTAINER_TYPE& rhs, EQUALS_COMPARER&& equalsComparer, [[maybe_unused]] bool useIterableSize) const
    {
        return SequentialEquals (*this, rhs, forward<EQUALS_COMPARER> (equalsComparer));
    }
    DISABLE_COMPILER_GCC_WARNING_END ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_CLANG_WARNING_END ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_MSC_WARNING_END (4996)
    template <typename T>
#if qCompilerAndStdLib_RequiresNotMatchInlineOutOfLineForTemplateClassBeingDefined_Buggy
    template <typename RESULT_CONTAINER, predicate<T> INCLUDE_PREDICATE>
#else
    template <derived_from<Iterable<T>> RESULT_CONTAINER, predicate<T> INCLUDE_PREDICATE>
#endif
    inline RESULT_CONTAINER Iterable<T>::Where (INCLUDE_PREDICATE&& includeIfTrue) const
    {
        //
        // LAZY evaluate Iterable<> and for concrete container types, explicitly create the object.
        //
        if constexpr (same_as<RESULT_CONTAINER, Iterable<T>>) {
            // If we have many iterator copies, we need ONE copy of this sharedContext (they all share a reference to the same Iterable)
            auto sharedContext = Memory::MakeSharedPtr<Iterable<T>> (*this);
            // If we have many iterator copies, each needs to copy their 'base iterator' (this is their 'index' into the container)
            // Both the 'sharedContext' and the i' get stored into the lambda closure so they get appropriately copied as you copy iterators
            function<optional<T> ()> getNext = [sharedContext, i = sharedContext->MakeIterator (), includeIfTrue] () mutable -> optional<T> {
                while (i and not includeIfTrue (*i)) {
                    ++i;
                }
                if (i) {
                    auto tmp = *i;
                    ++i;
                    return move (tmp);
                }
                return nullopt;
            };
            return CreateGenerator (getNext);
        }
        else {
            return Where<RESULT_CONTAINER> (forward<INCLUDE_PREDICATE> (includeIfTrue), RESULT_CONTAINER{});
        }
    }
    template <typename T>
#if qCompilerAndStdLib_RequiresNotMatchInlineOutOfLineForTemplateClassBeingDefined_Buggy
    template <typename RESULT_CONTAINER, predicate<T> INCLUDE_PREDICATE>
#else
    template <derived_from<Iterable<T>> RESULT_CONTAINER, predicate<T> INCLUDE_PREDICATE>
#endif
    RESULT_CONTAINER Iterable<T>::Where (INCLUDE_PREDICATE&& includeIfTrue, [[maybe_unused]] RESULT_CONTAINER&& emptyResult) const
    {
        if constexpr (same_as<RESULT_CONTAINER, Iterable<T>>) {
            // no point in emptyResult overload; vector to one spot for Iterable<> lazy implementation
            return Where<RESULT_CONTAINER> (forward<INCLUDE_PREDICATE> (includeIfTrue));
        }
        else {
            Require (emptyResult.empty ());
            RESULT_CONTAINER result = forward<RESULT_CONTAINER> (emptyResult);
            this->Apply ([&result, &includeIfTrue] (ArgByValueType<T> arg) {
                if (includeIfTrue (arg)) {
                    Containers::Adapters::Adder<RESULT_CONTAINER>::Add (&result, arg);
                }
            });
            return result;
        }
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    Iterable<T> Iterable<T>::Distinct (EQUALS_COMPARER&& equalsComparer) const
    {
        vector<T> tmp; // Simplistic/stupid/weak implementation
        if constexpr (same_as<equal_to<T>, EQUALS_COMPARER> and is_invocable_v<less<T>>) {
            set<T> t1{begin (), end ()};
            tmp = vector<T>{t1.begin (), t1.end ()};
        }
        else {
            for (const auto& i : *this) {
                if (find_if (tmp.begin (), tmp.end (), [&] (ArgByValueType<T> n) { return equalsComparer (n, i); }) == tmp.end ()) {
                    tmp.push_back (i);
                }
            }
        }
        function<optional<T> ()> getNext = [container = move (tmp), idx = size_t{0}] () mutable -> optional<T> {
            if (idx < container.size ()) {
                return container[idx++];
            }
            else {
                return nullopt;
            }
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    template <typename RESULT, Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    Iterable<RESULT> Iterable<T>::Distinct (const function<RESULT (ArgByValueType<T>)>& extractElt, EQUALS_COMPARER&& equalsComparer) const
    {
        RequireNotNull (extractElt);
        vector<RESULT> tmp; // Simplistic/stupid/weak implementation
        if constexpr (same_as<equal_to<T>, EQUALS_COMPARER> and is_invocable_v<less<T>>) {
            set<RESULT> t1;
            for (const T& i : *this) {
                t1.add (extractElt (i));
            }
            tmp = vector<RESULT>{t1.begin (), t1.end ()};
        }
        else {
            for (const T& i : *this) {
                RESULT item2Test = extractElt (i);
                if (find_if (tmp.begin (), tmp.end (), [&] (ArgByValueType<T> n) { return equalsComparer (n, item2Test); }) == tmp.end ()) {
                    tmp.push_back (item2Test);
                }
            }
        }
        function<optional<RESULT> ()> getNext = [container = move (tmp), idx = size_t{0}] () mutable -> optional<RESULT> {
            if (idx < container.size ()) {
                return container[idx++];
            }
            else {
                return nullopt;
            }
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    template <ranges::range RESULT_CONTAINER, invocable<T> ELEMENT_MAPPER>
    RESULT_CONTAINER Iterable<T>::Map (ELEMENT_MAPPER&& elementMapper) const
        requires (convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, typename RESULT_CONTAINER::value_type> or
                  convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, optional<typename RESULT_CONTAINER::value_type>>)
    {
        using RESULT_ELEMENT = typename RESULT_CONTAINER::value_type;
        constexpr bool kLazyEvaluateIteration_ = same_as<RESULT_CONTAINER, Iterable<RESULT_ELEMENT>>; // For now use vector and lazy not truly implemented
        [[maybe_unused]] constexpr bool kOptionalExtractor_ =
            not convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, typename RESULT_CONTAINER::value_type> and
            convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, optional<typename RESULT_CONTAINER::value_type>>;
        if constexpr (kLazyEvaluateIteration_) {
            // If we have many iterator copies, we need ONE copy of this sharedContext (they all share a reference to the same Iterable)
            auto sharedContext = Memory::MakeSharedPtr<Iterable<T>> (*this);
            // Both the 'sharedContext' and the 'i' get stored into the lambda closure so they get appropriately copied as you copy iterators
            function<optional<RESULT_ELEMENT> ()> getNext = [sharedContext, i = sharedContext->MakeIterator (),
                                                             elementMapper] () mutable -> optional<RESULT_ELEMENT> {
                // tricky. The function we are defining returns nullopt as a sentinel to signal end of iteration. The function we are GIVEN returns nullopt
                // to signal skip this item. So adjust accordingly
                if constexpr (kOptionalExtractor_) {
                    while (i) {
                        optional<RESULT_ELEMENT> t = elementMapper (*i);
                        ++i;
                        if (t) {
                            return *t;
                        }
                    }
                    return nullopt;
                }
                else {
                    if (i) {
                        RESULT_ELEMENT result = elementMapper (*i);
                        ++i;
                        return move (result);
                    }
                    return nullopt;
                }
            };
            return CreateGenerator (getNext);
        }
        else {
            // subclasseers can replace this 'else' branch if RESULT_CONTAINER cannot or should not be default constructed
            return this->Map<RESULT_CONTAINER> (forward<ELEMENT_MAPPER> (elementMapper), RESULT_CONTAINER{});
        }
    }
    template <typename T>
    template <ranges::range RESULT_CONTAINER, invocable<T> ELEMENT_MAPPER>
    RESULT_CONTAINER Iterable<T>::Map (ELEMENT_MAPPER&& elementMapper, RESULT_CONTAINER&& emptyResult) const
        requires (convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, typename RESULT_CONTAINER::value_type> or
                  convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, optional<typename RESULT_CONTAINER::value_type>>)
    {
        using RESULT_ELEMENT = typename RESULT_CONTAINER::value_type;
        constexpr bool kLazyEvaluateIteration_ = same_as<RESULT_CONTAINER, Iterable<RESULT_ELEMENT>>; // For now use vector and lazy not truly implemented
        constexpr bool kOptionalExtractor_ = not convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, typename RESULT_CONTAINER::value_type> and
                                             convertible_to<invoke_result_t<ELEMENT_MAPPER, T>, optional<typename RESULT_CONTAINER::value_type>>;
        if constexpr (kLazyEvaluateIteration_) {
            return this->Map<RESULT_CONTAINER> (forward<ELEMENT_MAPPER> (elementMapper)); // ignore useless emptyResult if provided, and invoke other overload to share code
        }
        else {
            RESULT_CONTAINER c = forward<RESULT_CONTAINER> (emptyResult);
            /*
             *  \note   BUG - see https://github.com/SophistSolutions/Stroika/issues/1163
             *
             *          This reserves iff the TARGET supports reserve () and we are not filtering - it does
             *          NOT establish that our own size () is cheap, despite what this comment used to say.
             *          _IRep::size () defaults to counting by iteration, so for a lazy source (Where ()
             *          returning Iterable<T> is a generator closure) this walks everything for the size and
             *          then Apply () walks it all again. Performance only - generator Iterables are
             *          re-traversable, so the result is correct, just computed twice.
             *
             *          Not reachable from in-tree code today: no Stroika container has reserve (), and no
             *          in-tree caller does Map<vector<...>> (). It bites user code mapping into a
             *          std::vector. The clean fix wants a PeekSize () - declined for now, see issue #1162.
             */
            if constexpr (not kOptionalExtractor_ and requires (RESULT_CONTAINER p) { p.reserve (3u); }) {
                c.reserve (this->size ());
            }
            this->Apply ([&c, &elementMapper] (ArgByValueType<T> arg) {
                if constexpr (kOptionalExtractor_) {
                    if (auto oarg = elementMapper (arg)) {
                        Containers::Adapters::Adder<RESULT_CONTAINER>::Add (&c, *oarg);
                    }
                }
                else {
                    Containers::Adapters::Adder<RESULT_CONTAINER>::Add (&c, elementMapper (arg));
                }
            });
            return c;
        }
    }
    template <typename T>
    template <typename RESULT_T, invocable<T> CONVERT_TO_RESULT, invocable<RESULT_T, RESULT_T, bool> COMBINER>
    RESULT_T Iterable<T>::Join (const CONVERT_TO_RESULT& convertToResult, const COMBINER& combiner) const
        requires (convertible_to<invoke_result_t<CONVERT_TO_RESULT, T>, RESULT_T> and
                  convertible_to<invoke_result_t<COMBINER, RESULT_T, RESULT_T, bool>, RESULT_T>)
    {
        RESULT_T result{};
        size_t   idx{0};
        size_t   cnt = this->size ();
        for (auto i : *this) {
            if (idx == 0) {
                result = convertToResult (i);
            }
            else {
                result = combiner (result, convertToResult (i), idx + 1 == cnt);
            }
            ++idx;
        }
        return result;
    }
    template <typename T>
    Iterable<T> Iterable<T>::Skip (size_t nItems) const
    {
        // If we have many iterator copies, we need ONE copy of this sharedContext (they all share a reference to the same Iterable)
        auto sharedContext = Memory::MakeSharedPtr<Iterable<T>> (*this);
        // If we have many iterator copies, each needs to copy their 'base iterator' (this is their 'index' into the container)
        // Both the 'sharedContext' and the i' get stored into the lambda closure so they get appropriately copied as you copy iterators
        // perIteratorContextNItemsToSkip also must be cloned per iterator instance
        function<optional<T> ()> getNext = [sharedContext, i = sharedContext->MakeIterator (),
                                            perIteratorContextNItemsToSkip = nItems] () mutable -> optional<T> {
            while (i and perIteratorContextNItemsToSkip > 0) {
                --perIteratorContextNItemsToSkip;
                ++i;
            }
            if (i) {
                auto result = *i;
                ++i;
                return move (result);
            }
            return nullopt;
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    Iterable<T> Iterable<T>::Take (size_t nItems) const
    {
        // If we have many iterator copies, we need ONE copy of this sharedContext (they all share a reference to the same Iterable)
        auto sharedContext = Memory::MakeSharedPtr<Iterable<T>> (*this);
        // If we have many iterator copies, each needs to copy their 'base iterator' (this is their 'index' into the container)
        // Both the 'sharedContext' and the i' get stored into the lambda closure so they get appropriately copied as you copy iterators
        // perIteratorContextNItemsToTake also must be cloned per iterator instance
        function<optional<T> ()> getNext = [sharedContext, i = sharedContext->MakeIterator (),
                                            perIteratorContextNItemsToTake = nItems] () mutable -> optional<T> {
            if (perIteratorContextNItemsToTake == 0) {
                return nullopt;
            }
            perIteratorContextNItemsToTake--;
            if (i) {
                auto result = *i;
                ++i;
                return move (result);
            }
            return nullopt;
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    Iterable<T> Iterable<T>::Slice (size_t from, size_t to) const
    {
        // If we have many iterator copies, we need ONE copy of this sharedContext (they all share a reference to the same Iterable)
        auto sharedContext = Memory::MakeSharedPtr<Iterable<T>> (*this);
        // If we have many iterator copies, each needs to copy their 'base iterator' (this is their 'index' into the container)
        // Both the 'sharedContext' and the i' get stored into the lambda closure so they get appropriately copied as you copy iterators
        // perIteratorContextNItemsToSkip also must be cloned per iterator instance
        // perIteratorContextNItemsToTake also must be cloned per iterator instance
        function<optional<T> ()> getNext = [sharedContext, i = sharedContext->MakeIterator (), perIteratorContextNItemsToSkip = from,
                                            perIteratorContextNItemsToTake = to - from] () mutable -> optional<T> {
            while (i and perIteratorContextNItemsToSkip > 0) {
                --perIteratorContextNItemsToSkip;
                ++i;
            }
            if (perIteratorContextNItemsToTake == 0) {
                return nullopt;
            }
            perIteratorContextNItemsToTake--;
            if (i) {
                auto result = *i;
                ++i;
                return move (result);
            }
            return nullopt;
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> COMPARER>
    optional<T> Iterable<T>::Top (COMPARER&& cmp) const
    {
        /*
         *  'cmp' defines a sort ORDER, and 'top' is whichever element would come first in that order - ie the
         *  minimum under cmp, which is what min_element computes. With the default greater<T>, that is the
         *  largest element.
         *
         *  Runs directly off the Iterable's own iterators (Iterator<T> models forward_iterator, which is all
         *  min_element requires), so unlike the Top (n, ...) overloads there is no copy of the container and
         *  no sort: O(S), a single traversal.
         *
         *  @todo   min_element () copy-assigns its running 'smallest' ITERATOR each time it sees a better
         *          element, and copy-assigning an Iterator<T> clones the rep - a heap allocation. So this
         *          allocates once per new-best element: fine on average, but O(S) allocations in the worst
         *          case, which is an already-ordered input (with the default greater<T>, every element is a
         *          new best). Tracking the best VALUE in an optional<T> and looping by hand avoids that
         *          entirely. Purely a performance nit - no API or correctness impact - so not urgent.
         */
        auto endI = Iterator<T>{end ()};
        auto i    = min_element (begin (), endI, forward<COMPARER> (cmp));
        if (i == endI) {
            return nullopt; // empty Iterable
        }
        return *i;
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> COMPARER>
    Iterable<T> Iterable<T>::Top (size_t n, COMPARER&& cmp) const
    {
        vector<T> tmp = this->As<vector<T>> ();
        // Clamp rather than special-casing 'n >= size ()': partial_sort with middle == end IS a full sort, so
        // the n-too-large case needs no separate path (and this avoids a second, virtual, size () call).
        n = min (n, tmp.size ());
        partial_sort (tmp.begin (), tmp.begin () + n, tmp.end (), forward<COMPARER> (cmp));
        size_t idx{0};
        tmp.erase (tmp.begin () + n, tmp.end ());
        function<optional<T> ()> getNext = [tmp, idx] () mutable -> optional<T> {
            if (idx < tmp.size ()) {
                return tmp[idx++];
            }
            else {
                return nullopt;
            }
        };
        return CreateGenerator (getNext);
    }
    template <typename T>
    inline optional<T> Iterable<T>::Top () const
    {
        return Top (std::greater<T>{});
    }
    template <typename T>
    inline Iterable<T> Iterable<T>::Top (size_t n) const
    {
        return Top (n, std::greater<T>{});
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> INORDER_COMPARER_TYPE>
    inline Iterable<T> Iterable<T>::OrderBy (INORDER_COMPARER_TYPE&& inorderComparer) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        return OrderBy (forward<INORDER_COMPARER_TYPE> (inorderComparer), Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> INORDER_COMPARER_TYPE>
    Iterable<T> Iterable<T>::OrderBy (INORDER_COMPARER_TYPE&& inorderComparer, [[maybe_unused]] Execution::SequencePolicy seq) const
    {
        vector<T> tmp = this->As<vector<T>> ();
        switch (seq) {
#if __cpp_lib_execution >= 201603L
                // only ePar goes parallel; 'default' running sequentially is deliberate - see the dispatch note
                // on Execution::SequencePolicy
            case Execution::SequencePolicy::ePar:
                stable_sort (execution::par, tmp.begin (), tmp.end (), forward<INORDER_COMPARER_TYPE> (inorderComparer));
                break;
                // @todo add other Execution::SequencePolicy cases
#endif
            default:
                stable_sort (tmp.begin (), tmp.end (), forward<INORDER_COMPARER_TYPE> (inorderComparer));
                break;
        }
        /*
         *  Hand back a rep that OWNS the sorted vector and exposes it as contiguous storage, rather than
         *  a generator reading out of a captured copy of it. Two things follow, and the second is the
         *  reason to bother:
         *
         *      o   the sorted data is moved in once and then shared. The generator this replaced captured
         *          the vector BY VALUE, so every copy of the returned Iterable duplicated it.
         *      o   the RESULT offers _IRep::PeekContiguousStorage (), so whatever is done to it AFTERWARDS
         *          - As<> (), Contains (), IndexOf (), Min ()/Max ()/Sum (), SequentialEquals () - takes
         *          the bulk fast path. A generator can offer no storage, so sorting used to throw away
         *          the contiguity that everything downstream now depends on.
         *
         *  Sharing rather than copying is safe because nothing can mutate it: the vector is local, moved
         *  in here, and never handed out except as span<const T>.
         */
        struct SortedRep_ : Iterable<T>::_IRep, Memory::UseBlockAllocationIfAppropriate<SortedRep_> {
            shared_ptr<const vector<T>> fData_; // const pointee: sharing is only safe because nothing can mutate it
            SortedRep_ (vector<T>&& data)
                : fData_{Memory::MakeSharedPtr<vector<T>> (move (data))}
            {
            }
            virtual Iterator<T> MakeIterator () const override
            {
                // a fresh independent cursor per call, so no iterator tracking is needed
                return CreateGeneratorIterator<T> ([data = fData_, idx = size_t{0}] () mutable -> optional<T> {
                    return idx < data->size () ? optional<T>{(*data)[idx++]} : nullopt;
                });
            }
            virtual size_t size () const override
            {
                return fData_->size ();
            }
            virtual bool empty () const override
            {
                return fData_->empty ();
            }
            virtual optional<span<const T>> PeekContiguousStorage () const override
            {
                return span<const T>{*fData_};
            }
            virtual shared_ptr<typename Iterable<T>::_IRep> Clone () const override
            {
                return Memory::MakeSharedPtr<SortedRep_> (*this); // shares fData_, does not copy it
            }
        };
        return Iterable<T>{Memory::MakeSharedPtr<SortedRep_> (move (tmp))};
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> INORDER_COMPARER_TYPE>
    bool Iterable<T>::IsOrderedBy (INORDER_COMPARER_TYPE&& inorderComparer) const
    {
        optional<T> last;
        for (const T& i : *this) {
            if (last.has_value ()) [[likely]] {
                // inorderComparer is 'strict inorder' - so case of equals we keep going...
                if (inorderComparer (i, *last)) [[unlikely]] {
                    return false;
                }
            }
            last = i;
        }
        return true;
    }
    template <typename T>
    inline optional<T> Iterable<T>::First () const
    {
        auto i = begin ();
        return i ? *i : optional<T>{};
    }
    template <typename T>
    template <invocable<T> F>
    inline optional<T> Iterable<T>::First (F&& that) const
        requires (convertible_to<invoke_result_t<F, T>, bool>)
    {
        constexpr bool kUseIterableRepIteration_ = true; // same semantics, but maybe faster cuz avoids Stroika iterator extra virtual calls overhead
        if (kUseIterableRepIteration_) {
            Iterator<T> t = this->_fRep->Find (/*findFirst*/ true, forward<F> (that), Execution::SequencePolicy::eSeq);
            return t ? optional<T>{*t} : optional<T>{};
        }
        else {
            for (const auto& i : *this) {
                if (that (i)) {
                    return i;
                }
            }
            return nullopt;
        }
    }
    template <typename T>
    template <typename RESULT_T>
    inline optional<RESULT_T> Iterable<T>::First (const function<optional<RESULT_T> (ArgByValueType<T>)>& that) const
    {
        RequireNotNull (that);
        constexpr bool kUseIterableRepIteration_ = true; // same semantics, but maybe faster cuz avoids Stroika iterator extra virtual calls overhead
        if (kUseIterableRepIteration_) {
            optional<RESULT_T>          result; // actual result captured in side-effect of lambda
            auto                        f = [&that, &result] (ArgByValueType<T> i) { return (result = that (i)).has_value (); };
            _SafeReadRepAccessor<_IRep> accessor{this};
            Iterator<T>                 t = accessor._ConstGetRep ().Find (/*findFirst*/ true, f, Execution::SequencePolicy::eSeq);
            return t ? result : optional<RESULT_T>{};
        }
        else {
            for (const auto& i : *this) {
                if (auto r = that (i)) {
                    return r;
                }
            }
            return nullopt;
        }
    }
    template <typename T>
    inline T Iterable<T>::FirstValue (ArgByValueType<T> defaultValue) const
    {
        return this->First ().value_or (defaultValue);
    }
    template <typename T>
    template <invocable<T> F>
    inline T Iterable<T>::FirstValue (F&& that, ArgByValueType<T> defaultValue) const
        requires (convertible_to<invoke_result_t<F, T>, bool>)
    {
        return this->First (forward<F> (that)).value_or (defaultValue);
    }
    template <typename T>
    optional<T> Iterable<T>::Last () const
    {
        auto i = begin ();
        if (i) {
            auto prev = i;
            while (i) {
                prev = i;
                ++i;
            }
            return *prev;
        }
        return nullopt;
    }
    template <typename T>
    template <invocable<T> F>
    inline optional<T> Iterable<T>::Last (F&& that) const
        requires (convertible_to<invoke_result_t<F, T>, bool>)
    {
        optional<T> result;
        for (const auto& i : *this) {
            if (that (i)) {
                result = i;
            }
        }
        return result;
    }
    template <typename T>
    template <typename RESULT_T>
    inline optional<RESULT_T> Iterable<T>::Last (const function<optional<RESULT_T> (ArgByValueType<T>)>& that) const
    {
        RequireNotNull (that);
        optional<T> result;
        for (const auto& i : *this) {
            if (auto o = that (i)) {
                result = *o;
            }
        }
        return result;
    }
    template <typename T>
    inline T Iterable<T>::LastValue (ArgByValueType<T> defaultValue) const
    {
        return this->Last ().value_or (defaultValue);
    }
    template <typename T>
    template <invocable<T> F>
    inline T Iterable<T>::LastValue (F&& that, ArgByValueType<T> defaultValue) const
        requires (convertible_to<invoke_result_t<F, T>, bool>)
    {
        return this->Last (forward<F> (that)).value_or (defaultValue);
    }
    template <typename T>
    bool Iterable<T>::All (const function<bool (ArgByValueType<T>)>& testEachElt) const
    {
        RequireNotNull (testEachElt);
        for (const auto& i : *this) {
            if (not testEachElt (i)) {
                return false;
            }
        }
        return true;
    }
    template <typename T>
    template <typename REDUCED_TYPE>
    optional<REDUCED_TYPE> Iterable<T>::Reduce (const function<REDUCED_TYPE (ArgByValueType<T>, ArgByValueType<T>)>& op) const
    {
        optional<REDUCED_TYPE> result;
        for (const auto& i : *this) {
            if (result) {
                // NB: ACCUMULATOR FIRST, element second - as std::accumulate and Join () do. Until
                // Stroika v3.0d24 this was op (i, *result), which silently REVERSED any non-commutative
                // operation (Sum () over String returned "CBA" for {A,B,C}).
                result = op (*result, i);
            }
            else {
                result = i;
            }
        }
        return result;
    }
    template <typename T>
    template <typename REDUCED_TYPE>
    inline REDUCED_TYPE Iterable<T>::ReduceValue (const function<REDUCED_TYPE (ArgByValueType<T>, ArgByValueType<T>)>& op,
                                                  ArgByValueType<REDUCED_TYPE>                                         defaultValue) const
    {
        return Reduce<REDUCED_TYPE> (op).value_or (defaultValue);
    }
    template <typename T>
    inline optional<T> Iterable<T>::Min () const
    {
        /*
         *  FAST PATH - see the note on Max () below; Min ()/Max ()/Sum () all bypass Reduce () rather
         *  than accelerate it, because Reduce () takes a std::function.
         */
        {
            _SafeReadRepAccessor<> accessor{this};
            if (auto s = accessor._ConstGetRep ().PeekContiguousStorage ()) {
                if (s->empty ()) [[unlikely]] {
                    return nullopt;
                }
                return *min_element (s->begin (), s->end ());
            }
        }
        return Reduce<T> ([] (ArgByValueType<T> lhs, ArgByValueType<T> rhs) -> T { return min (lhs, rhs); });
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline RESULT_TYPE Iterable<T>::MinValue (ArgByValueType<RESULT_TYPE> defaultValue) const
    {
        return Min ().value_or (defaultValue);
    }
    template <typename T>
    inline optional<T> Iterable<T>::Max () const
    {
        /*
         *  FAST PATH - when the backend keeps its elements contiguously.
         *
         *  Note this BYPASSES Reduce () rather than adding a fast path to it. Reduce () takes its
         *  operation as a std::function<>, so it pays an indirect call PER ELEMENT on top of the
         *  per-element virtual iteration - and for a cheap T that type-erasure tax is the larger of the
         *  two (the OrderBy design probe measured it at 3.4x for int; see TODO.md). Going through
         *  min_element/max_element here keeps the comparison inlined, so both costs go away rather than
         *  just the iteration. A fast path inside Reduce () would still leave every caller paying the
         *  std::function call, so it is a separate (smaller) question.
         */
        {
            _SafeReadRepAccessor<> accessor{this};
            if (auto s = accessor._ConstGetRep ().PeekContiguousStorage ()) {
                if (s->empty ()) [[unlikely]] {
                    return nullopt;
                }
                return *max_element (s->begin (), s->end ());
            }
        }
        return Reduce<T> ([] (ArgByValueType<T> lhs, ArgByValueType<T> rhs) -> T { return max (lhs, rhs); });
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline RESULT_TYPE Iterable<T>::MaxValue (ArgByValueType<RESULT_TYPE> defaultValue) const
    {
        return Max ().value_or (defaultValue);
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline optional<RESULT_TYPE> Iterable<T>::Mean () const
    {
        Iterator<T> i = begin ();
        if (i == end ()) [[unlikely]] {
            return nullopt;
        }
        return Math::Mean (i, end ());
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline RESULT_TYPE Iterable<T>::MeanValue (ArgByValueType<RESULT_TYPE> defaultValue) const
    {
        return Mean ().value_or (defaultValue);
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline optional<RESULT_TYPE> Iterable<T>::Sum () const
    {
        /*
         *  FAST PATH - see the note on Max (); this bypasses Reduce () for the same reason.
         *
         *  Gated on RESULT_TYPE being T: when they differ, the general path passes the running
         *  RESULT_TYPE total back through an op declared to take two T, so the accumulation is
         *  converted to T on every step (ie Sum<double> () over an Iterable<int> truncates each partial
         *  sum). That quirk is not replicated here; such calls simply keep the general path.
         */
        if constexpr (same_as<RESULT_TYPE, T>) {
            _SafeReadRepAccessor<> accessor{this};
            if (auto s = accessor._ConstGetRep ().PeekContiguousStorage ()) {
                if (s->empty ()) [[unlikely]] {
                    return nullopt;
                }
                T total = *s->begin ();
                for (auto i = s->begin () + 1; i != s->end (); ++i) {
                    total = total + *i; // accumulator first, matching Reduce ()
                }
                return total;
            }
        }
        return Reduce<RESULT_TYPE> ([] (ArgByValueType<T> lhs, ArgByValueType<T> rhs) { return lhs + rhs; });
    }
    template <typename T>
    template <typename RESULT_TYPE>
    inline RESULT_TYPE Iterable<T>::SumValue (ArgByValueType<RESULT_TYPE> defaultValue) const
    {
        return Sum ().value_or (defaultValue);
    }
    template <typename T>
    template <constructible_from<T> RESULT_TYPE, Common::IPotentiallyComparer<RESULT_TYPE> INORDER_COMPARE_FUNCTION>
    inline optional<RESULT_TYPE> Iterable<T>::Median (const INORDER_COMPARE_FUNCTION& compare) const
    {
        Iterator<T> i = begin ();
        if (i == end ()) [[unlikely]] {
            return nullopt;
        }
        return Math::Median<RESULT_TYPE> (i, end (), compare);
    }
    template <typename T>
    template <constructible_from<T> RESULT_TYPE>
    inline RESULT_TYPE Iterable<T>::MedianValue (ArgByValueType<RESULT_TYPE> defaultValue) const
    {
        return Median ().value_or (defaultValue);
    }
    template <typename T>
    Iterable<T> Iterable<T>::Repeat (size_t count) const
    {
        switch (count) {
            case 0:
                return Iterable<T>{};
            case 1:
                return *this;
            default: {
                // Somewhat simplistic / inefficient implementation
                vector<T>                origList = this->As<vector<T>> ();
                size_t                   repeatCountIndex{1}; // start at one, cuz we don't copy the zeroth time
                size_t                   innerIndex{0};
                function<optional<T> ()> getNext = [origList, repeatCountIndex, innerIndex, count] () mutable -> optional<T> {
                    Again:
                        if (innerIndex < origList.size ()) [[likely]] {
                            return origList[innerIndex++];
                        }
                        if (repeatCountIndex < count) [[likely]] {
                            ++repeatCountIndex;
                            innerIndex = 0;
                            goto Again;
                        }
                        return nullopt;
                };
                return CreateGenerator (getNext);
            }
        }
    }
    template <typename T>
    inline bool Iterable<T>::Any () const
    {
        return not empty ();
    }
    template <typename T>
    inline bool Iterable<T>::Any (const function<bool (ArgByValueType<T>)>& includeIfTrue) const
    {
        return static_cast<bool> (Find (includeIfTrue));
    }
    template <typename T>
    inline size_t Iterable<T>::Count () const
    {
        return size ();
    }
    template <typename T>
    inline size_t Iterable<T>::Count (const function<bool (ArgByValueType<T>)>& includeIfTrue) const
    {
        size_t cnt{};
        Apply ([&] (ArgByValueType<T> a) {
            if (includeIfTrue (a))
                ++cnt;
        });
        Ensure (cnt == Where (includeIfTrue).size ());
        return cnt;
    }
    template <typename T>
    inline size_t Iterable<T>::length () const
    {
        return size ();
    }
    template <typename T>
    inline Iterator<T> Iterable<T>::begin () const
    {
        return MakeIterator ();
    }
    template <typename T>
    constexpr default_sentinel_t Iterable<T>::end () noexcept
    {
        return Iterator<T>::GetEmptyIterator ();
    }
    template <typename T>
    inline void Iterable<T>::Apply (const function<void (ArgByValueType<T> item)>& doToElement) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        Apply (doToElement, Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    inline void Iterable<T>::Apply (const function<void (ArgByValueType<T> item)>& doToElement, Execution::SequencePolicy seq) const
    {
        RequireNotNull (doToElement);
        _SafeReadRepAccessor<> accessor{this};
        accessor._ConstGetRep ().Apply (doToElement, seq);
    }
    template <typename T>
    template <predicate<T> THAT_FUNCTION>
    inline Iterator<T> Iterable<T>::Find (THAT_FUNCTION&& that) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        return Find (forward<THAT_FUNCTION> (that), Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    template <predicate<T> THAT_FUNCTION>
    inline Iterator<T> Iterable<T>::Find (THAT_FUNCTION&& that, Execution::SequencePolicy seq) const
    {
        // NB: This transforms perfectly forwarded 'THAT_FUNCTION' and converts it to std::function<> - preventing further inlining at this point -
        // just so it can be done
        _SafeReadRepAccessor<> accessor{this};
        return accessor._ConstGetRep ().Find (/*findFirst*/ false, forward<THAT_FUNCTION> (that), seq);
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    inline Iterator<T> Iterable<T>::Find (ArgByValueType<T> v, EQUALS_COMPARER&& equalsComparer) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        return Find (v, forward<EQUALS_COMPARER> (equalsComparer), Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    inline Iterator<T> Iterable<T>::Find (ArgByValueType<T> v, EQUALS_COMPARER&& equalsComparer, Execution::SequencePolicy seq) const
    {
        /*
         *  NB: deliberately NO _IRep::PeekContiguousStorage () fast path here, unlike Contains () and
         *  Sequence<T>::IndexOf (). Find () must return a live Iterator<T> positioned at the match, and a
         *  span can only give a POSITION - there is no way to synthesize a Stroika iterator from a
         *  pointer, and _IRep offers only MakeIterator (), never an 'iterator at index N'. So a span
         *  would locate the element quickly and then have to walk to it anyway, for no net gain.
         *
         *  The hook that DOES fit a contiguous backend here is _IRep::Find_equal_to () just below, which
         *  a backend can override to use its own storage AND its own iterator construction - which is how
         *  the tree/hash backends already accelerate this. That is per-backend work, not a generic span
         *  path.
         */
        if constexpr (same_as<remove_cvref_t<EQUALS_COMPARER>, equal_to<T>> and Common::IEqualToOptimizable<T>) {
            // This CAN be much faster than the default implementation for this special (but common) case (often a tree structure will have been maintained making this find faster)
            _SafeReadRepAccessor<> accessor{this};
            return accessor._ConstGetRep ().Find_equal_to (v, seq);
        }
        else {
            return Find ([v, equalsComparer] (ArgByValueType<T> arg) { return equalsComparer (v, arg); }, seq);
        }
    }
    template <typename T>
    template <predicate<T> THAT_FUNCTION>
    inline Iterator<T> Iterable<T>::Find (const Iterator<T>& startAt, THAT_FUNCTION&& that) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        return Find (startAt, forward<THAT_FUNCTION> (that), Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    template <predicate<T> THAT_FUNCTION>
    inline Iterator<T> Iterable<T>::Find (const Iterator<T>& startAt, THAT_FUNCTION&& that, [[maybe_unused]] Execution::SequencePolicy seq) const
    {
        for (Iterator<T> i = startAt; i != end (); ++i) {
            if (forward<THAT_FUNCTION> (that) (*i)) [[unlikely]] {
                return i;
            }
        }
        return end ();
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    inline Iterator<T> Iterable<T>::Find (const Iterator<T>& startAt, ArgByValueType<T> v, EQUALS_COMPARER&& equalsComparer) const
    {
        // @todo measure the crossover and auto-choose the policy here - eSeq is a placeholder, not a decision
        return Find (startAt, v, forward<EQUALS_COMPARER> (equalsComparer), Execution::SequencePolicy::eSeq);
    }
    template <typename T>
    template <Common::IPotentiallyComparer<T> EQUALS_COMPARER>
    Iterator<T> Iterable<T>::Find (const Iterator<T>& startAt, ArgByValueType<T> v, EQUALS_COMPARER&& equalsComparer,
                                   [[maybe_unused]] Execution::SequencePolicy seq) const
    {
        for (Iterator<T> i = startAt; i != end (); ++i) {
            if (forward<EQUALS_COMPARER> (equalsComparer) (v, *i)) [[unlikely]] {
                return i;
            }
        }
        return end ();
    }
    template <typename T>
    template <IIterableOfFrom<T> CONTAINER_OF_T, typename... CONTAINER_OF_T_CONSTRUCTOR_ARGS>
    inline CONTAINER_OF_T Iterable<T>::As (CONTAINER_OF_T_CONSTRUCTOR_ARGS... args) const
    {
        /*
         *  FAST PATH - when this backend keeps its elements contiguously, construct the target directly
         *  from that buffer. A span's iterators are (effectively) pointers, so the target's range CTOR
         *  can bulk-copy - for trivial T, a memcpy - rather than walking this Iterable one element at a
         *  time through virtual calls.
         *
         *  Applies to EVERY target type. Nothing about it is vector-specific, and the same saving is
         *  available to As<list<T>> (), As<Sequence<T>> (), ... - though where the target's own insertion
         *  cost dominates (a node per element) the saving is a much smaller share of the total.
         *
         *  Guarded by constructible_from so this stays purely additive: a CONTAINER_OF_T that accepts
         *  Stroika's iterators but not a plain pointer pair simply keeps the slow path below.
         *
         *  The accessor must outlive the span, which is why it is a named local rather than a temporary
         *  - see the precondition on _IRep::PeekContiguousStorage ().
         *
         *  Backends with no contiguous storage (linked lists, hash tables, skip lists, and notably the
         *  generator rep that Iterable<T> wraps a plain STL container in) return nullopt and fall through
         *  to a generic implementation.
         */
        using ContiguousIterator_ = typename span<const T>::iterator; // NB: not necessarily const T* (eg checked iterators)
        if constexpr (constructible_from<CONTAINER_OF_T, CONTAINER_OF_T_CONSTRUCTOR_ARGS..., ContiguousIterator_, ContiguousIterator_>) {
            _SafeReadRepAccessor<> accessor{this};
            if (auto s = accessor._ConstGetRep ().PeekContiguousStorage ()) {
                return CONTAINER_OF_T (forward<CONTAINER_OF_T_CONSTRUCTOR_ARGS> (args)..., s->begin (), s->end ());
            }
        }
        // some containers require two iterators as arguments, but Stroika ones work with default_sentinel_t or iterator
        // use CONTAINER_OF_T () instead of CONTAINER_OF_T{} because we do want to allow coercion here - since use explicitly called As<>
        if constexpr (derived_from<CONTAINER_OF_T, Iterable<T>>) {
            return CONTAINER_OF_T (forward<CONTAINER_OF_T_CONSTRUCTOR_ARGS> (args)..., begin (), end ());
        }
        else {
            return CONTAINER_OF_T (forward<CONTAINER_OF_T_CONSTRUCTOR_ARGS> (args)..., begin (), Iterator<T>{end ()});
        }
    }
    template <typename T>
    inline T Iterable<T>::Nth (ptrdiff_t n) const
    {
        Require (n < static_cast<ptrdiff_t> (size ()));
        Require (n > -static_cast<ptrdiff_t> (size ()));
        size_t useIndex = n >= 0 ? static_cast<size_t> (n) : static_cast<size_t> (n + static_cast<ptrdiff_t> (size ()));
        size_t idx      = useIndex; // countdown
        for (const T& i : *this) {
            if (idx == 0) {
                return i;
            }
            --idx;
        }
        AssertNotReached ();
        return *begin ();
    }
    template <typename T>
    inline T Iterable<T>::NthValue (ptrdiff_t n, ArgByValueType<T> defaultValue) const
    {
        size_t useIndex = n >= 0 ? static_cast<size_t> (n) : static_cast<size_t> (n + static_cast<ptrdiff_t> (size ()));
        size_t idx      = useIndex; // countdown
        for (const T& i : *this) {
            if (idx == 0) {
                return i;
            }
            --idx;
        }
        return defaultValue;
    }
 
    /*
     ********************************************************************************
     ******************** Iterable<T>::SequentialEqualsComparer *********************
     ********************************************************************************
     */
    template <typename T>
    template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (IEqualsComparer<T>) T_EQUALS_COMPARER>
    constexpr Iterable<T>::SequentialEqualsComparer<T_EQUALS_COMPARER>::SequentialEqualsComparer (const T_EQUALS_COMPARER& elementEqualsComparer)
        : fElementComparer{elementEqualsComparer}
    {
    }
    DISABLE_COMPILER_MSC_WARNING_START (4996)
    DISABLE_COMPILER_CLANG_WARNING_START ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_GCC_WARNING_START ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
    template <typename T>
    template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (IEqualsComparer<T>) T_EQUALS_COMPARER>
    constexpr Iterable<T>::SequentialEqualsComparer<T_EQUALS_COMPARER>::SequentialEqualsComparer (const T_EQUALS_COMPARER& elementEqualsComparer,
                                                                                                  [[maybe_unused]] bool useIterableSize)
        : fElementComparer{elementEqualsComparer}
    {
    }
    DISABLE_COMPILER_GCC_WARNING_END ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_CLANG_WARNING_END ("clang diagnostic ignored \"-Wdeprecated-declarations\"")
    DISABLE_COMPILER_MSC_WARNING_END (4996)
    template <typename T>
    template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (IEqualsComparer<T>) T_EQUALS_COMPARER>
    inline bool Iterable<T>::SequentialEqualsComparer<T_EQUALS_COMPARER>::operator() (const Iterable& lhs, const Iterable& rhs) const
    {
        return SequentialEquals (lhs, rhs, fElementComparer);
    }
 
    /*
     ********************************************************************************
     ******************** Iterable<T>::SequentialThreeWayComparer *******************
     ********************************************************************************
     */
    template <typename T>
    template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (IThreeWayComparer<T>) T_THREEWAY_COMPARER>
    constexpr Iterable<T>::SequentialThreeWayComparer<T_THREEWAY_COMPARER>::SequentialThreeWayComparer (const T_THREEWAY_COMPARER& elementComparer)
        : fElementComparer{elementComparer}
    {
    }
    DISABLE_COMPILER_MSC_WARNING_START (4701)
    template <typename T>
    template <qCompilerAndStdLib_ConstraintDiffersInTemplateRedeclaration_BWA (IThreeWayComparer<T>) T_THREEWAY_COMPARER>
    inline auto Iterable<T>::SequentialThreeWayComparer<T_THREEWAY_COMPARER>::operator() (const Iterable& lhs, const Iterable& rhs) const
    {
        auto li = lhs.begin ();
        auto le = lhs.end ();
        auto ri = rhs.begin ();
        auto re = rhs.end ();
        DISABLE_COMPILER_MSC_WARNING_START (6001)
        DISABLE_COMPILER_GCC_WARNING_START ("GCC diagnostic ignored \"-Wmaybe-uninitialized\"")
        // no need for c' initialization cuz only used in else return at end, but never get there
        // unless set at least once
        optional<strong_ordering> c;
        while ((li != le) and (ri != re) and (c = fElementComparer (*li, *ri)) == strong_ordering::equal) {
            ++li;
            ++ri;
        }
        if (li == le) {
            if (ri == re) {
                return strong_ordering::equal; // all items same and loop ended with both things at end
            }
            else {
                return strong_ordering::less; // lhs shorter but an initial sequence of rhs
            }
        }
        else if (ri == re) {
            return strong_ordering::greater; // rhs shorter but an initial sequence of lhs
        }
        else {
            Assert (li != le and ri != re);
            Assert (c == fElementComparer (*li, *ri));
            return c.value ();
        }
        DISABLE_COMPILER_GCC_WARNING_END ("GCC diagnostic ignored \"-Wmaybe-uninitialized\"")
        DISABLE_COMPILER_MSC_WARNING_END (6001)
    }
    DISABLE_COMPILER_MSC_WARNING_END (4701)
}