gee/queue.vala

   1 /* queue.vala
   2  *
   3  * Copyright (C) 2009  Didier Villevalois
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18  *
  19  * Author:
  20  *      Didier 'Ptitjes Villevalois <ptitjes@free.fr>
  21  */
  22
  23 /**
  24  * A collection designed for holding elements prior to processing.
  25  *
  26  * Although all Queue implementations do not limit the amount of elements they
  27  * can contain, this interface supports for capacity-bounded queues. When
  28  * capacity is not bound, then the {@link capacity} and
  29  * {@link remaining_capacity} both return {@link UNBOUNDED_CAPACITY}.
  30  *
  31  * This interface defines methods that will never fail whatever the state of
  32  * the queue is. For capacity-bounded queues, those methods will either return
  33  * ``false`` or ``null`` to specify that the insert or retrieval did not occur
  34  * because the queue was full or empty.
  35  *
  36  * Queue implementations are not limited to First-In-First-Out behavior and can
  37  * propose different ordering of their elements. Each Queue implementation have
  38  * to specify how it orders its elements.
  39  *
  40  * Queue implementations do not allow insertion of ``null`` elements, although
  41  * some implementations, such as {@link LinkedList}, do not prohibit insertion
  42  * of ``null``. Even in the implementations that permit it, ``null`` should not be
  43  * inserted into a Queue, as ``null`` is also used as a special return value by
  44  * the poll method to indicate that the queue contains no elements.
  45  */
  46 [GenericAccessors]
  47 public interface Gee.Queue<G> : Collection<G> {
  48
  49         /**
  50          * The unbounded capacity value.
  51          */
  52         public static const int UNBOUNDED_CAPACITY = -1;
  53
  54         /**
  55          * The capacity of this queue (or ``null`` if capacity is not bound).
  56          */
  57         public abstract int capacity { get; }
  58
  59         /**
  60          * The remaining capacity of this queue (or ``null`` if capacity is not
  61          * bound).
  62          */
  63         public abstract int remaining_capacity { get; }
  64
  65         /**
  66          * Specifies whether this queue is full.
  67          */
  68         public abstract bool is_full { get; }
  69
  70         /**
  71          * Offers the specified element to this queue.
  72          *
  73          * @param element the element to offer to the queue
  74          *
  75          * @return        ``true`` if the element was added to the queue
  76          */
  77         public virtual bool offer (G element) {
  78                 return add (element);
  79         }
  80
  81         /**
  82          * Peeks (retrieves, but not remove) an element from this queue.
  83          *
  84          * @return the element peeked from the queue (or ``null`` if none was
  85          *         available)
  86          */
  87         public abstract G? peek ();
  88
  89         /**
  90          * Polls (retrieves and remove) an element from this queue.
  91          *
  92          * @return the element polled from the queue (or ``null`` if none was
  93          *         available)
  94          */
  95         public abstract G? poll ();
  96
  97         /**
  98          * Drains the specified amount of elements from this queue in the specified
  99          * recipient collection.
 100          *
 101          * @param recipient the recipient collection to drain the elements to
 102          * @param amount    the amount of elements to drain
 103          *
 104          * @return          the amount of elements that were actually drained
 105          */
 106         public virtual int drain (Collection<G> recipient, int amount = -1) {
 107                 G? item = null;
 108                 int drained = 0;
 109                 while((amount == -1 || --amount >= 0) && (item = poll ()) != null) {
 110                         recipient.add (item);
 111                         drained++;
 112                 }
 113                 return drained;
 114         }
 115 }