CVS difference for ai05s/ai05-0212-1.txt
--- ai05s/ai05-0212-1.txt 2011/01/23 04:37:32 1.2
+++ ai05s/ai05-0212-1.txt 2011/01/29 02:18:54 1.3
@@ -1,4 +1,4 @@
-!standard A.18.2(9/2) 11-01-22 AI05-0212-1/02
+!standard A.18.2(9/2) 11-01-28 AI05-0212-1/03
!class Amendment 10-04-26
!status work item 10-04-26
!status received 10-02-27
@@ -29,44 +29,36 @@
with Ada.Iterator_Interfaces;
-Modify the definition of the cursor and container types for each of the containers
+Modify the definition of the container types for each of the containers
(with suitable substitutions for the names of types) as follows:
- type Vector;
+ type Vector is tagged private
+ with
+ Constant_Indexing => Constant_Reference,
+ Variable_Indexing => Reference,
+ Default_Iterator => Iterate,
+ Iterator_Element => Element_Type;
+ pragma Preelaborable_Initialization(Vector);
- package Cursors is
- type Cursor is private;
- pragma Preelaborable_Initialization(Cursor);
-
- No_Element : constant Cursor;
- private
- ... -- not specified by the language
- end Cursors;
- subtype Cursor is Cursors.Cursor;
- No_Element : Cursor renames Cursors.No_Element;
- package Iterators is new
- Ada.Iterator_Interfaces (Cursors, No_Element);
-
- type Vector is new Iterators with private with
- Constant_Indexing => Constant_Reference,
- Variable_Indexing => Reference,
- Default_Iterator => Iterate,
- Iterator_Element => Element_Type;
+Add after constant No_Element:
- pragma Preelaborable_Initialization(Vectors);
+ package Vector_Iterator_Interfaces is new
+ Ada.Iterator_Interfaces (Cursors, No_Element);
Add the following to each Ada.Containers package immediately after
Update_Element (with suitable substitutions for the names of types).
type Constant_Reference_Type (Element : not null access constant Element_Type) is
- limited new Ada.Reference.References with private with
- Implicit_Dereference => Element;
+ with private
+ with
+ Implicit_Dereference => Element;
type Reference_Type (Element : not null access Element_Type) is
- limited new Ada.Reference.References with private with
- Implicit_Dereference => Element;
+ with private
+ with
+ Implicit_Dereference => Element;
Constant_Reference_Type and Reference_Type need finalization.
@@ -142,7 +134,8 @@
The element designated by Position is not an empty element after successful
completion of this operation.
-Add the following to Ada.Containers.Hashed_Maps and the various other Map containers:
+Add the following to Ada.Containers.Hashed_Maps and the various other Map containers,
+as well as inside of the Generic_Keys package for the various Set containers:
function Constant_Reference (Container : aliased in Map; Key : in Key_Type)
return Constant_Reference_Type;
@@ -159,8 +152,17 @@
This function (combined with the Variable_Indexing and Implicit_Dereference aspects)
provides a convinient way to get read and write access to the individual elements of
a container starting with an index value.
+
+Equivalent to Reference (Container, Find (Container, Key)).
+
+[Note: The versions for the set containers are unfortunately not primitive operations;
+therefore they cannot be used via the _Indexing magic nor can they be called with
+prefix notation. However, the reference semantics is operational, so the discriminant
+and .all can be omitted; and they're probably still easier to use than Update_Element.
+That seems like enough to justify defining them.
-Equivalent to Reference (Container, Find (Container, Key).
+The Reference function for a Set and Key may need to work like the
+Update_Element_Preserving_Key routine. More thought needed.]
After the existing procedure Reverse_Iterate of each container that has Reverse_Iterate,
@@ -175,11 +177,32 @@
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.
+ 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.]
+After the above routine for various Vector and List containers, add a new function:
+
+ function Iterate (Container : in Vector; Start : in Cursor) return Iterators.Reversible_Iterator'Class;
+
+ 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.
+
+ 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
+ exit when Cur = Stop;
+ in the body of the loop.
+
After the existing procedure Iterate of each container that does not have a procedure
Reverse_Iterate (for example, Hashed_Sets), add a new function:
@@ -190,7 +213,8 @@
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.
+ 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:
@@ -201,7 +225,8 @@
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.
+ 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;
@@ -212,7 +237,8 @@
propagated. Program_Error is propagated if any operation (in particular,
the sequence_of_statements of the loop_statement whose iterator_specification denotes
this object) tampers with the cursors of the container in which the node designated by Position
- exists while the returned object exists.
+ exists while the returned object exists. The returned
+ object from Iterate needs finalization.
function Iterate_Children (Container : in Tree; Parent : in Cursor) return Iterators.Reversible_Iterator'Class;
@@ -225,13 +251,19 @@
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.
+ this object) tampers with the cursors of Container while the returned object exists. The returned
+ object from Iterate needs finalization.
+
+For each bounded container, delete the bullet and associated implementation note that says:
+The pragma Preelaborate is replaced with pragma Pure.
-[Question: Should we have other kinds of iterators for containers? In particular, should
-the vectors and linked lists support an iterator where the start and end cursors are specified
-(to allow iterating over a slice?).]
+Add an AARM note after the bullet about when the container needs finalization:
+Implementation Note: The type Vector cannot depend on package Ada.Finalization unless the element
+type depends on that package. The objects returned from the Iterator and Reference functions
+probably do depend on package Ada.Finalization. Restricted environments may need to avoid
+use of those functions and their associated types.
Add the following to the Erroneous Execution section of each container package:
@@ -250,8 +282,13 @@
question is not visible in the specification of the type. (This is the same
reason we have to say this for invalid cursors.)
-Add an Example subpart to each container (with suitable changes to the type names):
+Add a new clause at the end of the containers section: (Currently A.18.33)
+A.18.33 Example of container use.
+
+[** TBD - bigger, better examples are supposed to be coming from Ed and Steve.
+ Examples of iterator use need to be included. **]
+
For the following declarations:
type Point is record
@@ -521,7 +558,8 @@
Locations.Insert ("Steve", (X | Y => 20));
Locations.Insert ("John", (X => 50, Y => 100));
-we can reference the elements directly via the keys:
+we can reference the elements directly via the keys (again we're using the
+Variable_Indexing aspect to simplify the calls):
if Locations("Randy").X > 10 then ...
if Locations("Tucker").all = (X | Y => 0) then ...
@@ -567,5 +605,27 @@
ACATS tests would be needed for these changes.
!appendix
+
+From: Randy Brukardt
+Sent: Never (Written January 28, 2011)
+
+Notes on version /03 (compared to the /02 discussed at the phone meeting):
+
+The declaration of the container type does not need an interface because we
+replaced that by an aspect several versions back in AI05-0139-2. Sorry about
+having completely forgotten that. That simplifies the description and eliminates
+the incompatibility that we talked about.
+
+Used the name "Vector_Iterator_Interfaces" for the magic instance, as the
+suggested name "Iterator_Implementation" doesn't make much sense.
+
+Added notes about the Set implementation of the Reference and Constant_Reference
+routines for Keys.
+
+Added a sentence about the object returned from the various iterator functions
+needing finalization.
+
+Added a note that all of the bounded containers are Preelaborated, not Pure.
+(This drops A.18.19(3/3) and similar bullets.)
****************************************************************
Questions? Ask the ACAA Technical Agent