/[classpath]/classpath/java/util/Collection.java
ViewVC logotype

Diff of /classpath/java/util/Collection.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.6 by mark, Sun Feb 18 15:39:58 2001 UTC revision 1.7 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* Collection.java -- Interface that represents a collection of objects  /* Collection.java -- Interface that represents a collection of objects
2     Copyright (C) 1998 Free Software Foundation, Inc.     Copyright (C) 1998, 2001 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 25  This exception does not however invalida Line 25  This exception does not however invalida
25  executable file might be covered by the GNU General Public License. */  executable file might be covered by the GNU General Public License. */
26    
27    
 // TO DO:  
 // ~ Maybe some more @see clauses would be helpful.  
   
28  package java.util;  package java.util;
29    
30  /**  /**
# Line 57  package java.util; Line 54  package java.util;
54   * and returns a collection containing the same elements (that is, creates a   * and returns a collection containing the same elements (that is, creates a
55   * copy of the argument using its own implementation).   * copy of the argument using its own implementation).
56   *   *
57   * @see java.util.List   * @author Original author unknown
58   * @see java.util.Set   * @author Eric Blake <ebb9@email.byu.edu>
59   * @see java.util.AbstractCollection   * @see List
60     * @see Set
61     * @see Map
62     * @see SortedSet
63     * @see SortedMap
64     * @see HashSet
65     * @see TreeSet
66     * @see ArrayList
67     * @see LinkedList
68     * @see Vector
69     * @see Collections
70     * @see Arrays
71     * @see AbstractCollection
72     * @since 1.2
73     * @status updated to 1.4
74   */   */
75  public interface Collection  public interface Collection
76  {  {
# Line 67  public interface Collection Line 78  public interface Collection
78     * Add an element to this collection.     * Add an element to this collection.
79     *     *
80     * @param o the object to add.     * @param o the object to add.
81     * @returns true if the collection was modified as a result of this action.     * @return true if the collection was modified as a result of this action.
82     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
83     *   support the add operation.     *   support the add operation.
84     * @exception ClassCastException if o cannot be added to this collection due     * @throws ClassCastException if o cannot be added to this collection due
85     *   to its type.     *   to its type.
86     * @exception IllegalArgumentException if o cannot be added to this     * @throws IllegalArgumentException if o cannot be added to this
87     *   collection for some other reason.     *   collection for some other reason.
88     */     */
89    boolean add(Object o);    boolean add(Object o);
# Line 81  public interface Collection Line 92  public interface Collection
92     * Add the contents of a given collection to this collection.     * Add the contents of a given collection to this collection.
93     *     *
94     * @param c the collection to add.     * @param c the collection to add.
95     * @returns true if the collection was modified as a result of this action.     * @return true if the collection was modified as a result of this action.
96     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
97     *   support the addAll operation.     *   support the addAll operation.
98     * @exception ClassCastException if some element of c cannot be added to this     * @throws ClassCastException if some element of c cannot be added to this
99     *   collection due to its type.     *   collection due to its type.
100     * @exception IllegalArgumentException if some element of c cannot be added     * @throws IllegalArgumentException if some element of c cannot be added
101     *   to this collection for some other reason.     *   to this collection for some other reason.
102     */     */
103    boolean addAll(Collection c);    boolean addAll(Collection c);
# Line 95  public interface Collection Line 106  public interface Collection
106     * Clear the collection, such that a subsequent call to isEmpty() would     * Clear the collection, such that a subsequent call to isEmpty() would
107     * return true.     * return true.
108     *     *
109     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
110     *   support the clear operation.     *   support the clear operation.
111     */     */
112    void clear();    void clear();
# Line 105  public interface Collection Line 116  public interface Collection
116     * elements.     * elements.
117     *     *
118     * @param o the element to look for.     * @param o the element to look for.
119     * @returns true if this collection contains at least one element e such that     * @return true if this collection contains at least one element e such that
120     *   <code>o == null ? e == null : o.equals(e)</code>.     *   <code>o == null ? e == null : o.equals(e)</code>.
121     */     */
122    boolean contains(Object o);    boolean contains(Object o);
# Line 114  public interface Collection Line 125  public interface Collection
125     * Test whether this collection contains every element in a given collection.     * Test whether this collection contains every element in a given collection.
126     *     *
127     * @param c the collection to test for.     * @param c the collection to test for.
128     * @returns true if for every element o in c, contains(o) would return true.     * @return true if for every element o in c, contains(o) would return true.
129     */     */
130    boolean containsAll(Collection c);    boolean containsAll(Collection c);
131    
# Line 132  public interface Collection Line 143  public interface Collection
143     * preserve the symmetry of the relation.     * preserve the symmetry of the relation.
144     *     *
145     * @param o the object to compare to this collection.     * @param o the object to compare to this collection.
146     * @returns true if the o is equal to this collection.     * @return true if the o is equal to this collection.
147     */     */
148    boolean equals(Object o);    boolean equals(Object o);
149    
# Line 148  public interface Collection Line 159  public interface Collection
159     * method renders it impossible to correctly implement both Set and List, as     * method renders it impossible to correctly implement both Set and List, as
160     * the required implementations are mutually exclusive.     * the required implementations are mutually exclusive.
161     *     *
162     * @returns a hash code for this collection.     * @return a hash code for this collection.
163     */     */
164    int hashCode();    int hashCode();
165    
166    /**    /**
167     * Test whether this collection is empty, that is, if size() == 0.     * Test whether this collection is empty, that is, if size() == 0.
168     *     *
169     * @returns true if this collection contains no elements.     * @return true if this collection contains no elements.
170     */     */
171    boolean isEmpty();    boolean isEmpty();
172    
173    /**    /**
174     * Obtain an Iterator over this collection.     * Obtain an Iterator over this collection.
175     *     *
176     * @returns an Iterator over the elements of this collection, in any order.     * @return an Iterator over the elements of this collection, in any order.
177     */     */
178    Iterator iterator();    Iterator iterator();
179    
# Line 172  public interface Collection Line 183  public interface Collection
183     *   : o.equals(e)</code>.     *   : o.equals(e)</code>.
184     *     *
185     * @param o the object to remove.     * @param o the object to remove.
186     * @returns true if the collection changed as a result of this call, that is,     * @return true if the collection changed as a result of this call, that is,
187     *   if the collection contained at least one occurrence of o.     *   if the collection contained at least one occurrence of o.
188     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
189     *   support the remove operation.     *   support the remove operation.
190     */     */
191    boolean remove(Object o);    boolean remove(Object o);
# Line 183  public interface Collection Line 194  public interface Collection
194     * Remove all elements of a given collection from this collection. That is,     * Remove all elements of a given collection from this collection. That is,
195     * remove every element e such that c.contains(e).     * remove every element e such that c.contains(e).
196     *     *
197     * @returns true if this collection was modified as a result of this call.     * @return true if this collection was modified as a result of this call.
198     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
199     *   support the removeAll operation.     *   support the removeAll operation.
200     */     */
201    boolean removeAll(Collection c);    boolean removeAll(Collection c);
# Line 193  public interface Collection Line 204  public interface Collection
204     * Remove all elements of this collection that are not contained in a given     * Remove all elements of this collection that are not contained in a given
205     * collection. That is, remove every element e such that !c.contains(e).     * collection. That is, remove every element e such that !c.contains(e).
206     *     *
207     * @returns true if this collection was modified as a result of this call.     * @return true if this collection was modified as a result of this call.
208     * @exception UnsupportedOperationException if this collection does not     * @throws UnsupportedOperationException if this collection does not
209     *   support the retainAll operation.     *   support the retainAll operation.
210     */     */
211    boolean retainAll(Collection c);    boolean retainAll(Collection c);
# Line 202  public interface Collection Line 213  public interface Collection
213    /**    /**
214     * Get the number of elements in this collection.     * Get the number of elements in this collection.
215     *     *
216     * @returns the number of elements in the collection.     * @return the number of elements in the collection.
217     */     */
218    int size();    int size();
219    
220    /**    /**
221     * Copy the current contents of this collection into an array.     * Copy the current contents of this collection into an array.
222     *     *
223     * @returns an array of type Object[] and length equal to the size of this     * @return an array of type Object[] and length equal to the size of this
224     *   collection, containing the elements currently in this collection, in     *   collection, containing the elements currently in this collection, in
225     *   any order.     *   any order.
226     */     */
# Line 227  public interface Collection Line 238  public interface Collection
238     * if it is known that this collection does not contain any null elements.     * if it is known that this collection does not contain any null elements.
239     *     *
240     * @param a the array to copy this collection into.     * @param a the array to copy this collection into.
241     * @returns an array containing the elements currently in this collection, in     * @return an array containing the elements currently in this collection, in
242     *   any order.     *   any order.
243     * @exception ArrayStoreException if the type of any element of the     * @throws ArrayStoreException if the type of any element of the
244     *   collection is not a subtype of the element type of a.     *   collection is not a subtype of the element type of a.
245     */     */
246    Object[] toArray(Object[] a);    Object[] toArray(Object[] a);

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26