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 public interface Gee.Deque<G> : Queue<G> {
  50         /**
  51          * Offers the specified element to the head of this deque.
  52          *
  53          * @param element the element to offer to the queue
  54          *
  55          * @return        ``true`` if the element was added to the queue
  56          */
  57         public abstract bool offer_head (G element);
  58
  59         /**
  60          * Peeks (retrieves, but not remove) an element from this queue.
  61          *
  62          * @return the element peeked from the queue (or ``null`` if none was
  63          *         available)
  64          */
  65         public abstract G? peek_head ();
  66
  67         /**
  68          * Polls (retrieves and remove) an element from the head of this queue.
  69          *
  70          * @return the element polled from the queue (or ``null`` if none was
  71          *         available)
  72          */
  73         public abstract G? poll_head ();
  74
  75         /**
  76          * Drains the specified amount of elements from the head of this queue in
  77          * the specified recipient collection.
  78          *
  79          * @param recipient the recipient collection to drain the elements to
  80          * @param amount    the amount of elements to drain
  81          *
  82          * @return          the amount of elements that were actually drained
  83          */
  84         public abstract int drain_head (Collection<G> recipient, int amount = -1);
  85
  86         /**
  87          * Offers the specified element to the tail of this deque
  88          *
  89          * @param element the element to offer to the queue
  90          *
  91          * @return        ``true`` if the element was added to the queue
  92          */
  93         public abstract bool offer_tail (G element);
  94
  95         /**
  96          * Peeks (retrieves, but not remove) an element from the tail of this
  97          * queue.
  98          *
  99          * @return the element peeked from the queue (or ``null`` if none was
 100          *         available)
 101          */
 102         public abstract G? peek_tail ();
 103
 104         /**
 105          * Polls (retrieves and remove) an element from the tail of this queue.
 106          *
 107          * @return the element polled from the queue (or ``null`` if none was
 108          *         available)
 109          */
 110         public abstract G? poll_tail ();
 111
 112         /**
 113          * Drains the specified amount of elements from the tail of this queue in
 114          * the specified recipient collection.
 115          *
 116          * @param recipient the recipient collection to drain the elements to
 117          * @param amount    the amount of elements to drain
 118          *
 119          * @return          the amount of elements that were actually drained
 120          */
 121         public abstract int drain_tail (Collection<G> recipient, int amount = -1);
 122 }