Library: clarify name of index-based iterator

Originally, this helper was called `IterIndex`, thereby following a
common naming scheme of iteration-related facilities in Lumiera, e.g.
 * `IterAdapter`
 * `IterExplorer`
 * `IterSource`

However, I myself was not able to recall this name, and found myself
now for the second time unable to find this piece of code, even while
still able to recall vaguely that I had written something of this kind.
(and unable to find it by a text search for "index", for obvious reasons)

So, on a second thought, the original name is confusing: we do not create
an index of / for iterators; rather we are iterating an index. So this
is what it should be called...

src/lib/index-iter.hpp

@@ -1,5 +1,5 @@
 /*
-  ITER-INDEX.hpp  -  iterator with indexed random-access to referred container
+  INDEX-ITER.hpp  -  iterator with indexed random-access to referred container
 
   Copyright (C)         Lumiera.org
     2024,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,7 +21,7 @@
 */
 
 
-/** @file iter-index.hpp
+/** @file index-iter.hpp
  ** Iterator-style access handle to a referred container with subscript index.
  ** This wrapper packages a current index number and a back-link to some data container
  ** with subscript operator and range check. This allows to hand out a navigable access point
@@ -31,14 +31,14 @@
  ** to re-set the iteration to the container's start. Optionally, a smart-ptr can be
  ** embedded, allowing the handle also to own and manage the data container.
  ** 
- ** @see IterIndex_test
+ ** @see IndexIter_test
  ** @see iter-adapter.hpp
  ** @see [usage example](\ref lib::TextTemplate::InstanceCore)
  */
 
 
-#ifndef SRC_LIB_ITER_INDEX_H
-#define SRC_LIB_ITER_INDEX_H
+#ifndef SRC_LIB_INDEX_ITER_H
+#define SRC_LIB_INDEX_ITER_H
 
 
 #include "lib/iter-adapter.hpp"
@@ -114,20 +114,20 @@ namespace lib {
    * @tparam CON a container with `operator[]` and a function `size()`
    * @tparam PTR how to refer to this container; can be defined as smart-ptr,
    *             additionally allowing to manage this container automatically.
-   * @remark while a default constructed IterIndex and some _exhausted_ IterIndex
+   * @remark while a default constructed IndexIter and some _exhausted_ IndexIter
    *             compare equal, only the latter can be re-set into active state.
    */
   template<class CON, typename PTR = CON*>
-  class IterIndex
+  class IndexIter
     : public iter::IndexAccessCore<PTR>::IterWrapper
     {
       using _Cor = iter::IndexAccessCore<PTR>;
       using _Par = typename _Cor::IterWrapper;
       
     public:
-      IterIndex()  = default;
-      IterIndex (CON& container)  : IterIndex{&container}{ };
-      IterIndex (PTR pContainer)
+      IndexIter()  = default;
+      IndexIter (CON& container)  : IndexIter{&container}{ };
+      IndexIter (PTR pContainer)
         : _Par{_Cor{pContainer, 0}}
         { }
       
@@ -152,4 +152,4 @@ namespace lib {
   
   
 } // namespace lib
-#endif /*SRC_LIB_ITER_INDEX_H*/
+#endif /*SRC_LIB_INDEX_ITER_H*/

src/lib/several.hpp

@@ -61,7 +61,7 @@
 
 
 #include "lib/nocopy.hpp"
-#include "lib/iter-index.hpp"
+#include "lib/index-iter.hpp"
 
 #include <cstddef>
 #include <functional>
@@ -216,8 +216,8 @@ namespace lib {
       I& front() { return operator[] (0);                         }
       I& back()  { return operator[] (data_? data_->cnt-1 : 0);   }
       
-      using iterator       = lib::IterIndex<Several>;
-      using const_iterator = lib::IterIndex<const Several>;
+      using iterator       = lib::IndexIter<Several>;
+      using const_iterator = lib::IndexIter<const Several>;
       
       iterator begin()             { return iterator{*this};      }
       iterator end()               { return iterator{};           }

src/lib/text-template.hpp

@@ -175,7 +175,7 @@
 
 #include "lib/error.hpp"
 #include "lib/nocopy.hpp"
-#include "lib/iter-index.hpp"
+#include "lib/index-iter.hpp"
 #include "lib/iter-explorer.hpp"
 #include "lib/format-string.hpp"
 #include "lib/format-util.hpp"
@@ -380,7 +380,7 @@ namespace lib {
       template<class SRC>
       class InstanceCore
         {
-          using ActionIter = IterIndex<const ActionSeq>;
+          using ActionIter = IndexIter<const ActionSeq>;
           using DataCtxIter = typename SRC::Iter;
           using NestedCtx = std::pair<DataCtxIter, SRC>;
           using CtxStack = std::stack<NestedCtx, std::vector<NestedCtx>>;

src/steam/engine/node-builder.hpp

@@ -100,7 +100,7 @@
 #include "steam/engine/turnout.hpp"
 #include "lib/several-builder.hpp"
 #include "lib/format-string.hpp"
-#include "lib/iter-index.hpp"
+#include "lib/index-iter.hpp"
 #include "lib/test/test-helper.hpp"/////////////////////TODO TOD-oh
 
 #include <utility>
@@ -341,7 +341,7 @@ namespace engine {
       connectLeadPort (ProcNode& leadNode, uint port)
         {
           uint knownEntry{0};
-          for (auto& lead : lib::IterIndex{_Par::leads_})
+          for (auto& lead : lib::IndexIter{_Par::leads_})
             if (util::isSameObject (leadNode, lead))
               break;
             else

tests/12metaprogramming.tests

@@ -317,6 +317,11 @@ return: 0
 END
 
 
+TEST "index-based iterator" IndexIter_test 20 <<END
+return: 0
+END
+
+
 TEST "Iterable data source" IterSource_test 13 <<END
 out: ::13::12::11::10::9::8::7::6::5::4::3::2::1
 out: ::.............::............::...........::..........::.........::........::.......::......::.....::....::...::..::.$

tests/library/index-iter-test.cpp

@@ -1,5 +1,5 @@
 /*
-  IterIndex(Test)  -  verify index access packaged as iterator handle
+  IndexIter(Test)  -  verify index access packaged as iterator handle
 
   Copyright (C)         Lumiera.org
     2024,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,13 +21,13 @@
 * *****************************************************/
 
 /** @file iter-index-test.cpp
- ** unit test \ref IterIndex_test
+ ** unit test \ref IndexIter_test
  */
 
 
 
 #include "lib/test/run.hpp"
-#include "lib/iter-index.hpp"
+#include "lib/index-iter.hpp"
 #include "lib/test/test-helper.hpp"
 #include "lib/iter-explorer.hpp"
 #include "lib/format-util.hpp"
@@ -57,9 +57,9 @@ namespace test{
     const uint NUM_ELMS = 10;
     
     using Numz = vector<uint>;
-    using Iter = IterIndex<Numz>;
-    using CIter = IterIndex<const Numz>;
-    using SMIter = IterIndex<Numz, shared_ptr<Numz>>;
+    using Iter = IndexIter<Numz>;
+    using CIter = IndexIter<const Numz>;
+    using SMIter = IndexIter<Numz, shared_ptr<Numz>>;
     
     inline Numz
     makeNumz()
@@ -86,7 +86,7 @@ namespace test{
    * @see iter-adapter.hpp
    * @see [usage example](\ref event-log.hpp)
    */
-  class IterIndex_test : public Test
+  class IndexIter_test : public Test
     {
       
       virtual void
@@ -127,11 +127,11 @@ namespace test{
       
       
       
-      /** @test verify the ability of IterIndex to access and manipulate
+      /** @test verify the ability of IndexIter to access and manipulate
        * the current index position, which can be done any time, while in
        * the middle of iteration, and even after iteration end. That means,
        * even an exhausted iterator can be „reanimated“. This manipulation
-       * is not allowed on a default constructed IterIndex, though.
+       * is not allowed on a default constructed IndexIter, though.
        */
       void
       verify_randomAccess ()
@@ -289,7 +289,7 @@ namespace test{
         }
     };
   
-  LAUNCHER (IterIndex_test, "unit common");
+  LAUNCHER (IndexIter_test, "unit common");
   
   
 }} // namespace lib::test