1  /*
     2   * Copyright the original author or authors.
     3   * 
     4   * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   * 
     8   *      http://www.mozilla.org/MPL/MPL-1.1.html
     9   * 
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  import org.as2lib.data.holder.Iterator;
    18  import org.as2lib.core.BasicInterface;
    19  
    20  /**
    21   * {@code Queue} is the base interface for data holders that follow the 'first-in,
    22   * first-out' policy.
    23   * 
    24   * <p>It offers the opposite functionality of a stack which follows the 'last-in,
    25   * first-out' policy.
    26   * 
    27   * <p>'first-in, first-out' means that the first value that has been enqueued/added
    28   * to the queue is the first that gets dequeued/removed.
    29   * 
    30   * <p>The usage of a queue is quite simple. You have one method to add/enqueue values
    31   * {@link #enqueue} and one method to remove/dequeue them {@link #dequeue}. You can
    32   * also peek at the beginning of the queue to see what value has been added/enqueued
    33   * at first without removing it {@link #peek}.
    34   *
    35   * <p>If you want to iterate over the values of the queue you can either use the
    36   * iterator returned by the {@link #iterator} method or the array that contains the
    37   * queue's values returned by the {@link #toArray} method.
    38   * 
    39   * <p>The two methods {@link #isEmpty} and {@link #size} let you find
    40   * out whether the queue contains values and how many values it contains.
    41   *
    42   * <p>Example:
    43   * <code>
    44   *   // the queue gets set up
    45   *   var queue:Queue = new MyQueue();
    46   *   queue.enqueue("value1");
    47   *   queue.enqueue("value2");
    48   *   queue.enqueue("value3");
    49   *   // the queue gets used somewhere in your application
    50   *   trace(queue.peek()); // traces the first element without removing it
    51   *   while (!queue.isEmpty()) {
    52   *       trace(queue.dequeue());
    53   *   }
    54   * </code>
    55   *
    56   * <p>Output:
    57   * <pre>
    58   *   value1
    59   *   value1
    60   *   value2
    61   *   value3
    62   * </pre>
    63   *
    64   * @author Simon Wacker
    65   */
    66  interface org.as2lib.data.holder.Queue extends BasicInterface {
    67  	
    68  	/**
    69  	 * Adds the passed-in {@code value} to this queue.
    70  	 *
    71  	 * @param value the value to add
    72  	 */
    73  	public function enqueue(value):Void;
    74  	
    75  	/**
    76  	 * Removes and returns the firstly inserted value.
    77  	 * 
    78  	 * @return the firstly inserted value
    79  	 * @throws org.as2lib.data.holder.EmptyDataHolderException if this queue is empty
    80  	 */
    81  	public function dequeue(Void);
    82  	
    83  	/**
    84  	 * Returns the firstly inserted value.
    85  	 *
    86  	 * @return the firstly inserted value
    87  	 * @throws org.as2lib.data.holder.EmptyDataHolderException if this queue is empty
    88  	 */
    89  	public function peek(Void);
    90  	
    91  	/**
    92  	 * Returns an iterator to iterate over the values of this queue.
    93  	 *
    94  	 * @return an iterator to iterate over this queue's values
    95  	 * @see #toArray
    96  	 */
    97  	public function iterator(Void):Iterator;
    98  	
    99  	/**
   100  	 * Returns whether this queue contains any values.
   101  	 * 
   102  	 * @return {@code true} if this queue contains no values else {@code false}
   103  	 */
   104  	public function isEmpty(Void):Boolean;
   105  	
   106  	/**
   107  	 * Returns the number of enqueued elements.
   108  	 *
   109  	 * @return the number of enqueued elements
   110  	 * @see #enqueue
   111  	 */
   112  	public function size(Void):Number;
   113  	
   114  	/**
   115  	 * Returns the array representation of this queue.
   116  	 * 
   117  	 * <p>The elements are copied onto the array in a 'first-in, first-out' order,
   118  	 * similar to the order of the elements returned by a succession of calls to the
   119  	 * {@link #dequeue} method.
   120  	 *
   121  	 * @return the array representation of this queue
   122  	 */
   123  	public function toArray(Void):Array;
   124  	
   125  }
as2api