< prev index next >
src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java
Print this page
rev 55891 : 8222897: [vector] Renaming of shift, rotate operations. Few other api changes.
Summary: Renaming of shift, rotate operations. Few other api changes.
Reviewed-by: jrose, briangoetz
rev 55894 : 8222897: [vector] Renaming of shift, rotate operations. Few other api changes.
Summary: Renaming of shift, rotate operations. Few other api changes.
Reviewed-by: jrose, briangoetz
@@ -103,11 +103,11 @@
*
* <pre>{@code
* EVector a = ...;
* e[] ar = new e[a.length()];
* for (int i = 0; i < a.length(); i++) {
- * ar[i] = scalar_unary_op(a.get(i));
+ * ar[i] = scalar_unary_op(a.lane(i));
* }
* EVector r = EVector.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the input and result vectors will have the same
@@ -125,11 +125,11 @@
* <pre>{@code
* EVector a = ...;
* EVector b = ...;
* e[] ar = new e[a.length()];
* for (int i = 0; i < a.length(); i++) {
- * ar[i] = scalar_binary_op(a.get(i), b.get(i));
+ * ar[i] = scalar_binary_op(a.lane(i), b.lane(i));
* }
* EVector r = EVector.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the two input and result vectors will have the
@@ -157,11 +157,11 @@
* if it is associative:
* <pre>{@code
* EVector a = ...;
* e r = <identity value>;
* for (int i = 0; i < a.length(); i++) {
- * r = assoc_scalar_binary_op(r, a.get(i));
+ * r = assoc_scalar_binary_op(r, a.lane(i));
* }
* }</pre>
*
* Unless otherwise specified the scalar result type and element type will be
* the same.
@@ -176,11 +176,11 @@
* <pre>{@code
* EVector a = ...;
* EVector b = ...;
* boolean[] ar = new boolean[a.length()];
* for (int i = 0; i < a.length(); i++) {
- * ar[i] = scalar_binary_test_op(a.get(i), b.get(i));
+ * ar[i] = scalar_binary_test_op(a.lane(i), b.lane(i));
* }
* VectorMask r = VectorMask.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the two input vectors and result mask will have
@@ -276,11 +276,11 @@
public Class<E> elementType() { return species().elementType(); }
/**
* Returns the element size, in bits, of this vector.
*
- * @return the element size, in bits
+ * @return the element size, in bits, of this vector
*/
public int elementSize() { return species().elementSize(); }
/**
* Returns the shape of this vector.
@@ -295,13 +295,13 @@
* @return the number of vector lanes
*/
public int length() { return species().length(); }
/**
- * Returns the total vector size, in bits.
+ * Returns the total size, in bits, of this vector.
*
- * @return the total vector size, in bits
+ * @return the total size, in bits, of this vector
*/
public int bitSize() { return species().bitSize(); }
//Arithmetic
@@ -389,11 +389,11 @@
/**
* Negates this vector, selecting lane elements controlled by a mask.
* <p>
* This is a lane-wise unary operation which applies the primitive negation operation
- * ({@code -})to each lane.
+ * ({@code -}) to each lane.
*
* @param m the mask controlling lane selection
* @return the negation this vector
*/
public abstract Vector<E> neg(VectorMask<E> m);
@@ -473,11 +473,11 @@
// Comparisons
/**
* Tests if this vector is equal to an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive equals
+ * This is a lane-wise binary test operation which applies the primitive equals
* operation ({@code ==}) to each lane.
*
* @param v the input vector
* @return the result mask of testing if this vector is equal to the input
* vector
@@ -485,11 +485,11 @@
public abstract VectorMask<E> equal(Vector<E> v);
/**
* Tests if this vector is not equal to an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive not equals
+ * This is a lane-wise binary test operation which applies the primitive not equals
* operation ({@code !=}) to each lane.
*
* @param v the input vector
* @return the result mask of testing if this vector is not equal to the
* input vector
@@ -497,11 +497,11 @@
public abstract VectorMask<E> notEqual(Vector<E> v);
/**
* Tests if this vector is less than an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive less than
+ * This is a lane-wise binary test operation which applies the primitive less than
* operation ({@code <}) to each lane.
*
* @param v the input vector
* @return the mask result of testing if this vector is less than the input
* vector
@@ -509,11 +509,11 @@
public abstract VectorMask<E> lessThan(Vector<E> v);
/**
* Tests if this vector is less or equal to an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive less than
+ * This is a lane-wise binary test operation which applies the primitive less than
* or equal to operation ({@code <=}) to each lane.
*
* @param v the input vector
* @return the mask result of testing if this vector is less than or equal
* to the input vector
@@ -521,11 +521,11 @@
public abstract VectorMask<E> lessThanEq(Vector<E> v);
/**
* Tests if this vector is greater than an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive greater than
+ * This is a lane-wise binary test operation which applies the primitive greater than
* operation ({@code >}) to each lane.
*
* @param v the input vector
* @return the mask result of testing if this vector is greater than the
* input vector
@@ -533,11 +533,11 @@
public abstract VectorMask<E> greaterThan(Vector<E> v);
/**
* Tests if this vector is greater than or equal to an input vector.
* <p>
- * This is a lane-wise binary test operation where the primitive greater than
+ * This is a lane-wise binary test operation which applies the primitive greater than
* or equal to operation ({@code >=}) to each lane.
*
* @param v the input vector
* @return the mask result of testing if this vector is greater than or
* equal to the given vector
@@ -558,11 +558,11 @@
*
* @param i the number of lanes to rotate left
* @return the result of rotating left lane elements of this vector by the
* given number of lanes
*/
- public abstract Vector<E> rotateEL(int i);
+ public abstract Vector<E> rotateLanesLeft(int i);
/**
* Rotates right the lane elements of this vector by the given number of
* lanes, {@code i}, modulus the vector length.
* <p>
@@ -570,15 +570,15 @@
* vector.
* For each lane of the input vector, at lane index {@code N}, the lane
* element is placed into the result vector at lane index
* {@code (N + length() - (i % length())) % length()}
*
- * @param i the number of lanes to rotate left
+ * @param i the number of lanes to rotate right
* @return the result of rotating right lane elements of this vector by the
* given number of lanes
*/
- public abstract Vector<E> rotateER(int i);
+ public abstract Vector<E> rotateLanesRight(int i);
/**
* Shift left the lane elements of this vector by the given number of
* lanes, {@code i}, modulus the vector length.
* <p>
@@ -590,11 +590,11 @@
* @param i the number of lanes to shift left
* @return the result of shifting left lane elements of this vector by the
* given number of lanes
* @throws IllegalArgumentException if {@code i} is {@code < 0}.
*/
- public abstract Vector<E> shiftEL(int i);
+ public abstract Vector<E> shiftLanesLeft(int i);
/**
* Shift right the lane elements of this vector by the given number of
* lanes, {@code i}, modulus the vector length.
* <p>
@@ -606,11 +606,11 @@
* @param i the number of lanes to shift right
* @return the result of shifting right lane elements of this vector by the
* given number of lanes
* @throws IllegalArgumentException if {@code i} is {@code < 0}.
*/
- public abstract Vector<E> shiftER(int i);
+ public abstract Vector<E> shiftLanesRight(int i);
/**
* Blends the lane elements of this vector with those of an input vector,
* selecting lanes controlled by a mask.
* <p>
@@ -626,10 +626,25 @@
* those of an input vector
*/
public abstract Vector<E> blend(Vector<E> v, VectorMask<E> m);
/**
+ * Rearranges the lane elements of this vector selecting lane indexes
+ * controlled by a shuffle.
+ * <p>
+ * This is a cross-lane operation that rearranges the lane elements of this
+ * vector.
+ * For each lane of the shuffle, at lane index {@code N} with lane
+ * element {@code I}, the lane element at {@code I} from this vector is
+ * selected and placed into the resulting vector at {@code N}.
+ *
+ * @param s the shuffle controlling lane index selection
+ * @return the rearrangement of the lane elements of this vector
+ */
+ public abstract Vector<E> rearrange(VectorShuffle<E> s);
+
+ /**
* Rearranges the lane elements of this vector and those of an input vector,
* selecting lane indexes controlled by shuffles and a mask.
* <p>
* This is a cross-lane operation that rearranges the lane elements of this
* vector and the input vector. This method behaves as if it rearranges
@@ -645,30 +660,13 @@
* index selection of this vector
* @param m the mask controlling shuffled lane selection
* @return the rearrangement of lane elements of this vector and
* those of an input vector
*/
- @ForceInline
- // rearrange
public abstract Vector<E> rearrange(Vector<E> v,
VectorShuffle<E> s, VectorMask<E> m);
- /**
- * Rearranges the lane elements of this vector selecting lane indexes
- * controlled by a shuffle.
- * <p>
- * This is a cross-lane operation that rearranges the lane elements of this
- * vector.
- * For each lane of the shuffle, at lane index {@code N} with lane
- * element {@code I}, the lane element at {@code I} from this vector is
- * selected and placed into the resulting vector at {@code N}.
- *
- * @param s the shuffle controlling lane index selection
- * @return the rearrangement of the lane elements of this vector
- */
- // rearrange
- public abstract Vector<E> rearrange(VectorShuffle<E> s);
// Conversions
/**
@@ -714,21 +712,22 @@
* On a system with ByteOrder.BIG_ENDIAN, the value is instead 66051 because
* bytes are composed in order 0x0 0x1 0x2 0x3.
* <p>
* The following pseudocode expresses the behavior:
* <pre>{@code
- * int blen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
- * ByteBuffer bb = ByteBuffer.allocate(blen).order(ByteOrder.nativeOrder());
+ * int bufferLen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
+ * ByteBuffer bb = ByteBuffer.allocate(bufferLen).order(ByteOrder.nativeOrder());
* this.intoByteBuffer(bb, 0);
* return $type$Vector.fromByteBuffer(s, bb, 0);
* }</pre>
*
* @param s species of desired vector
* @param <F> the boxed element type of the species
* @return a vector transformed, by shape and element type, from this vector
+ * @see Vector#reshape(VectorSpecies)
+ * @see Vector#cast(VectorSpecies)
*/
- @ForceInline
public abstract <F> Vector<F> reinterpret(VectorSpecies<F> s);
@ForceInline
@SuppressWarnings("unchecked")
<F> Vector<F> defaultReinterpret(VectorSpecies<F> s) {
@@ -773,10 +772,12 @@
* return $type$Vector.fromByteArray(s, a, 0);
* }</pre>
*
* @param s species of the desired vector
* @return a vector transformed, by shape, from this vector
+ * @see Vector#reinterpret(VectorSpecies)
+ * @see Vector#cast(VectorSpecies)
*/
public abstract Vector<E> reshape(VectorSpecies<E> s);
// Cast
@@ -794,10 +795,12 @@
* subsequent lanes of the resulting vector.
*
* @param s species of the desired vector
* @param <F> the boxed element type of the species
* @return a vector converted by shape and element type from this vector
+ * @see Vector#reshape(VectorSpecies)
+ * @see Vector#reinterpret(VectorSpecies)
*/
public abstract <F> Vector<F> cast(VectorSpecies<F> s);
//Array stores
@@ -934,6 +937,188 @@
}
else {
throw new IllegalArgumentException("Bad vector type: " + c.getName());
}
}
+
+ /**
+ * Returns a mask of same species as {@code this} vector and where each lane is set or unset according to given
+ * {@code boolean} values.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorMask#fromValues(VectorSpecies, boolean...) fromValues()}
+ * method in VectorMask as follows:
+ * <pre> {@code
+ * return VectorMask.fromValues(this.species(), bits);
+ * } </pre>
+ *
+ * @param bits the given {@code boolean} values
+ * @return a mask where each lane is set or unset according to the given {@code boolean} value
+ * @throws IndexOutOfBoundsException if {@code bits.length < this.species().length()}
+ * @see VectorMask#fromValues(VectorSpecies, boolean...)
+ */
+ @ForceInline
+ public final VectorMask<E> maskFromValues(boolean... bits) {
+ return VectorMask.fromValues(this.species(), bits);
+ }
+
+ /**
+ * Loads a mask of same species as {@code this} vector from a {@code boolean} array starting at an offset.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorMask#fromArray(VectorSpecies, boolean[], int) fromArray()}
+ * method in VectorMask as follows:
+ * <pre> {@code
+ * return VectorMask.fromArray(this.species(), bits, offset);
+ * } </pre>
+ *
+ * @param bits the {@code boolean} array
+ * @param offset the offset into the array
+ * @return the mask loaded from a {@code boolean} array
+ * @throws IndexOutOfBoundsException if {@code offset < 0}, or
+ * {@code offset > bits.length - species.length()}
+ * @see VectorMask#fromArray(VectorSpecies, boolean[], int)
+ */
+ @ForceInline
+ public final VectorMask<E> maskFromArray(boolean[] bits, int offset) {
+ return VectorMask.fromArray(this.species(), bits, offset);
+ }
+
+ /**
+ * Returns a mask of same species as {@code this} vector and where all lanes are set.
+ *
+ * @return a mask where all lanes are set
+ * @see VectorMask#maskAllTrue(VectorSpecies)
+ */
+ @ForceInline
+ public final VectorMask<E> maskAllTrue() {
+ return VectorMask.maskAllTrue(this.species());
+ }
+
+ /**
+ * Returns a mask of same species as {@code this} vector and where all lanes are unset.
+ *
+ * @return a mask where all lanes are unset
+ * @see VectorMask#maskAllFalse(VectorSpecies)
+ */
+ @ForceInline
+ public final VectorMask<E> maskAllFalse() {
+ return VectorMask.maskAllFalse(this.species());
+ }
+
+ /**
+ * Returns a shuffle of same species as {@code this} vector and where each lane element is set to a given
+ * {@code int} value logically AND'ed by the species length minus one.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#fromValues(VectorSpecies, int...) fromValues()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return VectorShuffle.fromValues(this.species(), ixs);
+ * } </pre>
+ *
+ * @param ixs the given {@code int} values
+ * @return a shuffle where each lane element is set to a given
+ * {@code int} value
+ * @throws IndexOutOfBoundsException if the number of int values is
+ * {@code < this.species().length()}
+ * @see AbstractShuffle#fromValues(VectorSpecies, int...)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffleFromValues(int... ixs) {
+ return VectorShuffle.fromValues(this.species(), ixs);
+ }
+
+ /**
+ * Loads a shuffle of same species as {@code this} vector from an {@code int} array starting at an offset.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#fromArray(VectorSpecies, int[], int) fromArray()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return VectorShuffle.fromArray(this.species(), ixs, offset);
+ * } </pre>
+ *
+ * @param ixs the {@code int} array
+ * @param offset the offset into the array
+ * @return a shuffle loaded from the {@code int} array
+ * @throws IndexOutOfBoundsException if {@code offset < 0}, or
+ * {@code offset > ixs.length - this.species().length()}
+ * @see AbstractShuffle#fromArray(VectorSpecies, int[], int)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffleFromArray(int[] ixs, int offset) {
+ return VectorShuffle.fromArray(this.species(), ixs, offset);
+ }
+
+ /**
+ * Returns a shuffle of same species as {@code this} vector of mapped indexes where each lane element is
+ * the result of applying a mapping function to the corresponding lane
+ * index.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#shuffle(VectorSpecies, IntUnaryOperator) shuffle()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return AbstractShuffle.shuffle(this.species(), f);
+ * } </pre>
+ *
+ * @param f the lane index mapping function
+ * @return a shuffle of mapped indexes
+ * @see AbstractShuffle#shuffle(VectorSpecies, IntUnaryOperator)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffle(IntUnaryOperator f) {
+ return AbstractShuffle.shuffle(this.species(), f);
+ }
+
+ /**
+ * Returns a shuffle of same species as {@code this} vector and where each lane element is the value of its
+ * corresponding lane index.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#shuffleIota(VectorSpecies) shuffleIota()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return VectorShuffle.shuffleIota(this.species());
+ * } </pre>
+ *
+ * @return a shuffle of lane indexes
+ * @see AbstractShuffle#shuffleIota(VectorSpecies)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffleIota() {
+ return VectorShuffle.shuffleIota(this.species());
+ }
+
+ /**
+ * Returns a shuffle of same species as {@code this} vector and with lane elements set to sequential {@code int}
+ * values starting from {@code start}.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#shuffleIota(VectorSpecies, int) shuffleIota()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return VectorShuffle.shuffleIota(this.species(), start);
+ * } </pre>
+ *
+ * @param start starting value of sequence
+ * @return a shuffle of lane indexes
+ * @see AbstractShuffle#shuffleIota(VectorSpecies, int)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffleIota(int start) {
+ return VectorShuffle.shuffleIota(this.species(), start);
+ }
+
+ /**
+ * Returns a shuffle of same species as {@code this} vector and with lane elements set to sequential {@code int}
+ * values starting from {@code start} and looping around species length.
+ * <p>
+ * This method behaves as if it returns the result of calling the static {@link VectorShuffle#shuffleOffset(VectorSpecies, int) shuffleOffset()}
+ * method in VectorShuffle as follows:
+ * <pre> {@code
+ * return VectorShuffle.shuffleOffset(this.species(), start);
+ * } </pre>
+ *
+ * @param start starting value of sequence
+ * @return a shuffle of lane indexes
+ * @see AbstractShuffle#shuffleOffset(VectorSpecies, int)
+ */
+ @ForceInline
+ public final VectorShuffle<E> shuffleOffset(int start) {
+ return VectorShuffle.shuffleOffset(this.species(), start);
+ }
}
< prev index next >