<commit_before>/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2014.  All rights reserved
 */
#ifndef _Stroika_Foundation_Traversal_Iterable_h_
#define _Stroika_Foundation_Traversal_Iterable_h_  1

#include    "../StroikaPreComp.h"

#include    <functional>

#include    "../Common/Compare.h"
#include    "../Configuration/Common.h"
#include    "../Memory/SharedByValue.h"
#include    "../Memory/SharedPtr.h"

#include    "Iterator.h"



/**
 *  \file
 *
 *  TODO:
 *
 *      @todo   Ordering of parameters to SetEquals() etc templates? Type deduction versus
 *              default parameter?
 *
 *      @todo   REDO DOCS FOR ITERABLE - SO CLEAR ITS ALSO THE BASIS OF "GENERATORS". IT COULD  BE RENAMED
 *              GENERATOR (though dont)
 *
 *      @todo   since Iterator<T> now uses iterator<> traits stuff, so should Iterable<T>?
 */



namespace   Stroika {
    namespace   Foundation {
        namespace   Traversal {


            /**
             *  \brief  Iterable<T> is a base class for containers which easily produce an Iterator<T>
             *          to traverse them.
             *
             *  Iterable<T> is a base class for containers which easily produce an Iterator<T> to traverse them.
             *
             *  The Stroika iterators can be used either directly, or in the STL begin/end style - and this
             *  class supports both styles of usage.
             *
             *  Iterable<T> also supports read-only applicative operations on the contained data.
             *
             *  Iterable<T> is much like idea of 'abstract readonly container', but which only supports an
             *  exceedingly simplistic pattern of access.
             *
             *  *Important Design Note*:
             *      We have no:
             *          nonvirtual  void    _SetRep (SharedIRepPtr rep);
             *
             *      because allowing a _SetRep() method would complicate the efforts of subclasses of Iterable<T>
             *      to assure that the underlying type is of the appropriate subtype.
             *
             *      For example - see Bag_Array<T>::GetRep_().
             *
             *  *Design Note*:
             *      Why does Iterable<T> contain a GetLength () method?
             *
             *          o   It’s always well defined what GetLength() means (what you would get if you called
             *              MakeIterable() and iterated a bunch of times til the end).
             *
             *          o   Its almost always (and trivial) to perform that computation more efficiently than the
             *              iterate over each element apporach.
             *
             *          The gist of these two consideration means that if you need to find the length of
             *          an Iterable<T>, if it was defined as a method, you can access the trivial implemeantion,
             *          and if it was not defined, you would be forced into the costly implementation.
             *
             *      Adding GetLength () adds no conceptual cost – because its already so well and clearly defined
             *      in terms of its basic operation (iteration). And it provides value (maybe just modest value).
             *
             *  *Design Note*:
             *      Order of Iteration.
             *
             *      Iterables<T> provide no promises about the order of iteration. Specific subclasses (like SortedSet<>)
             *      often will make specific guarantees about order of iteration.
             *
             *      We do NOT even promise you will see the same items, or seem them in the same order as you iterate
             *      (so for example, you can have a "RandomSequence<>" subclass from Iterable<> and return a different
             *      sequence of numbers each time you make an iterate and run.
             *
             *  *Design Note*:
             *      Chose NOT to include an Equals(Iterable<T> rhs) const method here, but instead duplicatively in
             *      each subclass, so that it could more easily be implemented efficiently (not a biggie), but more
             *      importantly because it doesnt appear to me to make sense so say that a Stack<T> == Set<T>, even if
             *      their values were the same.
             *
             *      ((REVISION - 2013-12-21 - SEE NEW SETEUQALS/TALLYEQUALS/EXACTEUALS methods below)
             *
             *  *Important Design Note*:
             *      Probably important - for performance??? - that all these methods are const,
             *      so ??? think through - what this implies- but probably soemthing about not
             *      threading stuff and ???
             *
             *  *Important Design Note*:
             *      The Lifetime of Iterator<T> objects created by an Iterable<T> instance must always be less
             *      than the creating Iterable's lifetime.
             *
             *      This may not be enforced by implementations (but generally will be in debug builds). But
             *      it is a rule!
             *
             *      The reason for this is that the underlying memory referenced by the iterator may be going away.
             *      We could avoid this by adding a shared_ptr<> reference count into each iterator, but that
             *      would make iterator objects significantly more expensive, and with little apparent value added.
             *      Similarly for weak_ptr<> references.
             *
             *  *Design Note*:
             *      Rejected idea:
             *          Add overload of FindFirstThat() that takes Iterator<T> as arugument instead of T
             *          so you can delete the item pointed to by T.
             *
             *          This was rejected because it can easily be done directly with iterators, and seems
             *          a queeryly specific problem. I cannot see any patterns where one would want to do this.
             *
             *  \note   \em Thread-Safety   <a href="thread_safety.html#Automatically-Synchronized-Thread-Safety">Automatically-Synchronized-Thread-Safety</a>
             *
             */
            template    <typename T>
            class   Iterable {
            public:
                /**
                 *      \brief  ElementType is just a handly copy of the *T* template type which this
                 *              Iterable<T> parameterizes access to.
                 */
                using   ElementType =    T;

            protected:
                class  _IRep;

            protected:
                /**
                 *      Temporary name/define - for what SharedPtr/shared_ptr impl we are using.
                 *      Experimental, so dont use directly (yet) - til stablized.
                 *          -- LGP 2014-02-23
                 */
                template    <typename SHARED_T>
                using   _USING_SHARED_IMPL_ =   shared_ptr<SHARED_T>;
                //using _USING_SHARED_IMPL_ =   Memory::SharedPtr<SHARED_T>;

                template    <typename SHARED_T>
                using   _USING_SHARED_enable_shared_from_this_IMPL_ =   std::enable_shared_from_this<SHARED_T>;
                //using _USING_SHARED_enable_shared_from_this_IMPL_ =   Memory::enable_shared_from_this<SHARED_T>;

            protected:
                /**
                 *  For now, just use the std::shared_ptr<> - but we may want to go back to older Stroika
                 *  SharedPtr<> code - which I believe is more performant (but lacks the weak_ptr feature).
                 *
                 *  To support that possability, be sure to refernece _SharedPtrIRep instead of using shared_ptr<>
                 *  directly.
                 */
                using   _SharedPtrIRep  =   _USING_SHARED_IMPL_<_IRep>;

            public:
                /**
                 *  \brief  Iterable are safely copyable (by value).
                 */
                Iterable (const Iterable<T>& from) noexcept;

            public:
                /**
                 *  \brief  move CTOR - clears source
                 */
                explicit Iterable (Iterable<T>&& from) noexcept;

            protected:
                /**
                 *  \brief  Iterable's are typically constructed as concrete subtype objects, whose CTOR passed in a shared copyable rep.
                 */
                explicit Iterable (const _SharedPtrIRep& rep) noexcept;<commit_msg>test ITERABLEBASE<commit_after>/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2014.  All rights reserved
 */
#ifndef _Stroika_Foundation_Traversal_Iterable_h_
#define _Stroika_Foundation_Traversal_Iterable_h_  1

#include    "../StroikaPreComp.h"

#include    <functional>

#include    "../Common/Compare.h"
#include    "../Configuration/Common.h"
#include    "../Memory/SharedByValue.h"
#include    "../Memory/SharedPtr.h"

#include    "Iterator.h"



/**
 *  \file
 *
 *  TODO:
 *
 *      @todo   Ordering of parameters to SetEquals() etc templates? Type deduction versus
 *              default parameter?
 *
 *      @todo   REDO DOCS FOR ITERABLE - SO CLEAR ITS ALSO THE BASIS OF "GENERATORS". IT COULD  BE RENAMED
 *              GENERATOR (though dont)
 *
 *      @todo   since Iterator<T> now uses iterator<> traits stuff, so should Iterable<T>?
 */



namespace   Stroika {
    namespace   Foundation {
        namespace   Traversal {



            // experiemnt and see if this helps Mujltiset bug...
            struct  ITERABLEBASE {
            protected:
                /**
                 *      Temporary name/define - for what SharedPtr/shared_ptr impl we are using.
                 *      Experimental, so dont use directly (yet) - til stablized.
                 *          -- LGP 2014-02-23
                 */
                template    <typename SHARED_T>
                using   _USING_SHARED_IMPL_ =   shared_ptr<SHARED_T>;
                //using _USING_SHARED_IMPL_ =   Memory::SharedPtr<SHARED_T>;

                template    <typename SHARED_T>
                using   _USING_SHARED_enable_shared_from_this_IMPL_ =   std::enable_shared_from_this<SHARED_T>;
                //using _USING_SHARED_enable_shared_from_this_IMPL_ =   Memory::enable_shared_from_this<SHARED_T>;
            };


            /**
             *  \brief  Iterable<T> is a base class for containers which easily produce an Iterator<T>
             *          to traverse them.
             *
             *  Iterable<T> is a base class for containers which easily produce an Iterator<T> to traverse them.
             *
             *  The Stroika iterators can be used either directly, or in the STL begin/end style - and this
             *  class supports both styles of usage.
             *
             *  Iterable<T> also supports read-only applicative operations on the contained data.
             *
             *  Iterable<T> is much like idea of 'abstract readonly container', but which only supports an
             *  exceedingly simplistic pattern of access.
             *
             *  *Important Design Note*:
             *      We have no:
             *          nonvirtual  void    _SetRep (SharedIRepPtr rep);
             *
             *      because allowing a _SetRep() method would complicate the efforts of subclasses of Iterable<T>
             *      to assure that the underlying type is of the appropriate subtype.
             *
             *      For example - see Bag_Array<T>::GetRep_().
             *
             *  *Design Note*:
             *      Why does Iterable<T> contain a GetLength () method?
             *
             *          o   It’s always well defined what GetLength() means (what you would get if you called
             *              MakeIterable() and iterated a bunch of times til the end).
             *
             *          o   Its almost always (and trivial) to perform that computation more efficiently than the
             *              iterate over each element apporach.
             *
             *          The gist of these two consideration means that if you need to find the length of
             *          an Iterable<T>, if it was defined as a method, you can access the trivial implemeantion,
             *          and if it was not defined, you would be forced into the costly implementation.
             *
             *      Adding GetLength () adds no conceptual cost – because its already so well and clearly defined
             *      in terms of its basic operation (iteration). And it provides value (maybe just modest value).
             *
             *  *Design Note*:
             *      Order of Iteration.
             *
             *      Iterables<T> provide no promises about the order of iteration. Specific subclasses (like SortedSet<>)
             *      often will make specific guarantees about order of iteration.
             *
             *      We do NOT even promise you will see the same items, or seem them in the same order as you iterate
             *      (so for example, you can have a "RandomSequence<>" subclass from Iterable<> and return a different
             *      sequence of numbers each time you make an iterate and run.
             *
             *  *Design Note*:
             *      Chose NOT to include an Equals(Iterable<T> rhs) const method here, but instead duplicatively in
             *      each subclass, so that it could more easily be implemented efficiently (not a biggie), but more
             *      importantly because it doesnt appear to me to make sense so say that a Stack<T> == Set<T>, even if
             *      their values were the same.
             *
             *      ((REVISION - 2013-12-21 - SEE NEW SETEUQALS/TALLYEQUALS/EXACTEUALS methods below)
             *
             *  *Important Design Note*:
             *      Probably important - for performance??? - that all these methods are const,
             *      so ??? think through - what this implies- but probably soemthing about not
             *      threading stuff and ???
             *
             *  *Important Design Note*:
             *      The Lifetime of Iterator<T> objects created by an Iterable<T> instance must always be less
             *      than the creating Iterable's lifetime.
             *
             *      This may not be enforced by implementations (but generally will be in debug builds). But
             *      it is a rule!
             *
             *      The reason for this is that the underlying memory referenced by the iterator may be going away.
             *      We could avoid this by adding a shared_ptr<> reference count into each iterator, but that
             *      would make iterator objects significantly more expensive, and with little apparent value added.
             *      Similarly for weak_ptr<> references.
             *
             *  *Design Note*:
             *      Rejected idea:
             *          Add overload of FindFirstThat() that takes Iterator<T> as arugument instead of T
             *          so you can delete the item pointed to by T.
             *
             *          This was rejected because it can easily be done directly with iterators, and seems
             *          a queeryly specific problem. I cannot see any patterns where one would want to do this.
             *
             *  \note   \em Thread-Safety   <a href="thread_safety.html#Automatically-Synchronized-Thread-Safety">Automatically-Synchronized-Thread-Safety</a>
             *
             */
            template    <typename T>
            class   Iterable : ITERABLEBASE {
            public:
                /**
                 *      \brief  ElementType is just a handly copy of the *T* template type which this
                 *              Iterable<T> parameterizes access to.
                 */
                using   ElementType =    T;

            protected:
                class  _IRep;


            protected:
                /**
                 *  For now, just use the std::shared_ptr<> - but we may want to go back to older Stroika
                 *  SharedPtr<> code - which I believe is more performant (but lacks the weak_ptr feature).
                 *
                 *  To support that possability, be sure to refernece _SharedPtrIRep instead of using shared_ptr<>
                 *  directly.
                 */
                using   _SharedPtrIRep  =   _USING_SHARED_IMPL_<_IRep>;

            public:
                /**
                 *  \brief  Iterable are safely copyable (by value).
                 */
                Iterable (const Iterable<T>& from) noexcept;

            public:
                /**
                 *  \brief  move CTOR - clears source
                 */
                explicit Iterable (Iterable<T>&& from) noexcept;

            protected:
                /**
                 *  \brief  Iterable's are typically constructed as concrete subtype objects, whose CTOR passed in a shared copyable rep.
                 */
                explicit Iterable (const _SharedPtrIRep& rep) noexcept;
{'fraction_non_alphanumeric': 0.06375079761007019, 'fraction_numerical': 0.0029004002552352223, 'mean_word_length': 1.5, 'pattern_counts': {'":': 0, '<': 87, '<?xml version=': 0, '>': 87, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1885365', 'n_tokens_mistral': 4355, 'n_tokens_neox': 4170, 'n_words': 1625}