*
* This interface defines methods that will never fail whatever the state of
* the queue is. For capacity-bounded queues, those methods will either return
- * false or null to specify that the insert or retrieval did not occur because
- * the queue was full or empty.
+ * ``false`` or ``null`` to specify that the insert or retrieval did not occur
+ * because the queue was full or empty.
*
* Queue implementations are not limited to First-In-First-Out behavior and can
* propose different ordering of their elements. Each Queue implementation have
* to specify how it orders its elements.
*
- * Queue implementations do not allow insertion of null elements, although some
- * implementations, such as {@link LinkedList}, do not prohibit insertion of
- * null. Even in the implementations that permit it, null should not be
- * inserted into a Queue, as null is also used as a special return value by the
- * poll method to indicate that the queue contains no elements.
+ * Queue implementations do not allow insertion of ``null`` elements, although
+ * some implementations, such as {@link LinkedList}, do not prohibit insertion
+ * of ``null``. Even in the implementations that permit it, ``null`` should not be
+ * inserted into a Queue, as ``null`` is also used as a special return value by
+ * the poll method to indicate that the queue contains no elements.
*/
+[GenericAccessors]
public interface Gee.Queue<G> : Collection<G> {
/**
public static const int UNBOUNDED_CAPACITY = -1;
/**
- * The capacity of this queue (or null if capacity is not bound).
+ * The capacity of this queue (or ``null`` if capacity is not bound).
*/
public abstract int capacity { get; }
/**
- * The remaining capacity of this queue (or null if capacity is not bound).
+ * The remaining capacity of this queue (or ``null`` if capacity is not
+ * bound).
*/
public abstract int remaining_capacity { get; }
*
* @param element the element to offer to the queue
*
- * @return true if the element was added to the queue
+ * @return ``true`` if the element was added to the queue
*/
- public abstract bool offer (G element);
+ public virtual bool offer (G element) {
+ return add (element);
+ }
/**
* Peeks (retrieves, but not remove) an element from this queue.
*
- * @return the element peeked from the queue (or null if none was available)
+ * @return the element peeked from the queue (or ``null`` if none was
+ * available)
*/
public abstract G? peek ();
/**
* Polls (retrieves and remove) an element from this queue.
*
- * @return the element polled from the queue (or null if none was available)
+ * @return the element polled from the queue (or ``null`` if none was
+ * available)
*/
public abstract G? poll ();
*
* @return the amount of elements that were actually drained
*/
- public abstract int drain (Collection<G> recipient, int amount = -1);
+ public virtual int drain (Collection<G> recipient, int amount = -1) {
+ G? item = null;
+ int drained = 0;
+ while((amount == -1 || --amount >= 0) && (item = poll ()) != null) {
+ recipient.add (item);
+ drained++;
+ }
+ return drained;
+ }
}