Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
ICollection |
|
| 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 | 0 | package org.as3collections |
31 | { | |
32 | import org.as3collections.IIterable; | |
33 | import org.as3coreaddendum.system.ICloneable; | |
34 | import org.as3coreaddendum.system.IEquatable; | |
35 | ||
36 | /** | |
37 | * The root interface in the <em>collection hierarchy</em>. | |
38 | * A collection represents a group of objects, known as its <em>elements</em>. | |
39 | * <p>Some collections allow duplicate elements and others do not. Some are ordered and others unordered.</p> | |
40 | * <p>This interface is typically used to pass collections around and manipulate them where maximum generality is desired.</p> | |
41 | * <p>The methods that modify the collection are specified to throw org.as3coreaddendum.errors.UnsupportedOperationError if the collection does not support the operation. | |
42 | * These methods are documented as "optional operation".</p> | |
43 | * <p>This documentation is partially based in the <em>Java Collections Framework</em> JavaDoc documentation. | |
44 | * 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> | |
45 | * | |
46 | * @see org.as3collections.AbstractArrayCollection AbstractArrayCollection | |
47 | * @see org.as3collections.IIterable IIterable | |
48 | * @see org.as3collections.IList IList | |
49 | * @see http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/IEquatable.html org.as3coreaddendum.system.IEquatable | |
50 | * @see http://as3coreaddendum.org/en-us/documentation/asdoc/org/as3coreaddendum/system/ICloneable.html org.as3coreaddendum.system.ICloneable | |
51 | * @author Flávio Silva | |
52 | */ | |
53 | public interface ICollection extends IIterable, ICloneable, IEquatable | |
54 | { | |
55 | /** | |
56 | * Indicates whether all elements in this collection implement the interface <code>org.as3coreaddendum.system.IEquatable</code>. | |
57 | */ | |
58 | function get allEquatable(): Boolean; | |
59 | ||
60 | /** | |
61 | * Ensures that this collection contains the specified element (optional operation). | |
62 | * <p>Collections that support this operation may place limitations on what elements may be added to this collection. | |
63 | * 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. | |
64 | * Collection classes should clearly specify in their documentation any restrictions on what elements may be added.</p> | |
65 | * <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>). | |
66 | * This preserves the invariant that a collection always contains the specified element after this call returns.</p> | |
67 | * | |
68 | * @param element the element to be added. | |
69 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>add</code> operation is not supported by this collection. | |
70 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of the specified element prevents it from being added to this collection. | |
71 | * @throws ArgumentError if the specified element is <code>null</code> and this collection does not permit <code>null</code> elements. | |
72 | * @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. | |
73 | */ | |
74 | function add(element:*): Boolean; | |
75 | ||
76 | /** | |
77 | * Adds all of the elements in the specified collection to this collection (optional operation). | |
78 | * | |
79 | * @param collection collection containing elements to be added to this collection. | |
80 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>addAll</code> operation is not supported by this collection. | |
81 | * @throws org.as3coreaddendum.errors.ClassCastError if the class of an element of the specified collection prevents it from being added to this collection. | |
82 | * @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>. | |
83 | * @return <code>true</code> if this collection changed as a result of the call. | |
84 | */ | |
85 | function addAll(collection:ICollection): Boolean; | |
86 | ||
87 | /** | |
88 | * Removes all of the elements from this collection (optional operation). | |
89 | * The collection will be empty after this method returns. | |
90 | * | |
91 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>clear</code> operation is not supported by this collection. | |
92 | */ | |
93 | function clear(): void; | |
94 | ||
95 | /** | |
96 | * Returns <code>true</code> if this collection contains the specified object. | |
97 | * | |
98 | * @param o object whose presence in this collection is to be tested. | |
99 | * @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified object is incompatible with this collection (optional). | |
100 | * @throws ArgumentError if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional). | |
101 | * @return <code>true</code> if this collection contains the specified object. | |
102 | */ | |
103 | function contains(o:*): Boolean; | |
104 | ||
105 | /** | |
106 | * Returns <code>true</code> if this collection contains all of the elements in the specified collection. | |
107 | * | |
108 | * @param collection the collection to be checked for containment in this collection. | |
109 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in the specified collection are incompatible with this collection (optional). | |
110 | * @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>. | |
111 | * @return <code>true</code> if this collection contains all of the elements in the specified collection. | |
112 | */ | |
113 | function containsAll(collection:ICollection): Boolean; | |
114 | ||
115 | /** | |
116 | * Returns <code>true</code> if this collection contains no elements. | |
117 | * | |
118 | * @return <code>true</code> if this collection contains no elements. | |
119 | */ | |
120 | function isEmpty(): Boolean; | |
121 | ||
122 | /** | |
123 | * Removes a single instance (only one occurrence) of the specified object from this collection, if it is present (optional operation). | |
124 | * | |
125 | * @param o the object to be removed from this collection, if present. | |
126 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>remove</code> operation is not supported by this collection. | |
127 | * @throws org.as3coreaddendum.errors.ClassCastError if the type of the specified object is incompatible with this collection (optional). | |
128 | * @throws ArgumentError if the specified object is <code>null</code> and this collection does not permit <code>null</code> elements (optional). | |
129 | * @return <code>true</code> if an object was removed as a result of this call. | |
130 | * @see org.as3collections.utils.CollectionUtil#removeAllOccurances() CollectionUtil.removeAllOccurances() | |
131 | */ | |
132 | function remove(o:*): Boolean; | |
133 | ||
134 | /** | |
135 | * Removes all elements of this collection that are also contained in the specified collection (optional operation). | |
136 | * After this call returns, this collection will contain no elements in common with the specified collection. | |
137 | * | |
138 | * @param collection the collection containing elements to be removed from this collection. | |
139 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>removeAll</code> operation is not supported by this collection. | |
140 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in this collection are incompatible with the specified collection (optional). | |
141 | * @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>. | |
142 | * @return <code>true</code> if this collection has changed as a result of the call. | |
143 | */ | |
144 | function removeAll(collection:ICollection): Boolean; | |
145 | ||
146 | /** | |
147 | * Retains only the elements in this collection that are contained in the specified collection (optional operation). | |
148 | * In other words, removes from this collection all of its elements that are not contained in the specified collection. | |
149 | * | |
150 | * @param collection the collection containing elements to be retained in this collection. | |
151 | * @throws org.as3coreaddendum.errors.UnsupportedOperationError if the <code>retainAll</code> operation is not supported by this collection. | |
152 | * @throws org.as3coreaddendum.errors.ClassCastError if the types of one or more elements in this collection are incompatible with the specified collection (optional). | |
153 | * @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>. | |
154 | * @return <code>true</code> if this collection changed as a result of the call. | |
155 | */ | |
156 | function retainAll(collection:ICollection): Boolean; | |
157 | ||
158 | /** | |
159 | * Returns the number of elements in this collection. | |
160 | * | |
161 | * @return the number of elements in this collection. | |
162 | */ | |
163 | function size(): int; | |
164 | ||
165 | /** | |
166 | * Returns an array containing all of the elements in this collection. | |
167 | * <p>If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.</p> | |
168 | * <p>The returned array will be "safe" in that no references to it are maintained by this collection. | |
169 | * (In other words, this method must allocate a new array even if this collection is backed by an array). | |
170 | * The caller is thus free to modify the returned array.</p> | |
171 | * | |
172 | * @return a new array object containing all of the elements in this collection. | |
173 | */ | |
174 | function toArray(): Array; | |
175 | } | |
176 | ||
177 | } |