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 18 package 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 */ 26 public 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 */ add(E object)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 */ addAll(Collection<? extends E> collection)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 */ clear()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 */ contains(Object object)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 */ containsAll(Collection<?> collection)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 */ equals(Object object)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 */ hashCode()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 */ isEmpty()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 */ iterator()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 */ remove(Object object)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 */ removeAll(Collection<?> collection)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 */ retainAll(Collection<?> collection)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 */ size()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 */ toArray()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 */ toArray(T[] array)195 public <T> T[] toArray(T[] array); 196 } 197