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
30 /**
31 * The root interface in the <i>collection hierarchy</i>. A collection
32 * represents a group of objects, known as its <i>elements</i>. Some
33 * collections allow duplicate elements and others do not. Some are ordered
34 * and others unordered. The JDK does not provide any <i>direct</i>
35 * implementations of this interface: it provides implementations of more
36 * specific subinterfaces like <tt>Set</tt> and <tt>List</tt>. This interface
37 * is typically used to pass collections around and manipulate them where
38 * maximum generality is desired.
39 *
40 * <p><i>Bags</i> or <i>multisets</i> (unordered collections that may contain
41 * duplicate elements) should implement this interface directly.
42 *
43 * <p>All general-purpose <tt>Collection</tt> implementation classes (which
44 * typically implement <tt>Collection</tt> indirectly through one of its
45 * subinterfaces) should provide two "standard" constructors: a void (no
46 * arguments) constructor, which creates an empty collection, and a
47 * constructor with a single argument of type <tt>Collection</tt>, which
48 * creates a new collection with the same elements as its argument. In
480 /**
481 * Returns the hash code value for this collection. While the
482 * <tt>Collection</tt> interface adds no stipulations to the general
483 * contract for the <tt>Object.hashCode</tt> method, programmers should
484 * take note that any class that overrides the <tt>Object.equals</tt>
485 * method must also override the <tt>Object.hashCode</tt> method in order
486 * to satisfy the general contract for the <tt>Object.hashCode</tt> method.
487 * In particular, <tt>c1.equals(c2)</tt> implies that
488 * <tt>c1.hashCode()==c2.hashCode()</tt>.
489 *
490 * @return the hash code value for this collection
491 *
492 * @see Object#hashCode()
493 * @see Object#equals(Object)
494 */
495 int hashCode();
496
497 /**
498 * Creates a {@link Spliterator} over the elements in this collection.
499 *
500 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED}.
501 * Implementations should document the reporting of additional
502 * characteristic values.
503 *
504 * @implSpec
505 * The default implementation creates a
506 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
507 * from the collections's {@code Iterator}. The spliterator inherits the
508 * <em>fail-fast</em> properties of the collection's iterator.
509 *
510 * @implNote
511 * The created {@code Spliterator} additionally reports
512 * {@link Spliterator#SUBSIZED}.
513 *
514 * @return a {@code Spliterator} over the elements in this collection
515 * @since 1.8
516 */
517 default Spliterator<E> spliterator() {
518 return Spliterators.spliterator(this, 0);
519 }
520 }
|
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 <tt>Set</tt> and <tt>List</tt>. 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 <tt>Collection</tt> implementation classes (which
46 * typically implement <tt>Collection</tt> indirectly through one of its
47 * subinterfaces) should provide two "standard" constructors: a void (no
48 * arguments) constructor, which creates an empty collection, and a
49 * constructor with a single argument of type <tt>Collection</tt>, which
50 * creates a new collection with the same elements as its argument. In
482 /**
483 * Returns the hash code value for this collection. While the
484 * <tt>Collection</tt> interface adds no stipulations to the general
485 * contract for the <tt>Object.hashCode</tt> method, programmers should
486 * take note that any class that overrides the <tt>Object.equals</tt>
487 * method must also override the <tt>Object.hashCode</tt> method in order
488 * to satisfy the general contract for the <tt>Object.hashCode</tt> method.
489 * In particular, <tt>c1.equals(c2)</tt> implies that
490 * <tt>c1.hashCode()==c2.hashCode()</tt>.
491 *
492 * @return the hash code value for this collection
493 *
494 * @see Object#hashCode()
495 * @see Object#equals(Object)
496 */
497 int hashCode();
498
499 /**
500 * Creates a {@link Spliterator} over the elements in this collection.
501 *
502 * <p>The returned {@code Spliterator} must report the characteristic
503 * {@link Spliterator#SIZED}; implementations should document any additional
504 * characteristic values reported by the returned Spliterator.
505 *
506 * <p>The default implementation should be overridden by subclasses that
507 * can return a more efficient spliterator. In order to
508 * preserve expected laziness behavior for the {@link #stream()} and
509 * {@link #parallelStream()}} methods, spliterators should either have the
510 * characteristic of {@code IMMUTABLE} or {@code CONCURRENT}, or be
511 * <em><a href="Spliterator.html#binding">late-binding</a></em>.
512 * If none of these is practical, the overriding class should describe the
513 * spliterator's documented policy of binding and structural interference,
514 * and should override the {@link #stream()} and {@link #parallelStream()}
515 * methods to create streams using a {@code Supplier} of the spliterator,
516 * as in:
517 * <pre>{@code
518 * Stream<E> s = Streams.stream(() -> spliterator(), spliteratorCharacteristics)
519 * }</pre>
520 * These requirements ensure that streams produced by the {@link #stream()}
521 * and {@link #parallelStream()} methods will reflect the contents of the
522 * collection as of initiation of the terminal stream operation.
523 *
524 * @implSpec
525 * The default implementation creates a
526 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
527 * from the collections's {@code Iterator}. The spliterator inherits the
528 * <em>fail-fast</em> properties of the collection's iterator.
529 *
530 * @implNote
531 * The returned {@code Spliterator} additionally reports
532 * {@link Spliterator#SUBSIZED}.
533 *
534 * @return a {@code Spliterator} over the elements in this collection
535 * @since 1.8
536 */
537 default Spliterator<E> spliterator() {
538 return Spliterators.spliterator(this, 0);
539 }
540
541 /**
542 * Creates a sequential {@code Stream} with this collection as its source.
543 *
544 * <p>This method should be overridden when the {@link #spliterator()}
545 * method cannot return a spliterator that is {@code IMMUTABLE},
546 * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
547 * for details.)
548 *
549 * @implSpec
550 * The default implementation creates a sequential {@code Stream} from the
551 * collection's {@code Spliterator}.
552 *
553 * @return a sequential {@code Stream} over the elements in this collection
554 * @since 1.8
555 */
556 default Stream<E> stream() {
557 return StreamSupport.stream(spliterator());
558 }
559
560 /**
561 * Creates a parallel {@code Stream} with this collection as its source.
562 * It is allowable for this method to return a sequential stream.
563 *
564 * <p>This method should be overridden when the {@link #spliterator()}
565 * method cannot return a spliterator that is {@code IMMUTABLE},
566 * {@code CONCURRENT}, or <em>late-binding</em>. (See {@link #spliterator()}
567 * for details.)
568 *
569 * @implSpec
570 * The default implementation creates a parallel {@code Stream} from the
571 * collection's {@code Spliterator}.
572 *
573 * @return a parallel {@code Stream} over the elements in this collection
574 * @since 1.8
575 */
576 default Stream<E> parallelStream() {
577 return StreamSupport.parallelStream(spliterator());
578 }
579 }
580
|