/* deque.vala
*
* Copyright (C) 2009 Didier Villevalois
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
* Author:
* Didier 'Ptitjes Villevalois <ptitjes@free.fr>
*/
/**
* A double-ended queue.
*
* A deque can be used either as a queue (First-In-First-Out behavior) or as a
* stack (Last-In-First-Out behavior).
*
* The methods defined by this interface behaves exactely in the same way as
* the {@link Queue} methods with respect to capacity bounds.
*
* The Deque interface inherits from the {@link Queue} interface. Thus, to use
* a deque as a queue, you can equivalently use the folowing method set:
*
* ||<)(> ''Queue method'' ||<)(> ''Deque method'' ||
* || {@link Queue.offer} || {@link offer_tail} ||
* || {@link Queue.peek} || {@link peek_head} ||
* || {@link Queue.poll} || {@link poll_head} ||
* || {@link Queue.drain} || {@link drain_head} ||
*
* To use a deque as a stack, just use the method set that acts at the head of
* the deque:
*
* ||<)(> ''Operation'' ||<)(> ''Deque method'' ||
* || push an element || {@link offer_head} ||
* || peek an element || {@link peek_head} ||
* || pop an element || {@link poll_head} ||
*/
[GenericAccessors]
public interface Gee.Deque<G> : Queue<G> {
/**
* Offers the specified element to the head of this deque.
*
* @param element the element to offer to the queue
*
* @return ``true`` if the element was added to the queue
*/
public abstract bool offer_head (G element);
/**
* Peeks (retrieves, but not remove) an element from this queue.
*
* @return the element peeked from the queue (or ``null`` if none was
* available)
*/
public abstract G? peek_head ();
/**
* Polls (retrieves and remove) an element from the head of this queue.
*
* @return the element polled from the queue (or ``null`` if none was
* available)
*/
public abstract G? poll_head ();
/**
* Drains the specified amount of elements from the head of this queue in
* the specified recipient collection.
*
* @param recipient the recipient collection to drain the elements to
* @param amount the amount of elements to drain
*
* @return the amount of elements that were actually drained
*/
public abstract int drain_head (Collection<G> recipient, int amount = -1);
/**
* Offers the specified element to the tail of this deque
*
* @param element the element to offer to the queue
*
* @return ``true`` if the element was added to the queue
*/
public abstract bool offer_tail (G element);
/**
* Peeks (retrieves, but not remove) an element from the tail of this
* queue.
*
* @return the element peeked from the queue (or ``null`` if none was
* available)
*/
public abstract G? peek_tail ();
/**
* Polls (retrieves and remove) an element from the tail of this queue.
*
* @return the element polled from the queue (or ``null`` if none was
* available)
*/
public abstract G? poll_tail ();
/**
* Drains the specified amount of elements from the tail of this queue in
* the specified recipient collection.
*
* @param recipient the recipient collection to drain the elements to
* @param amount the amount of elements to drain
*
* @return the amount of elements that were actually drained
*/
public abstract int drain_tail (Collection<G> recipient, int amount = -1);
}