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 Stack} is the base interface for data holders that follow the 'last-in,
    22   * first-out' policy.
    23   * 
    24   * <p>It offers the opposite functionality of a queue, which follows the 'first-in,
    25   * first-out' policy.
    26   *
    27   * <p>'last-in, first-out' means that the last value that has been pushed to the
    28   * stack is the first that is popped from the stack.
    29   *
    30   * <p>The usage of a stack is quite simple. You have one method to push values,
    31   * {@link #push}, and one method to pop values, {@link #pop}. You can also peek at
    32   * the top of the stack to see what's the last value that has been pushed to the
    33   * stack without removing it {@link #peek}.
    34   * 
    35   * <p>If you want to iterate over the values of the stack you can either use the
    36   * iterator returned by the {@link #iterator} method or the array that contains the
    37   * stack's values returned by the {@link #toArray} method.
    38   * 
    39   * <p>The two methods {@link #isEmpty} and {@link #size} let you find out whether
    40   * the stack contains values and how many values it contains.
    41   *
    42   * <p>Example:
    43   * <code>
    44   *   // the stack gets set up
    45   *   var stack:Stack = new MyStack();
    46   *   stack.push("value1");
    47   *   stack.push("value2");
    48   *   stack.push("value3");
    49   *   // the stack gets used somewhere in your application
    50   *   trace(stack.peek()); // traces the last element without removing it
    51   *   while (!stack.isEmpty()) {
    52   *       trace(stack.pop());
    53   *   }
    54   * </code>
    55   *
    56   * <p>Output:
    57   * <pre>
    58   *   value3
    59   *   value3
    60   *   value2
    61   *   value1
    62   * </pre>
    63   *
    64   * @author Simon Wacker
    65   */
    66  interface org.as2lib.data.holder.Stack extends BasicInterface {
    67  	
    68  	/**
    69  	 * Pushes the passed-in {@code value} to this stack.
    70  	 *
    71  	 * @param value the value to push to this stack
    72  	 */
    73  	public function push(value):Void;
    74  	
    75  	/**
    76  	 * Removes and returns the lastly pushed value.
    77  	 *
    78  	 * @return the lastly pushed value
    79  	 * @throws org.as2lib.data.holder.EmptyDataHolderException if this stack is empty
    80  	 */
    81  	public function pop(Void);
    82  	
    83  	/**
    84  	 * Returns the lastly pushed value without removing it.
    85  	 *
    86  	 * @return the lastly pushed value
    87  	 * @throws org.as2lib.data.holder.EmptyDataHolderException if this stack is empty
    88  	 */
    89  	public function peek(Void);
    90  	
    91  	/**
    92  	 * Returns an iterator to iterate over the values of this stack.
    93  	 *
    94  	 * @return an iterator to iterate over this stack's values
    95  	 * @see #toArray
    96  	 */
    97  	public function iterator(Void):Iterator;
    98  	
    99  	/**
   100  	 * Returns whether this stack is empty.
   101  	 *
   102  	 * @return {@code true} if this stack is empty else {@code false}
   103  	 */
   104  	public function isEmpty(Void):Boolean;
   105  	
   106  	/**
   107  	 * Returns the number of pushed values.
   108  	 *
   109  	 * @return the number of pushed values
   110  	 * @see #push
   111  	 */
   112  	public function size(Void):Number;
   113  	
   114  	/**
   115  	 * Returns the array representation of this stack.
   116  	 * 
   117  	 * <p>The elements are copied onto the array in a 'last-in, first-out' order, similar
   118  	 * to the order of the elements returned by a succession of calls to the {@link #pop}
   119  	 * method.
   120  	 *
   121  	 * @return the array representation of this stack
   122  	 */
   123  	 public function toArray(Void):Array;
   124  	
   125  }
as2api