DOC: a note regarding Lumiera Forward Iterators and the range-for loop

doc/devel/rfc/LumieraForwardIterator.txt

@@ -155,6 +155,29 @@ would require a ``deep copy'' of any underlying data structures.
 
 Ichthyostega:: 'Sa 07 Jan 2012 21:49:09 CET' ~<prg@ichthyostega.de>~ 
 
+NOTE: Lumiera Forward Iterators can be made to work together with the
+      'range for loop', as introduced with C++11. The preferred solution
+      is to define the necessary free functions `begin` and `end` for ADL.
+      This is best done on a per implementation base. We consider a generic
+      solution not worth the effort
+
+This is to say, these two concepts can be made to work together well. While,
+at a conceptual level, they are not really compatible, and build on a
+different understanding: The standard for-loop assumes ``a container'',
+while our Forward Iterator Concept deals with ``abstract data sources''.
+The user needs to understand the fine points of that conceptual difference:
+
+- if you apply the range-`for` construct on a container, you can iterate
+  as often as you like. Even if the iterators of that container are
+  implemented in compliance with the Lumiera Forward Iterator concept.
+- but if you apply the range-`for` construct on _a given iterator_,
+  you can do so only once. There is no way to reset that iterator,
+  other than obtaining a new one.
+
+See `71167be9c9aaa` for the typical bridge implementation
+
+Ichthyostega:: 'Sa 04 Jul 2015 22:57:51 CEST' ~<prg@ichthyostega.de>~
+
 
 //endof_comments:
 

wiki/renderengine.html

@@ -2219,7 +2219,7 @@ Of course, we can place other ~MObjects relative to some fork (that's the main r
 → [[Anatomy of the high-level model|HighLevelModel]]
 </pre>
 </div>
-<div title="ForwardIterator" modifier="Ichthyostega" created="200910312114" modified="200912190027" tags="Concepts def spec">
+<div title="ForwardIterator" modifier="Ichthyostega" created="200910312114" modified="201507042115" tags="Concepts def spec" changecount="1">
 <pre>The situation focussed by this concept is when an API needs to expose a sequence of results, values or objects, instead of just yielding a function result value. As the naive solution of passing an pointer or array creates coupling to internals, it was superseded by the ~GoF [[Iterator pattern|http://en.wikipedia.org/wiki/Iterator]]. Iteration can be implemented by convention, polymorphically or by generic programming; we use the latter approach.
 
 !Lumiera Forward Iterator concept
@@ -2237,6 +2237,17 @@ The Lumiera Forward Iterator concept is a blend of the STL iterators and iterato
 
 Another notable difference to the STL iterators is the default ctor and the {{{bool}}} conversion. The latter allows using iterators painlessly within {{{for}}} and {{{while}}} loops; a default constructed iterator is equivalent to the STL container's {{{end()}}} value &amp;mdash; indeed any //container-like// object exposing Lumiera Forward Iteration is encouraged to provide such an {{{end()}}}-function, additionally enabling iteration by {{{std::for_each}}} (or Lumiera's even more convenient {{{util::for_each()}}}).
 
+!!!interoperation with the C++11 range-for construct
+Lumiera Forward Iterators can be made to work together with the  'range for loop', as introduced with C++11. The preferred solution is to define the necessary free functions {{{begin}}} and {{{end}}} for ADL. This is best done on a per implementation base. We consider a generic solution not worth the effort. See {{{71167be9c9aaa}}}.
+
+This is to say, these two concepts can be made to work together well. While, at a conceptual level, they are not really compatible, and build on a different understanding: The standard for-loop assumes //a container,// while our Forward Iterator Concept deals with //abstract data sources.//. 
+The user needs to understand the fine points of that conceptual difference:
+* if you apply the range-`for` construct on a container, you can iterate as often as you like. Even if the iterators of that container are  implemented in compliance with the Lumiera Forward Iterator concept.
+* but if you apply the range-`for` construct on //a given iterator, //  you can do so only once. There is no way to reset that iterator, other than obtaining a new one.
+ 
+The bridge methods are usually defined so that the {{{end}}}-function just returns a default constructed iterator, which -- by concept -- is the marker for iteration end
+
+
 !!Implementation notes
 ''iter-adapter.hpp'' provides some helper templates for building Lumiera Forward Iterators.
 * __~IterAdapter__ is the most flexible variant, intended for use by custom facilities. An ~IterAdapter maintains an internal back-link to a facilitiy exposing an iteration control API, which is accessed through free functions as extension point. This iteration control API is similar to C#, allowing to advance to the next result and to check the current iteration state.