Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
AbstractArrayCollection |
|
| 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.utils.CollectionUtil; | |
33 | import org.as3coreaddendum.errors.CloneNotSupportedError; | |
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>ICollection</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 class maintains a native <code>Array</code> object as its source.</p> | |
46 | * <p><b>IMPORTANT:</b></p> | |
47 | * <p>This class implements equality through <code>org.as3coreaddendum.system.IEquatable</code> interface in the <code>equals</code> method and in all methods that compares the elements inside this collection (i.e. <code>contains</code>, <code>containsAll</code>, <code>remove</code>, <code>removeAll</code> and <code>retainAll</code>).</p> | |
48 | * <p>In order to this collection uses the <code>equals</code> method of its elements in comparisons (rather than default '==' operator), <b>all elements in this collection must implement the</b> <code>org.as3coreaddendum.system.IEquatable</code> <b>interface and also the supplied element.</b></p> | |
49 | * <p>For example:</p> | |
50 | * <p>myCollection.contains(myElement);</p> | |
51 | * <p>All elements inside <code>myCollection</code>, and <code>myElement</code>, must implement the <code>org.as3coreaddendum.system.IEquatable</code> interface so that <code>equals</code> method of each element can be used in the comparison. | |
52 | * Otherwise '==' operator is used.</p> | |
53 | * <p>All subclasses of this class <em>must</em> conform with this behavior.</p> | |
54 | * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation. | |
55 | * 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> | |
56 | * | |
57 | * @see org.as3collections.ICollection ICollection | |
58 | * @see org.as3collections.AbstractList AbstractList | |
59 | * @see org.as3collections.AbstractQueue AbstractQueue | |
60 | * @see http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/IEquatable.html org.as3coreaddendum.system.IEquatable | |
61 | * @author Flávio Silva | |
62 | */ | |
63 | public class AbstractArrayCollection implements ICollection | |
64 | { | |
65 | /** | |
66 | * @private | |
67 | */ | |
68 | protected var _totalEquatable: int; | |
69 | ||
70 | private var _data: Array; | |
71 | ||
72 | /** | |
73 | * @inheritDoc | |
74 | */ | |
75 | public function get allEquatable(): Boolean { return _totalEquatable == size(); } | |
76 | ||
77 | /** | |
78 | * @private | |
79 | */ | |
80 | protected function get data(): Array { return _data; } | |
81 | ||
82 | /** | |
83 | * This is an abstract class and shouldn't be instantiated directly. | |
84 | * | |
85 | * @param source an array to fill the collection. | |
86 | * @throws IllegalOperationError If this class is instantiated directly. In other words, if there is <em>not</em> another class extending this class. | |
87 | */ | |
88 | public function AbstractArrayCollection(source:Array = null) | |
89 | 1 | { |
90 | 1 | if (ReflectionUtil.classPathEquals(this, AbstractArrayCollection)) throw new IllegalOperationError(ReflectionUtil.getClassName(this) + " is an abstract class and shouldn't be instantiated directly."); |
91 | ||
92 | 1 | _data = []; |
93 | ||
94 | 1 | if (source && source.length > 0) |
95 | { | |
96 | 1 | _data.push.apply(_data, source); |
97 | ||
98 | 1 | var it:IIterator = iterator(); |
99 | var e:*; | |
100 | ||
101 | 1 | while(it.hasNext()) |
102 | { | |
103 | 1 | e = it.next(); |
104 | 1 | elementAdded(e); |
105 | } | |
106 | } | |
107 | 1 | } |
108 | ||
109 | /** | |
110 | * Ensures that this collection contains the specified element (optional operation). | |
111 | * <p>Collections that support this operation may place limitations on what elements may be added to this collection. | |
112 | * In particular, some collections will refuse to add <code>null</code> elements, and others will impose restrictions on the type of elements that may be added. | |
113 | * Collection classes should clearly specify in their documentation any restrictions on what elements may be added.</p> | |
114 | * <p>If a collection 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>). | |
115 | * This preserves the invariant that a collection always contains the specified element after this call returns.</p> | |
116 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
117 | * | |
118 | * @param element the element to be added. | |
119 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>add</code> operation is not supported by this collection. | |
120 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element prevents it from being added to this collection. | |
121 | * @throws ArgumentError if the specified element is <code>null</code> and this collection does not permit <code>null</code> elements. | |
122 | * @return <code>true</code> if this collection changed as a result of the call. Returns <code>false</code> if this collection does not permit duplicates and already contains the specified element. | |
123 | */ | |
124 | public function add(element:*): Boolean | |
125 | { | |
126 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
127 | } | |
128 | ||
129 | /** | |
130 | * Adds all of the elements in the specified collection to this collection (optional operation). | |
131 | * <p>This implementation iterates over the specified collection, and adds each object returned by the iterator to this collection, in turn.</p> | |
132 | * <p>Note that this implementation will throw an <code>UnsupportedOperationError</code> unless <code>add</code> is overridden (assuming the specified collection is non-empty).</p> | |
133 | * | |
134 | * @param collection the collection containing elements to be added to this collection. | |
135 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>addAll</code> operation is not supported by this collection. | |
136 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of an element of the specified collection prevents it from being added to this collection. | |
137 | * @throws ArgumentError if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements, or if the specified collection is <code>null</code>. | |
138 | * @return <code>true</code> if this collection changed as a result of the call. | |
139 | */ | |
140 | public function addAll(collection:ICollection): Boolean | |
141 | { | |
142 | 1 | if (!collection) throw new ArgumentError("The 'collection' argument must not be 'null'."); |
143 | 1 | if (collection.isEmpty()) return false; |
144 | ||
145 | 1 | var prevSize:int = size(); |
146 | 1 | var it:IIterator = collection.iterator(); |
147 | ||
148 | 1 | while (it.hasNext()) |
149 | { | |
150 | 1 | add(it.next()); |
151 | } | |
152 | ||
153 | 1 | return prevSize != size(); |
154 | } | |
155 | ||
156 | /** | |
157 | * Removes all of the elements from this collection (optional operation). | |
158 | * The collection will be empty after this method returns. | |
159 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
160 | * | |
161 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the clear operation is not supported by this collection. | |
162 | */ | |
163 | public function clear(): void | |
164 | { | |
165 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
166 | } | |
167 | ||
168 | /** | |
169 | * Creates and return a shallow copy of this collection. | |
170 | * <p>This implementation always throws a <code>org.as3coreaddendum.errors.CloneNotSupportedError</code>.</p> | |
171 | * | |
172 | * @throws org.as3coreaddendum.errors.CloneNotSupportedError if this collection doesn't support clone. | |
173 | * @return A new object that is a shallow copy of this instance. | |
174 | */ | |
175 | public function clone(): * | |
176 | { | |
177 | 1 | throw new CloneNotSupportedError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
178 | } | |
179 | ||
180 | /** | |
181 | * Returns <code>true</code> if this collection contains the specified object. | |
182 | * <p>If all elements in this collection and <code>o</code> argument implement <code>org.as3coreaddendum.system.IEquatable</code>, this implementation will iterate over this collection using <code>equals</code> method of the elements. | |
183 | * Otherwise this implementation uses native <code>Array.indexOf</code> method.</p> | |
184 | * | |
185 | * @param o object whose presence in this collection is to be tested. | |
186 | * @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified object is incompatible with this collection (optional). | |
187 | * @throws ArgumentError if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional). | |
188 | * @return <code>true</code> if this collection contains the specified object. | |
189 | */ | |
190 | public function contains(o:*): Boolean | |
191 | { | |
192 | 1 | if (isEmpty()) return false; |
193 | ||
194 | 1 | if (allEquatable && o is IEquatable) return containsByEquality(o); |
195 | ||
196 | 1 | return _data.indexOf(o) != -1; |
197 | } | |
198 | ||
199 | /** | |
200 | * Returns <code>true</code> if this collection contains all of the elements in the specified collection. | |
201 | * <p>This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. | |
202 | * If all elements are so contained <code>true</code> is returned, otherwise <code>false</code>.</p> | |
203 | * <p>If all elements in this collection and all elements in <code>collection</code> argument implement <code>org.as3coreaddendum.system.IEquatable</code>, <code>equals</code> method of the elements will be used. | |
204 | * Otherwise this implementation uses native <code>Array.indexOf</code> method.</p> | |
205 | * | |
206 | * @param collection the collection to be checked for containment in this collection. | |
207 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in the specified collection are incompatible with this collection (optional). | |
208 | * @throws ArgumentError if the specified collection contains one or more <code>null</code> elements and this collection does not permit <code>null</code> elements (optional), or if the specified collection is <code>null</code>. | |
209 | * @return <code>true</code> if this collection contains all of the elements in the specified collection. | |
210 | */ | |
211 | public function containsAll(collection:ICollection): Boolean | |
212 | { | |
213 | 1 | if (!collection) throw new ArgumentError("The 'collection' argument must not be 'null'."); |
214 | 1 | if (collection.isEmpty()) return true; |
215 | 1 | if (isEmpty()) return false; |
216 | ||
217 | 1 | if (allEquatable && collection.allEquatable) return containsAllByEquality(collection); |
218 | ||
219 | 1 | var it:IIterator = collection.iterator(); |
220 | ||
221 | 1 | while (it.hasNext()) |
222 | { | |
223 | 1 | if (!contains(it.next())) return false; |
224 | } | |
225 | ||
226 | 1 | return true; |
227 | } | |
228 | ||
229 | /** | |
230 | * This method uses <code>CollectionUtil.equalNotConsideringOrder</code> method to perform equality, sending this collection and <code>other</code> argument. | |
231 | * | |
232 | * @param other the object to be compared for equality. | |
233 | * @return <code>true</code> if the arbitrary evaluation considers the objects equal. | |
234 | * @see org.as3collections.utils.CollectionUtil#equalNotConsideringOrder() CollectionUtil.equalNotConsideringOrder() | |
235 | * @see http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/IEquatable.html org.as3coreaddendum.system.IEquatable | |
236 | */ | |
237 | public function equals(other:*): Boolean | |
238 | { | |
239 | 1 | return CollectionUtil.equalNotConsideringOrder(this, other); |
240 | } | |
241 | ||
242 | /** | |
243 | * @inheritDoc | |
244 | */ | |
245 | public function isEmpty(): Boolean | |
246 | { | |
247 | 1 | return size() == 0; |
248 | } | |
249 | ||
250 | /** | |
251 | * Returns an iterator over a set of elements. | |
252 | * <p>This implementation always throws an <code>UnsupportedOperationError</code>.</p> | |
253 | * | |
254 | * @return an iterator over a set of elements. | |
255 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError this method must be overridden in subclass. | |
256 | * @see org.as3collections.IIterator IIterator | |
257 | */ | |
258 | public function iterator(): IIterator | |
259 | { | |
260 | 1 | throw new UnsupportedOperationError("Method must be overridden in subclass: " + ReflectionUtil.getClassPath(this)); |
261 | } | |
262 | ||
263 | /** | |
264 | * Removes a single instance (only one occurrence) of the specified object from this collection, if it is present (optional operation). | |
265 | * <p>If all elements in this collection and <code>o</code> argument implement <code>org.as3coreaddendum.system.IEquatable</code>, this implementation iterates over this collection looking for the specified element. | |
266 | * If it finds the element, it removes the element from the collection using the iterator's remove method. | |
267 | * In this case, note that this implementation throws an <code>UnsupportedOperationError</code> if the iterator returned by this collection's iterator method does not implement the <code>remove</code> method.</p> | |
268 | * <p>Otherwise this implementation uses native <code>Array.indexOf</code> method to get the index of the element and then uses native <code>Array.splice</code> method to remove it.</p> | |
269 | * | |
270 | * @param o the object to be removed from this collection, if present. | |
271 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>remove</code> operation is not supported by this collection. | |
272 | * @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified object is incompatible with this collection (optional). | |
273 | * @throws ArgumentError if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional). | |
274 | * @return <code>true</code> if an object was removed as a result of this call. | |
275 | */ | |
276 | public function remove(o:*): Boolean | |
277 | { | |
278 | 1 | if (allEquatable && o is IEquatable) |
279 | { | |
280 | 1 | return removeByEquality(o); |
281 | } | |
282 | else | |
283 | { | |
284 | 1 | return removeByInstance(o); |
285 | } | |
286 | } | |
287 | ||
288 | /** | |
289 | * Removes all of this collection's elements that are also contained in the specified collection (optional operation). | |
290 | * After this call returns, this collection will contain no elements in common with the specified collection. | |
291 | * <p>This implementation iterates over this collection, checking each element returned by the iterator in turn to see if it's contained in the specified collection (using <code>contains</code> method of the <code>collection</code> argument). | |
292 | * If it's so contained, it's removed from this collection with the iterator's <code>remove</code> method.</p> | |
293 | * <p>Note that this implementation will throw an <code>UnsupportedOperationError</code> if the iterator returned by the iterator method does not implement the <code>remove</code> method and this collection contains one or more elements in common with the specified collection.</p> | |
294 | * | |
295 | * @param collection the collection containing elements to be removed from this collection. | |
296 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the removeAll operation is not supported by this collection. | |
297 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in the specified collection are incompatible with this collection (optional). | |
298 | * @throws ArgumentError if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements, or if the specified collection is <code>null</code>. | |
299 | * @return <code>true</code> if this collection changed as a result of the call. | |
300 | */ | |
301 | public function removeAll(collection:ICollection): Boolean | |
302 | { | |
303 | 1 | if (!collection) throw new ArgumentError("The 'collection' argument must not be 'null'."); |
304 | 1 | if (collection.isEmpty()) return false; |
305 | ||
306 | 1 | var prevSize:int = size(); |
307 | 1 | var it:IIterator = iterator(); |
308 | var e:*; | |
309 | ||
310 | 1 | while (it.hasNext()) |
311 | { | |
312 | 1 | e = it.next(); |
313 | ||
314 | 1 | if (collection.contains(e)) |
315 | { | |
316 | 1 | it.remove(); |
317 | 1 | elementRemoved(e); |
318 | } | |
319 | } | |
320 | ||
321 | 1 | return prevSize != size(); |
322 | } | |
323 | ||
324 | /** | |
325 | * Retains only the elements in this collection that are contained in the specified collection (optional operation). | |
326 | * In other words, removes from this collection all of its elements that are not contained in the specified collection. | |
327 | * <p>This implementation iterates over this collection, checking each element returned by the iterator in turn to see if it's contained in the specified collection (using <code>contains</code> method of the <code>collection</code> argument). | |
328 | * If it's not so contained, it's removed from this collection with the iterator's <code>remove</code> method.</p> | |
329 | * <p>Note that this implementation will throw an <code>UnsupportedOperationError</code> if the iterator returned by the iterator method does not implement the <code>remove</code> method and this collection contains one or more elements not present in the specified collection.</p> | |
330 | * | |
331 | * @param collection the collection containing elements to be retained in this collection. | |
332 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>retainAll</code> operation is not supported by this collection. | |
333 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in this collection are incompatible with the specified collection (optional). | |
334 | * @throws ArgumentError if the specified collection contains a <code>null</code> element and this collection does not permit <code>null</code> elements (optional), or if the specified collection is <code>null</code>. | |
335 | * @return <code>true</code> if this collection changed as a result of the call. | |
336 | */ | |
337 | public function retainAll(collection:ICollection): Boolean | |
338 | { | |
339 | 1 | if (!collection) throw new ArgumentError("The 'collection' argument must not be 'null'."); |
340 | 1 | if (collection.isEmpty()) return false; |
341 | ||
342 | 1 | var prevSize:int = size(); |
343 | 1 | var it:IIterator = iterator(); |
344 | var e:*; | |
345 | ||
346 | 1 | while (it.hasNext()) |
347 | { | |
348 | 1 | e = it.next(); |
349 | ||
350 | 1 | if (!collection.contains(e)) |
351 | { | |
352 | 1 | it.remove(); |
353 | 1 | elementRemoved(e); |
354 | } | |
355 | } | |
356 | ||
357 | 1 | return prevSize != size(); |
358 | } | |
359 | ||
360 | /** | |
361 | * @inheritDoc | |
362 | */ | |
363 | public function size(): int | |
364 | { | |
365 | 1 | return _data.length; |
366 | } | |
367 | ||
368 | /** | |
369 | * @inheritDoc | |
370 | */ | |
371 | public function toArray(): Array | |
372 | { | |
373 | 1 | return _data.concat(); |
374 | } | |
375 | ||
376 | /** | |
377 | * Returns the string representation of this instance. | |
378 | * <p>This method uses <code>CollectionUtil.toString</code> method.</p> | |
379 | * | |
380 | * @return the string representation of this instance. | |
381 | * @see org.as3collections.utils.CollectionUtil#toString() CollectionUtil.toString() | |
382 | */ | |
383 | public function toString(): String | |
384 | { | |
385 | 1 | return CollectionUtil.toString(this); |
386 | } | |
387 | ||
388 | /** | |
389 | * @private | |
390 | */ | |
391 | protected function elementAdded(element:*): void | |
392 | { | |
393 | 1 | if (element && element is IEquatable) _totalEquatable++; |
394 | 1 | } |
395 | ||
396 | /** | |
397 | * @private | |
398 | */ | |
399 | protected function elementRemoved(element:*): void | |
400 | { | |
401 | 1 | if (element && element is IEquatable) _totalEquatable--; |
402 | 1 | } |
403 | ||
404 | /** | |
405 | * @private | |
406 | */ | |
407 | private function containsAllByEquality(collection:ICollection): Boolean | |
408 | { | |
409 | 1 | var it:IIterator = collection.iterator(); |
410 | ||
411 | 1 | while (it.hasNext()) |
412 | { | |
413 | 1 | if (!containsByEquality(it.next())) return false; |
414 | } | |
415 | ||
416 | 1 | return true; |
417 | } | |
418 | ||
419 | /** | |
420 | * @private | |
421 | */ | |
422 | private function containsByEquality(o:*): Boolean | |
423 | { | |
424 | 1 | var it:IIterator = iterator(); |
425 | var e:IEquatable; | |
426 | ||
427 | 1 | while (it.hasNext()) |
428 | { | |
429 | 1 | e = it.next(); |
430 | 1 | if (e.equals(o)) return true; |
431 | } | |
432 | ||
433 | 1 | return false; |
434 | } | |
435 | ||
436 | /** | |
437 | * @private | |
438 | */ | |
439 | private function removeByEquality(o:*): Boolean | |
440 | { | |
441 | 1 | var it:IIterator = iterator(); |
442 | var e:IEquatable; | |
443 | var removed:Boolean; | |
444 | ||
445 | 1 | while (it.hasNext()) |
446 | { | |
447 | 1 | e = it.next(); |
448 | ||
449 | 1 | if (e.equals(o)) |
450 | { | |
451 | 1 | it.remove(); |
452 | 1 | elementRemoved(e); |
453 | 1 | removed = true; |
454 | 1 | break; |
455 | } | |
456 | } | |
457 | ||
458 | 1 | return removed; |
459 | } | |
460 | ||
461 | /** | |
462 | * @private | |
463 | */ | |
464 | private function removeByInstance(o:*): Boolean | |
465 | { | |
466 | 1 | var index:int = _data.indexOf(o); |
467 | 1 | if (index == -1) return false; |
468 | ||
469 | 1 | _data.splice(index, 1); |
470 | 1 | elementRemoved(o); |
471 | ||
472 | 1 | return true; |
473 | } | |
474 | ||
475 | } | |
476 | ||
477 | } |