< prev index next >

src/jdk.incubator.vector/share/classes/jdk/incubator/vector/ByteVector.java

Print this page
rev 55237 : javadoc changes

@@ -102,11 +102,12 @@
 
     /**
      * Returns a vector where all lane elements are set to the default
      * primitive value.
      *
-     * @return a zero vector
+     * @param species species of desired vector
+     * @return a zero vector of given species
      */
     @ForceInline
     @SuppressWarnings("unchecked")
     public static ByteVector zero(ByteSpecies species) {
         return species.zero();

@@ -123,10 +124,11 @@
      * {@link #fromByteBuffer(ByteSpecies, ByteBuffer, int, Mask) method} as follows:
      * <pre>{@code
      * return this.fromByteBuffer(ByteBuffer.wrap(a), i, this.maskAllTrue());
      * }</pre>
      *
+     * @param species species of desired vector
      * @param a the byte array
      * @param ix the offset into the array
      * @return a vector loaded from a byte array
      * @throws IndexOutOfBoundsException if {@code i < 0} or
      * {@code i > a.length - (this.length() * this.elementSize() / Byte.SIZE)}

@@ -158,10 +160,11 @@
      * {@link #fromByteBuffer(ByteSpecies, ByteBuffer, int, Mask) method} as follows:
      * <pre>{@code
      * return this.fromByteBuffer(ByteBuffer.wrap(a), i, m);
      * }</pre>
      *
+     * @param species species of desired vector
      * @param a the byte array
      * @param ix the offset into the array
      * @param m the mask
      * @return a vector loaded from a byte array
      * @throws IndexOutOfBoundsException if {@code i < 0} or

@@ -182,10 +185,11 @@
      * <p>
      * For each vector lane, where {@code N} is the vector lane index, the
      * array element at index {@code i + N} is placed into the
      * resulting vector at lane index {@code N}.
      *
+     * @param species species of desired vector
      * @param a the array
      * @param i the offset into the array
      * @return the vector loaded from an array
      * @throws IndexOutOfBoundsException if {@code i < 0}, or
      * {@code i > a.length - this.length()}

@@ -209,10 +213,11 @@
      * if the mask lane at index {@code N} is set then the array element at
      * index {@code i + N} is placed into the resulting vector at lane index
      * {@code N}, otherwise the default element value is placed into the
      * resulting vector at lane index {@code N}.
      *
+     * @param species species of desired vector
      * @param a the array
      * @param i the offset into the array
      * @param m the mask
      * @return the vector loaded from an array
      * @throws IndexOutOfBoundsException if {@code i < 0}, or

@@ -230,10 +235,11 @@
      * <p>
      * For each vector lane, where {@code N} is the vector lane index, the
      * array element at index {@code i + indexMap[j + N]} is placed into the
      * resulting vector at lane index {@code N}.
      *
+     * @param species species of desired vector
      * @param a the array
      * @param i the offset into the array, may be negative if relative
      * indexes in the index map compensate to produce a value within the
      * array bounds
      * @param indexMap the index map

@@ -254,14 +260,16 @@
      * For each vector lane, where {@code N} is the vector lane index,
      * if the mask lane at index {@code N} is set then the array element at
      * index {@code i + indexMap[j + N]} is placed into the resulting vector
      * at lane index {@code N}.
      *
+     * @param species species of desired vector
      * @param a the array
      * @param i the offset into the array, may be negative if relative
      * indexes in the index map compensate to produce a value within the
      * array bounds
+     * @param m the mask
      * @param indexMap the index map
      * @param j the offset into the index map
      * @return the vector loaded from an array
      * @throws IndexOutOfBoundsException if {@code j < 0}, or
      * {@code j > indexMap.length - this.length()},

@@ -285,10 +293,11 @@
      * {@link #fromByteBuffer(ByteSpecies, ByteBuffer, int, Mask)} method} as follows:
      * <pre>{@code
      *   return this.fromByteBuffer(b, i, this.maskAllTrue())
      * }</pre>
      *
+     * @param species species of desired vector
      * @param bb the byte buffer
      * @param ix the offset into the byte buffer
      * @return a vector loaded from a byte buffer
      * @throws IndexOutOfBoundsException if the offset is {@code < 0},
      * or {@code > b.limit()},

@@ -336,12 +345,14 @@
      *         es[n] = eb.get(n);
      * }
      * Vector<E> r = ((ESpecies<S>)this).fromArray(es, 0, m);
      * }</pre>
      *
+     * @param species species of desired vector
      * @param bb the byte buffer
      * @param ix the offset into the byte buffer
+     * @param m the mask
      * @return a vector loaded from a byte buffer
      * @throws IndexOutOfBoundsException if the offset is {@code < 0},
      * or {@code > b.limit()},
      * for any vector lane index {@code N} where the mask at lane {@code N}
      * is set

@@ -350,10 +361,23 @@
     @ForceInline
     public static ByteVector fromByteBuffer(ByteSpecies species, ByteBuffer bb, int ix, Mask<Byte> m) {
         return zero(species).blend(fromByteBuffer(species, bb, ix), m);
     }
 
+    /**
+     * Returns a mask where each lane is set or unset according to given
+     * {@code boolean} values
+     * <p>
+     * For each mask lane, where {@code N} is the mask lane index,
+     * if the given {@code boolean} value at index {@code N} is {@code true}
+     * then the mask lane at index {@code N} is set, otherwise it is unset.
+     *
+     * @param species mask species
+     * @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 < species.length()}
+     */
     @ForceInline
     public static Mask<Byte> maskFromValues(ByteSpecies species, boolean... bits) {
         if (species.boxType() == ByteMaxVector.class)
             return new ByteMaxVector.ByteMaxMask(bits);
         switch (species.bitSize()) {

@@ -388,10 +412,24 @@
             case 512: return Byte512Vector.Byte512Mask.FALSE_MASK;
             default: throw new IllegalArgumentException(Integer.toString(species.bitSize()));
         }
     }
 
+    /**
+     * Loads a mask from a {@code boolean} array starting at an offset.
+     * <p>
+     * For each mask lane, where {@code N} is the mask lane index,
+     * if the array element at index {@code i + N} is {@code true} then the
+     * mask lane at index {@code N} is set, otherwise it is unset.
+     *
+     * @param species mask species
+     * @param bits the {@code boolean} array
+     * @param ix the offset into the array
+     * @return the mask loaded from a {@code boolean} array
+     * @throws IndexOutOfBoundsException if {@code ix < 0}, or
+     * {@code ix > bits.length - species.length()}
+     */
     @ForceInline
     @SuppressWarnings("unchecked")
     public static Mask<Byte> maskFromArray(ByteSpecies species, boolean[] bits, int ix) {
         Objects.requireNonNull(bits);
         ix = VectorIntrinsics.checkIndex(ix, bits.length, species.length());

@@ -399,26 +437,62 @@
                                      bits, (((long) ix) << ARRAY_SHIFT) + Unsafe.ARRAY_BOOLEAN_BASE_OFFSET,
                                      bits, ix, species,
                                      (c, idx, s) -> (Mask<Byte>) ((ByteSpecies)s).opm(n -> c[idx + n]));
     }
 
+    /**
+     * Returns a mask where all lanes are a set.
+     *
+     * @param species mask species
+     * @return a mask where all lanes are a set
+     */
     @ForceInline
     @SuppressWarnings("unchecked")
     public static Mask<Byte> maskAllTrue(ByteSpecies species) {
         return VectorIntrinsics.broadcastCoerced((Class<Mask<Byte>>) species.maskType(), byte.class, species.length(),
                                                  (byte)-1,  species,
                                                  ((z, s) -> trueMask((ByteSpecies)s)));
     }
 
+    /**
+     * Returns a mask where all lanes are a unset.
+     *
+     * @param species mask species
+     * @return a mask where all lanes are a unset
+     */
     @ForceInline
     @SuppressWarnings("unchecked")
     public static Mask<Byte> maskAllFalse(ByteSpecies species) {
         return VectorIntrinsics.broadcastCoerced((Class<Mask<Byte>>) species.maskType(), byte.class, species.length(),
                                                  0, species, 
                                                  ((z, s) -> falseMask((ByteSpecies)s)));
     }
 
+    /**
+     * Returns a shuffle of mapped indexes where each lane element is
+     * the result of applying a mapping function to the corresponding lane
+     * index.
+     * <p>
+     * Care should be taken to ensure Shuffle values produced from this
+     * method are consumed as constants to ensure optimal generation of
+     * code.  For example, values held in static final fields or values
+     * held in loop constant local variables.
+     * <p>
+     * This method behaves as if a shuffle is created from an array of
+     * mapped indexes as follows:
+     * <pre>{@code
+     *   int[] a = new int[species.length()];
+     *   for (int i = 0; i < a.length; i++) {
+     *       a[i] = f.applyAsInt(i);
+     *   }
+     *   return this.shuffleFromValues(a);
+     * }</pre>
+     *
+     * @param species shuffle species
+     * @param f the lane index mapping function
+     * @return a shuffle of mapped indexes
+     */
     @ForceInline
     public static Shuffle<Byte> shuffle(ByteSpecies species, IntUnaryOperator f) {
         if (species.boxType() == ByteMaxVector.class)
             return new ByteMaxVector.ByteMaxShuffle(f);
         switch (species.bitSize()) {

@@ -428,10 +502,23 @@
             case 512: return new Byte512Vector.Byte512Shuffle(f);
             default: throw new IllegalArgumentException(Integer.toString(species.bitSize()));
         }
     }
 
+    /**
+     * Returns a shuffle where each lane element is the value of its
+     * corresponding lane index.
+     * <p>
+     * This method behaves as if a shuffle is created from an identity
+     * index mapping function as follows:
+     * <pre>{@code
+     *   return this.shuffle(i -> i);
+     * }</pre>
+     *
+     * @param species shuffle species
+     * @return a shuffle of lane indexes
+     */
     @ForceInline
     public static Shuffle<Byte> shuffleIota(ByteSpecies species) {
         if (species.boxType() == ByteMaxVector.class)
             return new ByteMaxVector.ByteMaxShuffle(AbstractShuffle.IDENTITY);
         switch (species.bitSize()) {

@@ -441,10 +528,26 @@
             case 512: return new Byte512Vector.Byte512Shuffle(AbstractShuffle.IDENTITY);
             default: throw new IllegalArgumentException(Integer.toString(species.bitSize()));
         }
     }
 
+    /**
+     * Returns a shuffle where each lane element is set to a given
+     * {@code int} value logically AND'ed by the species length minus one.
+     * <p>
+     * For each shuffle lane, where {@code N} is the shuffle lane index, the
+     * the {@code int} value at index {@code N} logically AND'ed by
+     * {@code species.length() - 1} is placed into the resulting shuffle at
+     * lane index {@code N}.
+     *
+     * @param species shuffle species
+     * @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 < species.length()}
+     */
     @ForceInline
     public static Shuffle<Byte> shuffleFromValues(ByteSpecies species, int... ixs) {
         if (species.boxType() == ByteMaxVector.class)
             return new ByteMaxVector.ByteMaxShuffle(ixs);
         switch (species.bitSize()) {

@@ -454,10 +557,25 @@
             case 512: return new Byte512Vector.Byte512Shuffle(ixs);
             default: throw new IllegalArgumentException(Integer.toString(species.bitSize()));
         }
     }
 
+    /**
+     * Loads a shuffle from an {@code int} array starting at an offset.
+     * <p>
+     * For each shuffle lane, where {@code N} is the shuffle lane index, the
+     * array element at index {@code i + N} logically AND'ed by
+     * {@code species.length() - 1} is placed into the resulting shuffle at lane
+     * index {@code N}.
+     *
+     * @param species shuffle species
+     * @param ixs the {@code int} array
+     * @param i the offset into the array
+     * @return a shuffle loaded from the {@code int} array
+     * @throws IndexOutOfBoundsException if {@code i < 0}, or
+     * {@code i > a.length - species.length()}
+     */
     @ForceInline
     public static Shuffle<Byte> shuffleFromArray(ByteSpecies species, int[] ixs, int i) {
         if (species.boxType() == ByteMaxVector.class)
             return new ByteMaxVector.ByteMaxShuffle(ixs, i);
         switch (species.bitSize()) {

@@ -925,11 +1043,11 @@
      * <p>
      * This is a vector binary operation where the primitive logical left shift
      * operation ({@code <<}) is applied to lane elements to left shift the
      * element by shift value as specified by the input scalar. Only the 3
      * lowest-order bits of shift value are used. It is as if the shift value
-     * were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to left shift
      * @return the result of logically left shifting left this vector by the
      * broadcast of an input scalar

@@ -942,11 +1060,11 @@
      * <p>
      * This is a vector binary operation where the primitive logical left shift
      * operation ({@code <<}) is applied to lane elements to left shift the
      * element by shift value as specified by the input scalar. Only the 3
      * lowest-order bits of shift value are used. It is as if the shift value
-     * were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to left shift
      * @param m the mask controlling lane selection
      * @return the result of logically left shifting left this vector by the

@@ -963,11 +1081,11 @@
      * <p>
      * This is a vector binary operation where the primitive logical right shift
      * operation ({@code >>>}) is applied to lane elements to logically right shift the
      * element by shift value as specified by the input scalar. Only the 3
      * lowest-order bits of shift value are used. It is as if the shift value
-     * were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to right shift
      * @return the result of logically right shifting this vector by the
      * broadcast of an input scalar

@@ -981,14 +1099,15 @@
      * <p>
      * This is a vector binary operation where the primitive logical right shift
      * operation ({@code >>>}) is applied to lane elements to logically right shift the
      * element by shift value as specified by the input scalar. Only the 3
      * lowest-order bits of shift value are used. It is as if the shift value
-     * were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to right shift
+     * @param m the mask controlling lane selection
      * @return the result of logically right shifting this vector by the
      * broadcast of an input scalar
      */
     public abstract ByteVector shiftR(int s, Mask<Byte> m);
 

@@ -999,11 +1118,11 @@
      * <p>
      * This is a vector binary operation where the primitive arithmetic right
      * shift operation ({@code >>}) is applied to lane elements  to arithmetically
      * right shift the element by shift value as specified by the input scalar.
      * Only the 3 lowest-order bits of shift value are used. It is as if the shift
-     * value were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * value were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to right shift
      * @return the result of arithmetically right shifting this vector by the
      * broadcast of an input scalar

@@ -1017,11 +1136,11 @@
      * <p>
      * This is a vector binary operation where the primitive arithmetic right
      * shift operation ({@code >>}) is applied to lane elements  to arithmetically
      * right shift the element by shift value as specified by the input scalar.
      * Only the 3 lowest-order bits of shift value are used. It is as if the shift
-     * value were subjected to a bitwise logical AND operator & with the mask value 0x7.
+     * value were subjected to a bitwise logical AND operator ({@code &}) with the mask value 0x7.
      * The shift distance actually used is therefore always in the range 0 to 7, inclusive.
      *
      * @param s the input scalar; the number of the bits to right shift
      * @param m the mask controlling lane selection
      * @return the result of arithmetically right shifting this vector by the

@@ -1042,11 +1161,10 @@
     @Override
     public abstract void intoByteBuffer(ByteBuffer bb, int ix, Mask<Byte> m);
 
 
     // Type specific horizontal reductions
-
     /**
      * Adds all lane elements of this vector.
      * <p>
      * This is an associative vector reduction operation where the addition
      * operation ({@code +}) is applied to lane elements,

@@ -1063,39 +1181,15 @@
      * This is an associative vector reduction operation where the addition
      * operation ({@code +}) is applied to lane elements,
      * and the identity value is {@code 0}.
      *
      * @param m the mask controlling lane selection
-     * @return the addition of all the lane elements of this vector
+     * @return the addition of the selected lane elements of this vector
      */
     public abstract byte addAll(Mask<Byte> m);
 
     /**
-     * Subtracts all lane elements of this vector.
-     * <p>
-     * This is an associative vector reduction operation where the subtraction
-     * operation ({@code -}) is applied to lane elements,
-     * and the identity value is {@code 0}.
-     *
-     * @return the subtraction of all the lane elements of this vector
-     */
-    public abstract byte subAll();
-
-    /**
-     * Subtracts all lane elements of this vector, selecting lane elements
-     * controlled by a mask.
-     * <p>
-     * This is an associative vector reduction operation where the subtraction
-     * operation ({@code -}) is applied to lane elements,
-     * and the identity value is {@code 0}.
-     *
-     * @param m the mask controlling lane selection
-     * @return the subtraction of all the lane elements of this vector
-     */
-    public abstract byte subAll(Mask<Byte> m);
-
-    /**
      * Multiplies all lane elements of this vector.
      * <p>
      * This is an associative vector reduction operation where the
      * multiplication operation ({@code *}) is applied to lane elements,
      * and the identity value is {@code 1}.

@@ -1120,11 +1214,12 @@
     /**
      * Returns the minimum lane element of this vector.
      * <p>
      * This is an associative vector reduction operation where the operation
      * {@code (a, b) -> Math.min(a, b)} is applied to lane elements,
-     * and the identity value is {@link Byte#MAX_VALUE}.
+     * and the identity value is
+     * {@link Byte#MAX_VALUE}.
      *
      * @return the minimum lane element of this vector
      */
     public abstract byte minAll();
 

@@ -1132,11 +1227,12 @@
      * Returns the minimum lane element of this vector, selecting lane elements
      * controlled by a mask.
      * <p>
      * This is an associative vector reduction operation where the operation
      * {@code (a, b) -> Math.min(a, b)} is applied to lane elements,
-     * and the identity value is {@link Byte#MAX_VALUE}.
+     * and the identity value is
+     * {@link Byte#MAX_VALUE}.
      *
      * @param m the mask controlling lane selection
      * @return the minimum lane element of this vector
      */
     public abstract byte minAll(Mask<Byte> m);

@@ -1144,11 +1240,12 @@
     /**
      * Returns the maximum lane element of this vector.
      * <p>
      * This is an associative vector reduction operation where the operation
      * {@code (a, b) -> Math.max(a, b)} is applied to lane elements,
-     * and the identity value is {@link Byte#MIN_VALUE}.
+     * and the identity value is
+     * {@link Byte#MIN_VALUE}.
      *
      * @return the maximum lane element of this vector
      */
     public abstract byte maxAll();
 

@@ -1156,11 +1253,12 @@
      * Returns the maximum lane element of this vector, selecting lane elements
      * controlled by a mask.
      * <p>
      * This is an associative vector reduction operation where the operation
      * {@code (a, b) -> Math.max(a, b)} is applied to lane elements,
-     * and the identity value is {@link Byte#MIN_VALUE}.
+     * and the identity value is
+     * {@link Byte#MIN_VALUE}.
      *
      * @param m the mask controlling lane selection
      * @return the maximum lane element of this vector
      */
     public abstract byte maxAll(Mask<Byte> m);

@@ -1426,11 +1524,11 @@
         /**
          * Returns a vector where each lane element is set to a randomly
          * generated primitive value.
          *
          * The semantics are equivalent to calling
-         * {@link (byte)ThreadLocalRandom#nextInt() }
+         * {@code (byte)ThreadLocalRandom#nextInt()}.
          *
          * @return a vector where each lane elements is set to a randomly
          * generated primitive value
          */
         public ByteVector random() {
< prev index next >