14c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath/* 24c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved. 34c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 44c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 54c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * This code is free software; you can redistribute it and/or modify it 64c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * under the terms of the GNU General Public License version 2 only, as 74c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * published by the Free Software Foundation. Oracle designates this 84c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * particular file as subject to the "Classpath" exception as provided 94c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * by Oracle in the LICENSE file that accompanied this code. 104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * This code is distributed in the hope that it will be useful, but WITHOUT 124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * version 2 for more details (a copy is included in the LICENSE file that 154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * accompanied this code). 164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * You should have received a copy of the GNU General Public License version 184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2 along with this work; if not, write to the Free Software Foundation, 194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * or visit www.oracle.com if you need additional information or have any 234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * questions. 244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathpackage java.util; 264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathimport java.util.function.Consumer; 284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathimport java.util.function.DoubleConsumer; 294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathimport java.util.function.IntConsumer; 304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathimport java.util.function.LongConsumer; 314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath/** 334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * An object for traversing and partitioning elements of a source. The source 344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * of elements covered by a Spliterator could be, for example, an array, a 354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Collection}, an IO channel, or a generator function. 364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A Spliterator may traverse elements individually ({@link 384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * #tryAdvance tryAdvance()}) or sequentially in bulk 394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * ({@link #forEachRemaining forEachRemaining()}). 404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A Spliterator may also partition off some of its elements (using 424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #trySplit}) as another Spliterator, to be used in 434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * possibly-parallel operations. Operations using a Spliterator that 444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * cannot split, or does so in a highly imbalanced or inefficient 454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * manner, are unlikely to benefit from parallelism. Traversal 464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and splitting exhaust elements; each Spliterator is useful for only a single 474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * bulk computation. 484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A Spliterator also reports a set of {@link #characteristics()} of its 504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * structure, source, and elements from among {@link #ORDERED}, 514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED}, {@link #NONNULL}, 524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #IMMUTABLE}, {@link #CONCURRENT}, and {@link #SUBSIZED}. These may 534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * be employed by Spliterator clients to control, specialize or simplify 544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * computation. For example, a Spliterator for a {@link Collection} would 554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * report {@code SIZED}, a Spliterator for a {@link Set} would report 564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code DISTINCT}, and a Spliterator for a {@link SortedSet} would also 574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * report {@code SORTED}. Characteristics are reported as a simple unioned bit 584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * set. 594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Some characteristics additionally constrain method behavior; for example if 614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code ORDERED}, traversal methods must conform to their documented ordering. 624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * New characteristics may be defined in the future, so implementors should not 634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * assign meanings to unlisted values. 644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p><a name="binding">A Spliterator that does not report {@code IMMUTABLE} or 664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code CONCURRENT} is expected to have a documented policy concerning: 674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * when the spliterator <em>binds</em> to the element source; and detection of 684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * structural interference of the element source detected after binding.</a> A 694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <em>late-binding</em> Spliterator binds to the source of elements at the 704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * point of first traversal, first split, or first query for estimated size, 714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * rather than at the time the Spliterator is created. A Spliterator that is 724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * not <em>late-binding</em> binds to the source of elements at the point of 734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * construction or first invocation of any method. Modifications made to the 744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * source prior to binding are reflected when the Spliterator is traversed. 754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * After binding a Spliterator should, on a best-effort basis, throw 764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link ConcurrentModificationException} if structural interference is 774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * detected. Spliterators that do this are called <em>fail-fast</em>. The 784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * bulk traversal method ({@link #forEachRemaining forEachRemaining()}) of a 794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator may optimize traversal and check for structural interference 804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * after all elements have been traversed, rather than checking per-element and 814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * failing immediately. 824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Spliterators can provide an estimate of the number of remaining elements 844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * via the {@link #estimateSize} method. Ideally, as reflected in characteristic 854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #SIZED}, this value corresponds exactly to the number of elements 864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * that would be encountered in a successful traversal. However, even when not 874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * exactly known, an estimated value value may still be useful to operations 884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * being performed on the source, such as helping to determine whether it is 894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * preferable to split further or traverse the remaining elements sequentially. 904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Despite their obvious utility in parallel algorithms, spliterators are not 924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * expected to be thread-safe; instead, implementations of parallel algorithms 934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * using spliterators should ensure that the spliterator is only used by one 944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * thread at a time. This is generally easy to attain via <em>serial 954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * thread-confinement</em>, which often is a natural consequence of typical 964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * parallel algorithms that work by recursive decomposition. A thread calling 974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #trySplit()} may hand over the returned Spliterator to another thread, 984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * which in turn may traverse or further split that Spliterator. The behaviour 994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * of splitting and traversal is undefined if two or more threads operate 1004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * concurrently on the same spliterator. If the original thread hands a 1014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * spliterator off to another thread for processing, it is best if that handoff 1024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * occurs before any elements are consumed with {@link #tryAdvance(Consumer) 1034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * tryAdvance()}, as certain guarantees (such as the accuracy of 1044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #estimateSize()} for {@code SIZED} spliterators) are only valid before 1054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * traversal has begun. 1064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Primitive subtype specializations of {@code Spliterator} are provided for 1084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link OfInt int}, {@link OfLong long}, and {@link OfDouble double} values. 1094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The subtype default implementations of 1104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Spliterator#tryAdvance(java.util.function.Consumer)} 1114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and {@link Spliterator#forEachRemaining(java.util.function.Consumer)} box 1124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * primitive values to instances of their corresponding wrapper class. Such 1134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing may undermine any performance advantages gained by using the primitive 1144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * specializations. To avoid boxing, the corresponding primitive-based methods 1154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * should be used. For example, 1164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Spliterator.OfInt#tryAdvance(java.util.function.IntConsumer)} 1174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and {@link Spliterator.OfInt#forEachRemaining(java.util.function.IntConsumer)} 1184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * should be used in preference to 1194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Spliterator.OfInt#tryAdvance(java.util.function.Consumer)} and 1204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Spliterator.OfInt#forEachRemaining(java.util.function.Consumer)}. 1214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Traversal of primitive values using boxing-based methods 1224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance tryAdvance()} and 1234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.Consumer) forEachRemaining()} 1244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * does not affect the order in which the values, transformed to boxed values, 1254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * are encountered. 1264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote 1284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Spliterators, like {@code Iterators}s, are for traversing the elements of 1294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * a source. The {@code Spliterator} API was designed to support efficient 1304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * parallel traversal in addition to sequential traversal, by supporting 1314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * decomposition as well as single-element iteration. In addition, the 1324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * protocol for accessing elements via a Spliterator is designed to impose 1334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * smaller per-element overhead than {@code Iterator}, and to avoid the inherent 1344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * race involved in having separate methods for {@code hasNext()} and 1354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code next()}. 1364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>For mutable sources, arbitrary and non-deterministic behavior may occur if 1384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the source is structurally interfered with (elements added, replaced, or 1394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * removed) between the time that the Spliterator binds to its data source and 1404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the end of traversal. For example, such interference will produce arbitrary, 1414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * non-deterministic results when using the {@code java.util.stream} framework. 1424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Structural interference of a source can be managed in the following ways 1444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * (in approximate order of decreasing desirability): 1454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <ul> 1464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The source cannot be structurally interfered with. 1474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>For example, an instance of 1484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link java.util.concurrent.CopyOnWriteArrayList} is an immutable source. 1494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * A Spliterator created from the source reports a characteristic of 1504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code IMMUTABLE}.</li> 1514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The source manages concurrent modifications. 1524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap} 1534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * is a concurrent source. A Spliterator created from the source reports a 1544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * characteristic of {@code CONCURRENT}.</li> 1554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The mutable source provides a late-binding and fail-fast Spliterator. 1564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>Late binding narrows the window during which interference can affect 1574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the calculation; fail-fast detects, on a best-effort basis, that structural 1584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * interference has occurred after traversal has commenced and throws 1594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link ConcurrentModificationException}. For example, {@link ArrayList}, 1604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and many other non-concurrent {@code Collection} classes in the JDK, provide 1614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * a late-binding, fail-fast spliterator.</li> 1624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The mutable source provides a non-late-binding but fail-fast Spliterator. 1634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>The source increases the likelihood of throwing 1644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code ConcurrentModificationException} since the window of potential 1654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * interference is larger.</li> 1664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The mutable source provides a late-binding and non-fail-fast Spliterator. 1674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>The source risks arbitrary, non-deterministic behavior after traversal 1684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * has commenced since interference is not detected. 1694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * </li> 1704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>The mutable source provides a non-late-binding and non-fail-fast 1714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator. 1724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <br>The source increases the risk of arbitrary, non-deterministic behavior 1734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * since non-detected interference may occur after construction. 1744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * </li> 1754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * </ul> 1764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p><b>Example.</b> Here is a class (not a very useful one, except 1784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for illustration) that maintains an array in which the actual data 1794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * are held in even locations, and unrelated tag data are held in odd 1804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * locations. Its Spliterator ignores the tags. 1814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <pre> {@code 1834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * class TaggedArray<T> { 1844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * private final Object[] elements; // immutable after construction 1854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * TaggedArray(T[] data, Object[] tags) { 1864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * int size = data.length; 1874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * if (tags.length != size) throw new IllegalArgumentException(); 1884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * this.elements = new Object[2 * size]; 1894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for (int i = 0, j = 0; i < size; ++i) { 1904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * elements[j++] = data[i]; 1914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * elements[j++] = tags[i]; 1924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 1934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 1944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public Spliterator<T> spliterator() { 1964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return new TaggedArraySpliterator<>(elements, 0, elements.length); 1974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 1984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 1994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * static class TaggedArraySpliterator<T> implements Spliterator<T> { 2004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * private final Object[] array; 2014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * private int origin; // current index, advanced on split or traversal 2024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * private final int fence; // one past the greatest index 2034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * TaggedArraySpliterator(Object[] array, int origin, int fence) { 2054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * this.array = array; this.origin = origin; this.fence = fence; 2064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public void forEachRemaining(Consumer<? super T> action) { 2094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for (; origin < fence; origin += 2) 2104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action.accept((T) array[origin]); 2114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public boolean tryAdvance(Consumer<? super T> action) { 2144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * if (origin < fence) { 2154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action.accept((T) array[origin]); 2164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * origin += 2; 2174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return true; 2184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * else // cannot advance 2204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return false; 2214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public Spliterator<T> trySplit() { 2244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * int lo = origin; // divide range in half 2254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * int mid = ((lo + fence) >>> 1) & ~1; // force midpoint to be even 2264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * if (lo < mid) { // split out left half 2274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * origin = mid; // reset this Spliterator's origin 2284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return new TaggedArraySpliterator<>(array, lo, mid); 2294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * else // too small to split 2314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return null; 2324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public long estimateSize() { 2354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return (long)((fence - origin) / 2); 2364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public int characteristics() { 2394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * return ORDERED | SIZED | IMMUTABLE | SUBSIZED; 2404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * }}</pre> 2434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>As an example how a parallel computation framework, such as the 2454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code java.util.stream} package, would use Spliterator in a parallel 2464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * computation, here is one way to implement an associated parallel forEach, 2474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * that illustrates the primary usage idiom of splitting off subtasks until 2484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the estimated amount of work is small enough to perform 2494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * sequentially. Here we assume that the order of processing across 2504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * subtasks doesn't matter; different (forked) tasks may further split 2514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and process elements concurrently in undetermined order. This 2524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * example uses a {@link java.util.concurrent.CountedCompleter}; 2534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * similar usages apply to other parallel task constructions. 2544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <pre>{@code 2564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * static <T> void parEach(TaggedArray<T> a, Consumer<T> action) { 2574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator<T> s = a.spliterator(); 2584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * long targetBatchSize = s.estimateSize() / (ForkJoinPool.getCommonPoolParallelism() * 8); 2594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * new ParEach(null, s, action, targetBatchSize).invoke(); 2604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * static class ParEach<T> extends CountedCompleter<Void> { 2634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * final Spliterator<T> spliterator; 2644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * final Consumer<T> action; 2654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * final long targetBatchSize; 2664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * ParEach(ParEach<T> parent, Spliterator<T> spliterator, 2684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Consumer<T> action, long targetBatchSize) { 2694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * super(parent); 2704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * this.spliterator = spliterator; this.action = action; 2714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * this.targetBatchSize = targetBatchSize; 2724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * public void compute() { 2754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator<T> sub; 2764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * while (spliterator.estimateSize() > targetBatchSize && 2774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * (sub = spliterator.trySplit()) != null) { 2784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * addToPendingCount(1); 2794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * new ParEach<>(this, sub, action, targetBatchSize).fork(); 2804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * spliterator.forEachRemaining(action); 2824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * propagateCompletion(); 2834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * } 2844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * }}</pre> 2854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implNote 2874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the boolean system property {@code org.openjdk.java.util.stream.tripwire} 2884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * is set to {@code true} then diagnostic warnings are reported if boxing of 2894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * primitive values occur when operating on primitive subtype specializations. 2904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param <T> the type of elements returned by this Spliterator 2924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 2934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @see Collection 2944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @since 1.8 2954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 2964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamathpublic interface Spliterator<T> { 2974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 2984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If a remaining element exists, performs the given action on it, 2994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * returning {@code true}; else returns {@code false}. If this 3004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator is {@link #ORDERED} the action is performed on the 3014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * next element in encounter order. Exceptions thrown by the 3024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action are relayed to the caller. 3034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param action The action 3054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return {@code false} if no remaining elements existed 3064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * upon entry to this method, else {@code true}. 3074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @throws NullPointerException if the specified action is null 3084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 3094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath boolean tryAdvance(Consumer<? super T> action); 3104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 3114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 3124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Performs the given action for each remaining element, sequentially in 3134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the current thread, until all elements have been processed or the action 3144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * throws an exception. If this Spliterator is {@link #ORDERED}, actions 3154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * are performed in encounter order. Exceptions thrown by the action 3164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * are relayed to the caller. 3174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 3194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The default implementation repeatedly invokes {@link #tryAdvance} until 3204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * it returns {@code false}. It should be overridden whenever possible. 3214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param action The action 3234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @throws NullPointerException if the specified action is null 3244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 3254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(Consumer<? super T> action) { 3264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath do { } while (tryAdvance(action)); 3274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 3284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 3294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 3304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If this spliterator can be partitioned, returns a Spliterator 3314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * covering elements, that will, upon return from this method, not 3324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * be covered by this Spliterator. 3334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>If this Spliterator is {@link #ORDERED}, the returned Spliterator 3354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * must cover a strict prefix of the elements. 3364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>Unless this Spliterator covers an infinite number of elements, 3384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * repeated calls to {@code trySplit()} must eventually return {@code null}. 3394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Upon non-null return: 3404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <ul> 3414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>the value reported for {@code estimateSize()} before splitting, 3424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * must, after splitting, be greater than or equal to {@code estimateSize()} 3434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for this and the returned Spliterator; and</li> 3444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <li>if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()} 3454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for this spliterator before splitting must be equal to the sum of 3464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code estimateSize()} for this and the returned Spliterator after 3474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * splitting.</li> 3484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * </ul> 3494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>This method may return {@code null} for any reason, 3514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * including emptiness, inability to split after traversal has 3524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * commenced, data structure constraints, and efficiency 3534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * considerations. 3544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote 3564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * An ideal {@code trySplit} method efficiently (without 3574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * traversal) divides its elements exactly in half, allowing 3584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * balanced parallel computation. Many departures from this ideal 3594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * remain highly effective; for example, only approximately 3604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * splitting an approximately balanced tree, or for a tree in 3614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * which leaf nodes may contain either one or two elements, 3624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * failing to further split these nodes. However, large 3634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * deviations in balance and/or overly inefficient {@code 3644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * trySplit} mechanics typically result in poor parallel 3654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * performance. 3664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return a {@code Spliterator} covering some portion of the 3684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * elements, or {@code null} if this spliterator cannot be split 3694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 3704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Spliterator<T> trySplit(); 3714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 3724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 3734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Returns an estimate of the number of elements that would be 3744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * encountered by a {@link #forEachRemaining} traversal, or returns {@link 3754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Long#MAX_VALUE} if infinite, unknown, or too expensive to compute. 3764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>If this Spliterator is {@link #SIZED} and has not yet been partially 3784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * traversed or split, or this Spliterator is {@link #SUBSIZED} and has 3794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * not yet been partially traversed, this estimate must be an accurate 3804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * count of elements that would be encountered by a complete traversal. 3814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Otherwise, this estimate may be arbitrarily inaccurate, but must decrease 3824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * as specified across invocations of {@link #trySplit}. 3834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote 3854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Even an inexact estimate is often useful and inexpensive to compute. 3864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * For example, a sub-spliterator of an approximately balanced binary tree 3874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * may return a value that estimates the number of elements to be half of 3884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * that of its parent; if the root Spliterator does not maintain an 3894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * accurate count, it could estimate size to be the power of two 3904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * corresponding to its maximum depth. 3914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 3924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return the estimated size, or {@code Long.MAX_VALUE} if infinite, 3934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * unknown, or too expensive to compute. 3944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 3954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath long estimateSize(); 3964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 3974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 3984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Convenience method that returns {@link #estimateSize()} if this 3994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator is {@link #SIZED}, else {@code -1}. 4004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 4014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The default implementation returns the result of {@code estimateSize()} 4024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * if the Spliterator reports a characteristic of {@code SIZED}, and 4034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code -1} otherwise. 4044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return the exact size, if known, else {@code -1}. 4064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default long getExactSizeIfKnown() { 4084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return (characteristics() & SIZED) == 0 ? -1L : estimateSize(); 4094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 4104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Returns a set of characteristics of this Spliterator and its 4134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * elements. The result is represented as ORed values from {@link 4144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED}, 4154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT}, 4164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #SUBSIZED}. Repeated calls to {@code characteristics()} on 4174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * a given spliterator, prior to or in-between calls to {@code trySplit}, 4184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * should always return the same result. 4194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>If a Spliterator reports an inconsistent set of 4214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * characteristics (either those returned from a single invocation 4224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * or across multiple invocations), no guarantees can be made 4234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * about any computation using this Spliterator. 4244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote The characteristics of a given spliterator before splitting 4264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * may differ from the characteristics after splitting. For specific 4274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * examples see the characteristic values {@link #SIZED}, {@link #SUBSIZED} 4284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * and {@link #CONCURRENT}. 4294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return a representation of characteristics 4314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath int characteristics(); 4334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Returns {@code true} if this Spliterator's {@link 4364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * #characteristics} contain all of the given characteristics. 4374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 4394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The default implementation returns true if the corresponding bits 4404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * of the given characteristics are set. 4414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param characteristics the characteristics to check for 4434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return {@code true} if all the specified characteristics are present, 4444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * else {@code false} 4454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default boolean hasCharacteristics(int characteristics) { 4474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return (characteristics() & characteristics) == characteristics; 4484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 4494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If this Spliterator's source is {@link #SORTED} by a {@link Comparator}, 4524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * returns that {@code Comparator}. If the source is {@code SORTED} in 4534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@linkplain Comparable natural order}, returns {@code null}. Otherwise, 4544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * if the source is not {@code SORTED}, throws {@link IllegalStateException}. 4554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 4574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The default implementation always throws {@link IllegalStateException}. 4584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return a Comparator, or {@code null} if the elements are sorted in the 4604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * natural order. 4614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @throws IllegalStateException if the spliterator does not report 4624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * a characteristic of {@code SORTED}. 4634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default Comparator<? super T> getComparator() { 4654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath throw new IllegalStateException(); 4664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 4674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that an encounter order is defined for 4704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * elements. If so, this Spliterator guarantees that method 4714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #trySplit} splits a strict prefix of elements, that method 4724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance} steps by one element in prefix order, and that 4734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining} performs actions in encounter order. 4744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A {@link Collection} has an encounter order if the corresponding 4764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Collection#iterator} documents an order. If so, the encounter 4774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * order is the same as the documented order. Otherwise, a collection does 4784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * not have an encounter order. 4794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 4804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote Encounter order is guaranteed to be ascending index order for 4814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * any {@link List}. But no order is guaranteed for hash-based collections 4824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * such as {@link HashSet}. Clients of a Spliterator that reports 4834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code ORDERED} are expected to preserve ordering constraints in 4844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * non-commutative parallel computations. 4854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int ORDERED = 0x00000010; 4874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that, for each pair of 4904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * encountered elements {@code x, y}, {@code !x.equals(y)}. This 4914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * applies for example, to a Spliterator based on a {@link Set}. 4924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 4934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int DISTINCT = 0x00000001; 4944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 4954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 4964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that encounter order follows a defined 4974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * sort order. If so, method {@link #getComparator()} returns the associated 4984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Comparator, or {@code null} if all elements are {@link Comparable} and 4994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * are sorted by their natural ordering. 5004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A Spliterator that reports {@code SORTED} must also report 5024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code ORDERED}. 5034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote The spliterators for {@code Collection} classes in the JDK that 5054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * implement {@link NavigableSet} or {@link SortedSet} report {@code SORTED}. 5064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int SORTED = 0x00000004; 5084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that the value returned from 5114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code estimateSize()} prior to traversal or splitting represents a 5124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * finite size that, in the absence of structural source modification, 5134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * represents an exact count of the number of elements that would be 5144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * encountered by a complete traversal. 5154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote Most Spliterators for Collections, that cover all elements of a 5174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code Collection} report this characteristic. Sub-spliterators, such as 5184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * those for {@link HashSet}, that cover a sub-set of elements and 5194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * approximate their reported size do not. 5204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int SIZED = 0x00000040; 5224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that the source guarantees that 5254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * encountered elements will not be {@code null}. (This applies, 5264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for example, to most concurrent collections, queues, and maps.) 5274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int NONNULL = 0x00000100; 5294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that the element source cannot be 5324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * structurally modified; that is, elements cannot be added, replaced, or 5334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * removed, so such changes cannot occur during traversal. A Spliterator 5344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * that does not report {@code IMMUTABLE} or {@code CONCURRENT} is expected 5354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * to have a documented policy (for example throwing 5364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link ConcurrentModificationException}) concerning structural 5374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * interference detected during traversal. 5384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int IMMUTABLE = 0x00000400; 5404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that the element source may be safely 5434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * concurrently modified (allowing additions, replacements, and/or removals) 5444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * by multiple threads without external synchronization. If so, the 5454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator is expected to have a documented policy concerning the impact 5464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * of modifications during traversal. 5474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A top-level Spliterator should not report both {@code CONCURRENT} and 5494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code SIZED}, since the finite size, if known, may change if the source 5504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * is concurrently modified during traversal. Such a Spliterator is 5514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * inconsistent and no guarantees can be made about any computation using 5524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * that Spliterator. Sub-spliterators may report {@code SIZED} if the 5534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * sub-split size is known and additions or removals to the source are not 5544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * reflected when traversing. 5554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote Most concurrent collections maintain a consistency policy 5574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * guaranteeing accuracy with respect to elements present at the point of 5584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator construction, but possibly not reflecting subsequent 5594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * additions or removals. 5604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int CONCURRENT = 0x00001000; 5624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Characteristic value signifying that all Spliterators resulting from 5654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code trySplit()} will be both {@link #SIZED} and {@link #SUBSIZED}. 5664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * (This means that all child Spliterators, whether direct or indirect, will 5674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * be {@code SIZED}.) 5684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * <p>A Spliterator that does not report {@code SIZED} as required by 5704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code SUBSIZED} is inconsistent and no guarantees can be made about any 5714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * computation using that Spliterator. 5724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @apiNote Some spliterators, such as the top-level spliterator for an 5744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * approximately balanced binary tree, will report {@code SIZED} but not 5754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code SUBSIZED}, since it is common to know the size of the entire tree 5764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * but not the exact sizes of subtrees. 5774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public static final int SUBSIZED = 0x00004000; 5794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 5804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 5814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * A Spliterator specialized for primitive values. 5824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param <T> the type of elements returned by this Spliterator. The 5844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * type must be a wrapper type for a primitive type, such as {@code Integer} 5854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * for the primitive {@code int} type. 5864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @paramthe type of primitive consumer. The type must be a 5874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * primitive specialization of {@link java.util.function.Consumer} for 5884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code T}, such as {@link java.util.function.IntConsumer} for 5894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code Integer}. 5904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param the type of primitive Spliterator. The type must be 5914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * a primitive specialization of Spliterator for {@code T}, such as 5924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link Spliterator.OfInt} for {@code Integer}. 5934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 5944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @see Spliterator.OfInt 5954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @see Spliterator.OfLong 5964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @see Spliterator.OfDouble 5974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @since 1.8 5984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 5994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public interface OfPrimitive<T, T_CONS, T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>> 6004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath extends Spliterator<T> { 6014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath T_SPLITR trySplit(); 6034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 6054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If a remaining element exists, performs the given action on it, 6064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * returning {@code true}; else returns {@code false}. If this 6074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Spliterator is {@link #ORDERED} the action is performed on the 6084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * next element in encounter order. Exceptions thrown by the 6094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action are relayed to the caller. 6104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 6114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param action The action 6124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @return {@code false} if no remaining elements existed 6134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * upon entry to this method, else {@code true}. 6144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @throws NullPointerException if the specified action is null 6154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 6164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @SuppressWarnings("overloads") 6174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath boolean tryAdvance(T_CONS action); 6184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 6204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * Performs the given action for each remaining element, sequentially in 6214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the current thread, until all elements have been processed or the 6224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action throws an exception. If this Spliterator is {@link #ORDERED}, 6234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * actions are performed in encounter order. Exceptions thrown by the 6244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * action are relayed to the caller. 6254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 6264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 6274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * The default implementation repeatedly invokes {@link #tryAdvance} 6284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * until it returns {@code false}. It should be overridden whenever 6294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * possible. 6304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * 6314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @param action The action 6324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @throws NullPointerException if the specified action is null 6334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 6344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @SuppressWarnings("overloads") 6354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(T_CONS action) { 6364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath do { } while (tryAdvance(action)); 6374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 6414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * A Spliterator specialized for {@code int} values. 6424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @since 1.8 6434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 6444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public interface OfInt extends OfPrimitive<Integer, IntConsumer, OfInt> { 6454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath OfInt trySplit(); 6484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath boolean tryAdvance(IntConsumer action); 6514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(IntConsumer action) { 6544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath do { } while (tryAdvance(action)); 6554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 6584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 6594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 6604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code IntConsumer} then it is cast 6614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * to {@code IntConsumer} and passed to 6624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.IntConsumer)}; otherwise 6634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the action is adapted to an instance of {@code IntConsumer}, by 6644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing the argument of {@code IntConsumer}, and then passed to 6654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.IntConsumer)}. 6664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 6674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default boolean tryAdvance(Consumer<? super Integer> action) { 6694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof IntConsumer) { 6704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((IntConsumer) action); 6714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 6734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 6744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 6754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfInt.tryAdvance((IntConsumer) action::accept)"); 6764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((IntConsumer) action::accept); 6774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 6804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 6814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 6824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 6834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code IntConsumer} then it is cast 6844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * to {@code IntConsumer} and passed to 6854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.IntConsumer)}; otherwise 6864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the action is adapted to an instance of {@code IntConsumer}, by 6874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing the argument of {@code IntConsumer}, and then passed to 6884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.IntConsumer)}. 6894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 6904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 6914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(Consumer<? super Integer> action) { 6924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof IntConsumer) { 6934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((IntConsumer) action); 6944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 6954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 6964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 6974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 6984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfInt.forEachRemaining((IntConsumer) action::accept)"); 6994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((IntConsumer) action::accept); 7004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 7054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * A Spliterator specialized for {@code long} values. 7064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @since 1.8 7074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 7084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public interface OfLong extends OfPrimitive<Long, LongConsumer, OfLong> { 7094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath OfLong trySplit(); 7124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath boolean tryAdvance(LongConsumer action); 7154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(LongConsumer action) { 7184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath do { } while (tryAdvance(action)); 7194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 7224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 7234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 7244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code LongConsumer} then it is cast 7254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * to {@code LongConsumer} and passed to 7264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.LongConsumer)}; otherwise 7274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the action is adapted to an instance of {@code LongConsumer}, by 7284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing the argument of {@code LongConsumer}, and then passed to 7294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.LongConsumer)}. 7304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 7314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default boolean tryAdvance(Consumer<? super Long> action) { 7334c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof LongConsumer) { 7344c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((LongConsumer) action); 7354c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7364c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 7374c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 7384c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 7394c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfLong.tryAdvance((LongConsumer) action::accept)"); 7404c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((LongConsumer) action::accept); 7414c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7424c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7434c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7444c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 7454c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 7464c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 7474c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code LongConsumer} then it is cast 7484c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * to {@code LongConsumer} and passed to 7494c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.LongConsumer)}; otherwise 7504c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the action is adapted to an instance of {@code LongConsumer}, by 7514c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing the argument of {@code LongConsumer}, and then passed to 7524c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.LongConsumer)}. 7534c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 7544c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7554c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(Consumer<? super Long> action) { 7564c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof LongConsumer) { 7574c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((LongConsumer) action); 7584c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7594c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 7604c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 7614c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 7624c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfLong.forEachRemaining((LongConsumer) action::accept)"); 7634c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((LongConsumer) action::accept); 7644c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7654c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7664c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7674c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7684c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 7694c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * A Spliterator specialized for {@code double} values. 7704c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @since 1.8 7714c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 7724c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath public interface OfDouble extends OfPrimitive<Double, DoubleConsumer, OfDouble> { 7734c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7744c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7754c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath OfDouble trySplit(); 7764c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7774c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7784c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath boolean tryAdvance(DoubleConsumer action); 7794c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7804c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7814c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(DoubleConsumer action) { 7824c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath do { } while (tryAdvance(action)); 7834c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 7844c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 7854c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 7864c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 7874c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 7884c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code DoubleConsumer} then it is 7894c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * cast to {@code DoubleConsumer} and passed to 7904c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.DoubleConsumer)}; otherwise 7914c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * the action is adapted to an instance of {@code DoubleConsumer}, by 7924c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * boxing the argument of {@code DoubleConsumer}, and then passed to 7934c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #tryAdvance(java.util.function.DoubleConsumer)}. 7944c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 7954c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 7964c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default boolean tryAdvance(Consumer<? super Double> action) { 7974c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof DoubleConsumer) { 7984c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((DoubleConsumer) action); 7994c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8004c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 8014c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 8024c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 8034c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfDouble.tryAdvance((DoubleConsumer) action::accept)"); 8044c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath return tryAdvance((DoubleConsumer) action::accept); 8054c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8064c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8074c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath 8084c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath /** 8094c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@inheritDoc} 8104c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * @implSpec 8114c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * If the action is an instance of {@code DoubleConsumer} then it is 8124c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * cast to {@code DoubleConsumer} and passed to 8134c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.DoubleConsumer)}; 8144c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * otherwise the action is adapted to an instance of 8154c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code DoubleConsumer}, by boxing the argument of 8164c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@code DoubleConsumer}, and then passed to 8174c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath * {@link #forEachRemaining(java.util.function.DoubleConsumer)}. 8184c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath */ 8194c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath @Override 8204c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath default void forEachRemaining(Consumer<? super Double> action) { 8214c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (action instanceof DoubleConsumer) { 8224c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((DoubleConsumer) action); 8234c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8244c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath else { 8254c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath if (Tripwire.ENABLED) 8264c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath Tripwire.trip(getClass(), 8274c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath "{0} calling Spliterator.OfDouble.forEachRemaining((DoubleConsumer) action::accept)"); 8284c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath forEachRemaining((DoubleConsumer) action::accept); 8294c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8304c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8314c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath } 8324c89023ef86f29fa9add7db2574f2169fe842577Narayan Kamath} 833