E
- the boxed version of ETYPE
, the element type of a vector 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 equals
is not an identity sensitive method. (Neither is toString
nor hashCode
.) Also, vector mask objects can be stored in locals and parameters and as static final
constants, but storing them in other Java fields or in array elements, while semantically valid, may incur performance penalties.public abstract class VectorMask<E> extends Object
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.
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);
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);
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)
Modifier and Type | Method | Description |
---|---|---|
abstract boolean |
allTrue() |
Returns true if all of the mask lanes are set. |
abstract VectorMask |
and |
Computes the logical intersection (as a&b ) between this mask and a second input mask. |
abstract VectorMask |
andNot |
Logically subtracts a second input mask from this mask (as a&~b ). |
abstract boolean |
anyTrue() |
Returns true if any of the mask lanes are set. |
abstract <F> VectorMask |
cast |
Converts this mask to a mask of the given species of element type F . |
abstract <F> VectorMask |
check |
Checks that this mask applies to vectors with the given element type, and returns this mask unchanged. |
abstract <F> VectorMask |
check |
Checks that this mask has the given species, and returns this mask unchanged. |
abstract VectorMask |
compress() |
Compresses set lanes from this mask. |
abstract VectorMask |
eq |
Determines logical equivalence of this mask to a second input mask (as boolean a==b or a^~b ). |
final boolean |
equals |
Indicates whether this mask is identical to some other object. |
abstract int |
firstTrue() |
Returns the index of the first mask lane that is set. |
static <E> VectorMask |
fromArray |
Loads a mask from a boolean array starting at an offset. |
static <E> VectorMask |
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. |
static <E> VectorMask |
fromValues |
Returns a mask where each lane is set or unset according to given boolean values. |
protected final Object |
getPayload() |
|
final int |
hashCode() |
Returns a hash code value for the mask, based on the mask bit settings and the vector species. |
abstract VectorMask |
indexInRange |
Removes lanes numbered N from this mask where the adjusted index N+offset , is not in the range [0..limit-1] . |
abstract VectorMask |
indexInRange |
Removes lanes numbered N from this mask where the adjusted index N+offset , is not in the range [0..limit-1] . |
abstract void |
intoArray |
Stores this mask into a boolean array starting at offset. |
abstract boolean |
laneIsSet |
Tests if the lane at index i is set |
abstract int |
lastTrue() |
Returns the index of the last mask lane that is set. |
final int |
length() |
Returns the number of mask lanes. |
abstract VectorMask |
not() |
Logically negates this mask. |
abstract VectorMask |
or |
Computes the logical union (as a|b ) of this mask and a second input mask. |
abstract boolean[] |
toArray() |
Returns an boolean array containing the lane elements of this mask. |
abstract long |
toLong() |
Returns the lane elements of this mask packed into a long 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. |
abstract Vector |
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 |
trueCount() |
Returns the number of mask lanes that are set. |
abstract VectorSpecies |
vectorSpecies() |
Returns the vector species to which this mask applies. |
abstract VectorMask |
xor |
Determines logical symmetric difference (as a^b ) of this mask and a second input mask. |
public abstract VectorSpecies<E> vectorSpecies()
public final int length()
public static <E> VectorMask<E> fromValues(VectorSpecies<E> species, boolean... bits)
boolean
values. For each mask lane, where N
is the mask lane index, if the given boolean
value at index N
is true
then the mask lane at index N
is set, otherwise it is unset.
The given species must have a number of lanes that is compatible with the given array.
E
- the boxed element typespecies
- vector species for the desired maskbits
- the given boolean
valuesboolean
valueIllegalArgumentException
- if bits.length != species.length()
public static <E> VectorMask<E> fromArray(VectorSpecies<E> species, boolean[] bits, int offset)
boolean
array starting at an offset. For each mask lane, where N
is the mask lane index, if the array element at index offset + N
is true
then the mask lane at index N
is set, otherwise it is unset.
E
- the boxed element typespecies
- vector species for the desired maskbits
- the boolean
arrayoffset
- the offset into the arrayboolean
arrayIndexOutOfBoundsException
- if offset < 0
, or offset > bits.length - species.length()
public static <E> VectorMask<E> fromLong(VectorSpecies<E> species, long bits)
For each mask lane, where N
is the mask lane index, if the expression (bits>>min(63,N))&1
is non-zero, then the mask lane at index N
is set, otherwise it is unset.
If the given species has fewer than 64 lanes, the high 64-VLENGTH
bits 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.
E
- the boxed element typespecies
- vector species for the desired maskbits
- the given mask bits, as a 64-bit signed integerpublic abstract <F> VectorMask<F> cast(VectorSpecies<F> species)
F
. The species.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 index N
is set, then the mask lane at index N
of the resulting mask is set, otherwise that mask lane is not set.
F
- the boxed element type of the speciesspecies
- vector species for the desired maskIllegalArgumentException
- if this mask length and the species length differpublic abstract long toLong()
long
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 the N
th bit is set to one in the resulting long
value, otherwise the N
th bit is set to zero. The mask must have no more than 64 lanes.
long
value.UnsupportedOperationException
- if there are more than 64 lanes in this maskpublic abstract boolean[] toArray()
boolean
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;
public abstract void intoArray(boolean[] a, int offset)
boolean
array starting at offset. For each mask lane, where N
is the mask lane index, the lane element at index N
is stored into the array element a[offset+N]
.
a
- the array, of type boolean[]offset
- the offset into the arrayIndexOutOfBoundsException
- if offset < 0
or offset > a.length - this.length()
public abstract boolean anyTrue()
true
if any of the mask lanes are set.true
if any of the mask lanes are set, otherwise false
.public abstract boolean allTrue()
true
if all of the mask lanes are set.true
if all of the mask lanes are set, otherwise false
.public abstract int trueCount()
public abstract int firstTrue()
VLENGTH
if none of them are set.VLENGTH
public abstract int lastTrue()
-1
if none of them are set.-1
public abstract VectorMask<E> and(VectorMask<E> m)
a&b
) between this mask and a second input mask. This is a lane-wise binary operation which applies the logical AND
operation (&
) to each corresponding pair of mask bits.
m
- the second input maskpublic abstract VectorMask<E> or(VectorMask<E> m)
a|b
) of this mask and a second input mask. This is a lane-wise binary operation which applies the logical OR
operation (|
) to each corresponding pair of mask bits.
m
- the input maskpublic abstract VectorMask<E> xor(VectorMask<E> m)
a^b
) of this mask and a second input mask. This is a lane-wise binary operation which applies the logical XOR
operation (^
) to each corresponding pair of mask bits.
m
- the input maskpublic abstract VectorMask<E> andNot(VectorMask<E> m)
a&~b
). This is a lane-wise binary operation which applies the logical ANDC
operation (&~
) to each corresponding pair of mask bits.
m
- the second input maskpublic abstract VectorMask<E> eq(VectorMask<E> m)
a==b
or a^~b
). This is a lane-wise 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.
m
- the input maskpublic abstract VectorMask<E> not()
This is a lane-wise binary operation which applies the logical NOT
operation (~
) to each mask bit.
public abstract VectorMask<E> indexInRange(int offset, int limit)
N
from this mask where the adjusted index N+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.
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 N
set lanes followed by a series of unset lanes can be obtained by calling allTrue.indexInRange(0, N)
, where allTrue
is a mask of all true bits. A mask of N1
unset lanes followed by N2
set lanes can be obtained by calling allTrue.indexInRange(-N1, N2)
.
offset
- the starting indexlimit
- the upper-bound (exclusive) of index rangepublic abstract VectorMask<E> indexInRange(long offset, long limit)
N
from this mask where the adjusted index N+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.
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 N
set lanes followed by a series of unset lanes can be obtained by calling allTrue.indexInRange(0, N)
, where allTrue
is a mask of all true bits. A mask of N1
unset lanes followed by N2
set lanes can be obtained by calling allTrue.indexInRange(-N1, N2)
.
offset
- the starting indexlimit
- the upper-bound (exclusive) of index rangepublic abstract Vector<E> toVector()
N
is the mask lane index, if the mask lane is set at N
then the specific non-default value -1
is placed into the resulting vector at lane index N
. Otherwise the default element value 0
is placed into the resulting vector at lane index N
. 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 values 0
or -1
. For every ETYPE
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)
, where ZERO
and MINUS_ONE
are vectors which replicate the default ETYPE
value and the ETYPE
value representing -1
, respectively.
public abstract boolean laneIsSet(int i)
i
is seti
- the lane indexi
is set, otherwise falseIndexOutOfBoundsException
- if the index is out of range (< 0 || >= length()
)public abstract <F> VectorMask<F> check(Class<F> elementType)
elementType == vectorSpecies().elementType()
? this
: throw new ClassCastException()
.F
- the boxed element type of the required lane typeelementType
- the required lane typeClassCastException
- if the element type is wrongpublic abstract <F> VectorMask<F> check(VectorSpecies<F> species)
species == vectorSpecies()
? this
: throw new ClassCastException()
.F
- the boxed element type of the required speciesspecies
- vector species required for this maskClassCastException
- if the species is wrongpublic final String toString()
"Mask[T.TT...]"
, reporting the mask bit settings (as 'T' or '.' characters) in lane order.public final boolean equals(Object obj)
public final int hashCode()
public abstract VectorMask<E> compress()
N
set lanes followed by a series of unset lanes, where N
is the true count of this mask.protected final Object getPayload()
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorMask.html