!standard A.18.10(157/3)                              13-05-30    AI12-0069-1/01
!class binding interpretation 13-05-30
!status work item 13-05-30
!status received 13-05-02
!priority Low
!difficulty Easy
!qualifier Error
!subject Inconsistency in Tree container definition

!summary

The root node is never visited by a container iterator.

!question

A.18.10(153/3) says:

Iterate calls Process.all with a cursor that designates each element in
Container, starting with the root node and proceeding in a depth-first order. 

whereas A.18.10(157/3) says:

Iterate returns an iterator object (see 5.5.1) that will generate a value for
a loop parameter (see 5.5.2) designating each node in Container, starting with
the root node and proceeding in a depth-first order. 

The first does not include the root node in the iteration (it has no element),
while the second does.

Should these work the same way? (Yes.)

!recommendation

(See !summary.)

!wording

Modify A.18.10(157/3):

"...will generate a value for a loop parameter (see 5.5.2) designating each
{element}[node] in Container, ..."

!discussion

AARM A.18.10(153.a/3) says that "Process is not called with the root node", so it's
clear that not visiting the root node is intended for the procedure Iterate.

Additionally, both of the Iterate_Subtree forms say "each element", so the root
node is not visited should it be passed to those routines.

It makes no sense for function Iterate to be different, especially as visiting the
root node would require all loops to test for that before accessing the element
(as the root node does not have an element and attempted to access the element
raises an exception).

Thus we change the wording to say "each element" rather than "each node".

!ACATS Test

No extra ACATS test is needed (presumably, any iteration test would fail if the
root node cursor was returned as most uses would raise an exception).

!ASIS

No ASIS effect.


!appendix

From: Randy Brukardt
Sent: Thursday, May  2, 2013  7:42 PM

A.18.10(153/3) says:

Iterate calls Process.all with a cursor that designates each element in
Container, starting with the root node and proceeding in a depth-first order. 

A.18.10(157/3) says:

Iterate returns an iterator object (see 5.5.1) that will generate a value for
a loop parameter (see 5.5.2) designating each node in Container, starting with
the root node and proceeding in a depth-first order. 

I would have expected these to work the same way. The first does *not* include
the root node in the iteration (it has no element), while the second does.

I think this was a wording mistake on the editor's part (that would be me), I
think they both should say "each element". There is an AARM note saying that the
"each element" wording was intended for A.18.10(153/3) -- the root node is not
visited by an iterator.

But there is no such note or evidence for the latter. In case there was some
reason for the difference, I'm mentioning it here rather than treating it as a
presentation mistake. (If we want to keep the difference, there surely ought to be
an AARM note mentioning it.)

Additional evidence for it being a mistake: A.18.10(159/3) says "each element" for
the Iterate_Subtree iterator.

****************************************************************