IteratorImplHelper.h

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Foundation_Containers_Private_IteratorImplHelper_h_
#define _Stroika_Foundation_Containers_Private_IteratorImplHelper_h_
 
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Containers/Common.h"
#include "Stroika/Foundation/Traversal/BidirectionalIterator.h"
#include "Stroika/Foundation/Traversal/Iterator.h"
#include "Stroika/Foundation/Traversal/RandomAccessIterator.h"
 
/**
 *  Private utility to support building of Traversal::Iterator<> objects for concrete Containers.
 *
 * TODO:
 *      @todo   Crazy temphack cuz current code assumes you must call++ before starting iteration! Crazy!
 *              Issue is way we implemented the 'CURRENT' stuff with iterators - filling in after the first
 *              More()...
 *
 *              At this point - this appears to be restricted to ALL BACKEND support Iterator (ForwardIterator) classes.
 *              The Stroika Iterator API doesn't appear to have this quirk.
 *
 *
 * Notes:
 *
 */
 
namespace Stroika::Foundation::Containers::Private {
 
    /**
     */
    struct ContainerDebugChangeCounts_ {
        using ChangeCountType = unsigned int;
#if qStroika_Foundation_Debug_AssertionsChecked
        static ChangeCountType mkInitial_ ();
#endif
 
        ContainerDebugChangeCounts_ ();
        ContainerDebugChangeCounts_ (const ContainerDebugChangeCounts_& src);
        ~ContainerDebugChangeCounts_ ();
 
#if qStroika_Foundation_Debug_AssertionsChecked
        // NOTE - might want to use weakly_shared_ptr (weakref) as safer 'debugging' check than this, but only
        // for debug checking, so not strictly needed (and might cost too much). CONSIDER going forward just
        // for DEBUG mode -- LGP 2021-11-11
        bool                    fDeleted{false};
        atomic<ChangeCountType> fChangeCount{0}; // overwritten with random# in CTOR
#endif
 
        /**
         */
        nonvirtual void PerformedChange ();
    };
 
    template <typename T, typename DATASTRUCTURE_CONTAINER>
    struct IteratorImplHelper_DefaultTraits {
        static_assert (not is_reference_v<T>);
        static_assert (not is_reference_v<DATASTRUCTURE_CONTAINER>);
        using DataStructureT               = DATASTRUCTURE_CONTAINER;
        using DataStructureIteratorT       = typename DATASTRUCTURE_CONTAINER::ForwardIterator;
        using DataStructureContainerValueT = typename DATASTRUCTURE_CONTAINER::value_type; // I THINK WE CAN LOSE THIS DEFINE
        //  static constexpr bool kConvertDataStructureIterationResult2ContainerIteratorResult = false;
        // see if can use auto in place of explict XX
        //template <typename XX>
        static constexpr T ConvertDataStructureIterationResult2ContainerIteratorResult (const DataStructureContainerValueT& t)
        //requires (Common::explicitly_convertible_to<DataStructureContainerValueT, T>)
        {
            static_assert (Common::explicitly_convertible_to<DataStructureContainerValueT, T>,
                           "dont use the default traits, but provide your own - see KeyedCollection_HashTable as example");
            return static_cast<T> (t);
        }
    };
 
    /**
     *  \brief helper to wrap a low level 'DataStructure Container Iterator' into a 'Stroika' Iterator::IRep iterator.
     *
     *  There is no requirement that Stroika concrete containers use this class. However, it
     *  so far has appeared a handy code sharing utility.
     *
     *  Plus, its details are intimately tied to how the Stroika containers manage lifetime, so
     *  its not likely well suited for use elsewhere.
     *
     *  \note   BASE_IREP defaults to Iterator<T>::IRep, but can be overridden (see BidirectionalIteratorImplHelper_/
     *          RandomAccessIteratorImplHelper_ below) to derive from BidirectionalIterator<T>::IRep or
     *          RandomAccessIterator<T>::IRep instead, so that subclass can legally override AtStart ()/Back ()/
     *          Advance ()/Difference ()/PeekAtElement () (else there's nothing for those overrides to override).
     *
     *  \todo   This class is a bit kludgy/fragile. (e.g. the cases where you have to override More needing to also override Clone). Maybe use CRTP? And not
     *          good compiler error messages - maybe use more/better concepts usage; low priority since private impl helper method;
     *          -- LGP 2024-09-05
     */
    template <typename T, typename DATASTRUCTURE_CONTAINER, typename TRAITS = IteratorImplHelper_DefaultTraits<T, DATASTRUCTURE_CONTAINER>,
              typename BASE_IREP = typename Iterator<T>::IRep>
    class IteratorImplHelper_ : public BASE_IREP,
                                public Memory::UseBlockAllocationIfAppropriate<IteratorImplHelper_<T, DATASTRUCTURE_CONTAINER, TRAITS, BASE_IREP>> {
    private:
        using inherited = BASE_IREP;
 
        //backward compat names
    private:
        using DATASTRUCTURE_CONTAINER_ITERATOR = typename TRAITS::DataStructureIteratorT;
        using DATASTRUCTURE_CONTAINER_VALUE    = typename TRAITS::DataStructureContainerValueT;
 
    public:
        using DataStructureImplValueType_ = DATASTRUCTURE_CONTAINER_VALUE;
 
    public:
        IteratorImplHelper_ ()                               = delete;
        IteratorImplHelper_ (IteratorImplHelper_&&) noexcept = default;
        IteratorImplHelper_ (const IteratorImplHelper_&)     = default;
        template <typename... ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS>
        explicit IteratorImplHelper_ (const DATASTRUCTURE_CONTAINER* data, const ContainerDebugChangeCounts_* changeCounter = nullptr,
                                      ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS&&... args)
            requires (constructible_from<DATASTRUCTURE_CONTAINER_ITERATOR, const DATASTRUCTURE_CONTAINER*, ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS...>);
        template <typename... ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS>
        explicit IteratorImplHelper_ (const ContainerDebugChangeCounts_* changeCounter = nullptr, ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS&&... args)
            requires (constructible_from<DATASTRUCTURE_CONTAINER_ITERATOR, ADDITIONAL_BACKEND_ITERATOR_CTOR_ARGUMENTS...>);
 
    public:
        virtual ~IteratorImplHelper_ () = default;
 
        // Iterator<T>::IRep
    public:
        virtual unique_ptr<typename Iterator<T>::IRep> Clone () const override;
        virtual bool                                   AtEnd () const override;
        virtual optional<T>                            Current () const override;
        virtual optional<T>                            More () override;
        virtual bool                                   Equals (const typename Iterator<T>::IRep* rhs) const override;
#if qStroika_Foundation_Debug_AssertionsChecked
        /**
         */
        virtual void Invariant () const noexcept override;
#endif
 
    public:
        /**
         * rarely used but in special cases when returning new derived/pathed iterator*
         */
        nonvirtual void UpdateChangeCount ();
 
    public:
        /**
         *  This is used internally by Stroika to assure iterators are not used after the container they iterate over
         *  has been changed.
         */
        nonvirtual void ValidateChangeCount () const;
 
    public:
        mutable DATASTRUCTURE_CONTAINER_ITERATOR fIterator{};
#if qStroika_Foundation_Debug_AssertionsChecked
        const ContainerDebugChangeCounts_*           fChangeCounter{nullptr};
        ContainerDebugChangeCounts_::ChangeCountType fLastCapturedChangeCount{};
#endif
    };
 
    /**
     *  \brief like IteratorImplHelper_ but for bidirectional iterators.
     *
     *  \note   BASE_IREP defaults to BidirectionalIterator<T>::IRep, but RandomAccessIteratorImplHelper_ (below)
     *          overrides it to RandomAccessIterator<T>::IRep, so it can inherit AtStart ()/Back () from here
     *          while still ultimately deriving from RandomAccessIterator<T>::IRep (needed so its own overrides
     *          of Advance ()/Difference ()/PeekAtElement () have something to override).
     */
    template <typename T, typename DATASTRUCTURE_CONTAINER, typename TRAITS = IteratorImplHelper_DefaultTraits<T, DATASTRUCTURE_CONTAINER>,
              typename BASE_IREP = typename Traversal::BidirectionalIterator<T>::IRep>
    class BidirectionalIteratorImplHelper_ : public IteratorImplHelper_<T, DATASTRUCTURE_CONTAINER, TRAITS, BASE_IREP> {
    private:
        using inherited = IteratorImplHelper_<T, DATASTRUCTURE_CONTAINER, TRAITS, BASE_IREP>;
 
    public:
        using inherited::inherited;
 
        // Iterator<T>::IRep
    public:
        // NOTE: must override Clone () again here (even though inherited::Clone () already 'works') because
        // inherited::Clone () constructs an instance of 'inherited' (IteratorImplHelper_) - which is abstract
        // once you factor in the AtStart ()/Back () pure virtuals added here - so Clone () must be re-overridden
        // at each level that adds new pure virtual overrides, to construct the right (most-derived) type.
        virtual unique_ptr<typename Iterator<T>::IRep> Clone () const override;
 
    public:
        virtual bool AtStart () const override;
        virtual T    Back () override;
    };
 
    /**
     *  \brief like IteratorImplHelper_ but for random access iterators.
     */
    template <typename T, typename DATASTRUCTURE_CONTAINER, typename TRAITS = IteratorImplHelper_DefaultTraits<T, DATASTRUCTURE_CONTAINER>>
    class RandomAccessIteratorImplHelper_
        : public BidirectionalIteratorImplHelper_<T, DATASTRUCTURE_CONTAINER, TRAITS, typename Traversal::RandomAccessIterator<T>::IRep> {
    private:
        using inherited = BidirectionalIteratorImplHelper_<T, DATASTRUCTURE_CONTAINER, TRAITS, typename Traversal::RandomAccessIterator<T>::IRep>;
 
    public:
        using inherited::inherited;
 
        // Iterator<T>::IRep
    public:
        // see NOTE on BidirectionalIteratorImplHelper_::Clone () above - same reasoning applies here.
        virtual unique_ptr<typename Iterator<T>::IRep> Clone () const override;
 
    public:
        virtual void      Advance (ptrdiff_t i) override;
        virtual ptrdiff_t Difference (const typename Traversal::RandomAccessIterator<T>::IRep* rhs) const override;
        virtual const T*  PeekAtElement (ptrdiff_t i) const override;
    };
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "IteratorImplHelper.inl"
 
#endif /*_Stroika_Foundation_Containers_Private_IteratorImplHelper_h_ */