java8.util.stream.Node Maven / Gradle / Ivy
Show all versions of streamsupport Show documentation
/*
* 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 java8.util.stream;
import java8.util.function.Consumer;
import java8.util.function.DoubleConsumer;
import java8.util.function.IntConsumer;
import java8.util.function.IntFunction;
import java8.util.function.LongConsumer;
import java8.util.Spliterator;
/**
* An immutable container for describing an ordered sequence of elements of some
* type {@code T}.
*
* 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 flat
* or a leaf; if it has children, it is considered an
* internal node. The size of an internal node is the sum of sizes of
* its children.
*
*
API Note:
*
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 the type of elements.
* @since 1.8
*/
interface Node {
/**
* 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 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 consumer);
/**
* Gets the {@code StreamShape} associated with this {@code Node}.
*
* Implementation Requirements:
The default in {@code Node} returns
* {@code StreamShape.REFERENCE}
*
* @return the stream shape associated with this node
*/
StreamShape getShape();
/**
* Returns the number of child nodes of this node.
*
*
Implementation Requirements:
The default implementation returns zero.
*
* @return the number of child nodes
*/
int getChildCount();
/**
* Retrieves the child {@code Node} at a given index.
*
*
Implementation Requirements:
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
*/
Node getChild(int i);
/**
* 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
*/
Node truncate(long from, long to, IntFunction generator);
/**
* Provides an array view of the contents of this node.
*
* 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 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);
/**
* 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 extends Sink {
/**
* 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 build();
/**
* Specialized @{code Node.Builder} for int elements
*/
interface OfInt extends Node.Builder, Sink.OfInt {
@Override
Node.OfInt build();
}
/**
* Specialized @{code Node.Builder} for long elements
*/
interface OfLong extends Node.Builder, Sink.OfLong {
@Override
Node.OfLong build();
}
/**
* Specialized @{code Node.Builder} for double elements
*/
interface OfDouble extends Node.Builder, Sink.OfDouble {
@Override
Node.OfDouble build();
}
}
public interface OfPrimitive,
T_NODE extends OfPrimitive>
extends Node {
/**
* {@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
T_NODE getChild(int i);
T_NODE truncate(long from, long to, IntFunction generator);
/**
* {@inheritDoc}
*
* Implementation Requirements:
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
T[] asArray(IntFunction generator);
/**
* Views this node as a primitive array.
*
* 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.
*
* @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 {
/**
* {@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
void forEach(Consumer consumer);
/**
* {@inheritDoc}
*
* Implementation Requirements:
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
void copyInto(Integer[] boxed, int offset);
@Override
Node.OfInt truncate(long from, long to, IntFunction generator);
@Override
int[] newArray(int count);
/**
* {@inheritDoc}
* Implementation Requirements:
The default in {@code Node.OfInt} returns
* {@code StreamShape.INT_VALUE}
*/
StreamShape getShape();
}
/**
* Specialized {@code Node} for long elements
*/
interface OfLong extends OfPrimitive {
/**
* {@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
void forEach(Consumer consumer);
/**
* {@inheritDoc}
*
* Implementation Requirements:
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
void copyInto(Long[] boxed, int offset);
@Override
Node.OfLong truncate(long from, long to, IntFunction generator);
@Override
long[] newArray(int count);
/**
* {@inheritDoc}
* Implementation Requirements:
The default in {@code Node.OfLong} returns
* {@code StreamShape.LONG_VALUE}
*/
StreamShape getShape();
}
/**
* Specialized {@code Node} for double elements
*/
interface OfDouble extends OfPrimitive {
/**
* {@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
void forEach(Consumer consumer);
//
/**
* {@inheritDoc}
*
* Implementation Requirements:
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
void copyInto(Double[] boxed, int offset);
@Override
Node.OfDouble truncate(long from, long to, IntFunction generator);
@Override
double[] newArray(int count);
/**
* {@inheritDoc}
*
* Implementation Requirements:
The default in {@code Node.OfDouble} returns
* {@code StreamShape.DOUBLE_VALUE}
*/
StreamShape getShape();
}
}