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