Class VectorMask<E>
 Type Parameters:
E
 the boxed version ofETYPE
, the element type of a vectorValuebased classes and identity operations
VectorMask
, along withVector
, is a valuebased class. WithVectorMask
, identitysensitive operations such as==
may yield unpredictable results, or reduced performance. Oddly enough,v.equals(w)
is likely to be faster thanv==w
, sinceequals
is not an identity sensitive method. (Neither istoString
norhashCode
.) Also, vector mask objects can be stored in locals and parameters and asstatic final
constants, but storing them in other Java fields or in array elements, while semantically valid, may incur performance penalties.
VectorMask
represents an ordered immutable sequence of boolean
values.
A VectorMask
and Vector
of the same
element type
(ETYPE
) and shape
have the same number of lanes,
and are therefore compatible (specifically, their vector species
are compatible).
Some vector operations accept (compatible) masks to control the selection and operation of lane elements of input vectors.
The number of values in the sequence is referred to as the VectorMask
length
. The length also corresponds to the number of
VectorMask lanes. The lane element at lane index N
(from 0
,
inclusive, to length, exclusive) corresponds to the N + 1
'th
value in the sequence.
A lane is said to be set if the lane element is true
,
otherwise a lane is said to be unset if the lane element is
false
.
VectorMask declares a limited set of unary, binary and reduction operations.

A lanewise unary operation operates on one input mask and produces a
result mask.
For each lane of the input mask the
lane element is operated on using the specified scalar unary operation and
the boolean result is placed into the mask result at the same lane.
The following pseudocode illustrates the behavior of this operation category:
VectorMask<E> a = ...; boolean[] ar = new boolean[a.length()]; for (int i = 0; i < a.length(); i++) { ar[i] = scalar_unary_op(a.laneIsSet(i)); } VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);

A lanewise binary operation operates on two input
masks to produce a result mask.
For each lane of the two input masks a and b,
the corresponding lane elements from a and b are operated on
using the specified scalar binary operation and the boolean result is placed
into the mask result at the same lane.
The following pseudocode illustrates the behavior of this operation category:
VectorMask<E> a = ...; VectorMask<E> b = ...; boolean[] ar = new boolean[a.length()]; for (int i = 0; i < a.length(); i++) { ar[i] = scalar_binary_op(a.laneIsSet(i), b.laneIsSet(i)); } VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);

A crosslane reduction operation accepts an input mask and produces a scalar result.
For each lane of the input mask the lane element is operated on, together with a scalar accumulation value,
using the specified scalar binary operation. The scalar result is the final value of the accumulator. The
following pseudocode illustrates the behaviour of this operation category:
Mask<E> a = ...; int acc = zero_for_scalar_binary_op; // 0, or 1 for & for (int i = 0; i < a.length(); i++) { acc = scalar_binary_op(acc, a.laneIsSet(i) ? 1 : 0); // &  + } return acc; // maybe boolean (acc != 0)

Method Summary
Modifier and TypeMethodDescriptionabstract boolean
allTrue()
Returnstrue
if all of the mask lanes are set.abstract VectorMask
<E> and
(VectorMask<E> m) Computes the logical intersection (asa&b
) between this mask and a second input mask.abstract VectorMask
<E> andNot
(VectorMask<E> m) Logically subtracts a second input mask from this mask (asa&~b
).abstract boolean
anyTrue()
Returnstrue
if any of the mask lanes are set.abstract <F> VectorMask
<F> cast
(VectorSpecies<F> species) Converts this mask to a mask of the given species of element typeF
.abstract <F> VectorMask
<F> Checks that this mask applies to vectors with the given element type, and returns this mask unchanged.abstract <F> VectorMask
<F> check
(VectorSpecies<F> species) Checks that this mask has the given species, and returns this mask unchanged.abstract VectorMask
<E> compress()
Compresses set lanes from this mask.abstract VectorMask
<E> eq
(VectorMask<E> m) Determines logical equivalence of this mask to a second input mask (as booleana==b
ora^~b
).final boolean
Indicates whether this mask is identical to some other object.abstract int
Returns the index of the first mask lane that is set.static <E> VectorMask
<E> fromArray
(VectorSpecies<E> species, boolean[] bits, int offset) Loads a mask from aboolean
array starting at an offset.static <E> VectorMask
<E> fromLong
(VectorSpecies<E> species, long bits) Returns a mask where each lane is set or unset according to the bits in the given bitmask, starting with the least significant bit, and continuing up to the sign bit.static <E> VectorMask
<E> fromValues
(VectorSpecies<E> species, boolean... bits) Returns a mask where each lane is set or unset according to givenboolean
values.protected final Object
final int
hashCode()
Returns a hash code value for the mask, based on the mask bit settings and the vector species.abstract VectorMask
<E> indexInRange
(int offset, int limit) Removes lanes numberedN
from this mask where the adjusted indexN+offset
, is not in the range[0..limit1]
.abstract VectorMask
<E> indexInRange
(long offset, long limit) Removes lanes numberedN
from this mask where the adjusted indexN+offset
, is not in the range[0..limit1]
.abstract void
intoArray
(boolean[] a, int offset) Stores this mask into aboolean
array starting at offset.abstract boolean
laneIsSet
(int i) Tests if the lane at indexi
is setabstract int
lastTrue()
Returns the index of the last mask lane that is set.final int
length()
Returns the number of mask lanes.abstract VectorMask
<E> not()
Logically negates this mask.abstract VectorMask
<E> or
(VectorMask<E> m) Computes the logical union (asab
) of this mask and a second input mask.abstract boolean[]
toArray()
Returns anboolean
array containing the lane elements of this mask.abstract long
toLong()
Returns the lane elements of this mask packed into along
value for at most the first 64 lane elements.final String
toString()
Returns a string representation of this mask, of the form"Mask[T.TT...]"
, reporting the mask bit settings (as 'T' or '.' characters) in lane order.toVector()
Returns a vector representation of this mask, the lane bits of which are set or unset in correspondence to the mask bits.abstract int
Returns the number of mask lanes that are set.abstract VectorSpecies
<E> Returns the vector species to which this mask applies.abstract VectorMask
<E> xor
(VectorMask<E> m) Determines logical symmetric difference (asa^b
) of this mask and a second input mask.

Method Details

vectorSpecies
Returns the vector species to which this mask applies. This mask applies to vectors of the same species, and the same number of lanes. Returns:
 the vector species of this mask

length
public final int length()Returns the number of mask lanes. This mask applies to vectors of the same number of lanes, and the same species. Returns:
 the number of mask lanes

fromValues
Returns a mask where each lane is set or unset according to givenboolean
values.For each mask lane, where
N
is the mask lane index, if the givenboolean
value at indexN
istrue
then the mask lane at indexN
is set, otherwise it is unset.The given species must have a number of lanes that is compatible with the given array.
 Type Parameters:
E
 the boxed element type Parameters:
species
 vector species for the desired maskbits
 the givenboolean
values Returns:
 a mask where each lane is set or unset according to the given
boolean
value  Throws:
IllegalArgumentException
 ifbits.length != species.length()
 See Also:

fromArray
Loads a mask from aboolean
array starting at an offset.For each mask lane, where
N
is the mask lane index, if the array element at indexoffset + N
istrue
then the mask lane at indexN
is set, otherwise it is unset. Type Parameters:
E
 the boxed element type Parameters:
species
 vector species for the desired maskbits
 theboolean
arrayoffset
 the offset into the array Returns:
 the mask loaded from the
boolean
array  Throws:
IndexOutOfBoundsException
 ifoffset < 0
, oroffset > bits.length  species.length()
 See Also:

fromLong
Returns a mask where each lane is set or unset according to the bits in the given bitmask, starting with the least significant bit, and continuing up to the sign bit.For each mask lane, where
N
is the mask lane index, if the expression(bits>>min(63,N))&1
is nonzero, then the mask lane at indexN
is set, otherwise it is unset.If the given species has fewer than 64 lanes, the high
64VLENGTH
bits of the bitmask are ignored. If the given species has more than 64 lanes, the sign bit is replicated into lane 64 and beyond. Type Parameters:
E
 the boxed element type Parameters:
species
 vector species for the desired maskbits
 the given mask bits, as a 64bit signed integer Returns:
 a mask where each lane is set or unset according to the bits in the given integer value
 See Also:

cast
Converts this mask to a mask of the given species of element typeF
. Thespecies.length()
must be equal to the mask length. The various mask lane bits are unmodified.For each mask lane, where
N
is the lane index, if the mask lane at indexN
is set, then the mask lane at indexN
of the resulting mask is set, otherwise that mask lane is not set. Type Parameters:
F
 the boxed element type of the species Parameters:
species
 vector species for the desired mask Returns:
 a mask converted by shape and element type
 Throws:
IllegalArgumentException
 if this mask length and the species length differ

toLong
public abstract long toLong()Returns the lane elements of this mask packed into along
value for at most the first 64 lane elements.The lane elements are packed in the order of least significant bit to most significant bit. For each mask lane where
N
is the mask lane index, if the mask lane is set then theN
th bit is set to one in the resultinglong
value, otherwise theN
th bit is set to zero. The mask must have no more than 64 lanes. Returns:
 the lane elements of this mask packed into a
long
value.  Throws:
UnsupportedOperationException
 if there are more than 64 lanes in this mask

toArray
public abstract boolean[] toArray()Returns anboolean
array containing the lane elements of this mask.This method behaves as if it stores this mask into an allocated array (using
intoArray(boolean[], int)
) and returns that array as follows:boolean[] a = new boolean[this.length()]; this.intoArray(a, 0); return a;
 Returns:
 an array containing the lane elements of this vector

intoArray
public abstract void intoArray(boolean[] a, int offset) Stores this mask into aboolean
array starting at offset.For each mask lane, where
N
is the mask lane index, the lane element at indexN
is stored into the array elementa[offset+N]
. Parameters:
a
 the array, of type boolean[]offset
 the offset into the array Throws:
IndexOutOfBoundsException
 ifoffset < 0
oroffset > a.length  this.length()

anyTrue
public abstract boolean anyTrue()Returnstrue
if any of the mask lanes are set. Returns:
true
if any of the mask lanes are set, otherwisefalse
.

allTrue
public abstract boolean allTrue()Returnstrue
if all of the mask lanes are set. Returns:
true
if all of the mask lanes are set, otherwisefalse
.

trueCount
public abstract int trueCount()Returns the number of mask lanes that are set. Returns:
 the number of mask lanes that are set.

firstTrue
public abstract int firstTrue()Returns the index of the first mask lane that is set. ReturnsVLENGTH
if none of them are set. Returns:
 the index of the first mask lane that is set, or
VLENGTH

lastTrue
public abstract int lastTrue()Returns the index of the last mask lane that is set. Returns1
if none of them are set. Returns:
 the index of the last mask lane that is set, or
1

and
Computes the logical intersection (asa&b
) between this mask and a second input mask.This is a lanewise binary operation which applies the logical
AND
operation (&
) to each corresponding pair of mask bits. Parameters:
m
 the second input mask Returns:
 the result of logically conjoining the two input masks

or
Computes the logical union (asab
) of this mask and a second input mask.This is a lanewise binary operation which applies the logical
OR
operation (
) to each corresponding pair of mask bits. Parameters:
m
 the input mask Returns:
 the result of logically disjoining the two input masks

xor
Determines logical symmetric difference (asa^b
) of this mask and a second input mask.This is a lanewise binary operation which applies the logical
XOR
operation (^
) to each corresponding pair of mask bits. Parameters:
m
 the input mask Returns:
 the result of logically disjunctively disjoining the two input masks

andNot
Logically subtracts a second input mask from this mask (asa&~b
).This is a lanewise binary operation which applies the logical
ANDC
operation (&~
) to each corresponding pair of mask bits. Parameters:
m
 the second input mask Returns:
 the result of logically subtracting the second mask from this mask

eq
Determines logical equivalence of this mask to a second input mask (as booleana==b
ora^~b
).This is a lanewise binary operation tests each corresponding pair of mask bits for equality. It is also equivalent to the logical
XNOR
operation (^~
) to each corresponding pair of mask bits. Parameters:
m
 the input mask Returns:
 a mask showing where the two input masks were equal
 See Also:

not
Logically negates this mask.This is a lanewise binary operation which applies the logical
NOT
operation (~
) to each mask bit. Returns:
 the result of logically negating this mask

indexInRange
Removes lanes numberedN
from this mask where the adjusted indexN+offset
, is not in the range[0..limit1]
.In all cases the series of set and unset lanes is assigned as if by using infinite precision or
VLENGTH
saturating additions or subtractions, without overflow or wraparound. API Note:
 This method performs a SIMD emulation of the check performed by
Objects.checkIndex(int,int)
, on the index numbers in the range[offset..offset+VLENGTH1]
. If an exception is desired, the resulting mask can be compared with the original mask; if they are not equal, then at least one lane was out of range, and exception processing can be performed.A mask which is a series of
N
set lanes followed by a series of unset lanes can be obtained by callingallTrue.indexInRange(0, N)
, whereallTrue
is a mask of all true bits. A mask ofN1
unset lanes followed byN2
set lanes can be obtained by callingallTrue.indexInRange(N1, N2)
.  Parameters:
offset
 the starting indexlimit
 the upperbound (exclusive) of index range Returns:
 the original mask, with outofrange lanes unset
 See Also:

indexInRange
Removes lanes numberedN
from this mask where the adjusted indexN+offset
, is not in the range[0..limit1]
.In all cases the series of set and unset lanes is assigned as if by using infinite precision or
VLENGTH
saturating additions or subtractions, without overflow or wraparound. API Note:
 This method performs a SIMD emulation of the check performed by
Objects.checkIndex(long,long)
, on the index numbers in the range[offset..offset+VLENGTH1]
. If an exception is desired, the resulting mask can be compared with the original mask; if they are not equal, then at least one lane was out of range, and exception processing can be performed.A mask which is a series of
N
set lanes followed by a series of unset lanes can be obtained by callingallTrue.indexInRange(0, N)
, whereallTrue
is a mask of all true bits. A mask ofN1
unset lanes followed byN2
set lanes can be obtained by callingallTrue.indexInRange(N1, N2)
.  Parameters:
offset
 the starting indexlimit
 the upperbound (exclusive) of index range Returns:
 the original mask, with outofrange lanes unset
 Since:
 19
 See Also:

toVector
Returns a vector representation of this mask, the lane bits of which are set or unset in correspondence to the mask bits. For each mask lane, whereN
is the mask lane index, if the mask lane is set atN
then the specific nondefault value1
is placed into the resulting vector at lane indexN
. Otherwise the default element value0
is placed into the resulting vector at lane indexN
. Whether the element type (ETYPE
) of this mask is floating point or integral, the lane value, as selected by the mask, will be one of the two arithmetic values0
or1
. For everyETYPE
the most significant bit of the vector lane is set if and only if the mask lane is set. In addition, for integral types, all lane bits are set in lanes where the mask is set.The vector returned is the same as would be computed by
ZERO.blend(MINUS_ONE, this)
, whereZERO
andMINUS_ONE
are vectors which replicate the defaultETYPE
value and theETYPE
value representing1
, respectively. API Note:
 For the sake of static type checking, users may wish to check the resulting vector against the expected integral lane type or species. If the mask is for a floatpoint species, then the resulting vector will have the same shape and lane size, but an integral type. If the mask is for an integral species, the resulting vector will be of exactly that species.
 Returns:
 a vector representation of this mask
 See Also:

laneIsSet
public abstract boolean laneIsSet(int i) Tests if the lane at indexi
is set Parameters:
i
 the lane index Returns:
 true if the lane at index
i
is set, otherwise false  Throws:
IndexOutOfBoundsException
 if the index is out of range (< 0  >= length()
)

check
Checks that this mask applies to vectors with the given element type, and returns this mask unchanged. The effect is similar to this pseudocode:elementType == vectorSpecies().elementType() ? this : throw new ClassCastException()
. Type Parameters:
F
 the boxed element type of the required lane type Parameters:
elementType
 the required lane type Returns:
 the same mask
 Throws:
ClassCastException
 if the element type is wrong See Also:

check
Checks that this mask has the given species, and returns this mask unchanged. The effect is similar to this pseudocode:species == vectorSpecies() ? this : throw new ClassCastException()
. Type Parameters:
F
 the boxed element type of the required species Parameters:
species
 vector species required for this mask Returns:
 the same mask
 Throws:
ClassCastException
 if the species is wrong See Also:

toString

equals
Indicates whether this mask is identical to some other object. Two masks are identical only if they have the same species and same source indexes, in the same order. 
hashCode

compress
Compresses set lanes from this mask. Returns a mask which is a series ofN
set lanes followed by a series of unset lanes, whereN
is the true count of this mask. Returns:
 the compressed mask of this mask
 Since:
 19

getPayload
