gee/deque.vala

   1 /* deque.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 double-ended queue.
  25  *
  26  * A deque can be used either as a queue (First-In-First-Out behavior) or as a
  27  * stack (Last-In-First-Out behavior).
  28  *
  29  * The methods defined by this interface behaves exactely in the same way as
  30  * the {@link Queue} methods with respect to capacity bounds.
  31  *
  32  * The Deque interface inherits from the {@link Queue} interface. Thus, to use
  33  * a deque as a queue, you can equivalently use the folowing method set:
  34  *
  35  * ||<)(> ''Queue method'' ||<)(>  ''Deque method'' ||
  36  * || {@link Queue.offer}  || {@link offer_tail}    ||
  37  * || {@link Queue.peek}   || {@link peek_head}     ||
  38  * || {@link Queue.poll}   || {@link poll_head}     ||
  39  * || {@link Queue.drain}  || {@link drain_head}    ||
  40  *
  41  * To use a deque as a stack, just use the method set that acts at the head of
  42  * the deque:
  43  *
  44  * ||<)(> ''Operation'' ||<)(>  ''Deque method'' ||
  45  * || push an element   || {@link offer_head}    ||
  46  * || peek an element   || {@link peek_head}     ||
  47  * || pop an element    || {@link poll_head}     ||
  48  */
  49 [GenericAccessors]
  50 public interface Gee.Deque<G> : Queue<G> {
  51         /**
  52          * Offers the specified element to the head of this deque.
  53          *
  54          * @param element the element to offer to the queue
  55          *
  56          * @return        ``true`` if the element was added to the queue
  57          */
  58         public abstract bool offer_head (G element);
  59
  60         /**
  61          * Peeks (retrieves, but not remove) an element from this queue.
  62          *
  63          * @return the element peeked from the queue (or ``null`` if none was
  64          *         available)
  65          */
  66         public abstract G? peek_head ();
  67
  68         /**
  69          * Polls (retrieves and remove) an element from the head of this queue.
  70          *
  71          * @return the element polled from the queue (or ``null`` if none was
  72          *         available)
  73          */
  74         public abstract G? poll_head ();
  75
  76         /**
  77          * Drains the specified amount of elements from the head of this queue in
  78          * the specified recipient collection.
  79          *
  80          * @param recipient the recipient collection to drain the elements to
  81          * @param amount    the amount of elements to drain
  82          *
  83          * @return          the amount of elements that were actually drained
  84          */
  85         public abstract int drain_head (Collection<G> recipient, int amount = -1);
  86
  87         /**
  88          * Offers the specified element to the tail of this deque
  89          *
  90          * @param element the element to offer to the queue
  91          *
  92          * @return        ``true`` if the element was added to the queue
  93          */
  94         public abstract bool offer_tail (G element);
  95
  96         /**
  97          * Peeks (retrieves, but not remove) an element from the tail of this
  98          * queue.
  99          *
 100          * @return the element peeked from the queue (or ``null`` if none was
 101          *         available)
 102          */
 103         public abstract G? peek_tail ();
 104
 105         /**
 106          * Polls (retrieves and remove) an element from the tail of this queue.
 107          *
 108          * @return the element polled from the queue (or ``null`` if none was
 109          *         available)
 110          */
 111         public abstract G? poll_tail ();
 112
 113         /**
 114          * Drains the specified amount of elements from the tail of this queue in
 115          * the specified recipient collection.
 116          *
 117          * @param recipient the recipient collection to drain the elements to
 118          * @param amount    the amount of elements to drain
 119          *
 120          * @return          the amount of elements that were actually drained
 121          */
 122         public abstract int drain_tail (Collection<G> recipient, int amount = -1);
 123 }