diff -r 5be31d9fa455 -r d382dacfd73f rt/emul/compact/src/main/java/java/util/Set.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/rt/emul/compact/src/main/java/java/util/Set.java Tue Feb 26 16:54:16 2013 +0100 @@ -0,0 +1,385 @@ +/* + * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code 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 + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package java.util; + +/** + * A collection that contains no duplicate elements. More formally, sets + * contain no pair of elements e1 and e2 such that + * e1.equals(e2), and at most one null element. As implied by + * its name, this interface models the mathematical set abstraction. + * + *

The Set interface places additional stipulations, beyond those + * inherited from the Collection interface, on the contracts of all + * constructors and on the contracts of the add, equals and + * hashCode methods. Declarations for other inherited methods are + * also included here for convenience. (The specifications accompanying these + * declarations have been tailored to the Set interface, but they do + * not contain any additional stipulations.) + * + *

The additional stipulation on constructors is, not surprisingly, + * that all constructors must create a set that contains no duplicate elements + * (as defined above). + * + *

Note: Great care must be exercised if mutable objects are used as set + * elements. The behavior of a set is not specified if the value of an object + * is changed in a manner that affects equals comparisons while the + * object is an element in the set. A special case of this prohibition is + * that it is not permissible for a set to contain itself as an element. + * + *

Some set implementations have restrictions on the elements that + * they may contain. For example, some implementations prohibit null elements, + * and some have restrictions on the types of their elements. Attempting to + * add an ineligible element throws an unchecked exception, typically + * NullPointerException or ClassCastException. Attempting + * to query the presence of an ineligible element may throw an exception, + * or it may simply return false; some implementations will exhibit the former + * behavior and some will exhibit the latter. More generally, attempting an + * operation on an ineligible element whose completion would not result in + * the insertion of an ineligible element into the set may throw an + * exception or it may succeed, at the option of the implementation. + * Such exceptions are marked as "optional" in the specification for this + * interface. + * + *

This interface is a member of the + * + * Java Collections Framework. + * + * @param the type of elements maintained by this set + * + * @author Josh Bloch + * @author Neal Gafter + * @see Collection + * @see List + * @see SortedSet + * @see HashSet + * @see TreeSet + * @see AbstractSet + * @see Collections#singleton(java.lang.Object) + * @see Collections#EMPTY_SET + * @since 1.2 + */ + +public interface Set extends Collection { + // Query Operations + + /** + * Returns the number of elements in this set (its cardinality). If this + * set contains more than Integer.MAX_VALUE elements, returns + * Integer.MAX_VALUE. + * + * @return the number of elements in this set (its cardinality) + */ + int size(); + + /** + * Returns true if this set contains no elements. + * + * @return true if this set contains no elements + */ + boolean isEmpty(); + + /** + * Returns true if this set contains the specified element. + * More formally, returns true if and only if this set + * contains an element e such that + * (o==null ? e==null : o.equals(e)). + * + * @param o element whose presence in this set is to be tested + * @return true if this set contains the specified element + * @throws ClassCastException if the type of the specified element + * is incompatible with this set + * (optional) + * @throws NullPointerException if the specified element is null and this + * set does not permit null elements + * (optional) + */ + boolean contains(Object o); + + /** + * Returns an iterator over the elements in this set. The elements are + * returned in no particular order (unless this set is an instance of some + * class that provides a guarantee). + * + * @return an iterator over the elements in this set + */ + Iterator iterator(); + + /** + * Returns an array containing all of the elements in this set. + * If this set makes any guarantees as to what order its elements + * are returned by its iterator, this method must return the + * elements in the same order. + * + *

The returned array will be "safe" in that no references to it + * are maintained by this set. (In other words, this method must + * allocate a new array even if this set is backed by an array). + * The caller is thus free to modify the returned array. + * + *

This method acts as bridge between array-based and collection-based + * APIs. + * + * @return an array containing all the elements in this set + */ + Object[] toArray(); + + /** + * Returns an array containing all of the elements in this set; the + * runtime type of the returned array is that of the specified array. + * If the set fits in the specified array, it is returned therein. + * Otherwise, a new array is allocated with the runtime type of the + * specified array and the size of this set. + * + *

If this set fits in the specified array with room to spare + * (i.e., the array has more elements than this set), the element in + * the array immediately following the end of the set is set to + * null. (This is useful in determining the length of this + * set only if the caller knows that this set does not contain + * any null elements.) + * + *

If this set makes any guarantees as to what order its elements + * are returned by its iterator, this method must return the elements + * in the same order. + * + *

Like the {@link #toArray()} method, this method acts as bridge between + * array-based and collection-based APIs. Further, this method allows + * precise control over the runtime type of the output array, and may, + * under certain circumstances, be used to save allocation costs. + * + *

Suppose x is a set known to contain only strings. + * The following code can be used to dump the set into a newly allocated + * array of String: + * + * 

+     *     String[] y = x.toArray(new String[0]);
+ * + * Note that toArray(new Object[0]) is identical in function to + * toArray(). + * + * @param a the array into which the elements of this set are to be + * stored, if it is big enough; otherwise, a new array of the same + * runtime type is allocated for this purpose. + * @return an array containing all the elements in this set + * @throws ArrayStoreException if the runtime type of the specified array + * is not a supertype of the runtime type of every element in this + * set + * @throws NullPointerException if the specified array is null + */ + T[] toArray(T[] a); + + + // Modification Operations + + /** + * Adds the specified element to this set if it is not already present + * (optional operation). More formally, adds the specified element + * e to this set if the set contains no element e2 + * such that + * (e==null ? e2==null : e.equals(e2)). + * If this set already contains the element, the call leaves the set + * unchanged and returns false. In combination with the + * restriction on constructors, this ensures that sets never contain + * duplicate elements. + * + *

The stipulation above does not imply that sets must accept all + * elements; sets may refuse to add any particular element, including + * null, and throw an exception, as described in the + * specification for {@link Collection#add Collection.add}. + * Individual set implementations should clearly document any + * restrictions on the elements that they may contain. + * + * @param e element to be added to this set + * @return true if this set did not already contain the specified + * element + * @throws UnsupportedOperationException if the add operation + * is not supported by this set + * @throws ClassCastException if the class of the specified element + * prevents it from being added to this set + * @throws NullPointerException if the specified element is null and this + * set does not permit null elements + * @throws IllegalArgumentException if some property of the specified element + * prevents it from being added to this set + */ + boolean add(E e); + + + /** + * Removes the specified element from this set if it is present + * (optional operation). More formally, removes an element e + * such that + * (o==null ? e==null : o.equals(e)), if + * this set contains such an element. Returns true if this set + * contained the element (or equivalently, if this set changed as a + * result of the call). (This set will not contain the element once the + * call returns.) + * + * @param o object to be removed from this set, if present + * @return true if this set contained the specified element + * @throws ClassCastException if the type of the specified element + * is incompatible with this set + * (optional) + * @throws NullPointerException if the specified element is null and this + * set does not permit null elements + * (optional) + * @throws UnsupportedOperationException if the remove operation + * is not supported by this set + */ + boolean remove(Object o); + + + // Bulk Operations + + /** + * Returns true if this set contains all of the elements of the + * specified collection. If the specified collection is also a set, this + * method returns true if it is a subset of this set. + * + * @param c collection to be checked for containment in this set + * @return true if this set contains all of the elements of the + * specified collection + * @throws ClassCastException if the types of one or more elements + * in the specified collection are incompatible with this + * set + * (optional) + * @throws NullPointerException if the specified collection contains one + * or more null elements and this set does not permit null + * elements + * (optional), + * or if the specified collection is null + * @see #contains(Object) + */ + boolean containsAll(Collection c); + + /** + * Adds all of the elements in the specified collection to this set if + * they're not already present (optional operation). If the specified + * collection is also a set, the addAll operation effectively + * modifies this set so that its value is the union of the two + * sets. The behavior of this operation is undefined if the specified + * collection is modified while the operation is in progress. + * + * @param c collection containing elements to be added to this set + * @return true if this set changed as a result of the call + * + * @throws UnsupportedOperationException if the addAll operation + * is not supported by this set + * @throws ClassCastException if the class of an element of the + * specified collection prevents it from being added to this set + * @throws NullPointerException if the specified collection contains one + * or more null elements and this set does not permit null + * elements, or if the specified collection is null + * @throws IllegalArgumentException if some property of an element of the + * specified collection prevents it from being added to this set + * @see #add(Object) + */ + boolean addAll(Collection c); + + /** + * Retains only the elements in this set that are contained in the + * specified collection (optional operation). In other words, removes + * from this set all of its elements that are not contained in the + * specified collection. If the specified collection is also a set, this + * operation effectively modifies this set so that its value is the + * intersection of the two sets. + * + * @param c collection containing elements to be retained in this set + * @return true if this set changed as a result of the call + * @throws UnsupportedOperationException if the retainAll operation + * is not supported by this set + * @throws ClassCastException if the class of an element of this set + * is incompatible with the specified collection + * (optional) + * @throws NullPointerException if this set contains a null element and the + * specified collection does not permit null elements + * (optional), + * or if the specified collection is null + * @see #remove(Object) + */ + boolean retainAll(Collection c); + + /** + * Removes from this set all of its elements that are contained in the + * specified collection (optional operation). If the specified + * collection is also a set, this operation effectively modifies this + * set so that its value is the asymmetric set difference of + * the two sets. + * + * @param c collection containing elements to be removed from this set + * @return true if this set changed as a result of the call + * @throws UnsupportedOperationException if the removeAll operation + * is not supported by this set + * @throws ClassCastException if the class of an element of this set + * is incompatible with the specified collection + * (optional) + * @throws NullPointerException if this set contains a null element and the + * specified collection does not permit null elements + * (optional), + * or if the specified collection is null + * @see #remove(Object) + * @see #contains(Object) + */ + boolean removeAll(Collection c); + + /** + * Removes all of the elements from this set (optional operation). + * The set will be empty after this call returns. + * + * @throws UnsupportedOperationException if the clear method + * is not supported by this set + */ + void clear(); + + + // Comparison and hashing + + /** + * Compares the specified object with this set for equality. Returns + * true if the specified object is also a set, the two sets + * have the same size, and every member of the specified set is + * contained in this set (or equivalently, every member of this set is + * contained in the specified set). This definition ensures that the + * equals method works properly across different implementations of the + * set interface. + * + * @param o object to be compared for equality with this set + * @return true if the specified object is equal to this set + */ + boolean equals(Object o); + + /** + * Returns the hash code value for this set. The hash code of a set is + * defined to be the sum of the hash codes of the elements in the set, + * where the hash code of a null element is defined to be zero. + * This ensures that s1.equals(s2) implies that + * s1.hashCode()==s2.hashCode() for any two sets s1 + * and s2, as required by the general contract of + * {@link Object#hashCode}. + * + * @return the hash code value for this set + * @see Object#equals(Object) + * @see Set#equals(Object) + */ + int hashCode(); +}