Version 1.4 of ai12s/ai12-0069-1.txt

Unformatted version of ai12s/ai12-0069-1.txt version 1.4
Other versions for file ai12s/ai12-0069-1.txt

!standard A.18.10(153/3)          13-10-07 AI12-0069-1/02
!standard A.18.10(155/3)
!standard A.18.10(157/3)
!standard A.18.10(159/3)
!class binding interpretation 13-05-30
!status Amendment 202x 13-07-11
!status ARG Approved 9-0-0 13-06-14
!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(153/3) and A.18.10(157/3):
"...starting {from}[with] the root node and proceeding..."
Modify A.18.10(155/3) and A.18.10(159/3):
"...starting {from}[with] the node designated by Position and proceeding..."
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 attempting to access the element raises an exception).
Thus we change the wording to say "each element" rather than "each node".
In looking at this, it was noted that the wording says "starting with the root node", which is misleading as the root node will never be returned. As such, we change the wording to "starting from the root node", in all of these iterators. This change includes the subtree iterators, as they could be passed a cursor to the root node.
!corrigendum A.18.10(153/3)
Replace the paragraph:
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. Tampering with the cursors of Container is prohibited during the execution of a call on Process.all. Any exception raised by Process.all is propagated.
by:
Iterate calls Process.all with a cursor that designates each element in Container, starting from the root node and proceeding in a depth-first order. Tampering with the cursors of Container is prohibited during the execution of a call on Process.all. Any exception raised by Process.all is propagated.
!corrigendum A.18.10(155/3)
Replace the paragraph:
If Position equals No_Element, then Constraint_Error is propagated. Otherwise, Iterate_Subtree calls Process.all with a cursor that designates each element in the subtree rooted by the node designated by Position, starting with the node designated by Position and proceeding in a depth-first order. Tampering with the cursors of the tree that contains the element designated by Position is prohibited during the execution of a call on Process.all. Any exception raised by Process.all is propagated.
by:
If Position equals No_Element, then Constraint_Error is propagated. Otherwise, Iterate_Subtree calls Process.all with a cursor that designates each element in the subtree rooted by the node designated by Position, starting from the node designated by Position and proceeding in a depth-first order. Tampering with the cursors of the tree that contains the element designated by Position is prohibited during the execution of a call on Process.all. Any exception raised by Process.all is propagated.
!corrigendum A.18.10(157/3)
Replace the paragraph:
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. Tampering with the cursors of Container is prohibited while the iterator object exists (in particular, in the sequence_of_statements of the loop_statement whose iterator_specification denotes this object). The iterator object needs finalization.
by:
Iterate returns an iterator object (see 5.5.1) that will generate a value for a loop parameter (see 5.5.2) designating each element in Container, starting from the root node and proceeding in a depth-first order. Tampering with the cursors of Container is prohibited while the iterator object exists (in particular, in the sequence_of_statements of the loop_statement whose iterator_specification denotes this object). The iterator object needs finalization.
!corrigendum A.18.10(159/3)
Replace the paragraph:
If Position equals No_Element, then Constraint_Error is propagated. Otherwise, Iterate_Subtree returns an iterator object (see 5.5.1) that will generate a value for a loop parameter (see 5.5.2) designating each element in the subtree rooted by the node designated by Position, starting with the node designated by Position and proceeding in a depth-first order. If Position equals No_Element, then Constraint_Error is propagated. Tampering with the cursors of the container that contains the node designated by Position is prohibited while the iterator object exists (in particular, in the sequence_of_statements of the loop_statement whose iterator_specification denotes this object). The iterator object needs finalization.
by:
If Position equals No_Element, then Constraint_Error is propagated. Otherwise, Iterate_Subtree returns an iterator object (see 5.5.1) that will generate a value for a loop parameter (see 5.5.2) designating each element in the subtree rooted by the node designated by Position, starting from the node designated by Position and proceeding in a depth-first order. If Position equals No_Element, then Constraint_Error is propagated. Tampering with the cursors of the container that contains the node designated by Position is prohibited while the iterator object exists (in particular, in the sequence_of_statements of the loop_statement whose iterator_specification denotes this object). The iterator object needs finalization.
!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.

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


Questions? Ask the ACAA Technical Agent