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

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

--- ai05s/ai05-0212-1.txt	2011/04/26 22:51:07	1.13
+++ ai05s/ai05-0212-1.txt	2011/06/19 02:29:35	1.14
@@ -1,6 +1,21 @@
-!standard A.18.2(9/2)                                  11-04-26  AI05-0212-1/10
+!standard 7.6(4/1)                                  11-06-18  AI05-0212-1/11
+!standard A.18.2(6/2)
+!standard A.18.2(8/2)
+!standard A.18.2(11/2)
+!standard A.18.2(34/2)
+!standard A.18.2(72/2)
+!standard A.18.2(74/2)
+!standard A.18.2(97/2)
+!standard A.18.2(147/2)
+!standard A.18.2(225/2)
+!standard A.18.2(226/2)
+!standard A.18.2(230/2)
+!standard A.18.2(252/2)
+!standard A.18.18(0)
 !standard A.18.33(0)
 !class Amendment 10-04-26
+!status Amendment 2012 11-06-18
+!status ARG Approved (by Letter Ballot) 9-0-2  11-05-16
 !status work item 11-04-26
 !status ARG Approved  8-0-0  11-03-17
 !status work item 10-04-26
@@ -36,22 +51,21 @@
 [This changes this to a Pure package, and drops "Remote_Types" (which is implicit
 in Pure).]
 
-Add the following with to each container package:
+Add the following with to each container package that has iterators:
 
    with Ada.Iterator_Interfaces;
 
 
 Modify the definition of the container types for each of the containers
-(with suitable substitutions for the names of types) as follows [note:
-Set does not have Variable_Indexing as it does not allow in-place
+that has a cursor (with suitable substitutions for the names of types) as follows
+[note: Set does not have Variable_Indexing as it does not allow in-place
 modification of elements]:
 
       type Vector is tagged private
-         with
-            Constant_Indexing => Constant_Reference,
-            Variable_Indexing => Reference,
-            Default_Iterator  => Iterate,
-            Iterator_Element  => Element_Type;
+         with Constant_Indexing => Constant_Reference,
+              Variable_Indexing => Reference,
+              Default_Iterator  => Iterate,
+              Iterator_Element  => Element_Type;
       pragma Preelaborable_Initialization(Vector);
 
 
@@ -66,17 +80,16 @@
 
 
 
-Add the following to each Ada.Containers package (other than the Queues packages)
-immediately after Update_Element (with suitable substitutions for the names of types):
+Add the following to each Ada.Containers package (other than the Queues packages,
+but including Indefinite_Holders) immediately after Update_Element (with suitable
+substitutions for the names of types):
 
     type Constant_Reference_Type (Element : not null access constant Element_Type) is
        private
-       with
-          Implicit_Dereference => Element;
+       with Implicit_Dereference => Element;
 
     type Reference_Type (Element : not null access Element_Type) is private
-       with
-          Implicit_Dereference => Element;
+       with Implicit_Dereference => Element;
 
 Constant_Reference_Type and Reference_Type need finalization.
 
@@ -97,9 +110,9 @@
     function Constant_Reference (Container : aliased in Vector; Position : in Cursor)
        return Constant_Reference_Type;
 
-This function (combined with the Constant_Indexing and Implicit_Dereference aspects)
-provides a convenient way to get read access to the individual elements of
-a container starting with a cursor.
+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 a cursor.
 
 If Position equals No_Element, then Constraint_Error is propagated; if Position
 does not designate an element in Container, then Program_Error is propagated.
@@ -111,9 +124,9 @@
     function Reference (Container : aliased in out Vector; Position : in Cursor)
        return Reference_Type;
 
-This function (combined with the Variable_Indexing and Implicit_Dereference aspects)
-provides a convenient way to get read and write access to the individual elements of
-a container starting with a cursor.
+This function (combined with the Variable_Indexing and Implicit_Dereference
+aspects) provides a convenient way to gain read and write access to the
+individual elements of a container starting with a cursor.
 
 If Position equals No_Element, then Constraint_Error is propagated; if Position
 does not designate an element in Container, then Program_Error is propagated.
@@ -130,9 +143,9 @@
     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 aspects)
-provides a convenient way to get read access to the individual elements of
-a container starting with an index value.
+This routine (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.
 
 If Index is not in the range First_Index (Container) .. Last_Index (Container),
 then Constraint_Error is propagated. Otherwise, Constant_Reference returns an object
@@ -143,9 +156,9 @@
     function Reference (Container : aliased in out Vector; Index : in Index_Type)
        return Reference_Type;
 
-This function (combined with the Variable_Indexing and Implicit_Dereference aspects)
-provides a convenient way to get read and write access to the individual elements of
-a container starting with an index value.
+This function (combined with the Variable_Indexing and Implicit_Dereference
+aspects) provides a convenient way to gain read and write access to the
+individual elements of a container starting with an index value.
 
 If Index is not in the range First_Index (Container) .. Last_Index (Container),
 then Constraint_Error is propagated. Otherwise, Reference returns an object whose
@@ -162,18 +175,18 @@
     function Constant_Reference (Container : aliased in Map; Key : in Key_Type)
        return Constant_Reference_Type;
 
-This routine (combined with the Constant_Indexing and Implicit_Dereference aspects)
-provides a convenient way to get read access to the individual elements of
-a container starting with a key value.
+This routine (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 a key value.
 
 Equivalent to Constant_Reference (Container, Find (Container, Key)).
 
     function Reference (Container : aliased in out Map; Key : in Key_Type)
        return Reference_Type;
 
-This function (combined with the Variable_Indexing and Implicit_Dereference aspects)
-provides a convenient way to get read and write access to the individual elements of
-a container starting with an key value.
+This function (combined with the Variable_Indexing and Implicit_Dereference
+aspects) provides a convenient way to gain read and write access to the
+individual elements of a container starting with an key value.
 
 Equivalent to Reference (Container, Find (Container, Key)).
 
@@ -187,8 +200,8 @@
        return Reference_Type;
 
 This function (combined with the Implicit_Dereference aspect)
-provides a convenient way to get read and write access to the individual elements of
-a container starting with an key value.
+provides a convenient way to gain read and write access to the individual
+elements of a container starting with an key value.
 
 If Position equals No_Element, then Constraint_Error is propagated; if Position
 does not designate an element in Container, then Program_Error is propagated.
@@ -205,7 +218,7 @@
        return Constant_Reference_Type;
 
 This routine (combined with the Implicit_Dereference aspect)
-provides a convenient way to get read access to the individual elements of
+provides a convenient way to gain read access to the individual elements of
 a container starting with a key value.
 
 Equivalent to Constant_Reference (Container, Find (Container, Key)).
@@ -214,7 +227,7 @@
        return Reference_Type;
 
 This function (combined with the Implicit_Dereference aspect)
-provides a convenient way to get read and write access to the individual elements of
+provides a convenient way to gain read and write access to the individual elements of
 a container starting with an key value.
 
 Equivalent to Reference_Preserving_Key (Container, Find (Container, Key)).
@@ -233,7 +246,7 @@
        return Constant_Reference_Type;
 
 This routine (combined with the Implicit_Dereference aspect)
-provides a convenient way to get read access to the contained element of
+provides a convenient way to gain read access to the contained element of
 a holder container.
 
 If Container is empty, Constraint_Error is propagated. Otherwise, Constant_Reference
@@ -245,7 +258,7 @@
     function Reference (Container : aliased in out Holder) return Reference_Type;
 
 This function (combined with the Implicit_Dereference aspects) provides a convenient
-way to get read and write access to the contained element of a holder container.
+way to gain read and write access to the contained element of a holder container.
 
 If Container is empty, Constraint_Error is propagated. Otherwise, Reference returns
 an object whose discriminant is an access value that designates the contained element.
@@ -259,15 +272,16 @@
 
    function Iterate (Container : in Vector) return Iterators.Reversible_Iterator'Class;
 
-      Iterate returns an object that can be used in a loop_statement to loop
-      with a loop parameter designating each node in Container, starting with
-      the first node and moving the cursor as per the Next function if the reserved word
-      *reverse* is not used in the iterator_specification, and starting
-      with the last node and moving the cursor as per the Previous function otherwise.
-      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 Container while the returned object exists. The returned
-      object from Iterate needs finalization.
+      Iterate returns a reversible iterator object that will generate a
+      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.
+      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
+      Container while the returned object exists. The returned object from
+      Iterate needs finalization.
 
 [Note: This wording will need to be adjusted for containers that don't have Next, like
 Maps. The wording will be parallel to that of the existing Iterate procedure.]
@@ -278,14 +292,15 @@
 
       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 an object that can be used in a loop_statement to loop
-      with a loop parameter designating each node in Container, starting with
-      the node designated by From and moving the cursor as per the Next function if the reserved word
-      *reverse* is not used in the iterator_specification, or moving the cursor as per the Previous
-      function otherwise. 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 Container while the returned object exists. The returned
-      object from Iterate needs finalization.
+      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
+      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
+      loop_statement whose iterator_specification denotes this object) tampers
+      with the cursors of Container while the returned object exists. The
+      returned object from Iterate needs finalization.
 
       AARM Note: Exits are allowed from the loops created using the iterator objects. In
       particular, to stop the iteration at a particalar cursor, just add
@@ -297,30 +312,31 @@
 
    function Iterate (Container : in Set) return Iterators.Forward_Iterator'Class;
 
-      Iterate returns an object that can be used in a loop_statement to loop
-      with a 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
-      with the cursors of Container while the returned object exists. The returned
-      object from Iterate needs finalization.
+      Iterate returns an iterator object that will generate a 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
+      with the cursors of Container while the returned object exists. The
+      returned object from Iterate needs finalization.
 
 
 Instead of the above, the Multiway_Tree containers would have:
 
    function Iterate (Container : in Tree) return Iterators.Forward_Iterator'Class;
 
-      Iterate returns an object that can be used in a loop_statement to loop
-      with a 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 of Container while the returned object exists. The returned
-      object from Iterate needs finalization.
+      Iterate returns an iterator object that will generate a 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
+      of Container while the returned object exists. The returned object from
+      Iterate needs finalization.
 
    function Iterate_Subtree (Position : in Cursor) return Iterators.Forward_Iterator'Class;
 
-      Iterate returns an object that can be used in a loop_statement to loop
-      with a loop parameter designating each element in the subtree rooted by the node designated by
+      Iterate 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
       propagated. Program_Error is propagated if any operation (in particular,
@@ -331,17 +347,18 @@
 
    function Iterate_Children (Container : in Tree; Parent : in Cursor) return Iterators.Reversible_Iterator'Class;
 
-      Iterate returns an object that can be used in a loop_statement to loop
-      with 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, if the reserved word *reverse* is not used in the
-      iterator_specification, the nodes are designated starting with the first child node and
-      moving the cursor as per the function Next_Sibling; if reserved word *reverse* is used, the
-      nodes are designated starting with the last child node and moving the cursor as per the
-      function Previous_Sibling. 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 Container while the returned object exists. The returned
-      object from Iterate needs finalization.
+      Iterate 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
+      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
+      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 Container while the returned object exists.
+      The returned object from Iterate needs finalization.
 
 Add the following to the Erroneous Execution section of each (unbounded) container package:
 
@@ -481,7 +498,7 @@
 end Shortest_Paths;
 
 
-Note that the effect of the Variable_Indexing aspect (on type Vector) and the
+Note that the effect of the Constant_Indexing aspect (on type Vector) and the
 Implicit_Dereference aspect (on type Reference_Type) is that
 
    G (Next)
@@ -516,7 +533,7 @@
             L : Adjacency_Lists.List renames G (Next);
             C : Adjacency_Lists.Cursor := L.First;
          begin
-            while C /= No_Element loop
+            while Has_Element (C) loop
                declare
                   E : Edge renames L(C).all;
                begin
@@ -817,7 +834,411 @@
 loop body to know where in the tree the element exists; the cursor form allows
 querying Depth, Parent, and many other useful functions.
 
+!corrigendum 7.6(4/2)
+
+@drepl
+@xcode<@b<package> Ada.Finalization @b<is>
+    @b<pragma> Preelaborate(Finalization);
+    @b<pragma> Remote_Types(Finalization);>
+@dby
+@xcode<@b<package> Ada.Finalization @b<is>
+    @b<pragma> Pure(Finalization);>
+
+!!corrigendum A.18.2(6/2)
+
+@drepl
+@xcode<@b<generic>
+   @b<type> Index_Type @b<is range> <@>;
+   @b<type> Element_Type @b<is private>;
+   @b<with function> "=" (Left, Right : Element_Type)
+      @b<return> Boolean @b<is> <@>;
+@b<package> Ada.Containers.Vectors @b<is>
+   @b<pragma> Preelaborate(Vectors);>
+@dby
+@xcode<@b<with> Ada.Iterator_Interfaces;
+@b<generic>
+   @b<type> Index_Type @b<is range> <@>;
+   @b<type> Element_Type @b<is private>;
+   @b<with function> "=" (Left, Right : Element_Type)
+      @b<return> Boolean @b<is> <@>;
+@b<package> Ada.Containers.Vectors @b<is>
+   @b<pragma> Preelaborate(Vectors);>
+
+!corrigendum A.18.2(8/2)
+
+@drepl
+@xcode<   @b<type> Vector @b<is tagged private>;
+   @b<pragma> Preelaborable_Initialization(Vector);>
+@drepl
+@xcode<   @b<type> Vector @b<is tagged private>
+      @b<with> Constant_Indexing =@> Constant_Reference,
+           Variable_Indexing =@> Reference,
+           Default_Iterator  =@> Iterate,
+           Iterator_Element  =@> Element_Type;
+   @b<pragma> Preelaborable_Initialization(Vector);>
+
+!corrigendum A.18.2(11/2)
+
+@dinsa
+@xcode<   No_Element : @b<constant> Cursor;>
+@dinss
+@xcode<   @b<function> Has_Element (Position : Cursor) @b<return> Boolean;
+
+   @b<package> Vector_Iterator_Interfaces @b<is new>
+       Ada.Iterator_Interfaces (Cursor, Has_Element);>
+
+!corrigendum A.18.2(34/2)
+
+@dinsa
+@xcode<   @b<procedure> Update_Element
+      (Container : @b<in out> Vector;
+       Position  : @b<in>     Cursor;
+       Process   : @b<not null access procedure>
+                           (Element : @b<in out> Element_Type));>
+@dinss
+@xcode<   @b<type> Constant_Reference_Type
+         (Element : @b<not null access constant> Element_Type) @b<is private>
+      @b<with> Implicit_Dereference =@> Element;
+
+   @b<type> Reference_Type (Element : @b<not null access> Element_Type) @b<is private>
+      @b<with> Implicit_Dereference =@> Element;
+
+   @b<function> Constant_Reference (Container : @b<aliased in> Vector; Index : @b<in> Index_Type)
+      @b<return> Constant_Reference_Type;
+
+   @b<function> Reference (Container : @b<aliased in out> Vector; Index : @b<in> Index_Type)
+      @b<return> Reference_Type;
+
+   @b<function> Constant_Reference (Container : @b<aliased in> Vector; Position : @b<in> Cursor)
+      @b<return> Constant_Reference_Type;
+
+   @b<function> Reference (Container : @b<aliased in out> Vector; Position : @b<in> Cursor)
+      @b<return> Reference_Type;>
+
+!corrigendum A.18.2(72/2)
+
+@ddel
+@xcode<   @b<function> Has_Element (Position : Cursor) @b<return> Boolean;>
+
+!corrigendum A.18.2(74/2)
+
+@dinsa
+@xcode<   @b<procedure> Reverse_Iterate
+     (Container : @b<in> Vector;
+      Process   : @b<not null access procedure> (Position : @b<in> Cursor));>
+@inss
+@xcode<   @b<function> Iterate (Container : @b<in> Vector) @b<return> Iterators.Reversible_Iterator'Class;>
+
+@xcode<   @b<function> Iterate (Container : @b<in> Vector; Start : @b<in> Cursor) @b<return> Iterators.Reversible_Iterator'Class;>
+
+!corrigendum A.18.2(97/2)
+
+@dinsa
+@xbullet<it replaces one or more elements of @i<V>, that is, it calls the Replace_Element,
+Reverse_Elements, or Swap procedures or the Sort or Merge procedures of an instance
+of Generic_Sorting with @i<V> as a parameter.>
+@dinss
+@xcode<@b<function> Has_Element (Position : Cursor) @b<return> Boolean;>
+
+@xindent<Returns True if Position designates an element, and returns False otherwise.>
+
+!corrigendum A.18.2(147/2)
+
+@dinsa
+@xindent<The element designated by Position is not an empty element after successful
+completion of this operation.>
+@dinss
+@xcode<@b<type> Constant_Reference_Type
+      (Element : @b<not null access constant> Element_Type) @b<is private>
+   @b<with> Implicit_Dereference =@> Element;>
+
+@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 default initialization of an object of type Constant_Reference_Type or Reference_Type
+propagates Program_Error.>
+
+@xcode<@b<function> Constant_Reference (Container : @b<aliased in> Vector; Index : @b<in> Index_Type)
+   @b<return> Constant_Reference_Type;>
+
+@xindent<This routine (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.>
+
+@xindent<If Index is not in the range First_Index (Container) .. Last_Index (Container),
+then Constraint_Error is propagated. Otherwise, Constant_Reference returns an object
+whose discriminant is an access value that designates the element at position Index.
+Program_Error is propagated if any operation tampers with the elements of Container
+while the object returned by Constant_Reference exists and has not been finalized.>
+
+@xcode<@b<function> Reference (Container : @b<aliased in out> Vector; Index : @b<in> Index_Type)
+   @b<return> Reference_Type;>
+
+@xindent<This function (combined with the Variable_Indexing and Implicit_Dereference
+aspects) provides a convenient way to gain read and write access to the
+individual elements of a container starting with an index value.>
+
+@xindent<If Index is not in the range First_Index (Container) .. Last_Index (Container),
+then Constraint_Error is propagated. Otherwise, Reference returns an object whose
+discriminant is an access value that designates the element at position Index.
+Program_Error is propagated if any operation tampers with the elements of Container
+while the object returned by Reference exists and has not been finalized.>
+
+@xindent<The element designated by Position is not an empty element after successful
+completion of this operation.>
+
+@xcode<@b<function> Constant_Reference (Container : @b<aliased in> Vector; Position : @b<in> Cursor)
+   @b<return> Constant_Reference_Type;>
+
+@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 a cursor.>
+
+@xindent<If Position equals No_Element, then Constraint_Error is propagated; if Position
+does not designate an element in Container, then Program_Error is propagated.
+Otherwise, Constant_Reference returns an object whose discriminant is an access
+value that designates the element designated by Position. Program_Error is propagated
+if any operation tampers with the elements of Container while the object returned
+by Constant_Reference exists and has not been finalized.>
+
+@xcode<@b<function> Reference (Container : @b<aliased in out> Vector; Position : @b<in> Cursor)
+   @b<return> Reference_Type;>
+
+@xindent<This function (combined with the Variable_Indexing and Implicit_Dereference
+aspects) provides a convenient way to gain read and write access to the
+individual elements of a container starting with a cursor.>
+
+@xindent<If Position equals No_Element, then Constraint_Error is propagated; if Position
+does not designate an element in Container, then Program_Error is propagated.
+Otherwise, Reference returns an object whose discriminant is an access value
+that designates the element designated by Position. Program_Error is propagated if
+any operation tampers with the elements of Container while the object returned
+by Reference exists and has not been finalized.>
+
+@xindent<The element designated by Position is not an empty element after successful
+completion of this operation.>
+
+!corrigendum A.18.2(225/2)
+
+@ddel
+@xcode<@b<function> Has_Element (Position : Cursor) @b<return> Boolean;>
+
+!corrigendum A.18.2(226/2)
+
+@ddel
+@xindent<Returns True if Position designates an element, and returns False otherwise.>
+
+!corrigendum A.18.2(230/2)
+
+@dinsa
+@xindent<Iterates over the elements in Container as per Iterate, except that elements
+are traversed in reverse index order.>
+@dinss
+@xcode<@b<function> Iterate (Container : @b<in> Vector) @b<return> Iterators.Reversible_Iterator'Class;>
+
+@xindent<Iterate returns a reversible iterator object that will generate a
+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.
+Program_Error is propagated if any operation (in
+particular, the @fa<sequence_of_statements> of the @fa<loop_statement> whose
+@fa<iterator_specification> denotes this object) tampers with the cursors of
+Container while the returned object exists. The returned object from
+Iterate needs finalization.>
+
+@xcode<@b<function> Iterate (Container : @b<in> Vector; Start : @b<in> Cursor) @b<return> Iterators.Reversible_Iterator'Class;>
+
+@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
+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
+@fa<loop_statement> whose @fa<iterator_specification> denotes this object) tampers
+with the cursors of Container while the returned object exists. The
+returned object from Iterate needs finalization.>
+
+!corrigendum A.18.2(252/2)
+
+@dinsa
+The result of "=" or Has_Element is unspecified if it is called with an invalid cursor parameter.
+Execution is erroneous if any other subprogram declared in Containers.Vectors is called with an
+invalid cursor parameter.
+@dinst
+Execution is erroneous if the vector associated with the result of a call to
+Reference or Constant_Reference is finalized before the result object returned
+by the call to Reference or Constant_Reference is finalized.
+
+
+
+
+
+!corrigendum A.18.18(0)
+
+@dinsc
+
+Force a conflict; the real text is in the conflict file.
+
+!corrigendum A.18.33(0)
+
+@dinsc
+
+The following example is an implementation of Dijkstra's shortest path algorithm in
+a directed graph with positive distances. The graph is represented by a map from nodes
+to sets of edges.
+
+@xcode<@b<with> Ada.Containers.Vectors;
+@b<with> Ada.Containers.Doubly_Linked_Lists;
+@b<use> Ada.Containers;
+@b<generic>
+   @b<type> Node @b<is range> <@>;
+@b<package> Shortest_Paths @b<is>
+   @b<type> Distance @b<is new> Float @b<range> 0.0 .. Float'Last;
+   @b<type> Edge @b<is record>
+      To, From : Node;
+      Length   : Distance;
+   @b<end record>;>
+
+@xcode<   @b<package> Node_Maps @b<is new> Vectors (Node, Node);
+   --  @i<@ft<The algorithm builds a map to indicate the node used to reach a given>>
+   --  @i<@ft<node in the shortest distance.>>>
+
+@xcode<   @b<package> Adjacency_Lists @b<is new> Doubly_Linked_Lists (Edge);
+   @b<use> Adjacency_Lists;>
+
+@xcode<   @b<package> Graphs @b<is new> Vectors (Node, Adjacency_Lists.List);>
+
+@xcode<   @b<package> Paths @b<is new> Doubly_Linked_Lists (Node);>
+
+@xcode<   @b<function> Shortest_Path
+     (G : Graphs.Vector; Source : Node; Target : Node) @b<return> Paths.List
+       @b<with> Pre =@> G (Source) /= Adjacency_Lists.Empty_List;>
+
+@xcode<@b<end> Shortest_Paths;>
+
+@xcode<@b<package body> Shortest_Paths @b<is>>
+
+@xcode<   @b<function> Shortest_Path
+     (G : Graphs.Vector; Source : Node; Target : Node) @b<return> Paths.List
+   @b<is>
+      @b<use> Adjacency_Lists, Node_Maps, Paths, Graphs;
+      Reached  : @b<array> (Node) @b<of> Boolean := (@b<others> =@> False);
+      --  @i<@ft<The set of nodes whose shortest distance to the source is known.>>>
+
+@xcode<      Reached_From : @b<array> (Node) @b<of> Node;
+      So_Far   : @b<array> (Node) @b<of> Distance := (@b<others> =@> Distance'Last);
+      The_Path : Paths.List := Paths.Empty_List;
+      Nearest_Distance : Distance;
+      Next     : Node;
+   @b<begin>
+      Reached (Source) := True;
+      So_Far (Source)  := 0.0;>
+
+@xcode<      @b<while not> Reached (Target) @b<loop>
+         Nearest_Distance := Distance'Last;>
+
+@xcode<         --  @i<@ft<Find closest node not reached yet, by iterating over all nodes.>>
+         --  @i<@ft<A more efficient algorithm uses a priority queue for this step.>>>
+
+@xcode<         Next := Source;
+         @b<for> N @b<in> Node'First .. Node'Last @b<loop>
+            @b<if not> Reached (N)
+              @b<and then> So_Far (N) < Nearest_Distance @b<then>
+                 Next := N;
+                 Nearest_Distance := So_Far (N);
+            @b<end if>;
+         @b<end loop>;>
+
+@xcode<         @b<if> Next = Source @b<then>  --  @i<@ft<No next node found, graph is not connected>>
+            @b<return> Paths.Empty_List;>
+
+@xcode<         @b<else>
+            Reached (Next) := True;
+         @b<end if>;>
+
+@xcode<         --  @i<@ft<Update minimum distance to newly reachable nodes.>>>
+
+@xcode<         @b<for> E @b<of> G (Next) @b<loop>
+            @b<if not> Reached (E.To) @b<then>
+               Nearest_Distance :=
+                 Distance'Min (So_Far (E.To) + So_Far (Next), So_Far (E.To));>
+
+@xcode<               @b<if> Nearest_Distance < So_Far (E.To) @b<then>
+                  Reached_From (E.To) := Next;
+                  So_Far (E.To) := Nearest_Distance;
+               @b<end if>;
+            @b<end if>;
+         @b<end loop>;
+      @b<end loop>;>
+
+@xcode<      --  @i<@ft<Rebuild path from target to source.>>>
+
+@xcode<      @b<declare>
+         N : Node := Target;
+      @b<begin>
+         @b<while> N /= Source @b<loop>
+            N := Reached_From (N);
+            Prepend (The_Path, N);
+         @b<end loop>;
+      @b<end>;>
+
+@xcode<      @b<return> The_Path;
+   @b<end>;
+@b<end> Shortest_Paths;>
+
+
+Note that the effect of the Constant_Indexing aspect (on type Vector) and the
+Implicit_Dereference aspect (on type Reference_Type) is that
+
+@xcode<G (Next)>
+
+is a convenient short hand for
+
+@xcode<G.Constant_Reference (Next).Element.@b<all>>
 
+Similarly, the effect of the loop:
+
+@xcode<@b<for> E @b<of> G (Next) @b<loop>
+   @b<if not> Reached (E.To) @b<then>
+      ...
+   @b<end if>;
+@b<end loop>;>
+
+is the same as:
+
+@xcode<@b<for> C @b<in> G (Next).Iterate @b<loop>
+   @b<declare>
+      E : Edge @b<renames> G (Next)(C).@b<all>;
+   @b<begin>
+      @b<if not> Reached (E.To) @b<then>
+         ...
+      @b<end if>;
+   @b<end>;
+@b<end loop>;>
+
+which is the same as:
+
+@xcode<@b<declare>
+   L : Adjacency_Lists.List @b<renames> G (Next);
+   C : Adjacency_Lists.Cursor := L.First;
+@b<begin>
+   @b<while> Has_Element (C) @b<loop>
+      @b<declare>
+         E : Edge @b<renames> L(C).@b<all>;
+      @b<begin>
+         @b<if not> Reached (E.To) @b<then>
+            ...
+         @b<end if>;
+      @b<end>;
+      C := L.Next (C);
+   @b<end loop>;
+@b<end>;>
+
 !ACATS test
 
 ACATS tests would be needed for these changes.
@@ -1570,5 +1991,311 @@
 
 That's right, I wanted to make sure that I had a version that compiled. I'm
 happy to have the more Ada2012 version of course.
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Monday, May  2, 2011  9:44 PM
+
+[The appropriate part of a longer message - Editor]
+
+AI05-0212-1/10  Accessors and Iterators for Ada.Containers
+    [The only change is to use Has_Element rather than No_Element in the iterator instances.]
+    Approve ___X___ Disapprove ______ Abstain _______
+   Comments:
+     This aspect_specification does not match the recommended formatting:
+      type Reference_Type (Element : not null access Element_Type) is private
+        with
+           Implicit_Dereference => Element
+     It should be simply:
+      type Reference_Type (Element : not null access Element_Type) is private
+        with Implicit_Dereference => Element
+     It also means one less line in the RM for each such declaration.
+
+     It is a bit unclear whether the following paragraph (and similar ones) are
+     intended to be in the RM, or if it is a "meta" comment in the AI:
+       This function (combined with the Constant_Indexing and Implicit_Dereference
+       aspects) provides a convenient way to get read access to the individual
+       elements of a container starting with a cursor.
+     If it is to be in the RM, then "get read access" would be better expressed
+     as "gain read access" I believe.  Also, it is tedious to see this same
+     paragraph over and over.  Can't we just have a single user NOTE somewhere
+     explaining the purpose of these operations?
+
+     Can we simplify this repeated wording: "Iterate returns an object that can
+     be used in a loop_statement to loop with a loop parameter designating each
+     node in Container"?  How about just saying "Iterate returns a container
+     element iterator for Container" or something like that?
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Monday, May  2, 2011  10:32 PM
+
+[The appropriate part of a longer message - Editor]
+
+> AI05-0212-1/10  Accessors and Iterators for Ada.Containers
+>     [The only change is to use Has_Element rather than No_Element in
+> the iterator instances.]
+>     Approve ___X___ Disapprove ______ Abstain _______
+>    Comments:
+...
+>      It is a bit unclear whether the following paragraph (and similar ones) are
+>      intended to be in the RM, or if it is a "meta" comment in the AI:
+>        This function (combined with the Constant_Indexing and Implicit_Dereference
+>        aspects) provides a convenient way to get read access to the individual
+>        elements of a container starting with a cursor.
+>      If it is to be in the RM, then "get read access" would be better expressed
+>      as "gain read access" I believe.  Also, it is tedious to see this same
+>      paragraph over and over.  Can't we just have a single user NOTE somewhere
+>      explaining the purpose of these operations?
+
+The intent is that the container definitions are expected to be mostly referred
+to in a reference fashion. Thus we have generally put each note (AARM and User)
+in each clause (since we don't expect people to read the Vectors in order to
+understand the Lists).
+
+And it was intended to put this text in the RM, because otherwise the purpose of
+these functions is very mysterious. And remember that there are only two of
+these per container; the repetition is much more obvious in this AI where they
+are all lumped together.
+
+It might make sense to try to combine the note for both routines (so it doesn't
+have to be repeated on the second one), but an obvious way to do that doesn't
+jump out at me (since the indexing aspects differ for the two routines).
+
+>      Can we simplify this repeated wording: "Iterate returns an object that can
+>      be used in a loop_statement to loop with a loop parameter designating each
+>      node in Container"?  How about just saying "Iterate returns a container element
+>      iterator for Container" or something like that?
+
+This wording was designed to be as close as possible to the existing Iterator,
+thus we get the part about "designating each node in Container". The rest of it
+is just to make that part make sense. I definitely don't want to say *less*
+about that here, especially as this is the only text that specifies what cursors
+are returned, and in what order. That had better be specified somewhere! If you
+have a better suggestion that includes that text (which I don't want to have to
+reorganize or reword, because that is very likely to be full of errors), I'd be
+glad to hear it.
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Tuesday, May  3, 2011  7:44 AM
+
+[The appropriate part of a longer message - Editor]
+
+>>       Can we simplify this repeated wording: "Iterate returns an object that can
+>>       be used in a loop_statement to loop with a loop parameter designating each
+>>       node in Container"?  How about just saying "Iterate returns a container element
+>>       iterator for Container" or something like that?
+>
+> This wording was designed to be as close as possible to the existing
+> Iterator, thus we get the part about "designating each node in Container".
+> The rest of it is just to make that part make sense. I definitely
+> don't want to say *less* about that here, especially as this is the
+> only text that specifies what cursors are returned, and in what order.
+> That had better be specified somewhere! If you have a better
+> suggestion that includes that text (which I don't want to have to
+> reorganize or reword, because that is very likely to be full of errors), I'd be glad to hear it.
+
+I was suggesting using the term "container element iterator" which is defined in
+the Iterator AI.  I see no reason to repeat the definition of an container
+element iterator, though of course a "see 5.5.1" might be helpful.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Tuesday, May  3, 2011  5:33 PM
+
+[The appropriate part of a longer message - Editor]
+
+> >> ... AI05-0212-1/10  Accessors and Iterators for Ada.Containers
+...
+> >>       Can we simplify this repeated wording: "Iterate returns an object
+> >>       that can be used in a loop_statement to loop with a loop parameter
+> >>       designating each node in Container"?  How about just saying "Iterate
+> >>       returns a container element
+> >>       iterator for Container" or something like that?
+> >
+> > This wording was designed to be as close as possible to the existing
+> > Iterator, thus we get the part about "designating each node in Container".
+> > The rest of it is just to make that part make sense. I definitely
+> > don't want to say *less* about that here, especially as this is the
+> > only text that specifies what cursors are returned, and in what order.
+> > That had better be specified somewhere! If you have a better
+> > suggestion that includes that text (which I don't want to have to
+> > reorganize or reword, because that is very likely to be full of
+> > errors), I'd be glad to hear it.
+>
+> I was suggesting using the term "container element iterator"
+> which is defined in the Iterator AI.  I see no reason to repeat the
+> definition of an container element iterator, though of course a "see
+> 5.5.1" might be helpful.
+
+Well, we have to define which elements are returned and in what order. 5.5.1 and
+5.5.2 provides no guidance there (and it can't, since these are general
+concepts). Remember that the actual type of the iterator is not defined here and
+thus the routines used to implement it aren't known either. (There is nothing
+requiring that the iterator Next does the same thing as the container Next, and
+that's rather important.)
+
+A second point is that this is a function returning an "iterator object". That
+object can be used in the first form of iterator (I'm reading the definitions in
+5.5.1 and 5.5.2.) Some of these functions are also used to provide the object
+for the default "container element iterator" (for the third form), but that is a
+secondary purpose. (And not all of them provide "container element iterator"s at
+all.)
+
+Remember that the first form allows one to iterate through the cursors of a
+container, the third form allows one to iterate through the elements of a
+container. You can get elements given a cursor, but you can't get cursors given
+elements, so the first form is more general. And this text is talking about the
+first form (if you are using the third form, you would not call this function
+explicitly).
+
+So I think your suggestion is just plain wrong. I can imagine simplifying this
+text somehow, but it doesn't have anything to do with a "container element
+iterator".
+
+The text currently is:
+
+Iterate returns an object that can be used in a loop_statement to loop with a
+loop parameter designating each node in Container, starting with the first node
+and moving the cursor as per the Next function if the reserved word *reverse* is
+not used in the iterator_specification, and starting with the last node and
+moving the cursor as per the Previous function otherwise.
+
+We could try to eliminate some small parts of this using more terminology from
+139-2, but we need most of it. In particular, we could say that the function
+returns an "iterator object (see 5.5.1)", when used in a "generalized iterator
+(see 5.5.2)", and describe the semantics for "forward iterators" and "reverse
+iterators". That would look something like:
+
+Iterate returns an iterator object (see 5.5.1) that can be used in a generalized
+iterator (see 5.5.2) causing the loop parameter to designate each node in
+Container, starting with the first node and moving the cursor as per the Next
+function if used as a forward iterator, and starting with the last node and
+moving the cursor as per the Previous function if used as a reverse iterator.
+
+I'm not sure this is a huge improvement, as we still have to mention the
+loop_statement in the tampering check text which follows this. But it does use
+the defined terminology. (I didn't use that originally because I thought you
+were going to get rid of a lot of it, as much of it never seems to be used.
+Maybe you're just trying to justify that work. ;-)
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Tuesday, May  3, 2011  6:59 PM
+
+> Iterate returns an iterator object (see 5.5.1) that can be used in a
+> generalized iterator (see 5.5.2) causing the loop parameter to
+> designate each node in Container, starting with the first node and
+> moving the cursor as per the Next function if used as a forward
+> iterator, and starting with the last node and moving the cursor as per
+> the Previous function if used as a reverse iterator.
+
+I don't think we need to say "that can be used in a generalized iterator causing
+the loop parameter" since that is all implicit in the definition of iterator
+object.  How about something like this:
+
+    Iterate returns a reversible iterator object (see 5.5.1) representing the
+    sequence of all nodes of the Container, with First, Next, Last, and Previous
+    corresponding to the same-named operations of this package.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Wednesday, May  4, 2011  2:47 PM
+
+That would work for the most of the basic iterators (modulo dealing with the
+iterators that aren't reversible), but it wouldn't work for the new ones that
+include a starting position. We don't have any existing functions that would
+return that would return that start position, so talking about First and Last
+would be very confusing. It also wouldn't work for the full tree ones, which
+just say "depth-first order"; there are no existing functions that will directly
+produce that order (you need a combination and a stack of some sort [or
+recursion, which can't be used in the Iterator object for obvious reasons]).
+
+I was trying to write wording that would change the existing iterator text as
+little as possible, rather than discarding it completely and starting over (with
+the certain set of bugs that will be introduced). Maybe that wasn't a worthy
+goal, but I don't see how to fit all of the iterators into the form you are
+proposing. (The AI has six different templates for Iterator text, I need to be
+able to change them all.)
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Wednesday, May  4, 2011  3:01 PM
+
+It just feels that we should be able to say what an iterator represents without
+a whole paragraph, especially if they are going to be used regularly.  An
+iterator represents a sequence of elements.  If "reverse" is present, then the
+sequence is processed from last to first, otherwise it is processed from first
+to last, but it is still just a single sequence. I would like us to be able to
+describe that sequence (e.g. is a depth-first walk of the nodes) and not say a
+whole lot more.  We shouldn't have to mention First, Next, Last, and Previous at
+all ideally.  We should just define the sequence, and have everything else be
+common semantics, which we define in just one place.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, May  5, 2011  2:07 PM
+
+> It just feels that we should be able to say what an iterator
+> represents without a whole paragraph, especially if they are going to
+> be used regularly.  An iterator represents a sequence of elements.  If
+> "reverse"
+> is present, then the sequence is processed from last to first,
+> otherwise it is processed from first to last, but it is still just a
+> single sequence.
+
+You are overspecifying what an iterator itself does. All it says is that a
+series of cursors will be presented in some order with some starting cursor.
+That order is defined by the specific iterator type, and all I'm trying to do is
+ensure that that order is well-defined.
+
+In particular, there is absolutely no requirement that an iterator "processes
+from first to last". It does whatever it is defined to do, limited only by the
+cleverness of the implementers! There is no concept of "first to last" for a
+depth first order, and it would be fine to have an iterator that processed in a
+random order.
+
+> I would like us to be able to describe that sequence (e.g. is a
+> depth-first walk of the nodes) and not say a whole lot more.
+
+That's fine and that's what I'm proposing.
+
+> We shouldn't have to mention First, Next, Last, and Previous at all
+> ideally.
+
+And we wouldn't for the trees, because the order is defined somewhere else.
+Your problem here is that you are looking at the wording for the Vector and the
+List, which is the most complex of all, and thinking that is the way they all
+will look.
+
+Neither Vectors nor Lists have much defined about ordering; pretty much
+everything is written in terms of using Next to find the next element.
+
+Clearly, we could rewrite all of this text to talk about starting at the first
+node and proceeding by successors -- but is that really helping anything?? And
+if we change this, we also have to change the existing iterator description (it
+needs to be consistent - it should be crystal clear that you can convert one to
+the other).
+
+This seems to me to be an exercise in churn; nothing will be shorter or more
+understandable, it will just be different.
+
+> We should just define the sequence,
+> and have everything else be common semantics, which we define in just
+> one place.
+
+Well, that doesn't make any sense, because the sequence itself would have to
+defined individually for each container, that hardly is "one place". And if we
+did define the sequence separately from the iterators, that is only going to
+save about one sentence total in the RM. Is that really worth it??
 
 ****************************************************************

Questions? Ask the ACAA Technical Agent