Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
IQueue |
|
| 0.0;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 | } |