Coverage Report - org.as3collections.IQueue
 
Classes in this File Line Coverage Branch Coverage Complexity
IQueue
100%
1/1
N/A
0
 
 1  
 /*
 2  
  * Licensed under the MIT License
 3  
  * 
 4  
  * Copyright 2010 (c) Flávio Silva, http://flsilva.com
 5  
  *
 6  
  * Permission is hereby granted, free of charge, to any person
 7  
  * obtaining a copy of this software and associated documentation
 8  
  * files (the "Software"), to deal in the Software without
 9  
  * restriction, including without limitation the rights to use,
 10  
  * copy, modify, merge, publish, distribute, sublicense, and/or sell
 11  
  * copies of the Software, and to permit persons to whom the
 12  
  * Software is furnished to do so, subject to the following
 13  
  * conditions:
 14  
  *
 15  
  * The above copyright notice and this permission notice shall be
 16  
  * included in all copies or substantial portions of the Software.
 17  
  *
 18  
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 19  
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 20  
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 21  
  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 22  
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 23  
  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 24  
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 25  
  * OTHER DEALINGS IN THE SOFTWARE.
 26  
  * 
 27  
  * http://www.opensource.org/licenses/mit-license.php
 28  
  */
 29  
 
 30  1
 package org.as3collections
 31  
 {
 32  
         import org.as3collections.ICollection;
 33  
 
 34  
         /**
 35  
          * A collection designed for holding elements prior to processing.
 36  
          * Besides basic <code>ICollection</code> operations, queues provide additional insertion, extraction, and inspection operations.
 37  
          * Each of these methods exists in two forms: one throws an error if the operation fails, the other returns a special value (either <code>null</code> or <code>false</code>, depending on the operation).
 38  
          * <p>
 39  
          * <table class="innertable">
 40  
          * <tr>
 41  
          * <th></th>
 42  
          * <th><em>Throws error</em></th>
 43  
          * <th><em>Returns special value</em></th>
 44  
          * </tr>
 45  
          * <tr>
 46  
          * <td><b>Insert</b></td>
 47  
          * <td><code>add</code></td>
 48  
          * <td><code>offer</code></td>
 49  
          * </tr>
 50  
          * <tr>
 51  
          * <td><b>Remove</b></td>
 52  
          * <td><code>dequeue</code></td>
 53  
          * <td><code>poll</code></td>
 54  
          * </tr>
 55  
          * <tr>
 56  
          * <td><b>Examine</b></td>
 57  
          * <td><code>element</code></td>
 58  
          * <td><code>peek</code></td>
 59  
          * </tr>
 60  
          * </table>
 61  
          * </p>
 62  
          * <p>Queues typically, but do not necessarily, order elements in a FIFO (first-in-first-out) manner.
 63  
          * Among the exceptions are priority queues, which order elements according to a supplied comparator, or the elements' natural ordering, and LIFO queues (or stacks) which order the elements LIFO (last-in-first-out).
 64  
          * Whatever the ordering used, the head of the queue is that element which would be removed by a call to <code>dequeue</code> or <code>poll</code>.
 65  
          * In a FIFO queue, all new elements are inserted at the <em>tail</em> of the queue.
 66  
          * Other kinds of queues may use different placement rules.
 67  
          * Every <code>IQueue</code> implementation must specify its ordering properties.</p>
 68  
          * <p>The <code>offer</code> method inserts an element if possible, otherwise returning <code>false</code>.
 69  
          * This differs from the <code>add</code> method, which can fail to add an element only by throwing an error.
 70  
          * The <code>offer</code> method is designed for use when failure is a normal, rather than exceptional occurrence.</p>
 71  
          * <p>The <code>dequeue</code> and <code>poll</code> methods remove and return the head of the queue.
 72  
          * Exactly which element is removed from the queue is a function of the queue's ordering policy, which differs from implementation to implementation.
 73  
          * The <code>dequeue</code> and <code>poll</code> methods differ only in their behavior when the queue is empty: the <code>dequeue</code> method throws an error, while the <code>poll</code> method returns <code>null</code>.</p> 
 74  
          * <p>The <code>element</code> and <code>peek</code> methods return, but do not remove, the head of the queue.
 75  
          * The <code>element</code> and <code>peek</code> methods differ only in their behavior when the queue is empty: the <code>element</code> method throws an error, while the <code>peek</code> method returns null.</p>
 76  
          * <p><code>IQueue</code> implementations generally do not allow insertion of <code>null</code> elements</p>
 77  
          * 
 78  
          * @author Flávio Silva
 79  
          */
 80  
         public interface IQueue extends ICollection
 81  
         {
 82  
                 /**
 83  
                  * Retrieves and removes the head of this queue.
 84  
                  * 
 85  
                  * @throws         org.as3collections.errors.NoSuchElementError         if this queue is empty.
 86  
                  * @return         the head of this queue.
 87  
                   */
 88  
                 function dequeue(): *;
 89  
 
 90  
                 /**
 91  
                  * Retrieves, but does not remove, the head of this queue.
 92  
                  * This method differs from <code>peek</code> only in that it throws an error if this queue is empty. 
 93  
                  * 
 94  
                  * @throws         org.as3collections.errors.NoSuchElementError         if this queue is empty.
 95  
                  * @return         the head of this queue.
 96  
                   */
 97  
                 function element(): *;
 98  
 
 99  
                 /**
 100  
                  * Inserts the specified element into this queue if it is possible to do so immediately without violating restrictions.
 101  
                  * When using a restricted queue (like <code>TypedQueue</code> and <code>UniqueQueue</code>), this method is generally preferable to <code>add</code>, which can fail to insert an element only by throwing an error. 
 102  
                  * 
 103  
                  * @param          element         the element to add.
 104  
                  * @return         <code>true</code> if the element was added to this queue, else <code>false</code>. 
 105  
                  */
 106  
                 function offer(element:*): Boolean;
 107  
 
 108  
                 /**
 109  
                  * Retrieves, but does not remove, the head of this queue, or returns <code>null</code> if this queue is empty. 
 110  
                  * 
 111  
                  * @return         the head of this queue, or <code>null</code> if this queue is empty.
 112  
                   */
 113  
                 function peek(): *;
 114  
 
 115  
                 /**
 116  
                  * Retrieves and removes the head of this queue, or returns <code>null</code> if this queue is empty. 
 117  
                  * 
 118  
                  * @return         the head of this queue, or <code>null</code> if this queue is empty.
 119  
                   */
 120  
                 function poll(): *;
 121  
         }
 122  
 
 123  
 }