/*
* Copyright (c) 2012, 2013, 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
*/
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++) { }
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.
*
* @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}
*/
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) {
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++) { }
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++) { }
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++) { }
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;
}
}
}