From ff0950fd3ba97b3eae6a89d4271cfa241d6184f7 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sat, 4 Jul 2015 23:16:17 +0200 Subject: [PATCH] DOC: a note regarding Lumiera Forward Iterators and the range-for loop --- doc/devel/rfc/LumieraForwardIterator.txt | 23 +++++++++++++++++++++++ wiki/renderengine.html | 13 ++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/doc/devel/rfc/LumieraForwardIterator.txt b/doc/devel/rfc/LumieraForwardIterator.txt index 5bb298127..673eeb9d2 100644 --- a/doc/devel/rfc/LumieraForwardIterator.txt +++ b/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' ~~ +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' ~~ + //endof_comments: diff --git a/wiki/renderengine.html b/wiki/renderengine.html index cf471541e..2766ce776 100644 --- a/wiki/renderengine.html +++ b/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]] -
+
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 — 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.