1 /*
2 * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
263 * result of the call). (This set will not contain the element once the
264 * call returns.)
265 *
266 * @param o object to be removed from this set, if present
267 * @return {@code true} if this set contained the specified element
268 * @throws ClassCastException if the type of the specified element
269 * is incompatible with this set
270 * (<a href="Collection.html#optional-restrictions">optional</a>)
271 * @throws NullPointerException if the specified element is null and this
272 * set does not permit null elements
273 * (<a href="Collection.html#optional-restrictions">optional</a>)
274 * @throws UnsupportedOperationException if the {@code remove} operation
275 * is not supported by this set
276 */
277 boolean remove(Object o);
278
279
280 // Bulk Operations
281
282 /**
283 * Returns {@code true} if this set contains all of the elements of the
284 * specified collection. If the specified collection is also a set, this
285 * method returns {@code true} if it is a <i>subset</i> of this set.
286 *
287 * @param c collection to be checked for containment in this set
288 * @return {@code true} if this set contains all of the elements of the
289 * specified collection
290 * @throws ClassCastException if the types of one or more elements
291 * in the specified collection are incompatible with this
292 * set
293 * (<a href="Collection.html#optional-restrictions">optional</a>)
294 * @throws NullPointerException if the specified collection contains one
295 * or more null elements and this set does not permit null
296 * elements
297 * (<a href="Collection.html#optional-restrictions">optional</a>),
298 * or if the specified collection is null
299 * @see #contains(Object)
300 */
301 boolean containsAll(Collection<?> c);
302
303 /**
304 * Adds all of the elements in the specified collection to this set if
305 * they're not already present (optional operation). If the specified
311 * @param c collection containing elements to be added to this set
312 * @return {@code true} if this set changed as a result of the call
313 *
314 * @throws UnsupportedOperationException if the {@code addAll} operation
315 * is not supported by this set
316 * @throws ClassCastException if the class of an element of the
317 * specified collection prevents it from being added to this set
318 * @throws NullPointerException if the specified collection contains one
319 * or more null elements and this set does not permit null
320 * elements, or if the specified collection is null
321 * @throws IllegalArgumentException if some property of an element of the
322 * specified collection prevents it from being added to this set
323 * @see #add(Object)
324 */
325 boolean addAll(Collection<? extends E> c);
326
327 /**
328 * Retains only the elements in this set that are contained in the
329 * specified collection (optional operation). In other words, removes
330 * from this set all of its elements that are not contained in the
331 * specified collection. If the specified collection is also a set, this
332 * operation effectively modifies this set so that its value is the
333 * <i>intersection</i> of the two sets.
334 *
335 * @param c collection containing elements to be retained in this set
336 * @return {@code true} if this set changed as a result of the call
337 * @throws UnsupportedOperationException if the {@code retainAll} operation
338 * is not supported by this set
339 * @throws ClassCastException if the class of an element of this set
340 * is incompatible with the specified collection
341 * (<a href="Collection.html#optional-restrictions">optional</a>)
342 * @throws NullPointerException if this set contains a null element and the
343 * specified collection does not permit null elements
344 * (<a href="Collection.html#optional-restrictions">optional</a>),
345 * or if the specified collection is null
346 * @see #remove(Object)
347 */
348 boolean retainAll(Collection<?> c);
349
350 /**
351 * Removes from this set all of its elements that are contained in the
352 * specified collection (optional operation). If the specified
353 * collection is also a set, this operation effectively modifies this
354 * set so that its value is the <i>asymmetric set difference</i> of
355 * the two sets.
356 *
357 * @param c collection containing elements to be removed from this set
358 * @return {@code true} if this set changed as a result of the call
359 * @throws UnsupportedOperationException if the {@code removeAll} operation
360 * is not supported by this set
361 * @throws ClassCastException if the class of an element of this set
362 * is incompatible with the specified collection
363 * (<a href="Collection.html#optional-restrictions">optional</a>)
364 * @throws NullPointerException if this set contains a null element and the
365 * specified collection does not permit null elements
366 * (<a href="Collection.html#optional-restrictions">optional</a>),
367 * or if the specified collection is null
368 * @see #remove(Object)
369 * @see #contains(Object)
370 */
371 boolean removeAll(Collection<?> c);
372
373 /**
374 * Removes all of the elements from this set (optional operation).
375 * The set will be empty after this call returns.
376 *
377 * @throws UnsupportedOperationException if the {@code clear} method
378 * is not supported by this set
379 */
380 void clear();
381
382
383 // Comparison and hashing
384
385 /**
386 * Compares the specified object with this set for equality. Returns
387 * {@code true} if the specified object is also a set, the two sets
388 * have the same size, and every member of the specified set is
389 * contained in this set (or equivalently, every member of this set is
390 * contained in the specified set). This definition ensures that the
391 * equals method works properly across different implementations of the
392 * set interface.
393 *
394 * @param o object to be compared for equality with this set
395 * @return {@code true} if the specified object is equal to this set
396 */
397 boolean equals(Object o);
398
399 /**
400 * Returns the hash code value for this set. The hash code of a set is
401 * defined to be the sum of the hash codes of the elements in the set,
402 * where the hash code of a {@code null} element is defined to be zero.
403 * This ensures that {@code s1.equals(s2)} implies that
404 * {@code s1.hashCode()==s2.hashCode()} for any two sets {@code s1}
405 * and {@code s2}, as required by the general contract of
406 * {@link Object#hashCode}.
407 *
408 * @return the hash code value for this set
409 * @see Object#equals(Object)
410 * @see Set#equals(Object)
411 */
412 int hashCode();
|
1 /*
2 * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
263 * result of the call). (This set will not contain the element once the
264 * call returns.)
265 *
266 * @param o object to be removed from this set, if present
267 * @return {@code true} if this set contained the specified element
268 * @throws ClassCastException if the type of the specified element
269 * is incompatible with this set
270 * (<a href="Collection.html#optional-restrictions">optional</a>)
271 * @throws NullPointerException if the specified element is null and this
272 * set does not permit null elements
273 * (<a href="Collection.html#optional-restrictions">optional</a>)
274 * @throws UnsupportedOperationException if the {@code remove} operation
275 * is not supported by this set
276 */
277 boolean remove(Object o);
278
279
280 // Bulk Operations
281
282 /**
283 * Returns {@code true} if this set contains all of the elements
284 * in the specified collection. This operation uses the membership
285 * semantics of this set. If the specified collection is also a set,
286 * this method returns {@code true} if it is a <i>subset</i> of this set.
287 *
288 * @implNote
289 * {@inheritDoc}
290 *
291 * @param c collection to be checked for containment in this set
292 * @return {@code true} if this set contains all of the elements of the
293 * specified collection
294 * @throws ClassCastException if the types of one or more elements
295 * in the specified collection are incompatible with this
296 * set
297 * (<a href="Collection.html#optional-restrictions">optional</a>)
298 * @throws NullPointerException if the specified collection contains one
299 * or more null elements and this set does not permit null
300 * elements
301 * (<a href="Collection.html#optional-restrictions">optional</a>),
302 * or if the specified collection is null
303 * @see #contains(Object)
304 */
305 boolean containsAll(Collection<?> c);
306
307 /**
308 * Adds all of the elements in the specified collection to this set if
309 * they're not already present (optional operation). If the specified
315 * @param c collection containing elements to be added to this set
316 * @return {@code true} if this set changed as a result of the call
317 *
318 * @throws UnsupportedOperationException if the {@code addAll} operation
319 * is not supported by this set
320 * @throws ClassCastException if the class of an element of the
321 * specified collection prevents it from being added to this set
322 * @throws NullPointerException if the specified collection contains one
323 * or more null elements and this set does not permit null
324 * elements, or if the specified collection is null
325 * @throws IllegalArgumentException if some property of an element of the
326 * specified collection prevents it from being added to this set
327 * @see #add(Object)
328 */
329 boolean addAll(Collection<? extends E> c);
330
331 /**
332 * Retains only the elements in this set that are contained in the
333 * specified collection (optional operation). In other words, removes
334 * from this set all of its elements that are not contained in the
335 * specified collection. This operation uses the membership semantics of the
336 * specified collection. If the specified collection is also a set, this
337 * operation effectively modifies this set so that its value is the
338 * <i>intersection</i> of the two sets.
339 *
340 * @implNote
341 * {@inheritDoc}
342 *
343 * @param c collection containing elements to be retained in this set
344 * @return {@code true} if this set changed as a result of the call
345 * @throws UnsupportedOperationException if the {@code retainAll} operation
346 * is not supported by this set
347 * @throws ClassCastException if the class of an element of this set
348 * is incompatible with the specified collection
349 * (<a href="Collection.html#optional-restrictions">optional</a>)
350 * @throws NullPointerException if this set contains a null element and the
351 * specified collection does not permit null elements
352 * (<a href="Collection.html#optional-restrictions">optional</a>),
353 * or if the specified collection is null
354 * @see #remove(Object)
355 */
356 boolean retainAll(Collection<?> c);
357
358 /**
359 * Removes from this set all of its elements that are contained in the
360 * specified collection (optional operation). After this call returns,
361 * this set will contain no elements in common with the specified
362 * collection. This operation uses the membership semantics of the specified
363 * collection. If the specified collection is also a set, this operation
364 * effectively modifies this set so that its value is the <i>asymmetric
365 * set difference</i> of the two sets.
366 *
367 * @implNote
368 * {@inheritDoc}
369 *
370 * @param c collection containing elements to be removed from this set
371 * @return {@code true} if this set changed as a result of the call
372 * @throws UnsupportedOperationException if the {@code removeAll} operation
373 * is not supported by this set
374 * @throws ClassCastException if the class of an element of this set
375 * is incompatible with the specified collection
376 * (<a href="Collection.html#optional-restrictions">optional</a>)
377 * @throws NullPointerException if this set contains a null element and the
378 * specified collection does not permit null elements
379 * (<a href="Collection.html#optional-restrictions">optional</a>),
380 * or if the specified collection is null
381 * @see #remove(Object)
382 * @see #contains(Object)
383 */
384 boolean removeAll(Collection<?> c);
385
386 /**
387 * Removes all of the elements from this set (optional operation).
388 * The set will be empty after this call returns.
389 *
390 * @throws UnsupportedOperationException if the {@code clear} method
391 * is not supported by this set
392 */
393 void clear();
394
395
396 // Comparison and hashing
397
398 /**
399 * Compares the specified object with this set for equality. Returns
400 * {@code true} if the specified object is also a set, the two sets
401 * have the same size, and every member of the specified set is
402 * contained in this set. This operation uses the membership semantics
403 * of this set. This definition ensures that the {@code equals} method
404 * works properly across different implementations of the
405 * {@code Set} interface.
406 *
407 * @implNote
408 * Most implementations will call this set's {@code contains}
409 * method repeatedly. This may result in performance problems if the
410 * {@code contains} method has linear or worse performance.
411 *
412 * @param o object to be compared for equality with this set
413 * @return {@code true} if the specified object is equal to this set
414 */
415 boolean equals(Object o);
416
417 /**
418 * Returns the hash code value for this set. The hash code of a set is
419 * defined to be the sum of the hash codes of the elements in the set,
420 * where the hash code of a {@code null} element is defined to be zero.
421 * This ensures that {@code s1.equals(s2)} implies that
422 * {@code s1.hashCode()==s2.hashCode()} for any two sets {@code s1}
423 * and {@code s2}, as required by the general contract of
424 * {@link Object#hashCode}.
425 *
426 * @return the hash code value for this set
427 * @see Object#equals(Object)
428 * @see Set#equals(Object)
429 */
430 int hashCode();
|