< prev index next >
src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java
Print this page
@@ -136,11 +136,11 @@
* a member of the {@link VectorShape} enumeration, and represents
* an implementation format shared in common by all vectors of a
* of that shape. Thus, the {@linkplain #bitSize() size in bits} of
* of a vector is determined by appealing to its vector shape.
*
- * <p> Some Java platforms given special support to only one shape,
+ * <p> Some Java platforms give special support to only one shape,
* while others support several. A typical platform is not likely
* to support all the shapes described by this API. For this reason,
* most vector operations work on a single input shape and
* produce the same shape on output. Operations which change
* shape are clearly documented as such <em>shape-changing</em>,
@@ -173,11 +173,11 @@
* <p> Vector shape, {@code VLENGTH}, and {@code ETYPE} are all
* mutually constrained, so that {@code VLENGTH} times the
* {@linkplain #elementSize() bit-size of each lane}
* must always match the bit-size of the vector's shape.
*
- * Thus, {@link plain #reinterpretShape(VectorSpecies,int) reinterpreting} a
+ * Thus, {@linkplain #reinterpretShape(VectorSpecies,int) reinterpreting} a
* vector via a cast may double its length if and only if it either
* halves the lane size, or else changes the shape. Likewise,
* reinterpreting a vector may double the lane size if and only if it
* either halves the length, or else changes the shape of the vector.
*
@@ -201,18 +201,16 @@
* creates and returns a float vector of the specified species, with elements
* loaded from the specified float array.
* It is recommended that Species instances be held in {@code static final}
* fields for optimal creation and usage of Vector values by the runtime compiler.
*
- * <p> The various typed vector classes expose static constants
- * corresponding to their supported species, and static methods on these
- * types generally take a species as a parameter. For example, the
+ * <p> As an example of static constants defined by the typed vector classes,
* constant {@link FloatVector#SPECIES_256 FloatVector.SPECIES_256}
* is the unique species whose lanes are {@code float}s and whose
* vector size is 256 bits. Again, the constant
- * {@link ShortVector#SPECIES_PREFERRED} is the species which
- * best supports processing of {@code short} vector lanes on
+ * {@link FloatVector#SPECIES_PREFERRED} is the species which
+ * best supports processing of {@code float} vector lanes on
* the currently running Java platform.
*
* <p> As another example, a broadcast scalar value of
* {@code (double)0.5} can be obtained by calling
* {@link DoubleVector#broadcast(VectorSpecies,double)
@@ -305,11 +303,11 @@
* <li>
* Generalizing from unary and binary operations,
* a <em>lane-wise n-ary</em> operation takes {@code N} input vectors {@code v[j]},
* distributing an n-ary scalar operator across the lanes,
* and produces a result vector of the same type and shape.
- * Except for a few ternary operations, this API has no support
+ * Except for a few ternary operations, this API has no support for
* lane-wise n-ary operations.
*
* For each lane of all of the input vectors {@code v[j]},
* the underlying scalar operator is applied to the lane values.
* The result is placed into the vector result in the same lane.
@@ -350,11 +348,11 @@
* results</em>, under the control of a {@code part} parameter, which
* is <a href="Vector.html#expansion">explained elsewhere</a>.
*
* <p> The following pseudocode illustrates the behavior of this
* operation category in the specific example of a conversion from
- * {@code int} to {@code double}:
+ * {@code int} to {@code double}, retaining lower lanes to maintain shape-invariance:
*
* <pre>{@code
* IntVector a = ...;
* int VLENGTH = a.length();
* VectorShape VSHAPE = a.shape();
@@ -423,11 +421,11 @@
* Masked operations are explained in
* <a href="Vector.html#masking">greater detail elsewhere</a>.
*
* <li>
* A very special case of a masked lane-wise binary operation is a
- * {@linkplain blend(Vector,VectorMask) blend}, which operates
+ * {@linkplain #blend(Vector,VectorMask) blend}, which operates
* lane-wise on two input vectors {@code a} and {@code b}, selecting lane
* values from one input or the other depending on a mask {@code m}.
* In lanes where {@code m} is set, the corresponding value from
* {@code b} is selected into the result; otherwise the value from
* {@code a} is selected. Thus, a blend acts as a vectorized version
@@ -481,11 +479,11 @@
* vector. In this case the scalar value is promoted to a vector by
* {@linkplain Vector#broadcast(long) broadcasting it}
* into the same lane structure as the first input.
*
* For example, to multiply all lanes of a {@code double} vector by
- * a scalar value{@code 1.1}, the expression {@code v.mul(1.1)} is
+ * a scalar value {@code 1.1}, the expression {@code v.mul(1.1)} is
* easier to work with than an equivalent expression with an explicit
* broadcast operation, such as {@code v.mul(v.broadcast(1.1))}
* or {@code v.mul(DoubleVector.broadcast(v.species(), 1.1))}.
*
* Unless otherwise specified the scalar variant always behaves as if
@@ -694,11 +692,11 @@
* fiction, because some related formulas are much simpler,
* specifically those which renumber bytes after lane structure
* changes. The earliest byte is invariantly earliest across all lane
* structure changes, but only if little-endian convention are used.
* The root cause of this is that bytes in scalars are numbered from
- * the least significant (rightmost) to the omst significant
+ * the least significant (rightmost) to the most significant
* (leftmost), and almost never vice-versa. If we habitually numbered
* sign bits as zero (as on some computers) then this API would reach
* for big-endian fictions to create unified addressing of vector
* bytes.
*
@@ -732,11 +730,11 @@
* creates and returns a float vector of some particular species {@code fsp},
* with elements loaded from some float array {@code fa}.
* The first lane is loaded from {@code fa[i]} and the last lane
* is initialized loaded from {@code fa[i+VL-1]}, where {@code VL}
* is the length of the vector as derived from the species {@code fsp}.
- * Then, {@link FloatVector#add(Vector<Float>) fv=FloatVector.add(fv2)}
+ * Then, {@link FloatVector#add(Vector<Float>) fv=fv.add(fv2)}
* will produce another float vector of that species {@code fsp},
* given a vector {@code fv2} of the same species {@code fsp}.
* Next, {@link FloatVector#compare(VectorOperators.Comparison,float)
* mnz=fv.compare(NE, 0.0f)} tests whether the result is zero,
*
@@ -1156,11 +1154,11 @@
/// Arithmetic
/**
* Operates on the lane values of this vector.
*
- * This is a lane-wise binary operation which applies
+ * This is a lane-wise unary operation which applies
* the selected operation to each lane.
*
* <p>FIXME: Write about the unary operators here.
*
* @apiNote
@@ -1169,21 +1167,21 @@
*
* @return the result of applying the operation lane-wise
to the input vector
* @throws UnsupportedOperationException if this vector does
* not support the requested operation
- * @see #lanewise(VectorOperators.Unary,Vector,VectorMask)
+ * @see #lanewise(VectorOperators.Unary,VectorMask)
* @see #lanewise(VectorOperators.Binary,Vector)
- * @see #lanewise(VectorOperators.Ternary,Vector)
+ * @see #lanewise(VectorOperators.Ternary,Vector,Vector)
*/
public abstract Vector<E> lanewise(VectorOperators.Unary op);
/**
* Operates on the lane values of this vector,
* with selection of lane elements controlled by a mask.
*
- * This is a lane-wise binary operation which applies
+ * This is a lane-wise unary operation which applies
* the selected operation to each lane.
*
* @apiNote
* Subtypes improve on this method by sharpening
* the method return type.
@@ -1191,11 +1189,11 @@
* @param m the mask controlling lane selection
* @return the result of applying the operation lane-wise
* to the input vector
* @throws UnsupportedOperationException if this vector does
* not support the requested operation
- * @see #lanewise(VectorOperators.Unary,Vector)
+ * @see #lanewise(VectorOperators.Unary)
*/
public abstract Vector<E> lanewise(VectorOperators.Unary op,
VectorMask<E> m);
/**
@@ -1221,12 +1219,12 @@
* @return the result of applying the operation lane-wise
* to the two input vectors
* @throws UnsupportedOperationException if this vector does
* not support the requested operation
* @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
- * @see #lanewise(VectorOperators.Unary,Vector)
- * @see #lanewise(VectorOperators.Ternary,Vector)
+ * @see #lanewise(VectorOperators.Unary)
+ * @see #lanewise(VectorOperators.Ternary,Vector, Vector)
*/
public abstract Vector<E> lanewise(VectorOperators.Binary op,
Vector<E> v);
/**
@@ -1341,11 +1339,11 @@
* @param v2 the third input vector
* @return the result of applying the operation lane-wise
* to the three input vectors
* @throws UnsupportedOperationException if this vector does
* not support the requested operation
- * @see #lanewise(VectorOperators.Unary,Vector)
+ * @see #lanewise(VectorOperators.Unary)
* @see #lanewise(VectorOperators.Binary,Vector)
* @see #lanewise(VectorOperators.Ternary,Vector,Vector,VectorMask)
*/
public abstract Vector<E> lanewise(VectorOperators.Ternary op,
Vector<E> v1,
@@ -1671,24 +1669,24 @@
* This is a lane-wise unary operation which applies
* the primitive negation operation ({@code -x})
* to each input lane.
*
* This method is also equivalent to the expression
- * {@link #lanewise(VectorOperators.Unary,Vector)
+ * {@link #lanewise(VectorOperators.Unary)
* lanewise}{@code (}{@link VectorOperators#NEG
- * MIN}{@code)}.
+ * NEG}{@code)}.
*
* @apiNote
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
- * {@linkplain #lanewise(VectorOperators.Unary,Vector,VectorMask)
+ * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
* lanewise method}.
*
* @return the negation of this vector
* @see VectorOperators#NEG
- * @see #lanewise(VectorOperators.Unary,Vector)
- * @see #lanewise(VectorOperators.Unary,Vector,VectorMask)
+ * @see #lanewise(VectorOperators.Unary)
+ * @see #lanewise(VectorOperators.Unary,VectorMask)
*/
public abstract Vector<E> neg();
/**
* Returns the absolute value of this vector.
@@ -1696,24 +1694,24 @@
* This is a lane-wise unary operation which applies
* the method {@code Math.abs}
* to each input lane.
*
* This method is also equivalent to the expression
- * {@link #lanewise(VectorOperators.Unary,Vector)
+ * {@link #lanewise(VectorOperators.Unary)
* lanewise}{@code (}{@link VectorOperators#ABS
- * MIN}{@code)}.
+ * ABS}{@code)}.
*
- * <p>
+ * @apiNote
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
- * {@linkplain #lanewise(VectorOperators.Unary,Vector,VectorMask)
+ * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
* lanewise method}.
*
* @return the absolute value of this vector
* @see VectorOperators#ABS
- * @see #lanewise(VectorOperators.Unary,Vector)
- * @see #lanewise(VectorOperators.Unary,Vector,VectorMask)
+ * @see #lanewise(VectorOperators.Unary)
+ * @see #lanewise(VectorOperators.Unary,VectorMask)
*/
public abstract Vector<E> abs();
/// Non-full-service binary ops: MIN, MAX
@@ -1727,11 +1725,11 @@
* This method is also equivalent to the expression
* {@link #lanewise(VectorOperators.Binary,Vector)
* lanewise}{@code (}{@link VectorOperators#MIN
* MIN}{@code , v)}.
*
- * <p>
+ * @apiNote
* This is not a full-service named operation like
* {@link #add(Vector) add()}. A masked version of
* version of this operation is not directly available
* but may be obtained via the masked version of
* {@code lanewise}. Subclasses define an additional
@@ -1840,17 +1838,17 @@
* If the operation is {@code MAX},
* then the identity value is the {@code MIN_VALUE}
* of the vector's native {@code ETYPE}.
* (In the case of floating point types, the value
* {@code NEGATIVE_INFINITY} is used, and will appear
- * after casting as {@code Long.MAX_VALUE}.
+ * after casting as {@code Long.MIN_VALUE}.
* <li>
* If the operation is {@code MIN},
- * then the identity value is the {@code MIN_VALUE}
+ * then the identity value is the {@code MAX_VALUE}
* of the vector's native {@code ETYPE}.
* (In the case of floating point types, the value
- * {@code NEGATIVE_INFINITY} is used, and will appear
+ * {@code POSITIVE_INFINITY} is used, and will appear
* after casting as {@code Long.MAX_VALUE}.
* </ul>
*
* @apiNote
* If the {@code ETYPE} is {@code float} or {@code double},
@@ -1927,12 +1925,12 @@
*
* @param v a second input vector
* @return the mask result of testing lane-wise if this vector
* compares to the input, according to the selected
* comparison operator
- * @see #equals(Vector)
- * @see #lessThan(Vector)
+ * @see #eq(Vector)
+ * @see #lt(Vector)
* @see VectorOperators.Comparison
* @see #compare(VectorOperators.Comparison, Vector, VectorMask)
*/
public abstract VectorMask<E> compare(VectorOperators.Comparison op,
Vector<E> v);
@@ -2170,11 +2168,11 @@
* respectively.
*
* @apiNote
*
* This method may be regarded as the inverse of
- * {@code #unslice(int,Vector,int) unslice()},
+ * {@link #unslice(int,Vector,int) unslice()},
* in that the sliced value could be unsliced back into its
* original position in the two input vectors, without
* disturbing unrelated elements, as in the following
* pseudocode:
* <pre>{@code
@@ -2472,11 +2470,11 @@
* the output lane {@code N} obtains the value from
* the input vector at lane {@code I}.
*
* @param s the shuffle controlling lane index selection
* @return the rearrangement of the lane elements of this vector
- * @throw IndexOutOfBoundsException if there are any exceptional
+ * @throws IndexOutOfBoundsException if there are any exceptional
* source indexes in the shuffle
* @see #rearrange(VectorShuffle,VectorMask)
* @see #rearrange(VectorShuffle,Vector)
* @see VectorShuffle#laneIsValid()
*/
@@ -2496,17 +2494,19 @@
* Otherwise the output lane {@code N} is set to zero.
*
* <p> This method returns the value of this pseudocode:
* <pre>{@code
* Vector<E> r = this.rearrange(s.wrapIndexes());
- * return broadcast(0).blend(r, s.laneIsValid());
+ * VectorMask<E> valid = s.laneIsValid();
+ * if (m.andNot(valid).anyTrue()) throw ...;
+ * return broadcast(0).blend(r, m);
* }</pre>
*
* @param s the shuffle controlling lane index selection
* @param m the mask controlling application of the shuffle
* @return the rearrangement of the lane elements of this vector
- * @throw IndexOutOfBoundsException if there are any exceptional
+ * @throws IndexOutOfBoundsException if there are any exceptional
* source indexes in the shuffle where the mask is set
* @see #rearrange(VectorShuffle)
* @see #rearrange(VectorShuffle,Vector)
* @see VectorShuffle#laneIsValid()
*/
@@ -2740,11 +2740,11 @@
* question were loaded or stored into memory, memory semantics
* has little to do or nothing with the actual implementation.
* The appeal to little-endian ordering is simply a shorthand
* for what could otherwise be a large number of detailed rules
* concerning the mapping between lane-structured vectors and
- * byte-sturctured vectors.
+ * byte-structured vectors.
*
* @param species the desired vector species
* @param part the <a href="Vector.html#expansion">part number</a>
* of the result, or zero if neither expanding nor contracting
* @param <F> the boxed element type of the species
@@ -2767,12 +2767,12 @@
* within the same vector, such as
* {@link Vector#reinterpretAsInts()}.
*
* @return a {@code ByteVector} with the same shape and information content
* @see Vector#reinterpretShape(VectorSpecies,int)
- * @see ByteVector#toIntArray
- * @see ByteVector#toFloatArray
+ * @see IntVector#intoByteArray(byte[], int)
+ * @see FloatVector#intoByteArray(byte[], int)
* @see VectorSpecies#withLanes(Class)
*/
public abstract ByteVector reinterpretAsBytes();
/**
@@ -2849,11 +2849,11 @@
* {@code VLENGTH}, and there is no change to the bitwise contents
* of the vector. If the vector's {@code ETYPE} is already an
* integral type, the same vector is returned unchanged.
*
* This method returns the value of this expression:
- * {@code convert(conv,part)}, where {@code conv} is
+ * {@code convert(conv,0)}, where {@code conv} is
* {@code VectorOperators.Conversion.ofReinterpret(E.class,F.class)},
* and {@code F} is the non-floating-point type of the
* same size as {@code E}.
*
* @apiNote
@@ -2878,11 +2878,11 @@
*
* If the vector's element size does not match any floating point
* type size, an {@code IllegalArgumentException} is thrown.
*
* This method returns the value of this expression:
- * {@code convert(conv,part)}, where {@code conv} is
+ * {@code convert(conv,0)}, where {@code conv} is
* {@code VectorOperators.Conversion.ofReinterpret(E.class,F.class)},
* and {@code F} is the floating-point type of the
* same size as {@code E}, if any.
*
* @apiNote
@@ -2948,11 +2948,11 @@
* In the case of an expansion, the lane value is first truncated
* to the smaller value (as if by an initial reinterpretation),
* and then converted before storing into the output lane.
*
* <p> An expanding conversion such as {@code S2I} ({@code short}
- * value to {@code long}) takes a scalar value and represents it
+ * value to {@code int}) takes a scalar value and represents it
* in a larger format (always with some information redundancy).
*
* A contracting conversion such as {@code D2F} ({@code double}
* value to {@code float}) takes a scalar value and represents it
* in a smaller format (always with some information loss).
@@ -3043,12 +3043,12 @@
* {@code part} is negative and greater {@code -M}
*
* @see VectorOperators#I2L
* @see VectorOperators.Conversion#ofCast(Class,Class)
* @see VectorSpecies#partLimit(VectorSpecies,boolean)
- * @see #viewAsFloatingLanes(VectorSpecies,int)
- * @see #viewAsIntegralLanes(VectorSpecies,int)
+ * @see #viewAsFloatingLanes()
+ * @see #viewAsIntegralLanes()
* @see #convertShape(VectorOperators.Conversion,VectorSpecies,int)
* @see #reinterpretShape(VectorSpecies,int)
*/
public abstract <F> Vector<F> convert(VectorOperators.Conversion<E,F> conv, int part);
< prev index next >