From af92b555d3841f170c3a22f08896d4004d3501e7 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sun, 27 Apr 2003 00:20:50 +0000 Subject: [PATCH] more edits [SVN r1213] --- doc/facade-and-adaptor.rst | 22 +++++++++---- doc/new-iter-concepts.rst | 67 ++++++++++++++++++++++---------------- 2 files changed, 54 insertions(+), 35 deletions(-) diff --git a/doc/facade-and-adaptor.rst b/doc/facade-and-adaptor.rst index 18fdd76..2687803 100755 --- a/doc/facade-and-adaptor.rst +++ b/doc/facade-and-adaptor.rst @@ -266,17 +266,25 @@ It is important to note that ``iterator_core_access`` does not open a safety loophole, as every core member function preserves the invariants of the iterator. -operator[]() -============ +``operator[]`` +================ -For operator[]() ``iterator_facade`` implements the semantics required -in the proposed resolution to issue `299`_ and adopted by proposal `n1477`_. -I.e. operator[]() is not required to return an lvalue. +The indexing operator for a generalized iterator presents special challenges; + +Writable iterators built with ``iterator_facade`` implement the +semantics required by the proposed resolution to issue `299`_ and +adopted by proposal `n1477`_: ``p[n] = x`` is equivalent to ``*(p + n) += x``. To make that possible regardless of the other details of the +iterator's implementation, the return type of ``operator[]`` is a +proxy object containing a copy of + +result of indexing the iterator is assignable +iterator .. _`299`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299 -operator->() -============ +``operator->`` +============== For ``readable iterators`` the reference type is only required to be convertible to the value type, but accessing members through diff --git a/doc/new-iter-concepts.rst b/doc/new-iter-concepts.rst index ca1993a..3f43c30 100644 --- a/doc/new-iter-concepts.rst +++ b/doc/new-iter-concepts.rst @@ -71,39 +71,49 @@ nonintuitive that at least one implementation erroneously assigns not return true references: there is the often cited example of disk-based collections. +.. I wonder if the disk-based collection argument is valid? I would + tend to do that with an internally stored lvalue. -DWA + .. _issue 96: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#96 -Another example of a hard-to-categorize iterator is a counting -iterator: an iterator the returns a sequence of integers when -incremented and dereferenced (see counting_iterator_). There are two -ways to implement this iterator, 1) return a true reference from -``operator[]`` (a reference to an integer data member of the counting -iterator) or 2) return the ``value_type`` or a proxy from -``operator[]``. Option 1) runs into the problems discussed in `issue -198`_, the reference will not be valid after the iterator is -destroyed. Option 2) is therefore a better choice, but then we have a -counting iterator that cannot be a random access iterator. +.. Another example of a hard-to-categorize iterator is a counting + iterator: an iterator the returns a sequence of integers when + incremented and dereferenced (see counting_iterator_). This iterator are two + ways to implement this iterator, 1) return a true reference from + ``operator[]`` (a reference to an integer data member of the counting + iterator) or 2) return the ``value_type`` or a proxy from + ``operator[]``. Option 1) runs into the problems discussed in `issue + 198`_: the reference will not be valid after the iterator is + destroyed. Option 2) is therefore a better choice, but then we have a + counting iterator that cannot be a random access iterator. .. Jeremy, option 1 is NOT an option, since there's no way to return a live reference from operator[]. I think you need to clarify/rework what you're saying here. I'd fix it myself, but I'm not sure what you're getting at. -DWA +.. On second thought, I think the whole paragraph is bogus (sorry). + The conclusion for option 2, "but then we have a counting iterator + that cannot be a random access iterator" is wrong, too: returning a + value from operator[] is compatible with the random access iterator + requirements. I commented it out. -DWA + .. _counting_iterator: http://www.boost.org/libs/utility/counting_iterator.htm .. _issue 198: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/lwg-active.html#198 -Yet another example is a transform iterator, an iterator adaptor that -applies a unary function object to the dereference value of the -wrapped iterator (see `transform_iterator`_). For unary functions -such as ``times`` the return type of ``operator*`` clearly needs -to be the ``result_type`` of the function object, which is typically -not a reference. However, with the current iterator requirements, if -you wrap ``int*`` with a transform iterator, you do not get a random -access iterator as expected, but an input iterator. +Another difficult-to-categorize iterator is the transform iterator, an +adaptor which applies a unary function object to the dereferenced +value of the some underlying iterator (see `transform_iterator`_). +For unary functions such as ``times``, the return type of +``operator*`` clearly needs to be the ``result_type`` of the function +object, which is typically not a reference. Because random access +iterators are prequired to return lvalues from ``operator*``, if you +wrap ``int*`` with a transform iterator, you do not get a random +access iterator as might be expected, but an input iterator. .. _`transform_iterator`: http://www.boost.org/libs/utility/transform_iterator.htm -A fourth example is found in the vertex and edge iterators of the +A third example is found in the vertex and edge iterators of the `Boost Graph Library`_. These iterators return vertex and edge descriptors, which are lightweight handles created on-the-fly. They must be returned by-value. As a result, their current standard @@ -121,10 +131,11 @@ In short, there are many useful iterators that do not fit into the current standard iterator categories. As a result, the following bad things happen: -- Iterators are often miss-categorized. -- Algorithm requirements are more strict than necessary, because they can - not separate out the need for random-access from the need for a true reference - return type. +- Iterators are often mis-categorized. + +- Algorithm requirements are more strict than necessary, because they + cannot separate the need for random access or bidirectional + traversal from the need for a true reference return type. ======================== @@ -276,11 +287,11 @@ direct approach for specifying ``operator[]`` would have a return type of ``reference``; the same as ``operator*``. However, going in this direction would mean that an iterator satisfying the old Random Access Iterator requirements would not necessarily be a model of Readable or -Writable Lvalue Iterator. Instead we have chosen a design that matches -the resolution of `issue 299`_. So ``operator[]`` is only required to -return something convertible to the ``value_type`` (for a Readable -Iterator), and is required to support assignment ``i[n] = t`` (for a -Writable Iterator). +Writable Lvalue Iterator. Instead we have chosen a design that +matches the resolution of `issue 299`_: ``operator[]`` is only +required to return something convertible to the ``value_type`` (for a +Readable Iterator), and is required to support assignment ``i[n] = t`` +(for a Writable Iterator). ===============