public enum StreamOpFlag extends Enum<StreamOpFlag>
Stream flags may be used to describe characteristics of several different entities associated with streams: stream sources, intermediate operations, and terminal operations. Not all stream flags are meaningful for all entities; the following table summarizes which flags are meaningful in what contexts:
DISTINCT |
SORTED |
ORDERED |
SIZED |
SHORT_CIRCUIT |
|||
---|---|---|---|---|---|---|---|
Stream source | Y | Y | Y | Y | N | ||
Intermediate operation | PCI | PCI | PCI | PC | PI | ||
Terminal operation | N | N | PC | N | PI | ||
Legend | |||||||
Flag | Meaning | ||||||
Y | Allowed | ||||||
N | Invalid | ||||||
P | Preserves | ||||||
C | Clears | ||||||
I | Injects |
In the above table, "PCI" means "may preserve, clear, or inject"; "PC" means "may preserve or clear", "PI" means "may preserve or inject", and "N" means "not valid".
Stream flags are represented by unioned bit sets, so that a single word may describe all the characteristics of a given stream entity, and that, for example, the flags for a stream source can be efficiently combined with the flags for later operations on that stream.
The bit masks STREAM_MASK
, OP_MASK
, and
TERMINAL_OP_MASK
can be ANDed with a bit set of stream flags to
produce a mask containing only the valid flags for that entity type.
When describing a stream source, one only need describe what
characteristics that stream has; when describing a stream operation, one need
describe whether the operation preserves, injects, or clears that
characteristic. Accordingly, two bits are used for each flag, so as to allow
representing not only the presence of of a characteristic, but how an
operation modifies that characteristic. There are two common forms in which
flag bits are combined into an int
bit set. Stream flags
are a unioned bit set constructed by ORing the enum characteristic values of
set()
(or, more commonly, ORing the corresponding static named
constants prefixed with IS_
). Operation flags are a unioned
bit set constructed by ORing the enum characteristic values of set()
or clear()
(to inject, or clear, respectively, the corresponding
flag), or more commonly ORing the corresponding named constants prefixed with
IS_
or NOT_
. Flags that are not marked with IS_
or
NOT_
are implicitly treated as preserved. Care must be taken when
combining bitsets that the correct combining operations are applied in the
correct order.
With the exception of SHORT_CIRCUIT
, stream characteristics can be
derived from the equivalent Spliterator
characteristics:
Spliterator.DISTINCT
, Spliterator.SORTED
,
Spliterator.ORDERED
, and
Spliterator.SIZED
. A spliterator characteristics bit set
can be converted to stream flags using the method
fromCharacteristics(java.util.Spliterator)
and converted back using
toCharacteristics(int)
. (The bit set
SPLITERATOR_CHARACTERISTICS_MASK
is used to AND with a bit set to
produce a valid spliterator characteristics bit set that can be converted to
stream flags.)
The source of a stream encapsulates a spliterator. The characteristics of that source spliterator when transformed to stream flags will be a proper subset of stream flags of that stream. For example:
Spliterator s = ...;
Stream stream = Streams.stream(s);
flagsFromSplitr = fromCharacteristics(s.characteristics());
assert(flagsFromSplitr & stream.getStreamFlags() == flagsFromSplitr);
An intermediate operation, performed on an input stream to create a new output stream, may preserve, clear or inject stream or operation characteristics. Similarly, a terminal operation, performed on an input stream to produce an output result may preserve, clear or inject stream or operation characteristics. Preservation means that if that characteristic is present on the input, then it is also present on the output. Clearing means that the characteristic is not present on the output regardless of the input. Injection means that the characteristic is present on the output regardless of the input. If a characteristic is not cleared or injected then it is implicitly preserved.
A pipeline consists of a stream source encapsulating a spliterator, one or
more intermediate operations, and finally a terminal operation that produces
a result. At each stage of the pipeline, a combined stream and operation
flags can be calculated, using combineOpFlags(int, int)
. Such flags
ensure that preservation, clearing and injecting information is retained at
each stage.
The combined stream and operation flags for the source stage of the pipeline
is calculated as follows:
int flagsForSourceStage = combineOpFlags(sourceFlags, INITIAL_OPS_VALUE);
The combined stream and operation flags of each subsequent intermediate
operation stage in the pipeline is calculated as follows:
int flagsForThisStage = combineOpFlags(flagsForPreviousStage, thisOpFlags);
Finally the flags output from the last intermediate operation of the pipeline
are combined with the operation flags of the terminal operation to produce
the flags output from the pipeline.
Those flags can then be used to apply optimizations. For example, if
SIZED.isKnown(flags)
returns true then the stream size remains
constant throughout the pipeline, this information can be utilized to
pre-allocate data structures and combined with
Spliterator.SUBSIZED
that information can be utilized to
perform concurrent in-place updates into a shared array.
For specific details see the AbstractPipeline
constructors.
Enum Constant and Description |
---|
DISTINCT
Characteristic value signifying that, for each pair of
encountered elements in a stream
x, y , {@code ! |
ORDERED
Characteristic value signifying that an encounter order is
defined for stream elements.
|
SHORT_CIRCUIT
Characteristic value signifying that an operation may short-circuit the
stream.
|
SIZED
Characteristic value signifying that size of the stream
is of a known finite size that is equal to the known finite
size of the source spliterator input to the first stream
in the pipeline.
|
SORTED
Characteristic value signifying that encounter order follows a natural
sort order of comparable elements.
|
Modifier and Type | Field and Description |
---|---|
static int |
INITIAL_OPS_VALUE
The initial value to be combined with the stream flags of the first
stream in the pipeline.
|
static int |
IS_DISTINCT
The bit value to set or inject
DISTINCT . |
static int |
IS_ORDERED
The bit value to set or inject
ORDERED . |
static int |
IS_SHORT_CIRCUIT
The bit value to inject
SHORT_CIRCUIT . |
static int |
IS_SIZED
The bit value to set
SIZED . |
static int |
IS_SORTED
The bit value to set or inject
SORTED . |
static int |
NOT_DISTINCT
The bit value to clear
DISTINCT . |
static int |
NOT_ORDERED
The bit value to clear
ORDERED . |
static int |
NOT_SIZED
The bit value to clear
SIZED . |
static int |
NOT_SORTED
The bit value to clear
SORTED . |
static int |
OP_MASK
The bit mask for intermediate operation flags.
|
static int |
SPLITERATOR_CHARACTERISTICS_MASK
The bit mask for spliterator characteristics
|
static int |
STREAM_MASK
The bit mask for source stream flags.
|
static int |
TERMINAL_OP_MASK
The bit mask for terminal operation flags.
|
static int |
UPSTREAM_TERMINAL_OP_MASK
The bit mask for upstream terminal operation flags.
|
Modifier and Type | Method and Description |
---|---|
boolean |
canSet(java.util.stream.StreamOpFlag.Type t)
Determines if this flag can be set for a flag type.
|
int |
clear()
Gets the bitmap associated with clearing this characteristic.
|
static int |
combineOpFlags(int newStreamOrOpFlags,
int prevCombOpFlags)
Combines stream or operation flags with previously combined stream and
operation flags to produce updated combined stream and operation flags.
|
static int |
fromCharacteristics(int characteristics)
Converts a spliterator characteristic bit set to stream flags.
|
static int |
fromCharacteristics(Spliterator<?> spliterator)
Converts a spliterator characteristic bit set to stream flags.
|
boolean |
isCleared(int flags)
Checks if this flag is cleared on operation flags or combined stream and
operation flags.
|
boolean |
isKnown(int flags)
Checks if this flag is set on stream flags, injected on operation flags,
and injected on combined stream and operation flags.
|
boolean |
isPreserved(int flags)
Checks if this flag is preserved on combined stream and operation flags.
|
boolean |
isStreamFlag()
Determines if this flag is a stream-based flag.
|
int |
set()
Gets the bitmap associated with setting this characteristic.
|
static int |
toCharacteristics(int streamFlags)
Converts stream flags to a spliterator characteristic bit set.
|
static int |
toStreamFlags(int combOpFlags)
Converts combined stream and operation flags to stream flags.
|
static StreamOpFlag |
valueOf(String name)
Returns the enum constant of this type with the specified name.
|
static StreamOpFlag[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
public static final StreamOpFlag DISTINCT
x, y
, !x.equals(y)
.
A stream may have this value or an intermediate operation can preserve, clear or inject this value.
public static final StreamOpFlag SORTED
A stream can have this value or an intermediate operation can preserve, clear or inject this value.
Note: The Spliterator.SORTED
characteristic can define
a sort order with an associated non-null comparator. Augmenting flag
state with addition properties such that those properties can be passed
to operations requires some disruptive changes for a singular use-case.
Furthermore, comparing comparators for equality beyond that of identity
is likely to be unreliable. Therefore the SORTED
characteristic
for a defined non-natural sort order is not mapped internally to the
SORTED
flag.
public static final StreamOpFlag ORDERED
A stream can have this value, an intermediate operation can preserve, clear or inject this value, or a terminal operation can preserve or clear this value.
public static final StreamOpFlag SIZED
A stream can have this value or an intermediate operation can preserve or clear this value.
public static final StreamOpFlag SHORT_CIRCUIT
An intermediate operation can preserve or inject this value, or a terminal operation can preserve or inject this value.
public static final int SPLITERATOR_CHARACTERISTICS_MASK
public static final int STREAM_MASK
public static final int OP_MASK
public static final int TERMINAL_OP_MASK
public static final int UPSTREAM_TERMINAL_OP_MASK
public static final int INITIAL_OPS_VALUE
public static final int IS_DISTINCT
DISTINCT
.public static final int NOT_DISTINCT
DISTINCT
.public static final int IS_SORTED
SORTED
.public static final int NOT_SORTED
SORTED
.public static final int IS_ORDERED
ORDERED
.public static final int NOT_ORDERED
ORDERED
.public static final int IS_SIZED
SIZED
.public static final int NOT_SIZED
SIZED
.public static final int IS_SHORT_CIRCUIT
SHORT_CIRCUIT
.public static StreamOpFlag[] values()
for (StreamOpFlag c : StreamOpFlag.values()) System.out.println(c);
public static StreamOpFlag valueOf(String name)
name
- the name of the enum constant to be returned.IllegalArgumentException
- if this enum type has no constant with the specified nameNullPointerException
- if the argument is nullpublic int set()
public int clear()
public boolean isStreamFlag()
public boolean isKnown(int flags)
flags
- the stream flags, operation flags, or combined stream and
operation flagspublic boolean isCleared(int flags)
flags
- the operation flags or combined stream and operations flags.public boolean isPreserved(int flags)
flags
- the combined stream and operations flags.public boolean canSet(java.util.stream.StreamOpFlag.Type t)
t
- the flag type.public static int combineOpFlags(int newStreamOrOpFlags, int prevCombOpFlags)
A flag set on stream flags or injected on operation flags, and injected combined stream and operation flags, will be injected on the updated combined stream and operation flags.
A flag set on stream flags or injected on operation flags, and cleared on the combined stream and operation flags, will be cleared on the updated combined stream and operation flags.
A flag set on the stream flags or injected on operation flags, and preserved on the combined stream and operation flags, will be injected on the updated combined stream and operation flags.
A flag not set on the stream flags or cleared/preserved on operation flags, and injected on the combined stream and operation flags, will be injected on the updated combined stream and operation flags.
A flag not set on the stream flags or cleared/preserved on operation flags, and cleared on the combined stream and operation flags, will be cleared on the updated combined stream and operation flags.
A flag not set on the stream flags, and preserved on the combined stream and operation flags will be preserved on the updated combined stream and operation flags.
A flag cleared on operation flags, and preserved on the combined stream and operation flags will be cleared on the updated combined stream and operation flags.
A flag preserved on operation flags, and preserved on the combined stream and operation flags will be preserved on the updated combined stream and operation flags.
newStreamOrOpFlags
- the stream or operation flags.prevCombOpFlags
- previously combined stream and operation flags.
The value {#link INITIAL_OPS_VALUE} must be used as the seed value.public static int toStreamFlags(int combOpFlags)
Each flag injected on the combined stream and operation flags will be set on the stream flags.
combOpFlags
- the combined stream and operation flags.public static int toCharacteristics(int streamFlags)
streamFlags
- the stream flags.public static int fromCharacteristics(Spliterator<?> spliterator)
spliterator
- the spliterator from which to obtain characteristic
bit set.public static int fromCharacteristics(int characteristics)
characteristics
- the spliterator characteristic bit set.