try to fix some minor dropdown bugs
[potlatch2.git] / org / idmedia / as3commons / util / Collection.as
1 /*
2  * Copyright the original author or authors.
3  * 
4  * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  * 
8  *      http://www.mozilla.org/MPL/MPL-1.1.html
9  * 
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 ´╗┐package org.idmedia.as3commons.util {
17   
18   /**
19    * The root interface in the <i>collection hierarchy</i>.  A collection
20    * represents a group of objects, known as its <i>elements</i>.  Some
21    * collections allow duplicate elements and others do not.  Some are ordered
22    * and others unordered.  The JDK does not provide any <i>direct</i>
23    * implementations of this interface: it provides implementations of more
24    * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>.  This interface
25    * is typically used to pass collections around and manipulate them where
26    * maximum generality is desired.
27    *
28    * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
29    * duplicate elements) should implement this interface directly.
30    *
31    * <p>The "destructive" methods contained in this interface, that is, the
32    * methods that modify the collection on which they operate, are specified to
33    * throw <tt>UnsupportedOperationException</tt> if this collection does not
34    * support the operation.  If this is the case, these methods may, but are not
35    * required to, throw an <tt>UnsupportedOperationException</tt> if the
36    * invocation would have no effect on the collection.  For example, invoking
37    * the #addAll(Collection) method on an unmodifiable collection may,
38    * but is not required to, throw the exception if the collection to be added
39    * is empty.
40    *
41    * <p>Some collection implementations have restrictions on the elements that
42    * they may contain.  For example, some implementations prohibit null elements,
43    * and some have restrictions on the types of their elements.  Attempting to
44    * add an ineligible element throws an unchecked exception, typically
45    * <tt>NullPointerException</tt> or <tt>ClassCastException</tt>.  Attempting
46    * to query the presence of an ineligible element may throw an exception,
47    * or it may simply return false; some implementations will exhibit the former
48    * behavior and some will exhibit the latter.  More generally, attempting an
49    * operation on an ineligible element whose completion would not result in
50    * the insertion of an ineligible element into the collection may throw an
51    * exception or it may succeed, at the option of the implementation.
52    * Such exceptions are marked as "optional" in the specification for this
53    * interface. 
54    *
55    * @author sleistner
56    */
57   public interface Collection {
58     
59     /**
60      * Ensures that this collection contains the specified element (optional
61      * operation).  Returns <tt>true</tt> if this collection changed as a
62      * result of the call.  (Returns <tt>false</tt> if this collection does
63      * not permit duplicates and already contains the specified element.)<p>
64      *
65      * Collections that support this operation may place limitations on what
66      * elements may be added to this collection.  In particular, some
67      * collections will refuse to add <tt>null</tt> elements, and others will
68      * impose restrictions on the type of elements that may be added.
69      * Collection classes should clearly specify in their documentation any
70      * restrictions on what elements may be added.<p>
71      *
72      * If a collection refuses to add a particular element for any reason
73      * other than that it already contains the element, it <i>must</i> throw
74      * an exception(rather than returning <tt>false</tt>).  This preserves
75      * the invariant that a collection always contains the specified element
76      * after this call returns.
77      *
78      * @param o element whose presence in this collection is to be ensured.
79      * @return <tt>true</tt> if this collection changed as a result of the
80      *         call
81      * 
82      * @throws UnsupportedOperationException <tt>add</tt> is not supported by
83      *         this collection.
84      * @throws NullPointerException if the specified element is null and this
85      *         collection does not support null elements.
86      * @throws IllegalArgumentException some aspect of this element prevents
87      *         it from being added to this collection.
88      */
89     function add(o:*):Boolean;
90     
91     /**
92      * Removes all of the elements from this collection (optional operation).
93      * This collection will be empty after this method returns unless it
94      * throws an exception.
95      *
96      * @throws UnsupportedOperationException if the <tt>clear</tt> method is
97      *         not supported by this collection.
98      */
99     function clear():void;
100     
101     /**
102      * Returns <tt>true</tt> if this collection contains the specified
103      * element.  More formally, returns <tt>true</tt> if and only if this
104      * collection contains at least one element <tt>e</tt> such that
105      * <tt>(value==null ? e==null : o.equals(e))</tt>.
106      *
107      * @param value element whose presence in this collection is to be tested.
108      * @return <tt>true</tt> if this collection contains the specified
109      *         element
110      * @throws NullPointerException if the specified element is null and this
111      *         collection does not support null elements (optional).
112      */
113     function contains(value:*):Boolean;
114     
115     /**
116      * Returns <tt>true</tt> if this collection contains all of the elements
117      * in the specified collection.
118      *
119      * @param  c collection to be checked for containment in this collection.
120      * @return <tt>true</tt> if this collection contains all of the elements
121      *         in the specified collection
122      * @throws NullPointerException if the specified collection contains one
123      *         or more null elements and this collection does not support null
124      *         elements(optional).
125      * @throws NullPointerException if the specified collection is
126      *         <tt>null</tt>.
127      * @see    #contains()
128      */
129     function containsAll(c:Collection):Boolean;
130     
131     /**
132      * Adds all of the elements in the specified collection to this collection
133      *(optional operation).  The behavior of this operation is undefined if
134      * the specified collection is modified while the operation is in progress.
135      * (This implies that the behavior of this call is undefined if the
136      * specified collection is this collection, and this collection is
137      * nonempty.)
138      *
139      * @param c elements to be inserted into this collection.
140      * @return <tt>true</tt> if this collection changed as a result of the
141      *         call
142      * 
143      * @throws UnsupportedOperationException if this collection does not
144      *         support the <tt>addAll</tt> method.
145      * @throws NullPointerException if the specified collection contains one
146      *         or more null elements and this collection does not support null
147      *         elements, or if the specified collection is <tt>null</tt>.
148      * @throws IllegalArgumentException some aspect of an element of the
149      *         specified collection prevents it from being added to this
150      *         collection.
151      * @see #add()
152      */
153     function addAll(c:Collection):Boolean;
154     
155     /**
156      * Returns <tt>true</tt> if this collection contains no elements.
157      *
158      * @return <tt>true</tt> if this collection contains no elements
159      */
160     function isEmpty():Boolean;
161     
162     /**
163      * Returns an iterator over the elements in this collection.  There are no
164      * guarantees concerning the order in which the elements are returned
165      * (unless this collection is an instance of some class that provides a
166      * guarantee).
167      * 
168      * @return an <tt>Iterator</tt> over the elements in this collection
169      */
170     function iterator():Iterator;
171     
172     /**
173      * Removes a single instance of the specified element from this
174      * collection, if it is present (optional operation).  More formally,
175      * removes an element <tt>e</tt> such that <tt>(value==null ?  e==null :
176      * o.equals(e))</tt>, if this collection contains one or more such
177      * elements.  Returns true if this collection contained the specified
178      * element (or equivalently, if this collection changed as a result of the
179      * call).
180      *
181      * @param value element to be removed from this collection, if present.
182      * @return <tt>true</tt> if this collection changed as a result of the
183      *         call
184      * 
185      * @throws NullPointerException if the specified element is null and this
186      *         collection does not support null elements (optional).
187      * @throws UnsupportedOperationException remove is not supported by this
188      *         collection.
189      */
190     function remove(value:* = null):Boolean;
191     
192     /**
193      * Returns the number of elements in this collection.  If this collection
194      * contains more than <tt>Number.MAX_VALUE</tt> elements, returns
195      * <tt>Number.MAX_VALUE</tt>.
196      * 
197      * @return the number of elements in this collection
198      */
199     function size():int;
200     
201     /**
202      * Returns an array containing all of the elements in this collection.  If
203      * the collection makes any guarantees as to what order its elements are
204      * returned by its iterator, this method must return the elements in the
205      * same order.<p>
206      *
207      * The returned array will be "safe" in that no references to it are
208      * maintained by this collection.  (In other words, this method must
209      * allocate a new array even if this collection is backed by an array).
210      * The caller is thus free to modify the returned array.<p>
211      *
212      * This method acts as bridge between array-based and collection-based
213      * APIs.
214      *
215      * @return an array containing all of the elements in this collection
216      */
217     function toArray():Array;
218   }
219 }