- java.lang.Object
-
- jdk.incubator.vector.VectorMask<E>
-
- Type Parameters:
E
- the boxed element type of this mask
public abstract class VectorMask<E> extends Object
AVectorMask
represents an ordered immutable sequence ofboolean
values. Some vector operations accept 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 indexN
(from0
, inclusive, to length, exclusive) corresponds to theN + 1
'th value in the sequence. A VectorMask and Vector of the same element type and shape have the same number of lanes.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 isfalse
.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 expresses 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.isSet(i)); } VectorMask<E> r = VectorMask.fromArray(a.species(), 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 expresses 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.isSet(i), b.isSet(i)); } VectorMask<E> r = VectorMask.fromArray(a.species(), 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 expresses 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.isSet(i) ? 1 : 0); // & | + } return acc; // maybe boolean (acc != 0)
-
-
Method Summary
Modifier and Type Method Description abstract boolean
allTrue()
Returnstrue
if all of the mask lanes are set.abstract VectorMask<E>
and(VectorMask<E> o)
Logically ands this mask with an input mask.abstract boolean
anyTrue()
Returnstrue
if any of the mask lanes are set.abstract <F> VectorMask<F>
cast(VectorSpecies<F> s)
Converts this mask to a mask of the given species shape of element typeF
.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>
fromValues(VectorSpecies<E> species, boolean... bits)
Returns a mask where each lane is set or unset according to givenboolean
values.abstract void
intoArray(boolean[] a, int offset)
Stores this mask into aboolean
array starting at offset.boolean
isSet(int i)
Tests if the lane at indexi
is setabstract boolean
lane(int i)
Tests if the lane at indexi
is setint
length()
Returns the number of mask lanes (the length).static <E> VectorMask<E>
maskAllFalse(VectorSpecies<E> species)
Returns a mask where all lanes are unset.static <E> VectorMask<E>
maskAllTrue(VectorSpecies<E> species)
Returns a mask where all lanes are set.abstract VectorMask<E>
not()
Logically negates this mask.abstract VectorMask<E>
or(VectorMask<E> o)
Logically ors this mask with an input mask.abstract VectorSpecies<E>
species()
Returns the species of this 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.abstract Vector<E>
toVector()
Returns a vector representation of this mask.abstract int
trueCount()
Returns the number of mask lanes that are set.
-
-
-
Method Detail
-
species
public abstract VectorSpecies<E> species()
Returns the species of this mask.- Returns:
- the species of this mask
-
length
public int length()
Returns the number of mask lanes (the length).- Returns:
- the number of mask lanes
-
fromValues
public static <E> VectorMask<E> fromValues(VectorSpecies<E> species, boolean... bits)
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.- Parameters:
species
- mask speciesbits
- the givenboolean
values- Returns:
- a mask where each lane is set or unset according to the given
boolean
value - Throws:
IndexOutOfBoundsException
- ifbits.length < species.length()
- See Also:
Vector.maskFromValues(boolean...)
-
fromArray
public static <E> VectorMask<E> fromArray(VectorSpecies<E> species, boolean[] bits, int offset)
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 indexix + N
istrue
then the mask lane at indexN
is set, otherwise it is unset.- Parameters:
species
- mask speciesbits
- theboolean
arrayoffset
- the offset into the array- Returns:
- the mask loaded from a
boolean
array - Throws:
IndexOutOfBoundsException
- ifoffset < 0
, oroffset > bits.length - species.length()
- See Also:
Vector.maskFromArray(boolean[], int)
-
maskAllTrue
public static <E> VectorMask<E> maskAllTrue(VectorSpecies<E> species)
Returns a mask where all lanes are set.- Parameters:
species
- mask species- Returns:
- a mask where all lanes are set
- See Also:
Vector.maskAllTrue()
-
maskAllFalse
public static <E> VectorMask<E> maskAllFalse(VectorSpecies<E> species)
Returns a mask where all lanes are unset.- Parameters:
species
- mask species- Returns:
- a mask where all lanes are unset
- See Also:
Vector.maskAllFalse()
-
cast
public abstract <F> VectorMask<F> cast(VectorSpecies<F> s)
Converts this mask to a mask of the given species shape of element typeF
.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:
s
- the species of 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.- Returns:
- the lane elements of this mask packed into a
long
value.
-
toArray
public abstract boolean[] toArray()
Returns anboolean
array containing the lane elements of this mask.This method behaves as if it
intoArray(boolean[], int)
stores} this mask into an allocated array and returns that array as follows:boolean[] a = new boolean[this.length()]; this.intoArray(a, 0); return a;
- Returns:
- an array containing the 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 at indexi + N
.- Parameters:
a
- the arrayoffset
- 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.
-
and
public abstract VectorMask<E> and(VectorMask<E> o)
Logically ands this mask with an input mask.This is a lane-wise binary operation which applies the logical and operation (
&&
) to each lane.- Parameters:
o
- the input mask- Returns:
- the result of logically and'ing this mask with an input mask
-
or
public abstract VectorMask<E> or(VectorMask<E> o)
Logically ors this mask with an input mask.This is a lane-wise binary operation which applies the logical or operation (
||
) to each lane.- Parameters:
o
- the input mask- Returns:
- the result of logically or'ing this mask with an input mask
-
not
public abstract VectorMask<E> not()
Logically negates this mask.This is a lane-wise unary operation which applies the logical not operation (
!
) to each lane.- Returns:
- the result of logically negating this mask.
-
toVector
public abstract Vector<E> toVector()
Returns a vector representation of this mask.For each mask lane, where
N
is the mask lane index, if the mask lane is set then an element value whose most significant bit is set is placed into the resulting vector at lane indexN
, otherwise the default element value is placed into the resulting vector at lane indexN
.- Returns:
- a vector representation of this mask.
-
lane
public abstract boolean lane(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
-
isSet
public boolean isSet(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 - See Also:
lane(int)
-
-