< 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 >