Flags corresponding to characteristics of streams and operations. Flags are utilized by the stream framework to control, specialize or optimize computation.

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:

Type Characteristics
		`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 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 java.util.Spliterator characteristics: java.util.Spliterator#DISTINCT, java.util.Spliterator#SORTED, java.util.Spliterator#ORDERED, and java.util.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 java.util.Spliterator#SUBSIZED that information can be utilized to perform concurrent in-place updates into a shared array. For specific details see the AbstractPipeline constructors.

Modifier and Type	Class and Description
private static class	StreamOpFlag.MaskBuilder
pack-priv static enum	StreamOpFlag.Type Type of a flag

Field Summary

Modifier and Type	Field and Description
private final int	bitPosition The bit position in the bit mask.
private final int	clear The clear 2 bit set offset at the bit position.
private static final int	CLEAR_BITS The bit pattern for clearing a flag.
public static final StreamOpFlag	DISTINCT Characteristic value signifying that, for each pair of encountered elements in a stream `x, y`, `!x.equals(y)`.
private static final int	FLAG_MASK Complete flag mask.
private static final int	FLAG_MASK_IS Flag mask for stream flags that are set.
private static final int	FLAG_MASK_NOT Flag mask for stream flags that are cleared.
pack-priv static final int	INITIAL_OPS_VALUE The initial value to be combined with the stream flags of the first stream in the pipeline.
pack-priv static final int	IS_DISTINCT The bit value to set or inject `DISTINCT`.
pack-priv static final int	IS_ORDERED The bit value to set or inject `ORDERED`.
pack-priv static final int	IS_SHORT_CIRCUIT The bit value to inject `SHORT_CIRCUIT`.
pack-priv static final int	IS_SIZE_ADJUSTING The bit value to inject `SIZE_ADJUSTING`.
pack-priv static final int	IS_SIZED The bit value to set `SIZED`.
pack-priv static final int	IS_SORTED The bit value to set or inject `SORTED`.
private final Map<StreamOpFlag.Type, Integer>	maskTable The mask table for a flag, this is used to determine if a flag corresponds to a certain flag type and for creating mask constants.
pack-priv static final int	NOT_DISTINCT The bit value to clear `DISTINCT`.
pack-priv static final int	NOT_ORDERED The bit value to clear `ORDERED`.
pack-priv static final int	NOT_SIZED The bit value to clear `SIZED`.
pack-priv static final int	NOT_SORTED The bit value to clear `SORTED`.
pack-priv static final int	OP_MASK The bit mask for intermediate operation flags.
public static final StreamOpFlag	ORDERED Characteristic value signifying that an encounter order is defined for stream elements.
private final int	preserve The preserve 2 bit set offset at the bit position.
private static final int	PRESERVE_BITS The bit pattern for preserving a flag.
private final int	set The set 2 bit set offset at the bit position.
private static final int	SET_BITS The bit pattern for setting/injecting a flag.
public static final StreamOpFlag	SHORT_CIRCUIT Characteristic value signifying that an operation may short-circuit the stream.
public static final StreamOpFlag	SIZE_ADJUSTING Characteristic value signifying that an operation may adjust the total size of the stream.
public static final StreamOpFlag	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.
public static final StreamOpFlag	SORTED Characteristic value signifying that encounter order follows a natural sort order of comparable elements.
pack-priv static final int	SPLITERATOR_CHARACTERISTICS_MASK The bit mask for spliterator characteristics
pack-priv static final int	STREAM_MASK The bit mask for source stream flags.
pack-priv static final int	TERMINAL_OP_MASK The bit mask for terminal operation flags.
pack-priv static final int	UPSTREAM_TERMINAL_OP_MASK The bit mask for upstream terminal operation flags.

Access	Constructor and Description
private	StreamOpFlag(int position, StreamOpFlag.MaskBuilder maskBuilder)

Method Summary

Modifier and Type	Method and Description
pack-priv boolean	Returns: true if this flag can be set for the flag type, otherwise false. canSet(StreamOpFlag.Type the flag type. t) Determines if this flag can be set for a flag type.
pack-priv int	Returns: the bitmap for clearing this characteristic clear() Gets the bitmap associated with clearing this characteristic.
pack-priv static int	Returns: the updated combined stream and operation flags. combineOpFlags(int the stream or operation flags. newStreamOrOpFlags, int previously combined stream and operation flags. The value {#link INITIAL_OPS_VALUE} must be used as the seed value. prevCombOpFlags) Combines stream or operation flags with previously combined stream and operation flags to produce updated combined stream and operation flags.
private static int	createFlagMask()
private static int	createMask(StreamOpFlag.Type t)
pack-priv static int	Returns: the stream flags. fromCharacteristics(Spliterator<?> the spliterator from which to obtain characteristic bit set. spliterator) Converts a spliterator characteristic bit set to stream flags.
pack-priv static int	Returns: the stream flags. fromCharacteristics(int the spliterator characteristic bit set. characteristics) Converts a spliterator characteristic bit set to stream flags.
private static int	getMask(int flags)
pack-priv boolean	Returns: true if this flag is preserved, otherwise false. isCleared(int the operation flags or combined stream and operations flags. flags) Checks if this flag is cleared on operation flags or combined stream and operation flags.
pack-priv boolean	Returns: true if this flag is known, otherwise false. isKnown(int the stream flags, operation flags, or combined stream and operation flags flags) Checks if this flag is set on stream flags, injected on operation flags, and injected on combined stream and operation flags.
pack-priv boolean	Returns: true if this flag is preserved, otherwise false. isPreserved(int the combined stream and operations flags. flags) Checks if this flag is preserved on combined stream and operation flags.
pack-priv boolean	Returns: true if a stream-based flag, otherwise false. isStreamFlag() Determines if this flag is a stream-based flag.
private static StreamOpFlag.MaskBuilder	set(StreamOpFlag.Type t)
pack-priv int	Returns: the bitmap for setting this characteristic set() Gets the bitmap associated with setting this characteristic.
pack-priv static int	Returns: the spliterator characteristic bit set. toCharacteristics(int the stream flags. streamFlags) Converts stream flags to a spliterator characteristic bit set.
pack-priv static int	Returns: the stream flags. toStreamFlags(int the combined stream and operation flags. combOpFlags) Converts combined stream and operation flags to stream flags.
public static StreamOpFlag	valueOf(String name)
public static StreamOpFlag[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

bitPosition	back to summary
private final int bitPosition The bit position in the bit mask.

clear	back to summary
private final int clear The clear 2 bit set offset at the bit position.

CLEAR_BITS	back to summary
private static final int CLEAR_BITS The bit pattern for clearing a flag.

DISTINCT back to summary

DISTINCT	back to summary
public static final StreamOpFlag DISTINCT Characteristic value signifying that, for each pair of encountered elements in a stream `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 DISTINCT

Characteristic value signifying that, for each pair of encountered elements in a stream x, y, !x.equals(y).

A stream may have this value or an intermediate operation can preserve, clear or inject this value.

FLAG_MASK	back to summary
private static final int FLAG_MASK Complete flag mask.

FLAG_MASK_IS	back to summary
private static final int FLAG_MASK_IS Flag mask for stream flags that are set.

FLAG_MASK_NOT	back to summary
private static final int FLAG_MASK_NOT Flag mask for stream flags that are cleared.

INITIAL_OPS_VALUE	back to summary
pack-priv static final int INITIAL_OPS_VALUE The initial value to be combined with the stream flags of the first stream in the pipeline.

IS_DISTINCT	back to summary
pack-priv static final int IS_DISTINCT The bit value to set or inject `DISTINCT`.

IS_ORDERED	back to summary
pack-priv static final int IS_ORDERED The bit value to set or inject `ORDERED`.

IS_SHORT_CIRCUIT	back to summary
pack-priv static final int IS_SHORT_CIRCUIT The bit value to inject `SHORT_CIRCUIT`.

IS_SIZE_ADJUSTING	back to summary
pack-priv static final int IS_SIZE_ADJUSTING The bit value to inject `SIZE_ADJUSTING`.

IS_SIZED	back to summary
pack-priv static final int IS_SIZED The bit value to set `SIZED`.

IS_SORTED	back to summary
pack-priv static final int IS_SORTED The bit value to set or inject `SORTED`.

maskTable	back to summary
private final Map<StreamOpFlag.Type, Integer> maskTable The mask table for a flag, this is used to determine if a flag corresponds to a certain flag type and for creating mask constants.

NOT_DISTINCT	back to summary
pack-priv static final int NOT_DISTINCT The bit value to clear `DISTINCT`.

NOT_ORDERED	back to summary
pack-priv static final int NOT_ORDERED The bit value to clear `ORDERED`.

NOT_SIZED	back to summary
pack-priv static final int NOT_SIZED The bit value to clear `SIZED`.

NOT_SORTED	back to summary
pack-priv static final int NOT_SORTED The bit value to clear `SORTED`.

OP_MASK	back to summary
pack-priv static final int OP_MASK The bit mask for intermediate operation flags.

ORDERED	back to summary
public static final StreamOpFlag ORDERED Characteristic value signifying that an encounter order is defined for stream elements. 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.

ORDERED

Modifier and Type	Method and Description
pack-priv Map<StreamOpFlag.Type, Integer>	build()
pack-priv StreamOpFlag.MaskBuilder	clear(StreamOpFlag.Type t)
pack-priv StreamOpFlag.MaskBuilder	mask(StreamOpFlag.Type t, Integer i)
pack-priv StreamOpFlag.MaskBuilder	set(StreamOpFlag.Type t)
pack-priv StreamOpFlag.MaskBuilder	setAndClear(StreamOpFlag.Type t)

Modifier and Type	Field and Description
public static final StreamOpFlag.Type	OP The flag is associated with intermediate operation flags.
public static final StreamOpFlag.Type	SPLITERATOR The flag is associated with spliterator characteristics.
public static final StreamOpFlag.Type	STREAM The flag is associated with stream flags.
public static final StreamOpFlag.Type	TERMINAL_OP The flag is associated with terminal operation flags.
public static final StreamOpFlag.Type	UPSTREAM_TERMINAL_OP The flag is associated with terminal operation flags that are propagated upstream across the last stateful operation boundary

Modifier and Type	Method and Description
public static StreamOpFlag.Type	valueOf(String name)
public static StreamOpFlag.Type[]	values()

pack-priv final Enum StreamOpFlag

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class StreamOpFlag.MaskBuilder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Enum StreamOpFlag.Type

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail