jdk/src/java.base/share/classes/java/util/Spliterator.java
author mchung
Fri, 22 May 2015 16:43:39 -0700
changeset 30789 9eca83469588
parent 28666 49cdfa0ea390
child 44844 b2b4d98404ba
permissions -rw-r--r--
8074431: Remove native2ascii tool Reviewed-by: erikj, alanb, okutsu, mfang, naoto
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     1
/*
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     2
 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     4
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    10
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    15
 * accompanied this code).
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    16
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    20
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    23
 * questions.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    24
 */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    25
package java.util;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    26
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    27
import java.util.function.Consumer;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    28
import java.util.function.DoubleConsumer;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    29
import java.util.function.IntConsumer;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    30
import java.util.function.LongConsumer;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    31
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    32
/**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    33
 * An object for traversing and partitioning elements of a source.  The source
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    34
 * of elements covered by a Spliterator could be, for example, an array, a
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    35
 * {@link Collection}, an IO channel, or a generator function.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    36
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    37
 * <p>A Spliterator may traverse elements individually ({@link
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    38
 * #tryAdvance tryAdvance()}) or sequentially in bulk
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    39
 * ({@link #forEachRemaining forEachRemaining()}).
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    40
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    41
 * <p>A Spliterator may also partition off some of its elements (using
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    42
 * {@link #trySplit}) as another Spliterator, to be used in
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    43
 * possibly-parallel operations.  Operations using a Spliterator that
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    44
 * cannot split, or does so in a highly imbalanced or inefficient
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    45
 * manner, are unlikely to benefit from parallelism.  Traversal
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    46
 * and splitting exhaust elements; each Spliterator is useful for only a single
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    47
 * bulk computation.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    48
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    49
 * <p>A Spliterator also reports a set of {@link #characteristics()} of its
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    50
 * structure, source, and elements from among {@link #ORDERED},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    51
 * {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED}, {@link #NONNULL},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    52
 * {@link #IMMUTABLE}, {@link #CONCURRENT}, and {@link #SUBSIZED}. These may
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    53
 * be employed by Spliterator clients to control, specialize or simplify
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    54
 * computation.  For example, a Spliterator for a {@link Collection} would
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    55
 * report {@code SIZED}, a Spliterator for a {@link Set} would report
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    56
 * {@code DISTINCT}, and a Spliterator for a {@link SortedSet} would also
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    57
 * report {@code SORTED}.  Characteristics are reported as a simple unioned bit
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    58
 * set.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    59
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    60
 * Some characteristics additionally constrain method behavior; for example if
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    61
 * {@code ORDERED}, traversal methods must conform to their documented ordering.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    62
 * New characteristics may be defined in the future, so implementors should not
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    63
 * assign meanings to unlisted values.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    64
 *
18796
486b43748d9b 8020294: Fix doclint issues in java.util.Spliterator
darcy
parents: 17920
diff changeset
    65
 * <p><a name="binding">A Spliterator that does not report {@code IMMUTABLE} or
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    66
 * {@code CONCURRENT} is expected to have a documented policy concerning:
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    67
 * when the spliterator <em>binds</em> to the element source; and detection of
18796
486b43748d9b 8020294: Fix doclint issues in java.util.Spliterator
darcy
parents: 17920
diff changeset
    68
 * structural interference of the element source detected after binding.</a>  A
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    69
 * <em>late-binding</em> Spliterator binds to the source of elements at the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    70
 * point of first traversal, first split, or first query for estimated size,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    71
 * rather than at the time the Spliterator is created.  A Spliterator that is
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    72
 * not <em>late-binding</em> binds to the source of elements at the point of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    73
 * construction or first invocation of any method.  Modifications made to the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    74
 * source prior to binding are reflected when the Spliterator is traversed.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    75
 * After binding a Spliterator should, on a best-effort basis, throw
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    76
 * {@link ConcurrentModificationException} if structural interference is
19435
9d7530ff42cb 8014824: Document Spliterator characteristics and binding policy of java util collection impls
psandoz
parents: 18796
diff changeset
    77
 * detected.  Spliterators that do this are called <em>fail-fast</em>.  The
9d7530ff42cb 8014824: Document Spliterator characteristics and binding policy of java util collection impls
psandoz
parents: 18796
diff changeset
    78
 * bulk traversal method ({@link #forEachRemaining forEachRemaining()}) of a
9d7530ff42cb 8014824: Document Spliterator characteristics and binding policy of java util collection impls
psandoz
parents: 18796
diff changeset
    79
 * Spliterator may optimize traversal and check for structural interference
9d7530ff42cb 8014824: Document Spliterator characteristics and binding policy of java util collection impls
psandoz
parents: 18796
diff changeset
    80
 * after all elements have been traversed, rather than checking per-element and
9d7530ff42cb 8014824: Document Spliterator characteristics and binding policy of java util collection impls
psandoz
parents: 18796
diff changeset
    81
 * failing immediately.
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    82
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    83
 * <p>Spliterators can provide an estimate of the number of remaining elements
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    84
 * via the {@link #estimateSize} method.  Ideally, as reflected in characteristic
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    85
 * {@link #SIZED}, this value corresponds exactly to the number of elements
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    86
 * that would be encountered in a successful traversal.  However, even when not
28059
e576535359cc 8067377: My hobby: caning, then then canning, the the can-can
martin
parents: 25859
diff changeset
    87
 * exactly known, an estimated value may still be useful to operations
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    88
 * being performed on the source, such as helping to determine whether it is
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    89
 * preferable to split further or traverse the remaining elements sequentially.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    90
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    91
 * <p>Despite their obvious utility in parallel algorithms, spliterators are not
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    92
 * expected to be thread-safe; instead, implementations of parallel algorithms
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    93
 * using spliterators should ensure that the spliterator is only used by one
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    94
 * thread at a time.  This is generally easy to attain via <em>serial
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    95
 * thread-confinement</em>, which often is a natural consequence of typical
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    96
 * parallel algorithms that work by recursive decomposition.  A thread calling
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    97
 * {@link #trySplit()} may hand over the returned Spliterator to another thread,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    98
 * which in turn may traverse or further split that Spliterator.  The behaviour
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
    99
 * of splitting and traversal is undefined if two or more threads operate
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   100
 * concurrently on the same spliterator.  If the original thread hands a
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   101
 * spliterator off to another thread for processing, it is best if that handoff
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   102
 * occurs before any elements are consumed with {@link #tryAdvance(Consumer)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   103
 * tryAdvance()}, as certain guarantees (such as the accuracy of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   104
 * {@link #estimateSize()} for {@code SIZED} spliterators) are only valid before
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   105
 * traversal has begun.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   106
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   107
 * <p>Primitive subtype specializations of {@code Spliterator} are provided for
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   108
 * {@link OfInt int}, {@link OfLong long}, and {@link OfDouble double} values.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   109
 * The subtype default implementations of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   110
 * {@link Spliterator#tryAdvance(java.util.function.Consumer)}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   111
 * and {@link Spliterator#forEachRemaining(java.util.function.Consumer)} box
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   112
 * primitive values to instances of their corresponding wrapper class.  Such
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   113
 * boxing may undermine any performance advantages gained by using the primitive
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   114
 * specializations.  To avoid boxing, the corresponding primitive-based methods
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   115
 * should be used.  For example,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   116
 * {@link Spliterator.OfInt#tryAdvance(java.util.function.IntConsumer)}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   117
 * and {@link Spliterator.OfInt#forEachRemaining(java.util.function.IntConsumer)}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   118
 * should be used in preference to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   119
 * {@link Spliterator.OfInt#tryAdvance(java.util.function.Consumer)} and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   120
 * {@link Spliterator.OfInt#forEachRemaining(java.util.function.Consumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   121
 * Traversal of primitive values using boxing-based methods
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   122
 * {@link #tryAdvance tryAdvance()} and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   123
 * {@link #forEachRemaining(java.util.function.Consumer) forEachRemaining()}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   124
 * does not affect the order in which the values, transformed to boxed values,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   125
 * are encountered.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   126
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   127
 * @apiNote
28541
f6b5d78556d6 8062901: Iterators is spelled incorrectly in the Javadoc for Spliterator
psandoz
parents: 28059
diff changeset
   128
 * <p>Spliterators, like {@code Iterator}s, are for traversing the elements of
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   129
 * a source.  The {@code Spliterator} API was designed to support efficient
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   130
 * parallel traversal in addition to sequential traversal, by supporting
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   131
 * decomposition as well as single-element iteration.  In addition, the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   132
 * protocol for accessing elements via a Spliterator is designed to impose
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   133
 * smaller per-element overhead than {@code Iterator}, and to avoid the inherent
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   134
 * race involved in having separate methods for {@code hasNext()} and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   135
 * {@code next()}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   136
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   137
 * <p>For mutable sources, arbitrary and non-deterministic behavior may occur if
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   138
 * the source is structurally interfered with (elements added, replaced, or
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   139
 * removed) between the time that the Spliterator binds to its data source and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   140
 * the end of traversal.  For example, such interference will produce arbitrary,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   141
 * non-deterministic results when using the {@code java.util.stream} framework.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   142
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   143
 * <p>Structural interference of a source can be managed in the following ways
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   144
 * (in approximate order of decreasing desirability):
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   145
 * <ul>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   146
 * <li>The source cannot be structurally interfered with.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   147
 * <br>For example, an instance of
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   148
 * {@link java.util.concurrent.CopyOnWriteArrayList} is an immutable source.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   149
 * A Spliterator created from the source reports a characteristic of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   150
 * {@code IMMUTABLE}.</li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   151
 * <li>The source manages concurrent modifications.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   152
 * <br>For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   153
 * is a concurrent source.  A Spliterator created from the source reports a
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   154
 * characteristic of {@code CONCURRENT}.</li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   155
 * <li>The mutable source provides a late-binding and fail-fast Spliterator.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   156
 * <br>Late binding narrows the window during which interference can affect
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   157
 * the calculation; fail-fast detects, on a best-effort basis, that structural
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   158
 * interference has occurred after traversal has commenced and throws
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   159
 * {@link ConcurrentModificationException}.  For example, {@link ArrayList},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   160
 * and many other non-concurrent {@code Collection} classes in the JDK, provide
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   161
 * a late-binding, fail-fast spliterator.</li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   162
 * <li>The mutable source provides a non-late-binding but fail-fast Spliterator.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   163
 * <br>The source increases the likelihood of throwing
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   164
 * {@code ConcurrentModificationException} since the window of potential
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   165
 * interference is larger.</li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   166
 * <li>The mutable source provides a late-binding and non-fail-fast Spliterator.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   167
 * <br>The source risks arbitrary, non-deterministic behavior after traversal
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   168
 * has commenced since interference is not detected.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   169
 * </li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   170
 * <li>The mutable source provides a non-late-binding and non-fail-fast
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   171
 * Spliterator.
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   172
 * <br>The source increases the risk of arbitrary, non-deterministic behavior
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   173
 * since non-detected interference may occur after construction.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   174
 * </li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   175
 * </ul>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   176
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   177
 * <p><b>Example.</b> Here is a class (not a very useful one, except
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   178
 * for illustration) that maintains an array in which the actual data
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   179
 * are held in even locations, and unrelated tag data are held in odd
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   180
 * locations. Its Spliterator ignores the tags.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   181
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   182
 * <pre> {@code
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   183
 * class TaggedArray<T> {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   184
 *   private final Object[] elements; // immutable after construction
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   185
 *   TaggedArray(T[] data, Object[] tags) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   186
 *     int size = data.length;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   187
 *     if (tags.length != size) throw new IllegalArgumentException();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   188
 *     this.elements = new Object[2 * size];
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   189
 *     for (int i = 0, j = 0; i < size; ++i) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   190
 *       elements[j++] = data[i];
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   191
 *       elements[j++] = tags[i];
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   192
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   193
 *   }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   194
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   195
 *   public Spliterator<T> spliterator() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   196
 *     return new TaggedArraySpliterator<>(elements, 0, elements.length);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   197
 *   }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   198
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   199
 *   static class TaggedArraySpliterator<T> implements Spliterator<T> {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   200
 *     private final Object[] array;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   201
 *     private int origin; // current index, advanced on split or traversal
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   202
 *     private final int fence; // one past the greatest index
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   203
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   204
 *     TaggedArraySpliterator(Object[] array, int origin, int fence) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   205
 *       this.array = array; this.origin = origin; this.fence = fence;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   206
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   207
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   208
 *     public void forEachRemaining(Consumer<? super T> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   209
 *       for (; origin < fence; origin += 2)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   210
 *         action.accept((T) array[origin]);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   211
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   212
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   213
 *     public boolean tryAdvance(Consumer<? super T> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   214
 *       if (origin < fence) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   215
 *         action.accept((T) array[origin]);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   216
 *         origin += 2;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   217
 *         return true;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   218
 *       }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   219
 *       else // cannot advance
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   220
 *         return false;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   221
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   222
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   223
 *     public Spliterator<T> trySplit() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   224
 *       int lo = origin; // divide range in half
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   225
 *       int mid = ((lo + fence) >>> 1) & ~1; // force midpoint to be even
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   226
 *       if (lo < mid) { // split out left half
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   227
 *         origin = mid; // reset this Spliterator's origin
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   228
 *         return new TaggedArraySpliterator<>(array, lo, mid);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   229
 *       }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   230
 *       else       // too small to split
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   231
 *         return null;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   232
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   233
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   234
 *     public long estimateSize() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   235
 *       return (long)((fence - origin) / 2);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   236
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   237
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   238
 *     public int characteristics() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   239
 *       return ORDERED | SIZED | IMMUTABLE | SUBSIZED;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   240
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   241
 *   }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   242
 * }}</pre>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   243
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   244
 * <p>As an example how a parallel computation framework, such as the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   245
 * {@code java.util.stream} package, would use Spliterator in a parallel
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   246
 * computation, here is one way to implement an associated parallel forEach,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   247
 * that illustrates the primary usage idiom of splitting off subtasks until
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   248
 * the estimated amount of work is small enough to perform
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   249
 * sequentially. Here we assume that the order of processing across
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   250
 * subtasks doesn't matter; different (forked) tasks may further split
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   251
 * and process elements concurrently in undetermined order.  This
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   252
 * example uses a {@link java.util.concurrent.CountedCompleter};
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   253
 * similar usages apply to other parallel task constructions.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   254
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   255
 * <pre>{@code
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   256
 * static <T> void parEach(TaggedArray<T> a, Consumer<T> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   257
 *   Spliterator<T> s = a.spliterator();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   258
 *   long targetBatchSize = s.estimateSize() / (ForkJoinPool.getCommonPoolParallelism() * 8);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   259
 *   new ParEach(null, s, action, targetBatchSize).invoke();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   260
 * }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   261
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   262
 * static class ParEach<T> extends CountedCompleter<Void> {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   263
 *   final Spliterator<T> spliterator;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   264
 *   final Consumer<T> action;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   265
 *   final long targetBatchSize;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   266
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   267
 *   ParEach(ParEach<T> parent, Spliterator<T> spliterator,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   268
 *           Consumer<T> action, long targetBatchSize) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   269
 *     super(parent);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   270
 *     this.spliterator = spliterator; this.action = action;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   271
 *     this.targetBatchSize = targetBatchSize;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   272
 *   }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   273
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   274
 *   public void compute() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   275
 *     Spliterator<T> sub;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   276
 *     while (spliterator.estimateSize() > targetBatchSize &&
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   277
 *            (sub = spliterator.trySplit()) != null) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   278
 *       addToPendingCount(1);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   279
 *       new ParEach<>(this, sub, action, targetBatchSize).fork();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   280
 *     }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   281
 *     spliterator.forEachRemaining(action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   282
 *     propagateCompletion();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   283
 *   }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   284
 * }}</pre>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   285
 *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   286
 * @implNote
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   287
 * If the boolean system property {@code org.openjdk.java.util.stream.tripwire}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   288
 * is set to {@code true} then diagnostic warnings are reported if boxing of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   289
 * primitive values occur when operating on primitive subtype specializations.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   290
 *
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   291
 * @param <T> the type of elements returned by this Spliterator
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   292
 *
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   293
 * @see Collection
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   294
 * @since 1.8
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   295
 */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   296
public interface Spliterator<T> {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   297
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   298
     * If a remaining element exists, performs the given action on it,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   299
     * returning {@code true}; else returns {@code false}.  If this
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   300
     * Spliterator is {@link #ORDERED} the action is performed on the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   301
     * next element in encounter order.  Exceptions thrown by the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   302
     * action are relayed to the caller.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   303
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   304
     * @param action The action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   305
     * @return {@code false} if no remaining elements existed
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   306
     * upon entry to this method, else {@code true}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   307
     * @throws NullPointerException if the specified action is null
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   308
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   309
    boolean tryAdvance(Consumer<? super T> action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   310
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   311
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   312
     * Performs the given action for each remaining element, sequentially in
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   313
     * the current thread, until all elements have been processed or the action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   314
     * throws an exception.  If this Spliterator is {@link #ORDERED}, actions
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   315
     * are performed in encounter order.  Exceptions thrown by the action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   316
     * are relayed to the caller.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   317
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   318
     * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   319
     * The default implementation repeatedly invokes {@link #tryAdvance} until
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   320
     * it returns {@code false}.  It should be overridden whenever possible.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   321
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   322
     * @param action The action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   323
     * @throws NullPointerException if the specified action is null
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   324
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   325
    default void forEachRemaining(Consumer<? super T> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   326
        do { } while (tryAdvance(action));
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   327
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   328
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   329
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   330
     * If this spliterator can be partitioned, returns a Spliterator
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   331
     * covering elements, that will, upon return from this method, not
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   332
     * be covered by this Spliterator.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   333
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   334
     * <p>If this Spliterator is {@link #ORDERED}, the returned Spliterator
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   335
     * must cover a strict prefix of the elements.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   336
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   337
     * <p>Unless this Spliterator covers an infinite number of elements,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   338
     * repeated calls to {@code trySplit()} must eventually return {@code null}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   339
     * Upon non-null return:
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   340
     * <ul>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   341
     * <li>the value reported for {@code estimateSize()} before splitting,
17693
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   342
     * must, after splitting, be greater than or equal to {@code estimateSize()}
2d7cbdb1bb53 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
psandoz
parents: 17190
diff changeset
   343
     * for this and the returned Spliterator; and</li>
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   344
     * <li>if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   345
     * for this spliterator before splitting must be equal to the sum of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   346
     * {@code estimateSize()} for this and the returned Spliterator after
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   347
     * splitting.</li>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   348
     * </ul>
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   349
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   350
     * <p>This method may return {@code null} for any reason,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   351
     * including emptiness, inability to split after traversal has
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   352
     * commenced, data structure constraints, and efficiency
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   353
     * considerations.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   354
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   355
     * @apiNote
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   356
     * An ideal {@code trySplit} method efficiently (without
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   357
     * traversal) divides its elements exactly in half, allowing
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   358
     * balanced parallel computation.  Many departures from this ideal
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   359
     * remain highly effective; for example, only approximately
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   360
     * splitting an approximately balanced tree, or for a tree in
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   361
     * which leaf nodes may contain either one or two elements,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   362
     * failing to further split these nodes.  However, large
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   363
     * deviations in balance and/or overly inefficient {@code
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   364
     * trySplit} mechanics typically result in poor parallel
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   365
     * performance.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   366
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   367
     * @return a {@code Spliterator} covering some portion of the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   368
     * elements, or {@code null} if this spliterator cannot be split
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   369
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   370
    Spliterator<T> trySplit();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   371
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   372
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   373
     * Returns an estimate of the number of elements that would be
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   374
     * encountered by a {@link #forEachRemaining} traversal, or returns {@link
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   375
     * Long#MAX_VALUE} if infinite, unknown, or too expensive to compute.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   376
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   377
     * <p>If this Spliterator is {@link #SIZED} and has not yet been partially
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   378
     * traversed or split, or this Spliterator is {@link #SUBSIZED} and has
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   379
     * not yet been partially traversed, this estimate must be an accurate
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   380
     * count of elements that would be encountered by a complete traversal.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   381
     * Otherwise, this estimate may be arbitrarily inaccurate, but must decrease
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   382
     * as specified across invocations of {@link #trySplit}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   383
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   384
     * @apiNote
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   385
     * Even an inexact estimate is often useful and inexpensive to compute.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   386
     * For example, a sub-spliterator of an approximately balanced binary tree
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   387
     * may return a value that estimates the number of elements to be half of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   388
     * that of its parent; if the root Spliterator does not maintain an
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   389
     * accurate count, it could estimate size to be the power of two
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   390
     * corresponding to its maximum depth.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   391
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   392
     * @return the estimated size, or {@code Long.MAX_VALUE} if infinite,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   393
     *         unknown, or too expensive to compute.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   394
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   395
    long estimateSize();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   396
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   397
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   398
     * Convenience method that returns {@link #estimateSize()} if this
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   399
     * Spliterator is {@link #SIZED}, else {@code -1}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   400
     * @implSpec
17920
eef25bc37ccd 8014732: Minor spec issue: java.util.Spliterator.getExactSizeIfKnown
psandoz
parents: 17694
diff changeset
   401
     * The default implementation returns the result of {@code estimateSize()}
eef25bc37ccd 8014732: Minor spec issue: java.util.Spliterator.getExactSizeIfKnown
psandoz
parents: 17694
diff changeset
   402
     * if the Spliterator reports a characteristic of {@code SIZED}, and
eef25bc37ccd 8014732: Minor spec issue: java.util.Spliterator.getExactSizeIfKnown
psandoz
parents: 17694
diff changeset
   403
     * {@code -1} otherwise.
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   404
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   405
     * @return the exact size, if known, else {@code -1}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   406
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   407
    default long getExactSizeIfKnown() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   408
        return (characteristics() & SIZED) == 0 ? -1L : estimateSize();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   409
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   410
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   411
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   412
     * Returns a set of characteristics of this Spliterator and its
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   413
     * elements. The result is represented as ORed values from {@link
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   414
     * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   415
     * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   416
     * {@link #SUBSIZED}.  Repeated calls to {@code characteristics()} on
20744
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   417
     * a given spliterator, prior to or in-between calls to {@code trySplit},
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   418
     * should always return the same result.
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   419
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   420
     * <p>If a Spliterator reports an inconsistent set of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   421
     * characteristics (either those returned from a single invocation
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   422
     * or across multiple invocations), no guarantees can be made
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   423
     * about any computation using this Spliterator.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   424
     *
20744
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   425
     * @apiNote The characteristics of a given spliterator before splitting
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   426
     * may differ from the characteristics after splitting.  For specific
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   427
     * examples see the characteristic values {@link #SIZED}, {@link #SUBSIZED}
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   428
     * and {@link #CONCURRENT}.
66fd18be6993 8020061: Clarify reporting characteristics between splits
psandoz
parents: 20183
diff changeset
   429
     *
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   430
     * @return a representation of characteristics
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   431
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   432
    int characteristics();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   433
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   434
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   435
     * Returns {@code true} if this Spliterator's {@link
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   436
     * #characteristics} contain all of the given characteristics.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   437
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   438
     * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   439
     * The default implementation returns true if the corresponding bits
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   440
     * of the given characteristics are set.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   441
     *
18796
486b43748d9b 8020294: Fix doclint issues in java.util.Spliterator
darcy
parents: 17920
diff changeset
   442
     * @param characteristics the characteristics to check for
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   443
     * @return {@code true} if all the specified characteristics are present,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   444
     * else {@code false}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   445
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   446
    default boolean hasCharacteristics(int characteristics) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   447
        return (characteristics() & characteristics) == characteristics;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   448
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   449
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   450
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   451
     * If this Spliterator's source is {@link #SORTED} by a {@link Comparator},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   452
     * returns that {@code Comparator}. If the source is {@code SORTED} in
17190
7e650321026c 8013413: javadoc warnings
alanb
parents: 16929
diff changeset
   453
     * {@linkplain Comparable natural order}, returns {@code null}.  Otherwise,
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   454
     * if the source is not {@code SORTED}, throws {@link IllegalStateException}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   455
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   456
     * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   457
     * The default implementation always throws {@link IllegalStateException}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   458
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   459
     * @return a Comparator, or {@code null} if the elements are sorted in the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   460
     * natural order.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   461
     * @throws IllegalStateException if the spliterator does not report
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   462
     *         a characteristic of {@code SORTED}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   463
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   464
    default Comparator<? super T> getComparator() {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   465
        throw new IllegalStateException();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   466
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   467
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   468
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   469
     * Characteristic value signifying that an encounter order is defined for
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   470
     * elements. If so, this Spliterator guarantees that method
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   471
     * {@link #trySplit} splits a strict prefix of elements, that method
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   472
     * {@link #tryAdvance} steps by one element in prefix order, and that
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   473
     * {@link #forEachRemaining} performs actions in encounter order.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   474
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   475
     * <p>A {@link Collection} has an encounter order if the corresponding
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   476
     * {@link Collection#iterator} documents an order. If so, the encounter
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   477
     * order is the same as the documented order. Otherwise, a collection does
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   478
     * not have an encounter order.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   479
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   480
     * @apiNote Encounter order is guaranteed to be ascending index order for
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   481
     * any {@link List}. But no order is guaranteed for hash-based collections
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   482
     * such as {@link HashSet}. Clients of a Spliterator that reports
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   483
     * {@code ORDERED} are expected to preserve ordering constraints in
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   484
     * non-commutative parallel computations.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   485
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   486
    public static final int ORDERED    = 0x00000010;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   487
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   488
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   489
     * Characteristic value signifying that, for each pair of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   490
     * encountered elements {@code x, y}, {@code !x.equals(y)}. This
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   491
     * applies for example, to a Spliterator based on a {@link Set}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   492
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   493
    public static final int DISTINCT   = 0x00000001;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   494
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   495
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   496
     * Characteristic value signifying that encounter order follows a defined
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   497
     * sort order. If so, method {@link #getComparator()} returns the associated
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   498
     * Comparator, or {@code null} if all elements are {@link Comparable} and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   499
     * are sorted by their natural ordering.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   500
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   501
     * <p>A Spliterator that reports {@code SORTED} must also report
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   502
     * {@code ORDERED}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   503
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   504
     * @apiNote The spliterators for {@code Collection} classes in the JDK that
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   505
     * implement {@link NavigableSet} or {@link SortedSet} report {@code SORTED}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   506
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   507
    public static final int SORTED     = 0x00000004;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   508
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   509
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   510
     * Characteristic value signifying that the value returned from
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   511
     * {@code estimateSize()} prior to traversal or splitting represents a
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   512
     * finite size that, in the absence of structural source modification,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   513
     * represents an exact count of the number of elements that would be
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   514
     * encountered by a complete traversal.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   515
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   516
     * @apiNote Most Spliterators for Collections, that cover all elements of a
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   517
     * {@code Collection} report this characteristic. Sub-spliterators, such as
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   518
     * those for {@link HashSet}, that cover a sub-set of elements and
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   519
     * approximate their reported size do not.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   520
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   521
    public static final int SIZED      = 0x00000040;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   522
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   523
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   524
     * Characteristic value signifying that the source guarantees that
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   525
     * encountered elements will not be {@code null}. (This applies,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   526
     * for example, to most concurrent collections, queues, and maps.)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   527
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   528
    public static final int NONNULL    = 0x00000100;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   529
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   530
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   531
     * Characteristic value signifying that the element source cannot be
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   532
     * structurally modified; that is, elements cannot be added, replaced, or
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   533
     * removed, so such changes cannot occur during traversal. A Spliterator
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   534
     * that does not report {@code IMMUTABLE} or {@code CONCURRENT} is expected
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   535
     * to have a documented policy (for example throwing
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   536
     * {@link ConcurrentModificationException}) concerning structural
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   537
     * interference detected during traversal.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   538
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   539
    public static final int IMMUTABLE  = 0x00000400;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   540
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   541
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   542
     * Characteristic value signifying that the element source may be safely
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   543
     * concurrently modified (allowing additions, replacements, and/or removals)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   544
     * by multiple threads without external synchronization. If so, the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   545
     * Spliterator is expected to have a documented policy concerning the impact
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   546
     * of modifications during traversal.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   547
     *
20183
584504d38d79 8024405: Spliterators.spliterator should support CONCURRENT characteristic
psandoz
parents: 19435
diff changeset
   548
     * <p>A top-level Spliterator should not report both {@code CONCURRENT} and
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   549
     * {@code SIZED}, since the finite size, if known, may change if the source
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   550
     * is concurrently modified during traversal. Such a Spliterator is
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   551
     * inconsistent and no guarantees can be made about any computation using
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   552
     * that Spliterator. Sub-spliterators may report {@code SIZED} if the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   553
     * sub-split size is known and additions or removals to the source are not
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   554
     * reflected when traversing.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   555
     *
28666
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   556
     * <p>A top-level Spliterator should not report both {@code CONCURRENT} and
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   557
     * {@code IMMUTABLE}, since they are mutually exclusive. Such a Spliterator
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   558
     * is inconsistent and no guarantees can be made about any computation using
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   559
     * that Spliterator. Sub-spliterators may report {@code IMMUTABLE} if
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   560
     * additions or removals to the source are not reflected when traversing.
49cdfa0ea390 8032513: The Spliterator characteristics CONCURRENT and IMMUTABLE are mutually exclusive
psandoz
parents: 28541
diff changeset
   561
     *
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   562
     * @apiNote Most concurrent collections maintain a consistency policy
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   563
     * guaranteeing accuracy with respect to elements present at the point of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   564
     * Spliterator construction, but possibly not reflecting subsequent
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   565
     * additions or removals.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   566
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   567
    public static final int CONCURRENT = 0x00001000;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   568
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   569
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   570
     * Characteristic value signifying that all Spliterators resulting from
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   571
     * {@code trySplit()} will be both {@link #SIZED} and {@link #SUBSIZED}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   572
     * (This means that all child Spliterators, whether direct or indirect, will
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   573
     * be {@code SIZED}.)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   574
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   575
     * <p>A Spliterator that does not report {@code SIZED} as required by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   576
     * {@code SUBSIZED} is inconsistent and no guarantees can be made about any
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   577
     * computation using that Spliterator.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   578
     *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   579
     * @apiNote Some spliterators, such as the top-level spliterator for an
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   580
     * approximately balanced binary tree, will report {@code SIZED} but not
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   581
     * {@code SUBSIZED}, since it is common to know the size of the entire tree
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   582
     * but not the exact sizes of subtrees.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   583
     */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   584
    public static final int SUBSIZED = 0x00004000;
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   585
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   586
    /**
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   587
     * A Spliterator specialized for primitive values.
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   588
     *
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   589
     * @param <T> the type of elements returned by this Spliterator.  The
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   590
     * type must be a wrapper type for a primitive type, such as {@code Integer}
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   591
     * for the primitive {@code int} type.
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   592
     * @param <T_CONS> the type of primitive consumer.  The type must be a
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   593
     * primitive specialization of {@link java.util.function.Consumer} for
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   594
     * {@code T}, such as {@link java.util.function.IntConsumer} for
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   595
     * {@code Integer}.
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   596
     * @param <T_SPLITR> the type of primitive Spliterator.  The type must be
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   597
     * a primitive specialization of Spliterator for {@code T}, such as
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   598
     * {@link Spliterator.OfInt} for {@code Integer}.
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   599
     *
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   600
     * @see Spliterator.OfInt
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   601
     * @see Spliterator.OfLong
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   602
     * @see Spliterator.OfDouble
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   603
     * @since 1.8
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   604
     */
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   605
    public interface OfPrimitive<T, T_CONS, T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>>
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   606
            extends Spliterator<T> {
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   607
        @Override
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   608
        T_SPLITR trySplit();
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   609
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   610
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   611
         * If a remaining element exists, performs the given action on it,
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   612
         * returning {@code true}; else returns {@code false}.  If this
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   613
         * Spliterator is {@link #ORDERED} the action is performed on the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   614
         * next element in encounter order.  Exceptions thrown by the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   615
         * action are relayed to the caller.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   616
         *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   617
         * @param action The action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   618
         * @return {@code false} if no remaining elements existed
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   619
         * upon entry to this method, else {@code true}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   620
         * @throws NullPointerException if the specified action is null
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   621
         */
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20744
diff changeset
   622
        @SuppressWarnings("overloads")
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   623
        boolean tryAdvance(T_CONS action);
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   624
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   625
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   626
         * Performs the given action for each remaining element, sequentially in
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   627
         * the current thread, until all elements have been processed or the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   628
         * action throws an exception.  If this Spliterator is {@link #ORDERED},
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   629
         * actions are performed in encounter order.  Exceptions thrown by the
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   630
         * action are relayed to the caller.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   631
         *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   632
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   633
         * The default implementation repeatedly invokes {@link #tryAdvance}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   634
         * until it returns {@code false}.  It should be overridden whenever
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   635
         * possible.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   636
         *
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   637
         * @param action The action
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   638
         * @throws NullPointerException if the specified action is null
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   639
         */
21339
20e8b81964d5 8025909: Lambda Library Spec Updates
henryjen
parents: 20744
diff changeset
   640
        @SuppressWarnings("overloads")
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   641
        default void forEachRemaining(T_CONS action) {
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   642
            do { } while (tryAdvance(action));
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   643
        }
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   644
    }
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   645
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   646
    /**
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   647
     * A Spliterator specialized for {@code int} values.
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   648
     * @since 1.8
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   649
     */
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   650
    public interface OfInt extends OfPrimitive<Integer, IntConsumer, OfInt> {
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   651
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   652
        @Override
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   653
        OfInt trySplit();
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   654
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   655
        @Override
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   656
        boolean tryAdvance(IntConsumer action);
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   657
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   658
        @Override
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   659
        default void forEachRemaining(IntConsumer action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   660
            do { } while (tryAdvance(action));
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   661
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   662
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   663
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   664
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   665
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   666
         * If the action is an instance of {@code IntConsumer} then it is cast
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   667
         * to {@code IntConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   668
         * {@link #tryAdvance(java.util.function.IntConsumer)}; otherwise
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   669
         * the action is adapted to an instance of {@code IntConsumer}, by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   670
         * boxing the argument of {@code IntConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   671
         * {@link #tryAdvance(java.util.function.IntConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   672
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   673
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   674
        default boolean tryAdvance(Consumer<? super Integer> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   675
            if (action instanceof IntConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   676
                return tryAdvance((IntConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   677
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   678
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   679
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   680
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   681
                                  "{0} calling Spliterator.OfInt.tryAdvance((IntConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   682
                return tryAdvance((IntConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   683
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   684
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   685
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   686
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   687
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   688
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   689
         * If the action is an instance of {@code IntConsumer} then it is cast
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   690
         * to {@code IntConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   691
         * {@link #forEachRemaining(java.util.function.IntConsumer)}; otherwise
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   692
         * the action is adapted to an instance of {@code IntConsumer}, by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   693
         * boxing the argument of {@code IntConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   694
         * {@link #forEachRemaining(java.util.function.IntConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   695
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   696
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   697
        default void forEachRemaining(Consumer<? super Integer> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   698
            if (action instanceof IntConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   699
                forEachRemaining((IntConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   700
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   701
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   702
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   703
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   704
                                  "{0} calling Spliterator.OfInt.forEachRemaining((IntConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   705
                forEachRemaining((IntConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   706
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   707
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   708
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   709
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   710
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   711
     * A Spliterator specialized for {@code long} values.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   712
     * @since 1.8
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   713
     */
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   714
    public interface OfLong extends OfPrimitive<Long, LongConsumer, OfLong> {
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   715
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   716
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   717
        OfLong trySplit();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   718
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   719
        @Override
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   720
        boolean tryAdvance(LongConsumer action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   721
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   722
        @Override
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   723
        default void forEachRemaining(LongConsumer action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   724
            do { } while (tryAdvance(action));
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   725
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   726
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   727
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   728
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   729
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   730
         * If the action is an instance of {@code LongConsumer} then it is cast
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   731
         * to {@code LongConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   732
         * {@link #tryAdvance(java.util.function.LongConsumer)}; otherwise
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   733
         * the action is adapted to an instance of {@code LongConsumer}, by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   734
         * boxing the argument of {@code LongConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   735
         * {@link #tryAdvance(java.util.function.LongConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   736
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   737
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   738
        default boolean tryAdvance(Consumer<? super Long> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   739
            if (action instanceof LongConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   740
                return tryAdvance((LongConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   741
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   742
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   743
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   744
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   745
                                  "{0} calling Spliterator.OfLong.tryAdvance((LongConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   746
                return tryAdvance((LongConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   747
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   748
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   749
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   750
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   751
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   752
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   753
         * If the action is an instance of {@code LongConsumer} then it is cast
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   754
         * to {@code LongConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   755
         * {@link #forEachRemaining(java.util.function.LongConsumer)}; otherwise
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   756
         * the action is adapted to an instance of {@code LongConsumer}, by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   757
         * boxing the argument of {@code LongConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   758
         * {@link #forEachRemaining(java.util.function.LongConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   759
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   760
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   761
        default void forEachRemaining(Consumer<? super Long> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   762
            if (action instanceof LongConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   763
                forEachRemaining((LongConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   764
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   765
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   766
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   767
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   768
                                  "{0} calling Spliterator.OfLong.forEachRemaining((LongConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   769
                forEachRemaining((LongConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   770
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   771
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   772
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   773
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   774
    /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   775
     * A Spliterator specialized for {@code double} values.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   776
     * @since 1.8
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   777
     */
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   778
    public interface OfDouble extends OfPrimitive<Double, DoubleConsumer, OfDouble> {
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   779
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   780
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   781
        OfDouble trySplit();
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   782
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   783
        @Override
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   784
        boolean tryAdvance(DoubleConsumer action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   785
17694
31d23e077ab3 8014133: Spliterator.OfPrimitive
psandoz
parents: 17693
diff changeset
   786
        @Override
16929
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   787
        default void forEachRemaining(DoubleConsumer action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   788
            do { } while (tryAdvance(action));
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   789
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   790
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   791
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   792
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   793
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   794
         * If the action is an instance of {@code DoubleConsumer} then it is
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   795
         * cast to {@code DoubleConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   796
         * {@link #tryAdvance(java.util.function.DoubleConsumer)}; otherwise
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   797
         * the action is adapted to an instance of {@code DoubleConsumer}, by
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   798
         * boxing the argument of {@code DoubleConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   799
         * {@link #tryAdvance(java.util.function.DoubleConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   800
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   801
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   802
        default boolean tryAdvance(Consumer<? super Double> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   803
            if (action instanceof DoubleConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   804
                return tryAdvance((DoubleConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   805
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   806
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   807
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   808
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   809
                                  "{0} calling Spliterator.OfDouble.tryAdvance((DoubleConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   810
                return tryAdvance((DoubleConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   811
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   812
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   813
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   814
        /**
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   815
         * {@inheritDoc}
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   816
         * @implSpec
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   817
         * If the action is an instance of {@code DoubleConsumer} then it is
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   818
         * cast to {@code DoubleConsumer} and passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   819
         * {@link #forEachRemaining(java.util.function.DoubleConsumer)};
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   820
         * otherwise the action is adapted to an instance of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   821
         * {@code DoubleConsumer}, by boxing the argument of
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   822
         * {@code DoubleConsumer}, and then passed to
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   823
         * {@link #forEachRemaining(java.util.function.DoubleConsumer)}.
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   824
         */
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   825
        @Override
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   826
        default void forEachRemaining(Consumer<? super Double> action) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   827
            if (action instanceof DoubleConsumer) {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   828
                forEachRemaining((DoubleConsumer) action);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   829
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   830
            else {
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   831
                if (Tripwire.ENABLED)
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   832
                    Tripwire.trip(getClass(),
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   833
                                  "{0} calling Spliterator.OfDouble.forEachRemaining((DoubleConsumer) action::accept)");
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   834
                forEachRemaining((DoubleConsumer) action::accept);
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   835
            }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   836
        }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   837
    }
c984ae5655cb 8010096: Initial java.util.Spliterator putback
briangoetz
parents:
diff changeset
   838
}