- Type Parameters:
- E- the boxed version of- ETYPE, the element type of a vector- Value-based classes and identity operations- VectorMask, along with- Vector, is a value-based class. With- VectorMask, identity-sensitive operations such as- ==may yield unpredictable results, or reduced performance. Oddly enough,- v.equals(w)is likely to be faster than- v==w, since- equalsis not an identity sensitive method. (Neither is- toStringnor- hashCode.) Also, vector mask objects can be stored in locals and parameters and as- static finalconstants, 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 lane-wise 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 lane-wise 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 cross-lane 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 SummaryModifier and TypeMethodDescriptionabstract booleanallTrue()Returnstrueif 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 booleananyTrue()Returnstrueif 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==bora^~b).final booleanIndicates whether this mask is identical to some other object.abstract intReturns 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 abooleanarray 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 givenbooleanvalues.protected final Objectfinal inthashCode()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 numberedNfrom this mask where the adjusted indexN+offset, is not in the range[0..limit-1].abstract VectorMask<E> indexInRange(long offset, long limit) Removes lanes numberedNfrom this mask where the adjusted indexN+offset, is not in the range[0..limit-1].abstract voidintoArray(boolean[] a, int offset) Stores this mask into abooleanarray starting at offset.abstract booleanlaneIsSet(int i) Tests if the lane at indexiis setabstract intlastTrue()Returns the index of the last mask lane that is set.final intlength()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 (asa|b) of this mask and a second input mask.abstract boolean[]toArray()Returns anbooleanarray containing the lane elements of this mask.abstract longtoLong()Returns the lane elements of this mask packed into alongvalue for at most the first 64 lane elements.final StringtoString()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 intReturns 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- 
vectorSpeciesReturns 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
 
- 
lengthpublic 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
 
- 
fromValuesReturns a mask where each lane is set or unset according to givenbooleanvalues.For each mask lane, where Nis the mask lane index, if the givenbooleanvalue at indexNistruethen the mask lane at indexNis 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 mask
- bits- the given- booleanvalues
- Returns:
- a mask where each lane is set or unset according to the given
         booleanvalue
- Throws:
- IllegalArgumentException- if- bits.length != species.length()
- See Also:
 
- 
fromArrayLoads a mask from abooleanarray starting at an offset.For each mask lane, where Nis the mask lane index, if the array element at indexoffset + Nistruethen the mask lane at indexNis set, otherwise it is unset.- Type Parameters:
- E- the boxed element type
- Parameters:
- species- vector species for the desired mask
- bits- the- booleanarray
- offset- the offset into the array
- Returns:
- the mask loaded from the booleanarray
- Throws:
- IndexOutOfBoundsException- if- offset < 0, or- offset > bits.length - species.length()
- See Also:
 
- 
fromLongReturns 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 Nis the mask lane index, if the expression(bits>>min(63,N))&1is non-zero, then the mask lane at indexNis set, otherwise it is unset.If the given species has fewer than 64 lanes, the high 64-VLENGTHbits of the bit-mask 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 mask
- bits- the given mask bits, as a 64-bit signed integer
- Returns:
- a mask where each lane is set or unset according to the bits in the given integer value
- See Also:
 
- 
castConverts 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 Nis the lane index, if the mask lane at indexNis set, then the mask lane at indexNof 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
 
- 
toLongpublic abstract long toLong()Returns the lane elements of this mask packed into alongvalue 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 Nis the mask lane index, if the mask lane is set then theNth bit is set to one in the resultinglongvalue, otherwise theNth bit is set to zero. The mask must have no more than 64 lanes.- Returns:
- the lane elements of this mask packed into a longvalue.
- Throws:
- UnsupportedOperationException- if there are more than 64 lanes in this mask
 
- 
toArraypublic abstract boolean[] toArray()Returns anbooleanarray 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
 
- 
intoArraypublic abstract void intoArray(boolean[] a, int offset) Stores this mask into abooleanarray starting at offset.For each mask lane, where Nis the mask lane index, the lane element at indexNis stored into the array elementa[offset+N].- Parameters:
- a- the array, of type boolean[]
- offset- the offset into the array
- Throws:
- IndexOutOfBoundsException- if- offset < 0or- offset > a.length - this.length()
 
- 
anyTruepublic abstract boolean anyTrue()Returnstrueif any of the mask lanes are set.- Returns:
- trueif any of the mask lanes are set, otherwise- false.
 
- 
allTruepublic abstract boolean allTrue()Returnstrueif all of the mask lanes are set.- Returns:
- trueif all of the mask lanes are set, otherwise- false.
 
- 
trueCountpublic abstract int trueCount()Returns the number of mask lanes that are set.- Returns:
- the number of mask lanes that are set.
 
- 
firstTruepublic abstract int firstTrue()Returns the index of the first mask lane that is set. ReturnsVLENGTHif none of them are set.- Returns:
- the index of the first mask lane that is set, or VLENGTH
 
- 
lastTruepublic abstract int lastTrue()Returns the index of the last mask lane that is set. Returns-1if none of them are set.- Returns:
- the index of the last mask lane that is set, or -1
 
- 
andComputes the logical intersection (asa&b) between this mask and a second input mask.This is a lane-wise binary operation which applies the logical ANDoperation (&) to each corresponding pair of mask bits.- Parameters:
- m- the second input mask
- Returns:
- the result of logically conjoining the two input masks
 
- 
orComputes the logical union (asa|b) of this mask and a second input mask.This is a lane-wise binary operation which applies the logical ORoperation (|) to each corresponding pair of mask bits.- Parameters:
- m- the input mask
- Returns:
- the result of logically disjoining the two input masks
 
- 
xorDetermines logical symmetric difference (asa^b) of this mask and a second input mask.This is a lane-wise binary operation which applies the logical XORoperation (^) to each corresponding pair of mask bits.- Parameters:
- m- the input mask
- Returns:
- the result of logically disjunctively disjoining the two input masks
 
- 
andNotLogically subtracts a second input mask from this mask (asa&~b).This is a lane-wise binary operation which applies the logical ANDCoperation (&~) 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
 
- 
eqDetermines logical equivalence of this mask to a second input mask (as booleana==bora^~b).This is a lane-wise binary operation tests each corresponding pair of mask bits for equality. It is also equivalent to the logical XNORoperation (^~) 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:
 
- 
notLogically negates this mask.This is a lane-wise binary operation which applies the logical NOToperation (~) to each mask bit.- Returns:
- the result of logically negating this mask
 
- 
indexInRangeRemoves lanes numberedNfrom this mask where the adjusted indexN+offset, is not in the range[0..limit-1].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 wrap-around.- 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+VLENGTH-1]. 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 Nset lanes followed by a series of unset lanes can be obtained by callingallTrue.indexInRange(0, N), whereallTrueis a mask of all true bits. A mask ofN1unset lanes followed byN2set lanes can be obtained by callingallTrue.indexInRange(-N1, N2).
- Parameters:
- offset- the starting index
- limit- the upper-bound (exclusive) of index range
- Returns:
- the original mask, with out-of-range lanes unset
- See Also:
 
- 
indexInRangeRemoves lanes numberedNfrom this mask where the adjusted indexN+offset, is not in the range[0..limit-1].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 wrap-around.- 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+VLENGTH-1]. 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 Nset lanes followed by a series of unset lanes can be obtained by callingallTrue.indexInRange(0, N), whereallTrueis a mask of all true bits. A mask ofN1unset lanes followed byN2set lanes can be obtained by callingallTrue.indexInRange(-N1, N2).
- Parameters:
- offset- the starting index
- limit- the upper-bound (exclusive) of index range
- Returns:
- the original mask, with out-of-range lanes unset
- Since:
- 19
- See Also:
 
- 
toVectorReturns 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, whereNis the mask lane index, if the mask lane is set atNthen the specific non-default value-1is placed into the resulting vector at lane indexN. Otherwise the default element value0is 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 values0or-1. For everyETYPEthe 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), whereZEROandMINUS_ONEare vectors which replicate the defaultETYPEvalue and theETYPEvalue representing-1, 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 float-point 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:
 
- 
laneIsSetpublic abstract boolean laneIsSet(int i) Tests if the lane at indexiis set- Parameters:
- i- the lane index
- Returns:
- true if the lane at index iis set, otherwise false
- Throws:
- IndexOutOfBoundsException- if the index is out of range (- < 0 || >= length())
 
- 
checkChecks 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:
 
- 
checkChecks 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:
 
- 
toStringReturns a string representation of this mask, of the form"Mask[T.TT...]", reporting the mask bit settings (as 'T' or '.' characters) in lane order.
- 
equalsIndicates 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.
- 
hashCodepublic final int hashCode()Returns a hash code value for the mask, based on the mask bit settings and the vector species.
- 
compressCompresses set lanes from this mask. Returns a mask which is a series ofNset lanes followed by a series of unset lanes, whereNis the true count of this mask.- Returns:
- the compressed mask of this mask
- Since:
- 19
 
- 
getPayload
 
-