1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package java.util;
19
20
21/**
22 * A {@code Set} is a data structure which does not allow duplicate elements.
23 *
24 * @since 1.2
25 */
26public interface Set<E> extends Collection<E> {
27
28    /**
29     * Adds the specified object to this set. The set is not modified if it
30     * already contains the object.
31     *
32     * @param object
33     *            the object to add.
34     * @return {@code true} if this set is modified, {@code false} otherwise.
35     * @throws UnsupportedOperationException
36     *             when adding to this set is not supported.
37     * @throws ClassCastException
38     *             when the class of the object is inappropriate for this set.
39     * @throws IllegalArgumentException
40     *             when the object cannot be added to this set.
41     */
42    public boolean add(E object);
43
44    /**
45     * Adds the objects in the specified collection which do not exist yet in
46     * this set.
47     *
48     * @param collection
49     *            the collection of objects.
50     * @return {@code true} if this set is modified, {@code false} otherwise.
51     * @throws UnsupportedOperationException
52     *             when adding to this set is not supported.
53     * @throws ClassCastException
54     *             when the class of an object is inappropriate for this set.
55     * @throws IllegalArgumentException
56     *             when an object cannot be added to this set.
57     */
58    public boolean addAll(Collection<? extends E> collection);
59
60    /**
61     * Removes all elements from this set, leaving it empty.
62     *
63     * @throws UnsupportedOperationException
64     *             when removing from this set is not supported.
65     * @see #isEmpty
66     * @see #size
67     */
68    public void clear();
69
70    /**
71     * Searches this set for the specified object.
72     *
73     * @param object
74     *            the object to search for.
75     * @return {@code true} if object is an element of this set, {@code false}
76     *         otherwise.
77     */
78    public boolean contains(Object object);
79
80    /**
81     * Searches this set for all objects in the specified collection.
82     *
83     * @param collection
84     *            the collection of objects.
85     * @return {@code true} if all objects in the specified collection are
86     *         elements of this set, {@code false} otherwise.
87     */
88    public boolean containsAll(Collection<?> collection);
89
90    /**
91     * Compares the specified object to this set, and returns true if they
92     * represent the <em>same</em> object using a class specific comparison.
93     * Equality for a set means that both sets have the same size and the same
94     * elements.
95     *
96     * @param object
97     *            the object to compare with this object.
98     * @return boolean {@code true} if the object is the same as this object,
99     *         and {@code false} if it is different from this object.
100     * @see #hashCode
101     */
102    public boolean equals(Object object);
103
104    /**
105     * Returns the hash code for this set. Two set which are equal must return
106     * the same value.
107     *
108     * @return the hash code of this set.
109     *
110     * @see #equals
111     */
112    public int hashCode();
113
114    /**
115     * Returns true if this set has no elements.
116     *
117     * @return {@code true} if this set has no elements, {@code false}
118     *         otherwise.
119     * @see #size
120     */
121    public boolean isEmpty();
122
123    /**
124     * Returns an iterator on the elements of this set. The elements are
125     * unordered.
126     *
127     * @return an iterator on the elements of this set.
128     * @see Iterator
129     */
130    public Iterator<E> iterator();
131
132    /**
133     * Removes the specified object from this set.
134     *
135     * @param object
136     *            the object to remove.
137     * @return {@code true} if this set was modified, {@code false} otherwise.
138     * @throws UnsupportedOperationException
139     *             when removing from this set is not supported.
140     */
141    public boolean remove(Object object);
142
143    /**
144     * Removes all objects in the specified collection from this set.
145     *
146     * @param collection
147     *            the collection of objects to remove.
148     * @return {@code true} if this set was modified, {@code false} otherwise.
149     * @throws UnsupportedOperationException
150     *             when removing from this set is not supported.
151     */
152    public boolean removeAll(Collection<?> collection);
153
154    /**
155     * Removes all objects from this set that are not contained in the specified
156     * collection.
157     *
158     * @param collection
159     *            the collection of objects to retain.
160     * @return {@code true} if this set was modified, {@code false} otherwise.
161     * @throws UnsupportedOperationException
162     *             when removing from this set is not supported.
163     */
164    public boolean retainAll(Collection<?> collection);
165
166    /**
167     * Returns the number of elements in this set.
168     *
169     * @return the number of elements in this set.
170     */
171    public int size();
172
173    /**
174     * Returns an array containing all elements contained in this set.
175     *
176     * @return an array of the elements from this set.
177     */
178    public Object[] toArray();
179
180    /**
181     * Returns an array containing all elements contained in this set. If the
182     * specified array is large enough to hold the elements, the specified array
183     * is used, otherwise an array of the same type is created. If the specified
184     * array is used and is larger than this set, the array element following
185     * the collection elements is set to null.
186     *
187     * @param array
188     *            the array.
189     * @return an array of the elements from this set.
190     * @throws ArrayStoreException
191     *             when the type of an element in this set cannot be stored in
192     *             the type of the specified array.
193     * @see Collection#toArray(Object[])
194     */
195    public <T> T[] toArray(T[] array);
196}
197