154 int size();
155
156 /**
157 * Returns {@code true} if this collection contains no elements.
158 *
159 * @return {@code true} if this collection contains no elements
160 */
161 boolean isEmpty();
162
163 /**
164 * Returns {@code true} if this collection contains the specified element.
165 * More formally, returns {@code true} if and only if this collection
166 * contains at least one element {@code e} such that
167 * {@code Objects.equals(o, e)}.
168 *
169 * @param o element whose presence in this collection is to be tested
170 * @return {@code true} if this collection contains the specified
171 * element
172 * @throws ClassCastException if the type of the specified element
173 * is incompatible with this collection
174 * (<a href="#optional-restrictions">optional</a>)
175 * @throws NullPointerException if the specified element is null and this
176 * collection does not permit null elements
177 * (<a href="#optional-restrictions">optional</a>)
178 */
179 boolean contains(Object o);
180
181 /**
182 * Returns an iterator over the elements in this collection. There are no
183 * guarantees concerning the order in which the elements are returned
184 * (unless this collection is an instance of some class that provides a
185 * guarantee).
186 *
187 * @return an {@code Iterator} over the elements in this collection
188 */
189 Iterator<E> iterator();
190
191 /**
192 * Returns an array containing all of the elements in this collection.
193 * If this collection makes any guarantees as to what order its elements
194 * are returned by its iterator, this method must return the elements in
195 * the same order.
196 *
197 * <p>The returned array will be "safe" in that no references to it are
284 * @throws IllegalArgumentException if some property of the element
285 * prevents it from being added to this collection
286 * @throws IllegalStateException if the element cannot be added at this
287 * time due to insertion restrictions
288 */
289 boolean add(E e);
290
291 /**
292 * Removes a single instance of the specified element from this
293 * collection, if it is present (optional operation). More formally,
294 * removes an element {@code e} such that
295 * {@code Objects.equals(o, e)}, if
296 * this collection contains one or more such elements. Returns
297 * {@code true} if this collection contained the specified element (or
298 * equivalently, if this collection changed as a result of the call).
299 *
300 * @param o element to be removed from this collection, if present
301 * @return {@code true} if an element was removed as a result of this call
302 * @throws ClassCastException if the type of the specified element
303 * is incompatible with this collection
304 * (<a href="#optional-restrictions">optional</a>)
305 * @throws NullPointerException if the specified element is null and this
306 * collection does not permit null elements
307 * (<a href="#optional-restrictions">optional</a>)
308 * @throws UnsupportedOperationException if the {@code remove} operation
309 * is not supported by this collection
310 */
311 boolean remove(Object o);
312
313
314 // Bulk Operations
315
316 /**
317 * Returns {@code true} if this collection contains all of the elements
318 * in the specified collection.
319 *
320 * @param c collection to be checked for containment in this collection
321 * @return {@code true} if this collection contains all of the elements
322 * in the specified collection
323 * @throws ClassCastException if the types of one or more elements
324 * in the specified collection are incompatible with this
325 * collection
326 * (<a href="#optional-restrictions">optional</a>)
327 * @throws NullPointerException if the specified collection contains one
328 * or more null elements and this collection does not permit null
329 * elements
330 * (<a href="#optional-restrictions">optional</a>),
331 * or if the specified collection is null.
332 * @see #contains(Object)
333 */
334 boolean containsAll(Collection<?> c);
335
336 /**
337 * Adds all of the elements in the specified collection to this collection
338 * (optional operation). The behavior of this operation is undefined if
339 * the specified collection is modified while the operation is in progress.
340 * (This implies that the behavior of this call is undefined if the
341 * specified collection is this collection, and this collection is
342 * nonempty.)
343 *
344 * @param c collection containing elements to be added to this collection
345 * @return {@code true} if this collection changed as a result of the call
346 * @throws UnsupportedOperationException if the {@code addAll} operation
347 * is not supported by this collection
348 * @throws ClassCastException if the class of an element of the specified
349 * collection prevents it from being added to this collection
350 * @throws NullPointerException if the specified collection contains a
356 * @throws IllegalStateException if not all the elements can be added at
357 * this time due to insertion restrictions
358 * @see #add(Object)
359 */
360 boolean addAll(Collection<? extends E> c);
361
362 /**
363 * Removes all of this collection's elements that are also contained in the
364 * specified collection (optional operation). After this call returns,
365 * this collection will contain no elements in common with the specified
366 * collection.
367 *
368 * @param c collection containing elements to be removed from this collection
369 * @return {@code true} if this collection changed as a result of the
370 * call
371 * @throws UnsupportedOperationException if the {@code removeAll} method
372 * is not supported by this collection
373 * @throws ClassCastException if the types of one or more elements
374 * in this collection are incompatible with the specified
375 * collection
376 * (<a href="#optional-restrictions">optional</a>)
377 * @throws NullPointerException if this collection contains one or more
378 * null elements and the specified collection does not support
379 * null elements
380 * (<a href="#optional-restrictions">optional</a>),
381 * or if the specified collection is null
382 * @see #remove(Object)
383 * @see #contains(Object)
384 */
385 boolean removeAll(Collection<?> c);
386
387 /**
388 * Removes all of the elements of this collection that satisfy the given
389 * predicate. Errors or runtime exceptions thrown during iteration or by
390 * the predicate are relayed to the caller.
391 *
392 * @implSpec
393 * The default implementation traverses all elements of the collection using
394 * its {@link #iterator}. Each matching element is removed using
395 * {@link Iterator#remove()}. If the collection's iterator does not
396 * support removal then an {@code UnsupportedOperationException} will be
397 * thrown on the first matching element.
398 *
399 * @param filter a predicate which returns {@code true} for elements to be
400 * removed
415 each.remove();
416 removed = true;
417 }
418 }
419 return removed;
420 }
421
422 /**
423 * Retains only the elements in this collection that are contained in the
424 * specified collection (optional operation). In other words, removes from
425 * this collection all of its elements that are not contained in the
426 * specified collection.
427 *
428 * @param c collection containing elements to be retained in this collection
429 * @return {@code true} if this collection changed as a result of the call
430 * @throws UnsupportedOperationException if the {@code retainAll} operation
431 * is not supported by this collection
432 * @throws ClassCastException if the types of one or more elements
433 * in this collection are incompatible with the specified
434 * collection
435 * (<a href="#optional-restrictions">optional</a>)
436 * @throws NullPointerException if this collection contains one or more
437 * null elements and the specified collection does not permit null
438 * elements
439 * (<a href="#optional-restrictions">optional</a>),
440 * or if the specified collection is null
441 * @see #remove(Object)
442 * @see #contains(Object)
443 */
444 boolean retainAll(Collection<?> c);
445
446 /**
447 * Removes all of the elements from this collection (optional operation).
448 * The collection will be empty after this method returns.
449 *
450 * @throws UnsupportedOperationException if the {@code clear} operation
451 * is not supported by this collection
452 */
453 void clear();
454
455
456 // Comparison and hashing
457
458 /**
459 * Compares the specified object with this collection for equality. <p>
|
154 int size();
155
156 /**
157 * Returns {@code true} if this collection contains no elements.
158 *
159 * @return {@code true} if this collection contains no elements
160 */
161 boolean isEmpty();
162
163 /**
164 * Returns {@code true} if this collection contains the specified element.
165 * More formally, returns {@code true} if and only if this collection
166 * contains at least one element {@code e} such that
167 * {@code Objects.equals(o, e)}.
168 *
169 * @param o element whose presence in this collection is to be tested
170 * @return {@code true} if this collection contains the specified
171 * element
172 * @throws ClassCastException if the type of the specified element
173 * is incompatible with this collection
174 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
175 * @throws NullPointerException if the specified element is null and this
176 * collection does not permit null elements
177 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
178 */
179 boolean contains(Object o);
180
181 /**
182 * Returns an iterator over the elements in this collection. There are no
183 * guarantees concerning the order in which the elements are returned
184 * (unless this collection is an instance of some class that provides a
185 * guarantee).
186 *
187 * @return an {@code Iterator} over the elements in this collection
188 */
189 Iterator<E> iterator();
190
191 /**
192 * Returns an array containing all of the elements in this collection.
193 * If this collection makes any guarantees as to what order its elements
194 * are returned by its iterator, this method must return the elements in
195 * the same order.
196 *
197 * <p>The returned array will be "safe" in that no references to it are
284 * @throws IllegalArgumentException if some property of the element
285 * prevents it from being added to this collection
286 * @throws IllegalStateException if the element cannot be added at this
287 * time due to insertion restrictions
288 */
289 boolean add(E e);
290
291 /**
292 * Removes a single instance of the specified element from this
293 * collection, if it is present (optional operation). More formally,
294 * removes an element {@code e} such that
295 * {@code Objects.equals(o, e)}, if
296 * this collection contains one or more such elements. Returns
297 * {@code true} if this collection contained the specified element (or
298 * equivalently, if this collection changed as a result of the call).
299 *
300 * @param o element to be removed from this collection, if present
301 * @return {@code true} if an element was removed as a result of this call
302 * @throws ClassCastException if the type of the specified element
303 * is incompatible with this collection
304 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
305 * @throws NullPointerException if the specified element is null and this
306 * collection does not permit null elements
307 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
308 * @throws UnsupportedOperationException if the {@code remove} operation
309 * is not supported by this collection
310 */
311 boolean remove(Object o);
312
313
314 // Bulk Operations
315
316 /**
317 * Returns {@code true} if this collection contains all of the elements
318 * in the specified collection.
319 *
320 * @param c collection to be checked for containment in this collection
321 * @return {@code true} if this collection contains all of the elements
322 * in the specified collection
323 * @throws ClassCastException if the types of one or more elements
324 * in the specified collection are incompatible with this
325 * collection
326 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
327 * @throws NullPointerException if the specified collection contains one
328 * or more null elements and this collection does not permit null
329 * elements
330 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
331 * or if the specified collection is null.
332 * @see #contains(Object)
333 */
334 boolean containsAll(Collection<?> c);
335
336 /**
337 * Adds all of the elements in the specified collection to this collection
338 * (optional operation). The behavior of this operation is undefined if
339 * the specified collection is modified while the operation is in progress.
340 * (This implies that the behavior of this call is undefined if the
341 * specified collection is this collection, and this collection is
342 * nonempty.)
343 *
344 * @param c collection containing elements to be added to this collection
345 * @return {@code true} if this collection changed as a result of the call
346 * @throws UnsupportedOperationException if the {@code addAll} operation
347 * is not supported by this collection
348 * @throws ClassCastException if the class of an element of the specified
349 * collection prevents it from being added to this collection
350 * @throws NullPointerException if the specified collection contains a
356 * @throws IllegalStateException if not all the elements can be added at
357 * this time due to insertion restrictions
358 * @see #add(Object)
359 */
360 boolean addAll(Collection<? extends E> c);
361
362 /**
363 * Removes all of this collection's elements that are also contained in the
364 * specified collection (optional operation). After this call returns,
365 * this collection will contain no elements in common with the specified
366 * collection.
367 *
368 * @param c collection containing elements to be removed from this collection
369 * @return {@code true} if this collection changed as a result of the
370 * call
371 * @throws UnsupportedOperationException if the {@code removeAll} method
372 * is not supported by this collection
373 * @throws ClassCastException if the types of one or more elements
374 * in this collection are incompatible with the specified
375 * collection
376 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
377 * @throws NullPointerException if this collection contains one or more
378 * null elements and the specified collection does not support
379 * null elements
380 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
381 * or if the specified collection is null
382 * @see #remove(Object)
383 * @see #contains(Object)
384 */
385 boolean removeAll(Collection<?> c);
386
387 /**
388 * Removes all of the elements of this collection that satisfy the given
389 * predicate. Errors or runtime exceptions thrown during iteration or by
390 * the predicate are relayed to the caller.
391 *
392 * @implSpec
393 * The default implementation traverses all elements of the collection using
394 * its {@link #iterator}. Each matching element is removed using
395 * {@link Iterator#remove()}. If the collection's iterator does not
396 * support removal then an {@code UnsupportedOperationException} will be
397 * thrown on the first matching element.
398 *
399 * @param filter a predicate which returns {@code true} for elements to be
400 * removed
415 each.remove();
416 removed = true;
417 }
418 }
419 return removed;
420 }
421
422 /**
423 * Retains only the elements in this collection that are contained in the
424 * specified collection (optional operation). In other words, removes from
425 * this collection all of its elements that are not contained in the
426 * specified collection.
427 *
428 * @param c collection containing elements to be retained in this collection
429 * @return {@code true} if this collection changed as a result of the call
430 * @throws UnsupportedOperationException if the {@code retainAll} operation
431 * is not supported by this collection
432 * @throws ClassCastException if the types of one or more elements
433 * in this collection are incompatible with the specified
434 * collection
435 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>)
436 * @throws NullPointerException if this collection contains one or more
437 * null elements and the specified collection does not permit null
438 * elements
439 * (<a href="{@docRoot}/java/util/Collection.html#optional-restrictions">optional</a>),
440 * or if the specified collection is null
441 * @see #remove(Object)
442 * @see #contains(Object)
443 */
444 boolean retainAll(Collection<?> c);
445
446 /**
447 * Removes all of the elements from this collection (optional operation).
448 * The collection will be empty after this method returns.
449 *
450 * @throws UnsupportedOperationException if the {@code clear} operation
451 * is not supported by this collection
452 */
453 void clear();
454
455
456 // Comparison and hashing
457
458 /**
459 * Compares the specified object with this collection for equality. <p>
|