Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
AbstractList |
|
| 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.errors.IndexOutOfBoundsError; | |
33 | import org.as3collections.utils.CollectionUtil; | |
34 | import org.as3coreaddendum.errors.UnsupportedOperationError; | |
35 | import org.as3coreaddendum.system.IEquatable; | |
36 | import org.as3utils.ReflectionUtil; | |
37 | ||
38 | import flash.errors.IllegalOperationError; | |
39 | ||
40 | /** | |
41 | * This class provides a skeletal implementation of the <code>IList</code> interface, to minimize the effort required to implement this interface. | |
42 | * <p>This is an abstract class and shouldn't be instantiated directly.</p> | |
43 | * <p>The documentation for each non-abstract method in this class describes its implementation in detail. | |
44 | * Each of these methods may be overridden if the collection being implemented admits a more efficient implementation.</p> | |
45 | * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation. | |
46 | * For further information see <a href="http://download.oracle.com/javase/6/docs/technotes/guides/collections/index.html" target="_blank">Java Collections Framework</a></p> | |
47 | * | |
48 | * @see org.as3collections.IList IList | |
49 | * @see org.as3collections.lists.ArrayList ArrayList | |
50 | * @author Flávio Silva | |
51 | */ | |
52 | public class AbstractList extends AbstractArrayCollection implements IList | |
53 | { | |
54 | /** | |
55 | * @private | |
56 | */ | |
57 | protected var _modCount: int; | |
58 | ||
59 | /** | |
60 | * @inheritDoc | |
61 | */ | |
62 | public function get modCount(): int { return _modCount; } | |
63 | ||
64 | /** | |
65 | * This is an abstract class and shouldn't be instantiated directly. | |
66 | * | |
67 | * @param source an array to fill the list. | |
68 | * @throws IllegalOperationError If this class is instantiated directly, in other words, if there is <b>not</b> another class extending this class. | |
69 | */ | |
70 | public function AbstractList(source:Array = null) | |
71 | { | |
72 | 1 | super(source); |
73 | 1 | if (ReflectionUtil.classPathEquals(this, AbstractList)) throw new IllegalOperationError(ReflectionUtil.getClassName(this) + " is an abstract class and shouldn't be instantiated directly."); |
74 | 1 | } |
75 | ||
76 | /** | |
77 | * Appends the specified element to the end of this list (optional operation). | |
78 | * <p>Lists that support this operation may place limitations on what elements may be added to this list. | |
79 | * In particular, some lists will refuse to add <code>null</code> elements, and others will impose restrictions on the type of elements that may be added. | |
80 | * Lists classes should clearly specify in their documentation any restrictions on what elements may be added.</p> | |
81 | * <p>If a list refuses to add a particular element for any reason other than that it already contains the element, it <em>must</em> throw an error (rather than returning <code>false</code>). | |
82 | * This preserves the invariant that a list always contains the specified element after this call returns.</p> | |
83 | * <p>This implementation calls <code>addAt(size(), element)</code>.</p> | |
84 | * <p>Note that this implementation throws an <code>UnsupportedOperationError</code> unless <code>addAt</code> is overridden.</p> | |
85 | * | |
86 | * @param element the element to be added. | |
87 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>add</code> operation is not supported by this list. | |
88 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element prevents it from being added to this list. | |
89 | * @throws ArgumentError if the specified element is <code>null</code> and this list does not permit <code>null</code> elements. | |
90 | * @return <code>true</code> if this list changed as a result of the call. Returns <code>false</code> if this list does not permit duplicates and already contains the specified element. | |
91 | */ | |
92 | override public function add(element:*): Boolean | |
93 | { | |
94 | 1 | return addAt(size(), element); |
95 | } | |
96 | ||
97 | /** | |
98 | * Adds all of the elements in the specified collection to this list (optional operation). | |
99 | * <p>This implementation calls <code>addAllAt(size(), collection)</code>.</p> | |
100 | * <p>Note that this implementation will throw an <code>UnsupportedOperationError</code> unless <code>addAt</code> is overridden (assuming the specified collection is non-empty).</p> | |
101 | * | |
102 | * @param collection the collection containing elements to be added to this list. | |
103 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>addAll</code> operation is not supported by this list. | |
104 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of an element of the specified collection prevents it from being added to this list. | |
105 | * @throws ArgumentError if the specified collection contains a <code>null</code> element and this list does not permit <code>null</code> elements, or if the specified collection is <code>null</code>. | |
106 | * @return <code>true</code> if this list changed as a result of the call. | |
107 | */ | |
108 | override public function addAll(collection:ICollection): Boolean | |
109 | { | |
110 | 1 | return addAllAt(size(), collection); |
111 | } | |
112 | ||
113 | /** | |
114 | * Inserts all of the elements in the specified collection into this list at the specified position (optional operation). | |
115 | * Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). | |
116 | * The new elements will appear in this list in the order that they are returned by the specified collection's iterator. | |
117 | * <p>This implementation gets an iterator over the specified collection and iterates over it, inserting the elements obtained from the iterator into this list at the appropriate position, one at a time, using <code>addAt</code>. | |
118 | * Other implementations can override this method for efficiency.</p> | |
119 | * <p>Note that this implementation throws an <code>UnsupportedOperationError</code> unless <code>addAt</code> is overridden.</p> | |
120 | * | |
121 | * @param index index at which to insert the first element from the specified collection. | |
122 | * @param collection the collection containing elements to be added to this list. | |
123 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>addAllAt</code> operation is not supported by this list. | |
124 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of an element of the specified collection prevents it from being added to this list. | |
125 | * @throws ArgumentError if the specified collection contains a <code>null</code> element and this list does not permit <code>null</code> elements, or if the specified collection is <code>null</code>. | |
126 | * @throws org.as3collections.errors.IndexOutOfBoundsError if the index is out of range <code>(index < 0 || index > size())</code>. | |
127 | * @return <code>true</code> if this list changed as a result of the call. | |
128 | */ | |
129 | public function addAllAt(index:int, collection:ICollection): Boolean | |
130 | { | |
131 | 1 | if (!collection) throw new ArgumentError("The 'collection' argument must not be 'null'."); |
132 | 1 | if (collection.isEmpty()) return false; |
133 | 1 | checkIndex(index, size()); |
134 | ||
135 | 1 | var prevSize:int = size(); |
136 | 1 | var it:IIterator = collection.iterator(); |
137 | ||
138 | 1 | while (it.hasNext()) |
139 | { | |
140 | 1 | if (addAt(index, it.next())) index++; |
141 | } | |
142 | ||
143 | 1 | return prevSize != size(); |
144 | } | |
145 | ||
146 | /** | |
147 | * Inserts the specified element at the specified position in this list (optional operation). | |
148 | * Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices). | |
149 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
150 | * | |
151 | * @param index index at which the specified element is to be inserted. | |
152 | * @param element the element to be added. | |
153 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>addAt</code> operation is not supported by this list. | |
154 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element prevents it from being added to this list. | |
155 | * @throws ArgumentError if the specified element is <code>null</code> and this list does not permit <code>null</code> elements. | |
156 | * @throws org.as3collections.errors.IndexOutOfBoundsError if the index is out of range <code>(index < 0 || index > size())</code>. | |
157 | * @return <code>true</code> if this list changed as a result of the call. Returns <code>false</code> if this list does not permit duplicates and already contains the specified element. | |
158 | */ | |
159 | public function addAt(index:int, element:*): Boolean | |
160 | { | |
161 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
162 | } | |
163 | ||
164 | /** | |
165 | * This method uses <code>CollectionUtil.equalConsideringOrder</code> method to perform equality, sending this list and <code>other</code> argument. | |
166 | * | |
167 | * @param other the object to be compared for equality. | |
168 | * @return <code>true</code> if the arbitrary evaluation considers the objects equal. | |
169 | * @see org.as3collections.utils.CollectionUtil#equalConsideringOrder() CollectionUtil.equalConsideringOrder() | |
170 | */ | |
171 | override public function equals(other:*): Boolean | |
172 | { | |
173 | 1 | return CollectionUtil.equalConsideringOrder(this, other); |
174 | } | |
175 | ||
176 | /** | |
177 | * @inheritDoc | |
178 | * @throws org.as3collections.errors.IndexOutOfBoundsError if the index is out of range <code>(index < 0 || index >= size())</code>. | |
179 | */ | |
180 | public function getAt(index:int): * | |
181 | { | |
182 | 1 | if (isEmpty()) throw new IndexOutOfBoundsError("This list is empty."); |
183 | ||
184 | 1 | checkIndex(index, size() - 1); |
185 | 1 | return data[index]; |
186 | } | |
187 | ||
188 | /** | |
189 | * Returns the index of the <em>first occurrence</em> of the specified element in this list, or -1 if this list does not contain the element. | |
190 | * <p>If all elements in this list and <code>element</code> argument implement <code>org.as3coreaddendum.system.IEquatable</code>, this implementation will iterate over this list using <code>equals</code> method of the elements. | |
191 | * Otherwise this implementation uses native <code>Array.indexOf</code> method.</p> | |
192 | * | |
193 | * @param element the element to search for. | |
194 | * @param fromIndex the position in the list from which to start searching for the element. | |
195 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element is incompatible with this list (optional). | |
196 | * @throws ArgumentError if the specified element is <code>null</code> and this list does not permit <code>null</code> elements (optional). | |
197 | * @return the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element. | |
198 | */ | |
199 | public function indexOf(element:*, fromIndex:int = 0): int | |
200 | { | |
201 | 1 | if (allEquatable && element is IEquatable) |
202 | { | |
203 | 1 | return indexOfByEquality(element, fromIndex); |
204 | } | |
205 | else | |
206 | { | |
207 | 1 | return data.indexOf(element, fromIndex); |
208 | } | |
209 | } | |
210 | ||
211 | /** | |
212 | * Returns the index of the <em>last occurrence</em> of the specified element in this list, or -1 if this list does not contain the element. | |
213 | * <p>If all elements in this list and <code>element</code> argument implement <code>org.as3coreaddendum.system.IEquatable</code>, this implementation will iterate over this list using <code>equals</code> method of the elements. | |
214 | * Otherwise this implementation uses native <code>Array.lastIndexOf</code> method.</p> | |
215 | * | |
216 | * @param element the element to search for. | |
217 | * @param fromIndex the position in the list from which to start searching for the element. The default is the maximum value allowed for an index. If you do not specify <code>fromIndex</code>, the search starts at the last item in the list. | |
218 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element is incompatible with this list (optional). | |
219 | * @throws ArgumentError if the specified element is <code>null</code> and this list does not permit <code>null</code> elements (optional). | |
220 | * @return the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element. | |
221 | */ | |
222 | public function lastIndexOf(element:*, fromIndex:int = 0x7fffffff): int | |
223 | { | |
224 | 1 | if (allEquatable && element is IEquatable) |
225 | { | |
226 | 1 | return lastIndexOfByEquality(element, fromIndex); |
227 | } | |
228 | else | |
229 | { | |
230 | 1 | return data.lastIndexOf(element, fromIndex); |
231 | } | |
232 | } | |
233 | ||
234 | /** | |
235 | * Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. | |
236 | * The specified index indicates the first element that would be returned by an initial call to <code>next</code>. | |
237 | * An initial call to <code>previous</code> would return the element with the specified index minus one. | |
238 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
239 | * | |
240 | * @param index index of first element to be returned from the list iterator (by a call to the <code>next</code> method) | |
241 | * @return a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. | |
242 | * @see org.as3collections.IListIterator IListIterator | |
243 | */ | |
244 | public function listIterator(index:int = 0): IListIterator | |
245 | { | |
246 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
247 | } | |
248 | ||
249 | /** | |
250 | * Removes the element at the specified position in this list (optional operation). | |
251 | * Shifts any subsequent elements to the left (subtracts one from their indices). | |
252 | * Returns the element that was removed from the list. | |
253 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
254 | * | |
255 | * @param index the index of the element to be removed. | |
256 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>removeAt</code> operation is not supported by this list. | |
257 | * @throws org.as3collections.errors.IndexOutOfBoundsError if the index is out of range <code>(index < 0 || index >= size())</code>. | |
258 | * @return the element previously at the specified position. | |
259 | */ | |
260 | public function removeAt(index:int): * | |
261 | { | |
262 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
263 | } | |
264 | ||
265 | /** | |
266 | * Removes all of the elements whose index is between <code>fromIndex</code>, inclusive, and <code>toIndex</code>, exclusive (optional operation). | |
267 | * Shifts any subsequent elements to the left (subtracts their indices). | |
268 | * <p>If <code>toIndex == fromIndex</code>, this operation has no effect.</p> | |
269 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
270 | * | |
271 | * @param fromIndex the index to start removing elements (inclusive). | |
272 | * @param toIndex the index to stop removing elements (exclusive). | |
273 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>removeRange</code> operation is not supported by this list. | |
274 | * @throws org.as3collections.errors.IndexOutOfBoundsError if <code>fromIndex</code> or <code>toIndex</code> is out of range <code>(index < 0 || index > size())</code>. | |
275 | * @return a new collection containing all the removed elements. | |
276 | */ | |
277 | public function removeRange(fromIndex:int, toIndex:int): ICollection | |
278 | { | |
279 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
280 | } | |
281 | ||
282 | /** | |
283 | * Reverses the order of the elements in this list. | |
284 | * This implementation uses native <code>Array.reverse</code> method. | |
285 | */ | |
286 | public function reverse(): void | |
287 | { | |
288 | 1 | if (size() < 2) return; |
289 | 1 | data.reverse(); |
290 | 1 | } |
291 | ||
292 | /** | |
293 | * Replaces the element at the specified position in this list with the specified element (optional operation). | |
294 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
295 | * | |
296 | * @param index index of the element to replace. | |
297 | * @param element element to be stored at the specified position. | |
298 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>setAt</code> operation is not supported by this list. | |
299 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element prevents it from being added to this list. | |
300 | * @throws ArgumentError if the specified element is <code>null</code> and this list does not permit <code>null</code> elements. | |
301 | * @throws org.as3collections.errors.IndexOutOfBoundsError if the index is out of range <code>(index < 0 || index >= size())</code>. | |
302 | * @return the element previously at the specified position. | |
303 | */ | |
304 | public function setAt(index:int, element:*): * | |
305 | { | |
306 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
307 | } | |
308 | ||
309 | /** | |
310 | * Returns a new list that is a view of the portion of this list between the specified <code>fromIndex</code>, inclusive, and <code>toIndex</code>, exclusive. | |
311 | * <p>This list should not be modified.</p> | |
312 | * <p>The returned list should support all of the optional list operations supported by this list.</p> | |
313 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
314 | * | |
315 | * @param fromIndex the index to start retrieving elements (inclusive). | |
316 | * @param toIndex the index to stop retrieving elements (exclusive). | |
317 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>subList</code> operation is not supported by this list. | |
318 | * @throws org.as3collections.errors.IndexOutOfBoundsError if <code>fromIndex</code> or <code>toIndex</code> is out of range <code>(index < 0 || index > size())</code>. | |
319 | * @return a new list that is a view of the specified range within this list. | |
320 | */ | |
321 | public function subList(fromIndex:int, toIndex:int): IList | |
322 | { | |
323 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
324 | } | |
325 | ||
326 | /** | |
327 | * @private | |
328 | */ | |
329 | protected function checkIndex(index:int, max:int):void | |
330 | { | |
331 | 1 | if (index < 0 || index > max) throw new IndexOutOfBoundsError("The 'index' argument is out of bounds: " + index + " (min: 0, max: " + max + ")"); |
332 | 1 | } |
333 | ||
334 | /** | |
335 | * @private | |
336 | */ | |
337 | override protected function elementAdded(element:*): void | |
338 | { | |
339 | 1 | super.elementAdded(element); |
340 | 1 | _modCount++; |
341 | 1 | } |
342 | ||
343 | /** | |
344 | * @private | |
345 | */ | |
346 | override protected function elementRemoved(element:*): void | |
347 | { | |
348 | 1 | super.elementRemoved(element); |
349 | 1 | _modCount++; |
350 | 1 | } |
351 | ||
352 | /** | |
353 | * @private | |
354 | */ | |
355 | private function indexOfByEquality(element:*, fromIndex:int = 0): int | |
356 | { | |
357 | 1 | var it:IListIterator = listIterator(fromIndex); |
358 | var e:IEquatable; | |
359 | ||
360 | 1 | while (it.hasNext()) |
361 | { | |
362 | 1 | e = it.next(); |
363 | 1 | if (e.equals(element)) return it.pointer(); |
364 | } | |
365 | ||
366 | 1 | return -1; |
367 | } | |
368 | ||
369 | /** | |
370 | * @private | |
371 | */ | |
372 | private function lastIndexOfByEquality(element:*, fromIndex:int = 0x7fffffff): int | |
373 | { | |
374 | 1 | if (fromIndex < 0x7fffffff) fromIndex++; |
375 | 1 | if (fromIndex > size()) fromIndex = size(); |
376 | ||
377 | 1 | var it:IListIterator = listIterator(fromIndex); |
378 | var e:IEquatable; | |
379 | ||
380 | 1 | while (it.hasPrevious()) |
381 | { | |
382 | 1 | e = it.previous(); |
383 | 1 | if (e.equals(element)) return it.nextIndex(); |
384 | } | |
385 | ||
386 | 1 | return -1; |
387 | } | |
388 | ||
389 | } | |
390 | ||
391 | } |