CVS difference for 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