ad5d50e6c7bed560d10ee17dcd1e8e3c566829da
[profile/ivi/libgee.git] / 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 }