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

Differences between 1.2 and version 1.3
Log of other versions for file 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