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
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.Predicate;
29 import java.util.stream.Stream;
30 import java.util.stream.StreamSupport;
31
32 /**
33 * The root interface in the <i>collection hierarchy</i>. A collection
34 * represents a group of objects, known as its <i>elements</i>. Some
35 * collections allow duplicate elements and others do not. Some are ordered
36 * and others unordered. The JDK does not provide any <i>direct</i>
37 * implementations of this interface: it provides implementations of more
38 * specific subinterfaces like {@code Set} and {@code List}. This interface
39 * is typically used to pass collections around and manipulate them where
40 * maximum generality is desired.
41 *
42 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
43 * duplicate elements) should implement this interface directly.
44 *
45 * <p>All general-purpose {@code Collection} implementation classes (which
46 * typically implement {@code Collection} indirectly through one of its
47 * subinterfaces) should provide two "standard" constructors: a void (no
259 * guarantees concerning the order in which the elements are returned
260 * (unless this collection is an instance of some class that provides a
261 * guarantee).
262 *
263 * @return an {@code Iterator} over the elements in this collection
264 */
265 Iterator<E> iterator();
266
267 /**
268 * Returns an array containing all of the elements in this collection.
269 * If this collection makes any guarantees as to what order its elements
270 * are returned by its iterator, this method must return the elements in
271 * the same order. The returned array's {@linkplain Class#getComponentType
272 * runtime component type} is {@code Object}.
273 *
274 * <p>The returned array will be "safe" in that no references to it are
275 * maintained by this collection. (In other words, this method must
276 * allocate a new array even if this collection is backed by an array).
277 * The caller is thus free to modify the returned array.
278 *
279 * <p>This method acts as bridge between array-based and collection-based
280 * APIs.
281 *
282 * @return an array, whose {@linkplain Class#getComponentType runtime component
283 * type} is {@code Object}, containing all of the elements in this collection
284 */
285 Object[] toArray();
286
287 /**
288 * Returns an array containing all of the elements in this collection;
289 * the runtime type of the returned array is that of the specified array.
290 * If the collection fits in the specified array, it is returned therein.
291 * Otherwise, a new array is allocated with the runtime type of the
292 * specified array and the size of this collection.
293 *
294 * <p>If this collection fits in the specified array with room to spare
295 * (i.e., the array has more elements than this collection), the element
296 * in the array immediately following the end of the collection is set to
297 * {@code null}. (This is useful in determining the length of this
298 * collection <i>only</i> if the caller knows that this collection does
299 * not contain any {@code null} elements.)
300 *
301 * <p>If this collection makes any guarantees as to what order its elements
302 * are returned by its iterator, this method must return the elements in
303 * the same order.
304 *
305 * <p>Like the {@link #toArray()} method, this method acts as bridge between
306 * array-based and collection-based APIs. Further, this method allows
307 * precise control over the runtime type of the output array, and may,
308 * under certain circumstances, be used to save allocation costs.
309 *
310 * <p>Suppose {@code x} is a collection known to contain only strings.
311 * The following code can be used to dump the collection into a newly
312 * allocated array of {@code String}:
313 *
314 * <pre>
315 * String[] y = x.toArray(new String[0]);</pre>
316 *
317 * Note that {@code toArray(new Object[0])} is identical in function to
318 * {@code toArray()}.
319 *
320 * @param <T> the component type of the array to contain the collection
321 * @param a the array into which the elements of this collection are to be
322 * stored, if it is big enough; otherwise, a new array of the same
323 * runtime type is allocated for this purpose.
324 * @return an array containing all of the elements in this collection
325 * @throws ArrayStoreException if the runtime type of any element in this
326 * collection is not assignable to the {@linkplain Class#getComponentType
327 * runtime component type} of the specified array
328 * @throws NullPointerException if the specified array is null
329 */
330 <T> T[] toArray(T[] a);
331
332 // Modification Operations
333
334 /**
335 * Ensures that this collection contains the specified element (optional
336 * operation). Returns {@code true} if this collection changed as a
337 * result of the call. (Returns {@code false} if this collection does
338 * not permit duplicates and already contains the specified element.)<p>
339 *
340 * Collections that support this operation may place limitations on what
341 * elements may be added to this collection. In particular, some
342 * collections will refuse to add {@code null} elements, and others will
343 * impose restrictions on the type of elements that may be added.
344 * Collection classes should clearly specify in their documentation any
345 * restrictions on what elements may be added.<p>
346 *
347 * If a collection refuses to add a particular element for any reason
348 * other than that it already contains the element, it <i>must</i> throw
349 * an exception (rather than returning {@code false}). This preserves
350 * the invariant that a collection always contains the specified element
351 * after this call returns.
|
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
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.IntFunction;
29 import java.util.function.Predicate;
30 import java.util.stream.Stream;
31 import java.util.stream.StreamSupport;
32
33 /**
34 * The root interface in the <i>collection hierarchy</i>. A collection
35 * represents a group of objects, known as its <i>elements</i>. Some
36 * collections allow duplicate elements and others do not. Some are ordered
37 * and others unordered. The JDK does not provide any <i>direct</i>
38 * implementations of this interface: it provides implementations of more
39 * specific subinterfaces like {@code Set} and {@code List}. This interface
40 * is typically used to pass collections around and manipulate them where
41 * maximum generality is desired.
42 *
43 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
44 * duplicate elements) should implement this interface directly.
45 *
46 * <p>All general-purpose {@code Collection} implementation classes (which
47 * typically implement {@code Collection} indirectly through one of its
48 * subinterfaces) should provide two "standard" constructors: a void (no
260 * guarantees concerning the order in which the elements are returned
261 * (unless this collection is an instance of some class that provides a
262 * guarantee).
263 *
264 * @return an {@code Iterator} over the elements in this collection
265 */
266 Iterator<E> iterator();
267
268 /**
269 * Returns an array containing all of the elements in this collection.
270 * If this collection makes any guarantees as to what order its elements
271 * are returned by its iterator, this method must return the elements in
272 * the same order. The returned array's {@linkplain Class#getComponentType
273 * runtime component type} is {@code Object}.
274 *
275 * <p>The returned array will be "safe" in that no references to it are
276 * maintained by this collection. (In other words, this method must
277 * allocate a new array even if this collection is backed by an array).
278 * The caller is thus free to modify the returned array.
279 *
280 * @apiNote
281 * This method acts as a bridge between array-based and collection-based APIs.
282 * It returns an array whose runtime type is {@code Object[]}.
283 * Use {@link #toArray(Object[]) toArray(T[])} to reuse an existing
284 * array, or use {@link #toArray(IntFunction)} to control the runtime type
285 * of the array.
286 *
287 * @return an array, whose {@linkplain Class#getComponentType runtime component
288 * type} is {@code Object}, containing all of the elements in this collection
289 */
290 Object[] toArray();
291
292 /**
293 * Returns an array containing all of the elements in this collection;
294 * the runtime type of the returned array is that of the specified array.
295 * If the collection fits in the specified array, it is returned therein.
296 * Otherwise, a new array is allocated with the runtime type of the
297 * specified array and the size of this collection.
298 *
299 * <p>If this collection fits in the specified array with room to spare
300 * (i.e., the array has more elements than this collection), the element
301 * in the array immediately following the end of the collection is set to
302 * {@code null}. (This is useful in determining the length of this
303 * collection <i>only</i> if the caller knows that this collection does
304 * not contain any {@code null} elements.)
305 *
306 * <p>If this collection makes any guarantees as to what order its elements
307 * are returned by its iterator, this method must return the elements in
308 * the same order.
309 *
310 * @apiNote
311 * This method acts as a bridge between array-based and collection-based APIs.
312 * It allows an existing array to be reused under certain circumstances.
313 * Use {@link #toArray()} to create an array whose runtime type is {@code Object[]},
314 * or use {@link #toArray(IntFunction)} to control the runtime type of
315 * the array.
316 *
317 * <p>Suppose {@code x} is a collection known to contain only strings.
318 * The following code can be used to dump the collection into a previously
319 * allocated {@code String} array:
320 *
321 * <pre>
322 * String[] y = new String[SIZE];
323 * ...
324 * y = x.toArray(y);</pre>
325 *
326 * <p>The return value is reassigned to the variable {@code y}, because a
327 * new array will be allocated and returned if the collection {@code x} has
328 * too many elements to fit into the existing array {@code y}.
329 *
330 * <p>Note that {@code toArray(new Object[0])} is identical in function to
331 * {@code toArray()}.
332 *
333 * @param <T> the component type of the array to contain the collection
334 * @param a the array into which the elements of this collection are to be
335 * stored, if it is big enough; otherwise, a new array of the same
336 * runtime type is allocated for this purpose.
337 * @return an array containing all of the elements in this collection
338 * @throws ArrayStoreException if the runtime type of any element in this
339 * collection is not assignable to the {@linkplain Class#getComponentType
340 * runtime component type} of the specified array
341 * @throws NullPointerException if the specified array is null
342 */
343 <T> T[] toArray(T[] a);
344
345 /**
346 * Returns an array containing all of the elements in this collection,
347 * using the provided {@code generator} function to allocate the returned array.
348 *
349 * <p>If this collection makes any guarantees as to what order its elements
350 * are returned by its iterator, this method must return the elements in
351 * the same order.
352 *
353 * @apiNote
354 * This method acts as a bridge between array-based and collection-based APIs.
355 * It allows creation of an array of a particular runtime type. Use
356 * {@link #toArray()} to create an array whose runtime type is {@code Object[]},
357 * or use {@link #toArray(Object[]) toArray(T[])} to reuse an existing array.
358 *
359 * <p>Suppose {@code x} is a collection known to contain only strings.
360 * The following code can be used to dump the collection into a newly
361 * allocated array of {@code String}:
362 *
363 * <pre>
364 * String[] y = x.toArray(String[]::new);</pre>
365 *
366 * @implSpec
367 * The default implementation calls the generator function with zero
368 * and then passes the resulting array to {@link #toArray(Object[]) toArray(T[])}.
369 *
370 * @param <T> the component type of the array to contain the collection
371 * @param generator a function which produces a new array of the desired
372 * type and the provided length
373 * @return an array containing all of the elements in this collection
374 * @throws ArrayStoreException if the runtime type of any element in this
375 * collection is not assignable to the {@linkplain Class#getComponentType
376 * runtime component type} of the generated array
377 * @throws NullPointerException if the generator function is null
378 * @since 10
379 */
380 default <T> T[] toArray(IntFunction<T[]> generator) {
381 return toArray(generator.apply(0));
382 }
383
384 // Modification Operations
385
386 /**
387 * Ensures that this collection contains the specified element (optional
388 * operation). Returns {@code true} if this collection changed as a
389 * result of the call. (Returns {@code false} if this collection does
390 * not permit duplicates and already contains the specified element.)<p>
391 *
392 * Collections that support this operation may place limitations on what
393 * elements may be added to this collection. In particular, some
394 * collections will refuse to add {@code null} elements, and others will
395 * impose restrictions on the type of elements that may be added.
396 * Collection classes should clearly specify in their documentation any
397 * restrictions on what elements may be added.<p>
398 *
399 * If a collection refuses to add a particular element for any reason
400 * other than that it already contains the element, it <i>must</i> throw
401 * an exception (rather than returning {@code false}). This preserves
402 * the invariant that a collection always contains the specified element
403 * after this call returns.
|