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

/**
 *
 *  \file
 *
 *  @todo   RETHINK RangedForIterator - I'm not sure why we need this. Make Tally<T> subclass
 *          from Iterable<TallyEntry<T>>?
 *
 *  @todo   FIX/LOSE qIteratorsRequireNoArgContructorForT stuff. Also related to quirk about REPS being constructed
 *          in the wrong state and requiring an initial ++.
 *          FIX THIS before supporting more types that require Iterable<T> / Iterator<T>.
 *          MAYBE just have ITERATOR define fVal as array of chars of size - sizeof(T), and carefully wrap access
 *          to assure right behavior when not constructed. Be careful about MOVE semantics...
 *          TIGHTLY coupled iwth next time - about merge ciurrent virtual call itno More()..
 *
 *  @todo   Merge Current virtual call into More() call? Trouble is constructing
 *          T. We could make fields char fCurrent_[sizeof(T)] but that poses problems
 *          for copying iterators. On balance, probably best to bag it!!!
 *
 *  @todo   CLARIFY (decide on?) the behavior if you lose all references to a container? Does the
 *          iterator remain valid? Does it effectively retain a reference to teh contianer?
 *          Or does it instantly go 'empty'?
 *
 *          Not sure it matters much which but we must document this clearly.
 */


#include    "../StroikaPreComp.h"

#include    "../Configuration/Common.h"

#include    "../Memory/SharedByValue.h"


// SSW 9/19/2011: remove this restriction for more efficiency and flexibility
#define qIteratorsRequireNoArgContructorForT    1






namespace   Stroika {
    namespace   Foundation {
        namespace   Containers {


            /**
             *  \brief
             *      An Iterator<T> is a copyable object which allows traversing the contents of some container.
             *
             *  An Iterator<T> is typically associated with some container (that is being iterated over)
             *  and which allows traversal from start to finish.
             *  (The iterator itself essentially provides a notion of *start* to *finish*).
             *
             *  There need not actually be a 'container' object. Other 'iterators' can be created, so long as
             *  they act like an iterator.
             *
             *  An Iterator<T> is a copyable object which can safely be used to capture (copy) the state of
             *  iteration and continue iterating from that spot. If the underlying container is
             *  modified, the iterator will be automatically updated to logically account for that update.
             *
             *  Iterators are robust in the presence of changes to their underlying container. Adding or
             *  removing items from a container will not invalidate the iteration.
             *
             *  Different kinds of containers can make further guarantees about the behavior of iterators
             *  in the presence of container modifications. For example a SequenceIterator will always
             *  traverse any items added after the current traversal index, and will never traverse items
             *  added with an index before the current traversal index.
             *
             *  For example:
             *
             *          for (Iterator<T> i = container.MakeIterator (); not i.Done (); i.Next ())  {
             *              f (i.Current ());
             *          }
             *
             *  or:
             *
             *          for (Iterator<T> i = container.begin (); i != container.end (); ++i)  {
             *              f (*i);
             *          }
             *
             *  or:
             *
             *          for (i : container)  {
             *              f (i);
             *          }
             *
             *  Key Differences between Stroika Iterators and STL Iterators:
             *
             *      1.      Stroika iterators are threadsafe. Updates to the underlying container
             *              never interfere with iteration, and need no explicit synchonization.
             *
             *      2.      Stroika iterators continue to work correctly when the underlying
             *              container is modified.
             *
             *      3.      Stroika iterators carry around their 'done' state all in one object.
             *              For compatability with existing C++ idiom, and some C++11 language features
             *              Stroika allows  use of end(), and i != end() to check for if an iterator is done.
             *              But internally, Stroika just checks i.Done(), and so can users of Stroika
             *              iterators.
             *
             *
             * Some Rules about Iterators:
             *
             *      1.      What is Done() cannot be UnDone()
             *              That is, once an iterator is done, it cannot be restarted.
             *
             *      2.      Iterators can be copied. They always refer to the same
             *              place they did before the copy, and the old iterator is unaffected
             *              by iteration in the new (though it can be affected indirectly
             *              thru mutations).
             *
             *      3.      Whether or not you encounter items added after an addition is
             *              undefined (by Iterator<T> but often defined in specifically for
             *              particular container subtypes).
             *
             *      4.      A consequence of the above, is that items added after you are done,
             *              are not encountered.
             *
             *
             *  Interesting Design Notes:
             *
             *      -   We considered a desgin for Current() - where it would dynamically
             *          grab the current value, as opposed to being defined to be frozen/copied
             *          at the time of iteration.
             *
             *          The advantage of the path not taken is that if you iterated several times without<commit_msg>comments in Iterator.h<commit_after>/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2012.  All rights reserved
 */
#ifndef _Stroika_Foundation_Containers_Iterator_h_
#define _Stroika_Foundation_Containers_Iterator_h_  1

/**
 *
 *  \file
 *
 *  @todo   RETHINK RangedForIterator - I'm not sure why we need this. Make Tally<T> subclass
 *          from Iterable<TallyEntry<T>>?
 *
 *  @todo   FIX/LOSE qIteratorsRequireNoArgContructorForT stuff. Also related to quirk about REPS being constructed
 *          in the wrong state and requiring an initial ++.
 *          FIX THIS before supporting more types that require Iterable<T> / Iterator<T>.
 *          MAYBE just have ITERATOR define fVal as array of chars of size - sizeof(T), and carefully wrap access
 *          to assure right behavior when not constructed. Be careful about MOVE semantics...
 *          TIGHTLY coupled iwth next time - about merge ciurrent virtual call itno More()..
 *
 *  @todo   Merge Current virtual call into More() call? Trouble is constructing
 *          T. We could make fields char fCurrent_[sizeof(T)] but that poses problems
 *          for copying iterators. On balance, probably best to bag it!!!
 *
 *  @todo   CLARIFY (decide on?) the behavior if you lose all references to a container? Does the
 *          iterator remain valid? Does it effectively retain a reference to teh contianer?
 *          Or does it instantly go 'empty'?
 *
 *          Not sure it matters much which but we must document this clearly.
 */


#include    "../StroikaPreComp.h"

#include    "../Configuration/Common.h"

#include    "../Memory/SharedByValue.h"


// SSW 9/19/2011: remove this restriction for more efficiency and flexibility
#define qIteratorsRequireNoArgContructorForT    1






namespace   Stroika {
    namespace   Foundation {
        namespace   Containers {


            /**
             *  \brief
             *      An Iterator<T> is a copyable object which allows traversing the contents of some container.
             *
             *  An Iterator<T> is typically associated with some container (that is being iterated over)
             *  and which allows traversal from start to finish.
             *  (The iterator itself essentially provides a notion of *start* to *finish*).
             *
             *  There need not actually be a 'container' object. Other 'iterators' can be created, so long as
             *  they act like an iterator.
             *
             *  An Iterator<T> is a copyable object which can safely be used to capture (copy) the state of
             *  iteration and continue iterating from that spot. If the underlying container is
             *  modified, the iterator will be automatically updated to logically account for that update.
             *
             *  Iterators are robust in the presence of changes to their underlying container. Adding or
             *  removing items from a container will not invalidate the iteration.
             *
             *  Different kinds of containers can make further guarantees about the behavior of iterators
             *  in the presence of container modifications. For example a SequenceIterator will always
             *  traverse any items added after the current traversal index, and will never traverse items
             *  added with an index before the current traversal index.
             *
             *  For example:
             *
             *          for (Iterator<T> i = container.MakeIterator (); not i.Done (); i.Next ())  {
             *              f (i.Current ());
             *          }
             *
             *  or:
             *
             *          for (Iterator<T> i = container.begin (); i != container.end (); ++i)  {
             *              f (*i);
             *          }
             *
             *  or:
             *
             *          for (i : container)  {
             *              f (i);
             *          }
             *
             *  Key Differences between Stroika Iterators and STL Iterators:
             *
             *      1.      Stroika iterators are threadsafe. Updates to the underlying container
             *              never interfere with iteration, and need no explicit synchonization.
             *
             *      2.      Stroika iterators continue to work correctly when the underlying
             *              container is modified.
             *
             *      3.      Stroika iterators carry around their 'done' state all in one object.
             *              For compatability with existing C++ idiom, and some C++11 language features
             *              Stroika allows  use of end(), and i != end() to check for if an iterator is done.
             *              But internally, Stroika just checks i.Done(), and so can users of Stroika
             *              iterators.
             *
             *      4.      Stroika iterators are not 'random access'. They just go forwards, one step at a
             *              time. In STL, some kinds of iterators act more like pointers where you can do
             *              address arithmatic.
             *
             *
             * Some Rules about Iterators:
             *
             *      1.      What is Done() cannot be UnDone()
             *              That is, once an iterator is done, it cannot be restarted.
             *
             *      2.      Iterators can be copied. They always refer to the same
             *              place they did before the copy, and the old iterator is unaffected
             *              by iteration in the new (though it can be affected indirectly
             *              thru mutations).
             *
             *      3.      Whether or not you encounter items added after an addition is
             *              undefined (by Iterator<T> but often defined in specifically for
             *              particular container subtypes).
             *
             *      4.      A consequence of the above, is that items added after you are done,
             *              are not encountered.
             *
             *
             *  Interesting Design Notes:
             *
             *      -   We considered a desgin for Current() - where it would dynamically
             *          grab the current value, as opposed to being defined to be frozen/copied
             *          at the time of iteration.
             *
             *          The advantage of the path not taken is that if you iterated several times without
{'fraction_non_alphanumeric': 0.05915558304979895, 'fraction_numerical': 0.004098360655737705, 'mean_word_length': 1.520070148090413, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 25, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '133509', 'n_tokens_mistral': 3082, 'n_tokens_neox': 2981, 'n_words': 1335}