+++ /dev/null
-/* Collection.java -- Interface that represents a collection of objects
- Copyright (C) 1998, 2001 Free Software Foundation, Inc.
-
-This file is part of GNU Classpath.
-
-GNU Classpath is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2, or (at your option)
-any later version.
-
-GNU Classpath is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with GNU Classpath; see the file COPYING. If not, write to the
-Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
-02111-1307 USA.
-
-Linking this library statically or dynamically with other modules is
-making a combined work based on this library. Thus, the terms and
-conditions of the GNU General Public License cover the whole
-combination.
-
-As a special exception, the copyright holders of this library give you
-permission to link this library with independent modules to produce an
-executable, regardless of the license terms of these independent
-modules, and to copy and distribute the resulting executable under
-terms of your choice, provided that you also meet, for each linked
-independent module, the terms and conditions of the license of that
-module. An independent module is a module which is not derived from
-or based on this library. If you modify this library, you may extend
-this exception to your version of the library, but you are not
-obligated to do so. If you do not wish to do so, delete this
-exception statement from your version. */
-
-
-package java.util;
-
-/**
- * Interface that represents a collection of objects. This interface is the
- * root of the collection hierarchy, and does not provide any guarantees about
- * the order of its elements or whether or not duplicate elements are
- * permitted.
- * <p>
- * All methods of this interface that are defined to modify the collection are
- * defined as <dfn>optional</dfn>. An optional operation may throw an
- * UnsupportedOperationException if the data backing this collection does not
- * support such a modification. This may mean that the data structure is
- * immutable, or that it is read-only but may change ("unmodifiable"), or
- * that it is modifiable but of fixed size (such as an array), or any number
- * of other combinations.
- * <p>
- * A class that wishes to implement this interface should consider subclassing
- * AbstractCollection, which provides basic implementations of most of the
- * methods of this interface. Classes that are prepared to make guarantees
- * about ordering or about absence of duplicate elements should consider
- * implementing List or Set respectively, both of which are subinterfaces of
- * Collection.
- * <p>
- * A general-purpose implementation of the Collection interface should in most
- * cases provide at least two constructors: One which takes no arguments and
- * creates an empty collection, and one which takes a Collection as an argument
- * and returns a collection containing the same elements (that is, creates a
- * copy of the argument using its own implementation).
- *
- * @author Original author unknown
- * @author Eric Blake <ebb9@email.byu.edu>
- * @see List
- * @see Set
- * @see Map
- * @see SortedSet
- * @see SortedMap
- * @see HashSet
- * @see TreeSet
- * @see ArrayList
- * @see LinkedList
- * @see Vector
- * @see Collections
- * @see Arrays
- * @see AbstractCollection
- * @since 1.2
- * @status updated to 1.4
- */
-public interface Collection
-{
- /**
- * Add an element to this collection.
- *
- * @param o the object to add.
- * @return true if the collection was modified as a result of this action.
- * @throws UnsupportedOperationException if this collection does not
- * support the add operation.
- * @throws ClassCastException if o cannot be added to this collection due
- * to its type.
- * @throws IllegalArgumentException if o cannot be added to this
- * collection for some other reason.
- */
- boolean add(Object o);
-
- /**
- * Add the contents of a given collection to this collection.
- *
- * @param c the collection to add.
- * @return true if the collection was modified as a result of this action.
- * @throws UnsupportedOperationException if this collection does not
- * support the addAll operation.
- * @throws ClassCastException if some element of c cannot be added to this
- * collection due to its type.
- * @throws IllegalArgumentException if some element of c cannot be added
- * to this collection for some other reason.
- */
- boolean addAll(Collection c);
-
- /**
- * Clear the collection, such that a subsequent call to isEmpty() would
- * return true.
- *
- * @throws UnsupportedOperationException if this collection does not
- * support the clear operation.
- */
- void clear();
-
- /**
- * Test whether this collection contains a given object as one of its
- * elements.
- *
- * @param o the element to look for.
- * @return true if this collection contains at least one element e such that
- * <code>o == null ? e == null : o.equals(e)</code>.
- */
- boolean contains(Object o);
-
- /**
- * Test whether this collection contains every element in a given collection.
- *
- * @param c the collection to test for.
- * @return true if for every element o in c, contains(o) would return true.
- */
- boolean containsAll(Collection c);
-
- /**
- * Test whether this collection is equal to some object. The Collection
- * interface does not explicitly require any behaviour from this method, and
- * it may be left to the default implementation provided by Object. The Set
- * and List interfaces do, however, require specific behaviour from this
- * method.
- * <p>
- * If an implementation of Collection, which is not also an implementation of
- * Set or List, should choose to implement this method, it should take care
- * to obey the contract of the equals method of Object. In particular, care
- * should be taken to return false when o is a Set or a List, in order to
- * preserve the symmetry of the relation.
- *
- * @param o the object to compare to this collection.
- * @return true if the o is equal to this collection.
- */
- boolean equals(Object o);
-
- /**
- * Obtain a hash code for this collection. The Collection interface does not
- * explicitly require any behaviour from this method, and it may be left to
- * the default implementation provided by Object. The Set and List interfaces
- * do, however, require specific behaviour from this method.
- * <p>
- * If an implementation of Collection, which is not also an implementation of
- * Set or List, should choose to implement this method, it should take care
- * to obey the contract of the hashCode method of Object. Note that this
- * method renders it impossible to correctly implement both Set and List, as
- * the required implementations are mutually exclusive.
- *
- * @return a hash code for this collection.
- */
- int hashCode();
-
- /**
- * Test whether this collection is empty, that is, if size() == 0.
- *
- * @return true if this collection contains no elements.
- */
- boolean isEmpty();
-
- /**
- * Obtain an Iterator over this collection.
- *
- * @return an Iterator over the elements of this collection, in any order.
- */
- Iterator iterator();
-
- /**
- * Remove a single occurrence of an object from this collection. That is,
- * remove an element e, if one exists, such that <code>o == null ? e == null
- * : o.equals(e)</code>.
- *
- * @param o the object to remove.
- * @return true if the collection changed as a result of this call, that is,
- * if the collection contained at least one occurrence of o.
- * @throws UnsupportedOperationException if this collection does not
- * support the remove operation.
- */
- boolean remove(Object o);
-
- /**
- * Remove all elements of a given collection from this collection. That is,
- * remove every element e such that c.contains(e).
- *
- * @return true if this collection was modified as a result of this call.
- * @throws UnsupportedOperationException if this collection does not
- * support the removeAll operation.
- */
- boolean removeAll(Collection c);
-
- /**
- * Remove all elements of this collection that are not contained in a given
- * collection. That is, remove every element e such that !c.contains(e).
- *
- * @return true if this collection was modified as a result of this call.
- * @throws UnsupportedOperationException if this collection does not
- * support the retainAll operation.
- */
- boolean retainAll(Collection c);
-
- /**
- * Get the number of elements in this collection.
- *
- * @return the number of elements in the collection.
- */
- int size();
-
- /**
- * Copy the current contents of this collection into an array.
- *
- * @return an array of type Object[] and length equal to the size of this
- * collection, containing the elements currently in this collection, in
- * any order.
- */
- Object[] toArray();
-
- /**
- * Copy the current contents of this collection into an array. If the array
- * passed as an argument has length less than the size of this collection, an
- * array of the same run-time type as a, and length equal to the size of this
- * collection, is allocated using Reflection. Otherwise, a itself is used.
- * The elements of this collection are copied into it, and if there is space
- * in the array, the following element is set to null. The resultant array is
- * returned.
- * Note: The fact that the following element is set to null is only useful
- * if it is known that this collection does not contain any null elements.
- *
- * @param a the array to copy this collection into.
- * @return an array containing the elements currently in this collection, in
- * any order.
- * @throws ArrayStoreException if the type of any element of the
- * collection is not a subtype of the element type of a.
- */
- Object[] toArray(Object[] a);
-}
projects / msp430-gcc.git / blobdiff