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

--- ai05s/ai05-0159-1.txt	2009/10/17 00:28:07	1.3
+++ ai05s/ai05-0159-1.txt	2009/10/22 03:43:10	1.4
@@ -1,4 +1,4 @@
-!standard  A.18.24                                 09-10-15    AI05-0159-1/02
+!standard  A.18.24                                 09-10-18    AI05-0159-1/03
 !class Amendment 05-10-24
 !status work item 06-03-15
 !status received 05-10-02
@@ -51,22 +51,28 @@
       Element   : out Element_Type) is abstract;
    pragma Implemented (Dequeue, By_Entry);
 
-   function Is_Empty (Container : Queue) return Boolean is abstract;
+   function Num_In_Use (Container : Queue) return Count_Type is abstract;
 
-   function Is_Full (Container : Queue) return Boolean is abstract;
+   function Max_In_Use (Container : Queue) return Count_Type is abstract;
 
 end Ada.Containers.Queues;
 
 [ARG]
 
-Any interest in a Peek?
+Any interest in a Peek?  (This was suggested on ada-comment.)  Could
+also have Peek_First (Peek_Head), Peek_Last (Peak_Tail).
 
-Conditional deque:
+Something like:
 
-   procedure Dequeue
-     (Container : in out Queue;
-      Element   : out Element_Type;
-      Available : out Boolean) is abstract;
+  procedure Peek_Head
+    (Container : Queue;
+     Element   : out Element_Type;
+     Available : out Boolean);
+
+  procedure Peek_Tail
+    (Container : Queue;
+     Element   : out Element_Type;
+     Available : out Boolean);
 
 [END ARG]
 
@@ -75,24 +81,26 @@
      (Container : in out Queue;
       New_Item  : Element_Type) is abstract;
 
-Copies New_Item onto the tail of the queue.  If Is_Full is True, then
-Enqueue waits on the entry for storage to become available.
+Copies New_Item onto the tail of the queue.  If the number of existing
+elements equals the capacity, then Enqueue waits on the entry for
+storage to become available.
 
    procedure Dequeue
      (Container : in out Queue;
       Element   : out Element_Type) is abstract;
 
-Removes the element at the head of the queue, and returns a copy of
-the element. Is Is_Empty is True, then Dequeue waits on the entry for
-an item to become available.
+Returns a copy of the element at the head of the queue, and removes it
+from the container. If the queue is empty, then Dequeue waits on the
+entry for an item to become available.
 
-   function Is_Empty (Container : Queue) return Boolean is abstract;
+   function Num_In_Use (Container : Queue) return Count_Type is abstract;
 
-Returns True if Container contains items.
+Returns the number of elements currently in the queue.
 
-   function Is_Full (Container : Queue) return Boolean is abstract;
+   function Max_In_Use (Container : Queue) return Count_Type is abstract;
 
-Returns True if Container is able to contain more items.
+Returns the maximum number of elements that have been in the queue at
+any one time.
 
 
 A.18.24 Containers.Unbounded_Queues
@@ -118,10 +126,13 @@
 
 end Ada.Containers.Unbounded_Queues;
 
-Is_Full always returns False, because storage for new items is
-allocated dynamically.
+[ARG]
 
+We need to say something about Enqueue never waiting for storage. Not sure what, though - RLB
 
+[End ARG]
+
+
 A.18.25  Containers.Bounded_Queues
 
 Static Semantics
@@ -150,12 +161,13 @@
 Element_Type needs finalization.
 
 [ARG]
-Is the above what we want?
-[End ARG]
 
-Is_Full returns True when the number of elements that have been
-enqueued equals the Capacity; otherwise it returns False.
+We probably need some wording to tie the Capacity here with the lower case
+"capacity" given in the interface. Maybe we need to define capacity better
+in the interface. - RLB
 
+[End ARG]
+
 Implementation Advice
 
 Bounded queue objects should be implemented without implicit pointers or dynamic
@@ -173,7 +185,7 @@
 with Ada.Containers.Queues;
 generic
    with package Queues is new Ada.Containers.Queues (<>);
-   with function "<"
+   with function Before
      (Left, Right : Queues.Element_Type) return Boolean is <>;
 
 package Ada.Containers.Unbounded_Priority_Queues is
@@ -186,46 +198,23 @@
    -- not specified by the language
 
 end Ada.Containers.Unbounded_Priority_Queues;
-
-[ARG]
-
-We might need to refactor this description, so that it applies to both
-priority queue forms.
 
-[Editor's note: Well, either that or duplicate it in the bounded form.
-Doing neither is just wrong.]
-
-[END ARG]
-
-Two elements E1 and E2 are equivalent if both E1 < E2 and E2 < E1
-return False, using the generic formal "<" operator for
-elements.
-
-The actual function for the generic formal function "<" on
-Element_Type values is expected to return the same value each time it
-is called with a particular pair of key values. It should define a
-strict ordering relationship, that is, be irreflexive, asymmetric, and
-transitive. If the actual for "<" behaves in some other manner, the
-behavior of this package is unspecified. Which subprograms of this
-package call "<" and how many times they call it, is unspecified.
-
-[ARG]
-
-Do we need that last sentence?
-
-[END ARG]
-
-If the value of an element stored in a set is changed other than by an
-operation in this package such that "<" gives a different result, the
-behavior of this package is unspecified.
-
-Enque inserts an item according to the order specified by the generic
-formal "<" operator.  If the queue already contains an element
-equivalent to New_Item, then the new item is inserted after existing
+Two elements E1 and E2 are equivalent if both Before (E1, E2) and
+Before (E2, E1) return False, using the generic formal function
+Before.
+
+Enqueue inserts an item according to the order specified by the generic
+formal Before operation. If the queue already contains elements
+equivalent to New_Item, then it is inserted after the existing
 equivalent elements.
 
-Is_Full always returns False, because storage for new items is
-allocated dynamically.
+The actual function for the generic formal function Before of
+Unbounded_Priority_Queues is expected to return the same value each
+time it is called with a particular pair of element values. It should
+define a strict weak ordering relationship (see A.18); it should not
+modify the elements. If the actual for Before behaves in some other
+manner, the behavior of Unbounded_Priority_Queues is unspecified. How
+many times Enqueue calls Before is unspecified.
 
 
 A.18.27  Containers.Bounded_Priority_Queues
@@ -256,12 +245,22 @@
 The type Queue needs finalization if and only type
 Element_Type needs finalization.
 
-[ARG]
-Is the above what we want?
-[End ARG]
+Two elements E1 and E2 are equivalent if both Before (E1, E2) and
+Before (E2, E1) return False, using the generic formal function
+Before.
+
+Enqueue inserts an item according to the order specified by the generic
+formal Before operation. If the queue already contains elements
+equivalent to New_Item, then it is inserted after the existing
+equivalent elements.
 
-Is_Full returns True when the number of elements that have been
-enqueued equals the Capacity; otherwise it returns False.
+The actual function for the generic formal function Before of
+Bounded_Priority_Queues is expected to return the same value each time
+it is called with a particular pair of element values. It should
+define a strict weak ordering relationship (see A.18); it should not
+modify the elements. If the actual for Before behaves in some other
+manner, the behavior of Bounded_Priority_Queues is unspecified. How
+many times Enqueue calls Before is unspecified.
 
 Implementation Advice