[boost] Re: PING: Lambda Documentation Problem

From: Stephan T. Lavavej (stl_at_[hidden])
Date: 2004-05-24 03:37:58

[David Abrahams]
> What *any* book other than the standard says has no bearing
> on whether a DR is appropriate.

Yes, of course.

Very well.  Though the Standard is clear to me, apparently it's not clear to
everyone, and it should be.  So here is a proposed DR.  Comments
(particularly on the Proposed Resolution)?  Once we get this DR into shape,
would you like to pass it on to the Committee?

---BEGIN DR---

Library DR [FIXME].

May the functor given to for_each modify its argument?

Section: 25.1.1 [lib.alg.foreach]

Status: Open

Submitter: Stephan T. Lavavej

Date: 24 May 2004

for_each is classified (without explanation) in [lib.alg.nonmodifying],
"25.1 Non-modifying sequence operations".  Every other algorithm in
[lib.alg.nonmodifying] is "really" non-modifying in the sense that neither
the algorithms themselves nor the functors given to them may modify the
sequences or elements in any way. The guarantee about the algorithms is
provided by their descriptions (and implicitly by their classification in
[lib.alg.nonmodifying], which is the subject of this DR), while the
guarantee about the functors is provided by the fact that they are all
Predicate or BinaryPredicate.

In contrast, for_each takes a Function. Library DR 290 complains that there
are no requirements placed on this Function; this DR complains that there
are no guarantees given about what the Function may do.

I believe that the intent of the Standard in classifying for_each as a
"non-modifying sequence operation" is to say that the algorithm itself does
not modify the sequence it is given (in contrast to "mutating sequence
operations" such as replace, where the algorithm itself does the
modifications), but that the Function given to for_each may modify the
elements it operates on.  This is supported by the bottom of Page 524 of The
C++ Programming Language Third Edition, fifth printing or higher (or any
printing of Special Edition).

The problem is that no guarantee is given that the Function may modify
elements it operates on, so conceivably an implementer could write for_each
in such a way as to disallow this, or a programmer may avoid using for_each
with element-modifying functors because of the belief that implementers have
such latitude.

Proposed Resolution:

Add the following sentence to the Notes in 25.1.1 [lib.alg.foreach]:

"/f/ may apply non-constant functions through the dereferenced iterators it
is applied to."

The phrasing here is chosen to be consistent with [lib.alg.foreach] Effects
("Applies /f/ to the result of dereferencing every iterator...") and the
opposite of the restrictions placed on Predicate in [lib.algorithms]
("/pred/ shall not apply any non-constant function through the dereferenced
iterator").

I believe that this guarantee coupled with the requirement proposed in
Library DR 290 covers all cases of what the Function passed to for_each may
and may not do.

Alternatively, phrasing based on the more detailed explanation in The C++
Programming Language Special Edition could be used (it explains that when an
element-modifying functor is used, the sequence has to be non-const; I
believe that the above phrasing implies this).

This guarantee merely clarifies what I believe is already the intent of the
Standard.  It is related to Library DR 290 but is independent of it, and
neither DR relies on the other.

---END DR---

The DR is probably unnecessarily verbose.

Stephan T. Lavavej
http://nuwen.net