CVS difference for ai05s/ai05-0212-1.txt

Differences between 1.17 and version 1.18
Log of other versions for file ai05s/ai05-0212-1.txt

--- ai05s/ai05-0212-1.txt	2011/09/29 06:34:02	1.17
+++ ai05s/ai05-0212-1.txt	2011/10/21 06:42:22	1.18
@@ -1,4 +1,4 @@
-!standard 7.6(4/1)                                  11-09-26  AI05-0212-1/13
+!standard 7.6(4/1)                                  11-10-12  AI05-0212-1/14
 !standard A.18.2(6/2)
 !standard A.18.2(8/2)
 !standard A.18.2(11/2)
@@ -146,7 +146,7 @@
     type Reference_Type (Element : not null access Element_Type) is private
        with Implicit_Dereference => Element;
 
-Constant_Reference_Type and Reference_Type need finalization.
+The types Constant_Reference_Type and Reference_Type need finalization.
 
 The default initialization of an object of type Constant_Reference_Type or Reference_Type
 propagates Program_Error.
@@ -200,7 +200,7 @@
     function Constant_Reference (Container : aliased in Vector; Index : in Index_Type)
        return Constant_Reference_Type;
 
-This routine (combined with the Constant_Indexing and Implicit_Dereference
+This function (combined with the Constant_Indexing and Implicit_Dereference
 aspects) provides a convenient way to gain read access to the individual
 elements of a container starting with an index value.
 
@@ -337,8 +337,8 @@
    function Iterate (Container : in Vector)
       return Vector_Iterator_Interfaces.Reversible_Iterator'Class;
 
-      Iterate returns a reversible iterator object that will generate a
-      loop parameter designating each node in Container, starting with
+      Iterate returns a reversible iterator object that will generate a value for
+      the loop parameter designating each node in Container, starting with
       the first node and moving the cursor as per the Next function when
       used as a forward iterator, and starting with the last node and moving
       the cursor as per the Previous function when used as a reverse iterator.
@@ -359,8 +359,8 @@
       If Start is not No_Element and does not designate an item in Container, then Program_Error
       is propagated. If Start is No_Element, the call is equivalent to Iterate (Container).
       Otherwise, Iterate returns a reversible iterator object that will generate
-      a loop parameter designating each node in Container, starting with the
-      node designated by From and moving the cursor as per the Next function
+      a value for the loop parameter designating each node in Container, starting with the
+      node designated by Start and moving the cursor as per the Next function
       when used as a forward iterator, or moving the cursor as per the Previous
       function when used as a reverse iterator. Program_Error is propagated if
       any operation (in particular, the sequence_of_statements of the
@@ -379,8 +379,8 @@
 
    function Iterate (Container : in Set) return Set_Iterator_Interfaces.Forward_Iterator'Class;
 
-      Iterate returns an iterator object that will generate a loop parameter
-      designating each node in Container, starting with the first node and
+      Iterate returns an iterator object that will generate a value for the loop
+      parameter designating each node in Container, starting with the first node and
       moving the cursor as per the Next function. Program_Error is propagated if
       any operation (in particular, the sequence_of_statements of the
       loop_statement whose iterator_specification denotes this object) tampers
@@ -393,8 +393,8 @@
    function Iterate (Container : in Tree)
       return Tree_Iterator_Interfaces.Forward_Iterator'Class;
 
-      Iterate returns an iterator object that will generate a loop parameter
-      designating each node in Container, starting with the root node and
+      Iterate returns an iterator object that will generate a value for the loop
+      parameter designating each node in Container, starting with the root node and
       proceeding in a depth-first order. Program_Error is propagated if any
       operation (in particular, the sequence_of_statements of the loop_statement
       whose iterator_specification denotes this object) tampers with the cursors
@@ -404,10 +404,10 @@
    function Iterate_Subtree (Position : in Cursor)
       return Tree_Iterator_Interfaces.Forward_Iterator'Class;
 
-      Iterate_Subtree returns an iterator object that will generate a loop parameter
-      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
+      Iterate_Subtree returns an iterator object that will generate a value for the
+      loop parameter 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. Program_Error is propagated if any operation (in particular,
       the sequence_of_statements of the loop_statement whose iterator_specification denotes
       this object) tampers with the cursors of the container in which the node designated by Position
@@ -417,10 +417,10 @@
       return Tree_Iterator_Interfaces.Reversible_Iterator'Class;
 
       Iterate_Children returns a reversible iterator object that will generate a
-      loop parameter designating each child node of Parent. If Parent equals
-      No_Element, then Constraint_Error is propagated. If Parent does not designate a node in Container, then
-      Program_Error is propagated. Otherwise, when used as a forward iterator,
-      the nodes are designated starting with the first child node and
+      value for the loop parameter designating each child node of Parent. If Parent
+      equals No_Element, then Constraint_Error is propagated. If Parent does not designate
+      a node in Container, then Program_Error is propagated. Otherwise, when used as
+      a forward iterator, the nodes are designated starting with the first child node and
       moving the cursor as per the function Next_Sibling; when used as a reverse
       iterator, the nodes are designated starting with the last child node and
       moving the cursor as per the function Previous_Sibling. Program_Error is
@@ -446,6 +446,12 @@
 reason we have to say this for invalid cursors.)
 
 
+Modify A.18.2(230/2), A.18.3(143/2), A.18.6(94/2), and A.18.9(113/2):
+"... as per {procedure} Iterate, ..."
+[Necessary as we are now adding Iterate functions, and this would then be ambiguous
+without the clarification.]
+
+
 For each bounded container, delete AARM implementation note that says:
 
 Package Containers.Bounded_Vectors cannot depend on package Ada.Finalization (because that
@@ -1030,7 +1036,7 @@
 @xcode<@b<type> Reference_Type (Element : @b<not null access> Element_Type) @b<is private>
    @b<with> Implicit_Dereference =@> Element;>
 
-@xindent<Constant_Reference_Type and Reference_Type need finalization.>
+@xindent<The types Constant_Reference_Type and Reference_Type need finalization.>
 
 @xindent<The default initialization of an object of type Constant_Reference_Type or Reference_Type
 propagates Program_Error.>
@@ -1039,7 +1045,7 @@
                                         Index     : @b<in> Index_Type)
    @b<return> Constant_Reference_Type;>
 
-@xindent<This routine (combined with the Constant_Indexing and Implicit_Dereference
+@xindent<This function (combined with the Constant_Indexing and Implicit_Dereference
 aspects) provides a convenient way to gain read access to the individual
 elements of a container starting with an index value.>
 
@@ -1111,15 +1117,18 @@
 
 !corrigendum A.18.2(230/2)
 
-@dinsa
+@drepl
 @xindent<Iterates over the elements in Container as per Iterate, except that elements
 are traversed in reverse index order.>
-@dinss
+@ddy
+@xindent<Iterates over the elements in Container as per procedure Iterate, except
+that elements are traversed in reverse index order.>
+
 @xcode<@b<function> Iterate (Container : @b<in> Vector)
    @b<return> Vector_Iterator_Interfaces.Reversible_Iterator'Class;>
 
 @xindent<Iterate returns a reversible iterator object that will generate a
-loop parameter designating each node in Container, starting with
+value for the loop parameter designating each node in Container, starting with
 the first node and moving the cursor as per the Next function when
 used as a forward iterator, and starting with the last node and moving
 the cursor as per the Previous function when used as a reverse iterator.
@@ -1135,8 +1144,8 @@
 @xindent<If Start is not No_Element and does not designate an item in Container, then Program_Error
 is propagated. If Start is No_Element, the call is equivalent to Iterate (Container).
 Otherwise, Iterate returns a reversible iterator object that will generate
-a loop parameter designating each node in Container, starting with the
-node designated by From and moving the cursor as per the Next function
+a value for the loop parameter designating each node in Container, starting with the
+node designated by Start and moving the cursor as per the Next function
 when used as a forward iterator, or moving the cursor as per the Previous
 function when used as a reverse iterator. Program_Error is propagated if
 any operation (in particular, the @fa<sequence_of_statements> of the
@@ -1275,7 +1284,7 @@
 @xcode<@b<type> Reference_Type (Element : @b<not null access> Element_Type) @b<is private>
    @b<with> Implicit_Dereference =@> Element;>
 
-@xindent<Constant_Reference_Type and Reference_Type need finalization.>
+@xindent<The types Constant_Reference_Type and Reference_Type need finalization.>
 
 @xindent<The default initialization of an object of type Constant_Reference_Type or Reference_Type
 propagates Program_Error.>
@@ -1322,15 +1331,18 @@
 
 !corrigendum A.18.3(144/2)
 
-@dinsa
+@drepl
 @xindent<Iterates over the elements in Container as per Iterate, except that elements
 are traversed in reverse index order.>
-@dinss
+@dby
+@xindent<Iterates over the elements in Container as per procedure Iterate, except that
+elements are traversed in reverse index order.>
+
 @xcode<@b<function> Iterate (Container : @b<in> List)
    @b<return> List_Iterator_Interfaces.Reversible_Iterator'Class;>
 
 @xindent<Iterate returns a reversible iterator object that will generate a
-loop parameter designating each node in Container, starting with
+value for the loop parameter designating each node in Container, starting with
 the first node and moving the cursor as per the Next function when
 used as a forward iterator, and starting with the last node and moving
 the cursor as per the Previous function when used as a reverse iterator.
@@ -1346,8 +1358,8 @@
 @xindent<If Start is not No_Element and does not designate an item in Container, then Program_Error
 is propagated. If Start is No_Element, the call is equivalent to Iterate (Container).
 Otherwise, Iterate returns a reversible iterator object that will generate
-a loop parameter designating each node in Container, starting with the
-node designated by From and moving the cursor as per the Next function
+a value for the loop parameter designating each node in Container, starting with the
+node designated by Start and moving the cursor as per the Next function
 when used as a forward iterator, or moving the cursor as per the Previous
 function when used as a reverse iterator. Program_Error is propagated if
 any operation (in particular, the @fa<sequence_of_statements> of the
@@ -1390,7 +1402,7 @@
 @xcode<@b<type> Reference_Type (Element : @b<not null access> Element_Type) @b<is private>
    @b<with> Implicit_Dereference =@> Element;>
 
-@xindent<Constant_Reference_Type and Reference_Type need finalization.>
+@xindent<The types Constant_Reference_Type and Reference_Type need finalization.>
 
 @xindent<The default initialization of an object of type Constant_Reference_Type or Reference_Type
 propagates Program_Error.>
@@ -1575,7 +1587,7 @@
    @b<return> Map_Iterator_Interfaces.Forward_Iterator'Class;>
 
 @xindent<Iterate returns an iterator object that will generate a
-loop parameter designating each node in Container, starting with
+value for the loop parameter designating each node in Container, starting with
 the first node and and moving the cursor according to the successor relation.
 Program_Error is propagated if any operation (in
 particular, the @fa<sequence_of_statements> of the @fa<loop_statement> whose
@@ -1678,15 +1690,18 @@
 
 !corrigendum A.18.6(94/2)
 
-@dinsa
+@drepl
 @xindent<Iterates over the elements in Container as per Iterate, except that elements
 are traversed in predecessor order, starting with the last node.>
-@dinss
+@dby
+@xindent<Iterates over the elements in Container as per procedure Iterate, except
+that elements are traversed in predecessor order, starting with the last node.>
+
 @xcode<@b<function> Iterate (Container : @b<in> Map)
    @b<return> Map_Iterator_Interfaces.Reversible_Iterator'Class;>
 
 @xindent<Iterate returns a reversible iterator object that will generate a
-loop parameter designating each node in Container, starting with
+value for the loop parameter designating each node in Container, starting with
 the first node and moving the cursor according to the successor relation when
 used as a forward iterator, and starting with the last node and moving
 the cursor according to the predecessor relation when used as a reverse iterator.
@@ -1720,7 +1735,7 @@
       (Element : @b<not null access constant> Element_Type) @b<is private>
    @b<with> Implicit_Dereference =@> Element;>
 
-@xindent<Constant_Reference_Type needs finalization.>
+@xindent<The type Constant_Reference_Type needs finalization.>
 
 @xindent<The default initialization of an object of type Constant_Reference_Type 
 propagates Program_Error.>
@@ -1760,7 +1775,7 @@
 @xcode<@b<type> Reference_Type (Element : @b<not null access> Element_Type) @b<is private>
    @b<with> Implicit_Dereference =@> Element;>
 
-@xindent<Reference_Type needs finalization.>
+@xindent<The type Reference_Type needs finalization.>
 
 @xindent<The default initialization of an object of type Reference_Type
 propagates Program_Error.>
@@ -1924,7 +1939,7 @@
    @b<return> Map_Iterator_Interfaces.Forward_Iterator'Class;>
 
 @xindent<Iterate returns an iterator object that will generate a
-loop parameter designating each element in Container, starting with
+value for the loop parameter designating each element in Container, starting with
 the first element and and moving the cursor according to the successor relation.
 Program_Error is propagated if any operation (in
 particular, the @fa<sequence_of_statements> of the @fa<loop_statement> whose
@@ -2031,15 +2046,18 @@
 
 !corrigendum A.18.9(113/2)
 
-@dinsa
+@drepl
 @xindent<Iterates over the elements in Container as per Iterate, except that elements
 are traversed in predecessor order, starting with the last element.>
-@dinss
+@dby
+@xindent<Iterates over the elements in Container as per procedure Iterate, except
+that elements are traversed in predecessor order, starting with the last element.>
+
 @xcode<@b<function> Iterate (Container : @b<in> Set)
    @b<return> Map_Iterator_Interfaces.Reversible_Iterator'Class;>
 
 @xindent<Iterate returns a reversible iterator object that will generate a
-loop parameter designating each element in Container, starting with
+value for the loop parameter designating each element in Container, starting with
 the first element and moving the cursor according to the successor relation when
 used as a forward iterator, and starting with the last element and moving
 the cursor according to the predecessor relation when used as a reverse iterator.
@@ -3318,5 +3336,68 @@
 have an "Is_Empty" bit with every element of a definite type. That seemed like
 overkill, especially for small elements like characters. If no exception is
 raised, the element must have a normal (but possibly invalid) value.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, October 13, 2011  12:20 AM
+
+Brad had in his review:
+
+> 14) A.18.2(230.2/3, 230.4/3) "will generate a loop parameter" 
+> How can Iterate "generate" a loop parameter. 
+> A loop parameter is a declaration. To generate one, it requires 
+> someone to type the declaration in a text editor. I think "generate" 
+> is the wrong choice of word.
+
+[He then goes on to repeat this comment a dozen more times, just in case I missed
+it the first time. :-)]
+
+This is really talking about the different values that the loop parameter will
+take on; the iterator "generates" those values. That's still the best word I can
+think of to describe what's going on.
+
+I do agree that "loop parameter" by itself is confusing, it really talking about
+the values that the parameter will have.
+
+So let's start with the original wording:
+
+Iterate returns a reversible iterator object that will generate a loop parameter
+designating each node in Container, ...
+
+[the "..." here describes the order the values are provided, and it is different
+for each iterator function; I want to concentrate on the common part so I don't
+just move the bump around.]
+
+The easiest fix is just to insert "value":
+
+Iterate returns a reversible iterator object that will generate a loop parameter {value}
+designating each node in Container, ...
+
+or reordering:
+
+Iterate returns a reversible iterator object that will generate a {value of the}
+loop parameter designating each node in Container, ...
+
+This is still a bit dicey, in that when the default iterator is used in the "of"
+form, the loop parameter is the element, not the cursor designating, but given
+the equivalence of the forms it should be OK.
+
+So, is this enough or is there some other change that would fix this problem??
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Thursday, October 13, 2011  12:31 AM
+
+I agree with "... will generate a value of the loop parameter"
+or perhaps "... will generate a value for the loop parameter ..."
+
+****************************************************************
+
+From: Brad Moore
+Sent: Thursday, October 13, 2011  8:05 AM
+
+I am also happy with either of these though I think "for" is marginally better than "of".
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent