changes: TINF-175 TZPC-4722

[platform/upstream/libgee.git] / gee / queue.vala

diff --git a/gee/queue.vala b/gee/queue.vala
index 321479b..3658e67 100644 (file)
--- a/gee/queue.vala
+++ b/gee/queue.vala
@@ -26,33 +26,41 @@
  * Although all Queue implementations do not limit the amount of elements they
  * can contain, this interface supports for capacity-bounded queues. When
  * capacity is not bound, then the {@link capacity} and
- * {@link remaining_capacity} both return null.
+ * {@link remaining_capacity} both return {@link UNBOUNDED_CAPACITY}.
  *
  * This interface defines methods that will never fail whatever the state of
  * the queue is. For capacity-bounded queues, those methods will either return
- * false or null to specify that the insert or retrieval did not occur because
- * the queue was full or empty.
+ * ``false`` or ``null`` to specify that the insert or retrieval did not occur
+ * because the queue was full or empty.
  *
  * Queue implementations are not limited to First-In-First-Out behavior and can
  * propose different ordering of their elements. Each Queue implementation have
  * to specify how it orders its elements.
  *
- * Queue implementations do not allow insertion of null elements, although some
- * implementations, such as {@link LinkedList}, do not prohibit insertion of
- * null. Even in the implementations that permit it, null should not be
- * inserted into a Queue, as null is also used as a special return value by the
- * poll method to indicate that the queue contains no elements.
+ * Queue implementations do not allow insertion of ``null`` elements, although
+ * some implementations, such as {@link LinkedList}, do not prohibit insertion
+ * of ``null``. Even in the implementations that permit it, ``null`` should not be
+ * inserted into a Queue, as ``null`` is also used as a special return value by
+ * the poll method to indicate that the queue contains no elements.
  */
+[GenericAccessors]
 public interface Gee.Queue<G> : Collection<G> {
+
+       /**
+        * The unbounded capacity value.
+        */
+       public static const int UNBOUNDED_CAPACITY = -1;
+
        /**
-        * The capacity of this queue (or null if capacity is not bound).
+        * The capacity of this queue (or ``null`` if capacity is not bound).
         */
-       public abstract int? capacity { get; }
+       public abstract int capacity { get; }
 
        /**
-        * The remaining capacity of this queue (or null if capacity is not bound).
+        * The remaining capacity of this queue (or ``null`` if capacity is not
+        * bound).
         */
-       public abstract int? remaining_capacity { get; }
+       public abstract int remaining_capacity { get; }
 
        /**
         * Specifies whether this queue is full.
@@ -64,21 +72,25 @@ public interface Gee.Queue<G> : Collection<G> {
         *
         * @param element the element to offer to the queue
         *
-        * @return        true if the element was added to the queue
+        * @return        ``true`` if the element was added to the queue
         */
-       public abstract bool offer (G element);
+       public virtual bool offer (G element) {
+               return add (element);
+       }
 
        /**
         * Peeks (retrieves, but not remove) an element from this queue.
         *
-        * @return the element peeked from the queue (or null if none was available)
+        * @return the element peeked from the queue (or ``null`` if none was
+        *         available)
         */
        public abstract G? peek ();
 
        /**
         * Polls (retrieves and remove) an element from this queue.
         *
-        * @return the element polled from the queue (or null if none was available)
+        * @return the element polled from the queue (or ``null`` if none was
+        *         available)
         */
        public abstract G? poll ();
 
@@ -91,5 +103,13 @@ public interface Gee.Queue<G> : Collection<G> {
         *
         * @return          the amount of elements that were actually drained
         */
-       public abstract int drain (Collection<G> recipient, int amount = -1);
+       public virtual int drain (Collection<G> recipient, int amount = -1) {
+               G? item = null;
+               int drained = 0;
+               while((amount == -1 || --amount >= 0) && (item = poll ()) != null) {
+                       recipient.add (item);
+                       drained++;
+               }
+               return drained;
+       }
 }