550 lines
20 KiB
Java
550 lines
20 KiB
Java
/*
|
|
* Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
|
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
*
|
|
* This code is free software; you can redistribute it and/or modify it
|
|
* under the terms of the GNU General Public License version 2 only, as
|
|
* published by the Free Software Foundation. Oracle designates this
|
|
* particular file as subject to the "Classpath" exception as provided
|
|
* by Oracle in the LICENSE file that accompanied this code.
|
|
*
|
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
* version 2 for more details (a copy is included in the LICENSE file that
|
|
* accompanied this code).
|
|
*
|
|
* You should have received a copy of the GNU General Public License version
|
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
*
|
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
* or visit www.oracle.com if you need additional information or have any
|
|
* questions.
|
|
*/
|
|
package java.util.stream;
|
|
|
|
import java.util.Spliterator;
|
|
import java.util.function.Consumer;
|
|
import java.util.function.DoubleConsumer;
|
|
import java.util.function.IntConsumer;
|
|
import java.util.function.IntFunction;
|
|
import java.util.function.LongConsumer;
|
|
|
|
/**
|
|
* An immutable container for describing an ordered sequence of elements of some
|
|
* type {@code T}.
|
|
*
|
|
* <p>A {@code Node} contains a fixed number of elements, which can be accessed
|
|
* via the {@link #count}, {@link #spliterator}, {@link #forEach},
|
|
* {@link #asArray}, or {@link #copyInto} methods. A {@code Node} may have zero
|
|
* or more child {@code Node}s; if it has no children (accessed via
|
|
* {@link #getChildCount} and {@link #getChild(int)}, it is considered <em>flat
|
|
* </em> or a <em>leaf</em>; if it has children, it is considered an
|
|
* <em>internal</em> node. The size of an internal node is the sum of sizes of
|
|
* its children.
|
|
*
|
|
* @apiNote
|
|
* <p>A {@code Node} typically does not store the elements directly, but instead
|
|
* mediates access to one or more existing (effectively immutable) data
|
|
* structures such as a {@code Collection}, array, or a set of other
|
|
* {@code Node}s. Commonly {@code Node}s are formed into a tree whose shape
|
|
* corresponds to the computation tree that produced the elements that are
|
|
* contained in the leaf nodes. The use of {@code Node} within the stream
|
|
* framework is largely to avoid copying data unnecessarily during parallel
|
|
* operations.
|
|
*
|
|
* @param <T> the type of elements.
|
|
* @since 1.8
|
|
* @hide Visible for CTS testing only (OpenJDK8 tests).
|
|
*/
|
|
// Android-changed: Made public for CTS tests only.
|
|
public interface Node<T> {
|
|
|
|
/**
|
|
* Returns a {@link Spliterator} describing the elements contained in this
|
|
* {@code Node}.
|
|
*
|
|
* @return a {@code Spliterator} describing the elements contained in this
|
|
* {@code Node}
|
|
*/
|
|
Spliterator<T> spliterator();
|
|
|
|
/**
|
|
* Traverses the elements of this node, and invoke the provided
|
|
* {@code Consumer} with each element. Elements are provided in encounter
|
|
* order if the source for the {@code Node} has a defined encounter order.
|
|
*
|
|
* @param consumer a {@code Consumer} that is to be invoked with each
|
|
* element in this {@code Node}
|
|
*/
|
|
void forEach(Consumer<? super T> consumer);
|
|
|
|
/**
|
|
* Returns the number of child nodes of this node.
|
|
*
|
|
* @implSpec The default implementation returns zero.
|
|
*
|
|
* @return the number of child nodes
|
|
*/
|
|
default int getChildCount() {
|
|
return 0;
|
|
}
|
|
|
|
/**
|
|
* Retrieves the child {@code Node} at a given index.
|
|
*
|
|
* @implSpec The default implementation always throws
|
|
* {@code IndexOutOfBoundsException}.
|
|
*
|
|
* @param i the index to the child node
|
|
* @return the child node
|
|
* @throws IndexOutOfBoundsException if the index is less than 0 or greater
|
|
* than or equal to the number of child nodes
|
|
*/
|
|
default Node<T> getChild(int i) {
|
|
throw new IndexOutOfBoundsException();
|
|
}
|
|
|
|
/**
|
|
* Return a node describing a subsequence of the elements of this node,
|
|
* starting at the given inclusive start offset and ending at the given
|
|
* exclusive end offset.
|
|
*
|
|
* @param from The (inclusive) starting offset of elements to include, must
|
|
* be in range 0..count().
|
|
* @param to The (exclusive) end offset of elements to include, must be
|
|
* in range 0..count().
|
|
* @param generator A function to be used to create a new array, if needed,
|
|
* for reference nodes.
|
|
* @return the truncated node
|
|
*/
|
|
default Node<T> truncate(long from, long to, IntFunction<T[]> generator) {
|
|
if (from == 0 && to == count())
|
|
return this;
|
|
Spliterator<T> spliterator = spliterator();
|
|
long size = to - from;
|
|
Node.Builder<T> nodeBuilder = Nodes.builder(size, generator);
|
|
nodeBuilder.begin(size);
|
|
for (int i = 0; i < from && spliterator.tryAdvance(e -> { }); i++) { }
|
|
if (to == count()) {
|
|
spliterator.forEachRemaining(nodeBuilder);
|
|
} else {
|
|
for (int i = 0; i < size && spliterator.tryAdvance(nodeBuilder); i++) { }
|
|
}
|
|
nodeBuilder.end();
|
|
return nodeBuilder.build();
|
|
}
|
|
|
|
/**
|
|
* Provides an array view of the contents of this node.
|
|
*
|
|
* <p>Depending on the underlying implementation, this may return a
|
|
* reference to an internal array rather than a copy. Since the returned
|
|
* array may be shared, the returned array should not be modified. The
|
|
* {@code generator} function may be consulted to create the array if a new
|
|
* array needs to be created.
|
|
*
|
|
* @param generator a factory function which takes an integer parameter and
|
|
* returns a new, empty array of that size and of the appropriate
|
|
* array type
|
|
* @return an array containing the contents of this {@code Node}
|
|
*/
|
|
T[] asArray(IntFunction<T[]> generator);
|
|
|
|
/**
|
|
* Copies the content of this {@code Node} into an array, starting at a
|
|
* given offset into the array. It is the caller's responsibility to ensure
|
|
* there is sufficient room in the array, otherwise unspecified behaviour
|
|
* will occur if the array length is less than the number of elements
|
|
* contained in this node.
|
|
*
|
|
* @param array the array into which to copy the contents of this
|
|
* {@code Node}
|
|
* @param offset the starting offset within the array
|
|
* @throws IndexOutOfBoundsException if copying would cause access of data
|
|
* outside array bounds
|
|
* @throws NullPointerException if {@code array} is {@code null}
|
|
*/
|
|
void copyInto(T[] array, int offset);
|
|
|
|
/**
|
|
* Gets the {@code StreamShape} associated with this {@code Node}.
|
|
*
|
|
* @implSpec The default in {@code Node} returns
|
|
* {@code StreamShape.REFERENCE}
|
|
*
|
|
* @return the stream shape associated with this node
|
|
*/
|
|
default StreamShape getShape() {
|
|
return StreamShape.REFERENCE;
|
|
}
|
|
|
|
/**
|
|
* Returns the number of elements contained in this node.
|
|
*
|
|
* @return the number of elements contained in this node
|
|
*/
|
|
long count();
|
|
|
|
/**
|
|
* A mutable builder for a {@code Node} that implements {@link Sink}, which
|
|
* builds a flat node containing the elements that have been pushed to it.
|
|
*/
|
|
interface Builder<T> extends Sink<T> {
|
|
|
|
/**
|
|
* Builds the node. Should be called after all elements have been
|
|
* pushed and signalled with an invocation of {@link Sink#end()}.
|
|
*
|
|
* @return the resulting {@code Node}
|
|
*/
|
|
Node<T> build();
|
|
|
|
/**
|
|
* Specialized @{code Node.Builder} for int elements
|
|
*/
|
|
interface OfInt extends Node.Builder<Integer>, Sink.OfInt {
|
|
@Override
|
|
Node.OfInt build();
|
|
}
|
|
|
|
/**
|
|
* Specialized @{code Node.Builder} for long elements
|
|
*/
|
|
interface OfLong extends Node.Builder<Long>, Sink.OfLong {
|
|
@Override
|
|
Node.OfLong build();
|
|
}
|
|
|
|
/**
|
|
* Specialized @{code Node.Builder} for double elements
|
|
*/
|
|
interface OfDouble extends Node.Builder<Double>, Sink.OfDouble {
|
|
@Override
|
|
Node.OfDouble build();
|
|
}
|
|
}
|
|
|
|
public interface OfPrimitive<T, T_CONS, T_ARR,
|
|
T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>,
|
|
T_NODE extends OfPrimitive<T, T_CONS, T_ARR, T_SPLITR, T_NODE>>
|
|
extends Node<T> {
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @return a {@link Spliterator.OfPrimitive} describing the elements of
|
|
* this node
|
|
*/
|
|
@Override
|
|
T_SPLITR spliterator();
|
|
|
|
/**
|
|
* Traverses the elements of this node, and invoke the provided
|
|
* {@code action} with each element.
|
|
*
|
|
* @param action a consumer that is to be invoked with each
|
|
* element in this {@code Node.OfPrimitive}
|
|
*/
|
|
@SuppressWarnings("overloads")
|
|
void forEach(T_CONS action);
|
|
|
|
@Override
|
|
default T_NODE getChild(int i) {
|
|
throw new IndexOutOfBoundsException();
|
|
}
|
|
|
|
T_NODE truncate(long from, long to, IntFunction<T[]> generator);
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @implSpec the default implementation invokes the generator to create
|
|
* an instance of a boxed primitive array with a length of
|
|
* {@link #count()} and then invokes {@link #copyInto(T[], int)} with
|
|
* that array at an offset of 0.
|
|
*/
|
|
@Override
|
|
default T[] asArray(IntFunction<T[]> generator) {
|
|
if (java.util.stream.Tripwire.ENABLED)
|
|
java.util.stream.Tripwire.trip(getClass(), "{0} calling Node.OfPrimitive.asArray");
|
|
|
|
long size = count();
|
|
if (size >= Nodes.MAX_ARRAY_SIZE)
|
|
throw new IllegalArgumentException(Nodes.BAD_SIZE);
|
|
T[] boxed = generator.apply((int) count());
|
|
copyInto(boxed, 0);
|
|
return boxed;
|
|
}
|
|
|
|
/**
|
|
* Views this node as a primitive array.
|
|
*
|
|
* <p>Depending on the underlying implementation this may return a
|
|
* reference to an internal array rather than a copy. It is the callers
|
|
* responsibility to decide if either this node or the array is utilized
|
|
* as the primary reference for the data.</p>
|
|
*
|
|
* @return an array containing the contents of this {@code Node}
|
|
*/
|
|
T_ARR asPrimitiveArray();
|
|
|
|
/**
|
|
* Creates a new primitive array.
|
|
*
|
|
* @param count the length of the primitive array.
|
|
* @return the new primitive array.
|
|
*/
|
|
T_ARR newArray(int count);
|
|
|
|
/**
|
|
* Copies the content of this {@code Node} into a primitive array,
|
|
* starting at a given offset into the array. It is the caller's
|
|
* responsibility to ensure there is sufficient room in the array.
|
|
*
|
|
* @param array the array into which to copy the contents of this
|
|
* {@code Node}
|
|
* @param offset the starting offset within the array
|
|
* @throws IndexOutOfBoundsException if copying would cause access of
|
|
* data outside array bounds
|
|
* @throws NullPointerException if {@code array} is {@code null}
|
|
*/
|
|
void copyInto(T_ARR array, int offset);
|
|
}
|
|
|
|
/**
|
|
* Specialized {@code Node} for int elements
|
|
*/
|
|
interface OfInt extends OfPrimitive<Integer, IntConsumer, int[], Spliterator.OfInt, OfInt> {
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @param consumer a {@code Consumer} that is to be invoked with each
|
|
* element in this {@code Node}. If this is an
|
|
* {@code IntConsumer}, it is cast to {@code IntConsumer} so the
|
|
* elements may be processed without boxing.
|
|
*/
|
|
@Override
|
|
default void forEach(Consumer<? super Integer> consumer) {
|
|
if (consumer instanceof IntConsumer) {
|
|
forEach((IntConsumer) consumer);
|
|
}
|
|
else {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfInt.forEachRemaining(Consumer)");
|
|
spliterator().forEachRemaining(consumer);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @implSpec the default implementation invokes {@link #asPrimitiveArray()} to
|
|
* obtain an int[] array then and copies the elements from that int[]
|
|
* array into the boxed Integer[] array. This is not efficient and it
|
|
* is recommended to invoke {@link #copyInto(Object, int)}.
|
|
*/
|
|
@Override
|
|
default void copyInto(Integer[] boxed, int offset) {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfInt.copyInto(Integer[], int)");
|
|
|
|
int[] array = asPrimitiveArray();
|
|
for (int i = 0; i < array.length; i++) {
|
|
boxed[offset + i] = array[i];
|
|
}
|
|
}
|
|
|
|
@Override
|
|
default Node.OfInt truncate(long from, long to, IntFunction<Integer[]> generator) {
|
|
if (from == 0 && to == count())
|
|
return this;
|
|
long size = to - from;
|
|
Spliterator.OfInt spliterator = spliterator();
|
|
Node.Builder.OfInt nodeBuilder = Nodes.intBuilder(size);
|
|
nodeBuilder.begin(size);
|
|
for (int i = 0; i < from && spliterator.tryAdvance((IntConsumer) e -> { }); i++) { }
|
|
if (to == count()) {
|
|
spliterator.forEachRemaining((IntConsumer) nodeBuilder);
|
|
} else {
|
|
for (int i = 0; i < size && spliterator.tryAdvance((IntConsumer) nodeBuilder); i++) { }
|
|
}
|
|
nodeBuilder.end();
|
|
return nodeBuilder.build();
|
|
}
|
|
|
|
@Override
|
|
default int[] newArray(int count) {
|
|
return new int[count];
|
|
}
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
* @implSpec The default in {@code Node.OfInt} returns
|
|
* {@code StreamShape.INT_VALUE}
|
|
*/
|
|
default StreamShape getShape() {
|
|
return StreamShape.INT_VALUE;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Specialized {@code Node} for long elements
|
|
*/
|
|
interface OfLong extends OfPrimitive<Long, LongConsumer, long[], Spliterator.OfLong, OfLong> {
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @param consumer A {@code Consumer} that is to be invoked with each
|
|
* element in this {@code Node}. If this is an
|
|
* {@code LongConsumer}, it is cast to {@code LongConsumer} so
|
|
* the elements may be processed without boxing.
|
|
*/
|
|
@Override
|
|
default void forEach(Consumer<? super Long> consumer) {
|
|
if (consumer instanceof LongConsumer) {
|
|
forEach((LongConsumer) consumer);
|
|
}
|
|
else {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfLong.forEachRemaining(Consumer)");
|
|
spliterator().forEachRemaining(consumer);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @implSpec the default implementation invokes {@link #asPrimitiveArray()}
|
|
* to obtain a long[] array then and copies the elements from that
|
|
* long[] array into the boxed Long[] array. This is not efficient and
|
|
* it is recommended to invoke {@link #copyInto(Object, int)}.
|
|
*/
|
|
@Override
|
|
default void copyInto(Long[] boxed, int offset) {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfInt.copyInto(Long[], int)");
|
|
|
|
long[] array = asPrimitiveArray();
|
|
for (int i = 0; i < array.length; i++) {
|
|
boxed[offset + i] = array[i];
|
|
}
|
|
}
|
|
|
|
@Override
|
|
default Node.OfLong truncate(long from, long to, IntFunction<Long[]> generator) {
|
|
if (from == 0 && to == count())
|
|
return this;
|
|
long size = to - from;
|
|
Spliterator.OfLong spliterator = spliterator();
|
|
Node.Builder.OfLong nodeBuilder = Nodes.longBuilder(size);
|
|
nodeBuilder.begin(size);
|
|
for (int i = 0; i < from && spliterator.tryAdvance((LongConsumer) e -> { }); i++) { }
|
|
if (to == count()) {
|
|
spliterator.forEachRemaining((LongConsumer) nodeBuilder);
|
|
} else {
|
|
for (int i = 0; i < size && spliterator.tryAdvance((LongConsumer) nodeBuilder); i++) { }
|
|
}
|
|
nodeBuilder.end();
|
|
return nodeBuilder.build();
|
|
}
|
|
|
|
@Override
|
|
default long[] newArray(int count) {
|
|
return new long[count];
|
|
}
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
* @implSpec The default in {@code Node.OfLong} returns
|
|
* {@code StreamShape.LONG_VALUE}
|
|
*/
|
|
default StreamShape getShape() {
|
|
return StreamShape.LONG_VALUE;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Specialized {@code Node} for double elements
|
|
*/
|
|
interface OfDouble extends OfPrimitive<Double, DoubleConsumer, double[], Spliterator.OfDouble, OfDouble> {
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @param consumer A {@code Consumer} that is to be invoked with each
|
|
* element in this {@code Node}. If this is an
|
|
* {@code DoubleConsumer}, it is cast to {@code DoubleConsumer}
|
|
* so the elements may be processed without boxing.
|
|
*/
|
|
@Override
|
|
default void forEach(Consumer<? super Double> consumer) {
|
|
if (consumer instanceof DoubleConsumer) {
|
|
forEach((DoubleConsumer) consumer);
|
|
}
|
|
else {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfLong.forEachRemaining(Consumer)");
|
|
spliterator().forEachRemaining(consumer);
|
|
}
|
|
}
|
|
|
|
//
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @implSpec the default implementation invokes {@link #asPrimitiveArray()}
|
|
* to obtain a double[] array then and copies the elements from that
|
|
* double[] array into the boxed Double[] array. This is not efficient
|
|
* and it is recommended to invoke {@link #copyInto(Object, int)}.
|
|
*/
|
|
@Override
|
|
default void copyInto(Double[] boxed, int offset) {
|
|
if (Tripwire.ENABLED)
|
|
Tripwire.trip(getClass(), "{0} calling Node.OfDouble.copyInto(Double[], int)");
|
|
|
|
double[] array = asPrimitiveArray();
|
|
for (int i = 0; i < array.length; i++) {
|
|
boxed[offset + i] = array[i];
|
|
}
|
|
}
|
|
|
|
@Override
|
|
default Node.OfDouble truncate(long from, long to, IntFunction<Double[]> generator) {
|
|
if (from == 0 && to == count())
|
|
return this;
|
|
long size = to - from;
|
|
Spliterator.OfDouble spliterator = spliterator();
|
|
Node.Builder.OfDouble nodeBuilder = Nodes.doubleBuilder(size);
|
|
nodeBuilder.begin(size);
|
|
for (int i = 0; i < from && spliterator.tryAdvance((DoubleConsumer) e -> { }); i++) { }
|
|
if (to == count()) {
|
|
spliterator.forEachRemaining((DoubleConsumer) nodeBuilder);
|
|
} else {
|
|
for (int i = 0; i < size && spliterator.tryAdvance((DoubleConsumer) nodeBuilder); i++) { }
|
|
}
|
|
nodeBuilder.end();
|
|
return nodeBuilder.build();
|
|
}
|
|
|
|
@Override
|
|
default double[] newArray(int count) {
|
|
return new double[count];
|
|
}
|
|
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @implSpec The default in {@code Node.OfDouble} returns
|
|
* {@code StreamShape.DOUBLE_VALUE}
|
|
*/
|
|
default StreamShape getShape() {
|
|
return StreamShape.DOUBLE_VALUE;
|
|
}
|
|
}
|
|
}
|