< prev index next >
src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java
Print this page
rev 54658 : refactored mask and shuffle creation methods, moved classes to top-level
rev 54660 : Javadoc changes
*** 40,62 ****
/**
* A {@code Vector} is designed for use in computations that can be transformed
* by a runtime compiler, on supported hardware, to Single Instruction Multiple
* Data (SIMD) computations leveraging vector hardware registers and vector
* hardware instructions. Such SIMD computations exploit data parallelism to
! * perform the same operation on multiple data points simultaneously in a
! * faster time it would ordinarily take to perform the same operation
* sequentially on each data point.
* <p>
* A Vector represents an ordered immutable sequence of values of the same
* element type {@code e} that is one of the following primitive types
* {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, or
* {@code double}). The type variable {@code E} corresponds to the boxed
* element type, specifically the class that wraps a value of {@code e} in an
* object (such the {@code Integer} class that wraps a value of {@code int}}.
! * A Vector has a {@link #shape() shape} {@code S}, extending type
! * {@link VectorShape}, that governs the total {@link #bitSize() size} in bits
! * of the sequence of values.
* <p>
* The number of values in the sequence is referred to as the Vector
* {@link #length() length}. The length also corresponds to the number of
* Vector lanes. The lane element at lane index {@code N} (from {@code 0},
* inclusive, to length, exclusive) corresponds to the {@code N + 1}'th value in
--- 40,63 ----
/**
* A {@code Vector} is designed for use in computations that can be transformed
* by a runtime compiler, on supported hardware, to Single Instruction Multiple
* Data (SIMD) computations leveraging vector hardware registers and vector
* hardware instructions. Such SIMD computations exploit data parallelism to
! * perform the same operation on multiple data points simultaneously in
! * less time than it would ordinarily take to perform the same operation
* sequentially on each data point.
* <p>
* A Vector represents an ordered immutable sequence of values of the same
* element type {@code e} that is one of the following primitive types
* {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, or
* {@code double}). The type variable {@code E} corresponds to the boxed
* element type, specifically the class that wraps a value of {@code e} in an
* object (such the {@code Integer} class that wraps a value of {@code int}}.
! * A Vector has a {@link #shape() shape} {@code S}, extending type {@link VectorShape},
! * that governs the total {@link #bitSize() size} in bits of the sequence of values.
! * The combination of element type and shape determines a <em>vector species</em>,
! * represented by {@link jdk.incubator.vector.VectorSpecies}.
* <p>
* The number of values in the sequence is referred to as the Vector
* {@link #length() length}. The length also corresponds to the number of
* Vector lanes. The lane element at lane index {@code N} (from {@code 0},
* inclusive, to length, exclusive) corresponds to the {@code N + 1}'th value in
*** 70,189 ****
* element types (such as addition). Sub-classes of Vector with a concrete
* boxed element type declare further operations that are specific to that
* element type (such as access to element values in lanes, logical operations
* on values of integral elements types, or transcendental operations on values
* of floating point element types).
! * There are six sub-classes of Vector corresponding to the supported set
* of element types, {@link ByteVector}, {@link ShortVector},
* {@link IntVector} {@link LongVector}, {@link FloatVector}, and
! * {@link DoubleVector}.
* <p>
! * Vector values, instances of Vector, are created from a special kind of
! * factory called a {@link VectorSpecies}. A VectorSpecies has an
! * element type and shape and creates Vector values of the same element type
! * and shape.
! * A species can be {@link VectorSpecies#of(Class, VectorShape)} obtained} given an element
! * type and shape, or a preferred species can be
! * {@link VectorSpecies#ofPreferred(Class)} obtained} given just an element type where the most
! * optimal shape is selected for the current platform. It is recommended that
! * VectorSpecies instances be held in {@code static final} fields for optimal creation
! * and usage of Vector values by the runtime compiler.
* <p>
! * Vector operations can be grouped into various categories and their behaviour
* generally specified as follows:
* <ul>
* <li>
! * A vector unary operation (1-ary) operates on one input vector to produce a
* result vector.
* For each lane of the input vector the
* lane element is operated on using the specified scalar unary operation and
* the element result is placed into the vector result at the same lane.
! * The following pseudocode expresses the behaviour of this operation category,
* where {@code e} is the element type and {@code EVector} corresponds to the
* primitive Vector type:
*
* <pre>{@code
! * EVector<S> a = ...;
* e[] ar = new e[a.length()];
* for (int i = 0; i < a.length(); i++) {
* ar[i] = scalar_unary_op(a.get(i));
* }
! * EVector<S> r = a.species().fromArray(ar, 0);
* }</pre>
*
* Unless otherwise specified the input and result vectors will have the same
* element type and shape.
*
* <li>
! * A vector binary operation (2-ary) operates on two input
! * vectors to produce a result vector.
! * For each lane of the two input vectors,
! * a and b say, the corresponding lane elements from a and b are operated on
* using the specified scalar binary operation and the element result is placed
* into the vector result at the same lane.
! * The following pseudocode expresses the behaviour of this operation category:
*
* <pre>{@code
! * EVector<S> a = ...;
! * EVector<S> 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));
* }
! * EVector<S> r = a.species().fromArray(ar, 0);
* }</pre>
*
* Unless otherwise specified the two input and result vectors will have the
* same element type and shape.
*
* <li>
! * Generalizing from unary (1-ary) and binary (2-ary) operations, a vector n-ary
! * operation operates in n input vectors to produce a
! * result vector.
* N lane elements from each input vector are operated on
* using the specified n-ary scalar operation and the element result is placed
* into the vector result at the same lane.
* Unless otherwise specified the n input and result vectors will have the same
* element type and shape.
*
* <li>
! * A vector reduction operation operates on all the lane
* elements of an input vector.
* An accumulation function is applied to all the
* lane elements to produce a scalar result.
* If the reduction operation is associative then the result may be accumulated
* by operating on the lane elements in any order using a specified associative
* scalar binary operation and identity value. Otherwise, the reduction
! * operation specifies the behaviour of the accumulation function.
! * The following pseudocode expresses the behaviour of this operation category
* if it is associative:
* <pre>{@code
! * EVector<S> a = ...;
* e r = <identity value>;
* for (int i = 0; i < a.length(); i++) {
* r = assoc_scalar_binary_op(r, a.get(i));
* }
* }</pre>
*
* Unless otherwise specified the scalar result type and element type will be
* the same.
*
* <li>
! * A vector binary test operation operates on two input vectors to produce a
* result mask. For each lane of the two input vectors, a and b say, the
* the corresponding lane elements from a and b are operated on using the
* specified scalar binary test operation and the boolean result is placed
* into the mask at the same lane.
! * The following pseudocode expresses the behaviour of this operation category:
* <pre>{@code
! * EVector<S> a = ...;
! * EVector<S> 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));
* }
! * VectorMask<E> r = a.species().maskFromArray(ar, 0);
* }</pre>
*
* Unless otherwise specified the two input vectors and result mask will have
* the same element type and shape.
*
--- 71,188 ----
* element types (such as addition). Sub-classes of Vector with a concrete
* boxed element type declare further operations that are specific to that
* element type (such as access to element values in lanes, logical operations
* on values of integral elements types, or transcendental operations on values
* of floating point element types).
! * There are six abstract sub-classes of Vector corresponding to the supported set
* of element types, {@link ByteVector}, {@link ShortVector},
* {@link IntVector} {@link LongVector}, {@link FloatVector}, and
! * {@link DoubleVector}. Along with type-specific operations these classes
! * support creation of vector values (instances of Vector).
! * They expose static constants corresponding to the supported species,
! * and static methods on these types generally take a species as a parameter.
! * For example,
! * {@link jdk.incubator.vector.FloatVector#fromArray(VectorSpecies, float[], int) FloatVector.fromArray()}
! * creates and returns a float vector of the specified species, with elements
! * loaded from the specified float array.
* <p>
! * 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>
! * Vector operations can be grouped into various categories and their behavior
* generally specified as follows:
* <ul>
* <li>
! * A lane-wise unary operation operates on one input vector and produces a
* result vector.
* For each lane of the input vector the
* lane element is operated on using the specified scalar unary operation and
* the element result is placed into the vector result at the same lane.
! * The following pseudocode expresses the behavior of this operation category,
* where {@code e} is the element type and {@code EVector} corresponds to the
* primitive Vector type:
*
* <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));
* }
! * EVector r = EVector.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the input and result vectors will have the same
* element type and shape.
*
* <li>
! * A lane-wise binary operation operates on two input
! * vectors and produces a result vector.
! * For each lane of the two input vectors a and b,
! * the corresponding lane elements from a and b are operated on
* using the specified scalar binary operation and the element result is placed
* into the vector result at the same lane.
! * The following pseudocode expresses the behavior of this operation category:
*
* <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));
* }
! * EVector r = EVector.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the two input and result vectors will have the
* same element type and shape.
*
* <li>
! * Generalizing from unary and binary operations, a lane-wise n-ary
! * operation operates on n input vectors and produces a result vector.
* N lane elements from each input vector are operated on
* using the specified n-ary scalar operation and the element result is placed
* into the vector result at the same lane.
* Unless otherwise specified the n input and result vectors will have the same
* element type and shape.
*
* <li>
! * A cross-lane vector reduction operation operates on all the lane
* elements of an input vector.
* An accumulation function is applied to all the
* lane elements to produce a scalar result.
* If the reduction operation is associative then the result may be accumulated
* by operating on the lane elements in any order using a specified associative
* scalar binary operation and identity value. Otherwise, the reduction
! * operation specifies the behavior of the accumulation function.
! * The following pseudocode expresses the behavior of this operation category
* 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));
* }
* }</pre>
*
* Unless otherwise specified the scalar result type and element type will be
* the same.
*
* <li>
! * A lane-wise binary test operation operates on two input vectors and produces a
* result mask. For each lane of the two input vectors, a and b say, the
* the corresponding lane elements from a and b are operated on using the
* specified scalar binary test operation and the boolean result is placed
* into the mask at the same lane.
! * The following pseudocode expresses the behavior of this operation category:
* <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));
* }
! * VectorMask r = VectorMask.fromArray(a.species(), ar, 0);
* }</pre>
*
* Unless otherwise specified the two input vectors and result mask will have
* the same element type and shape.
*
*** 193,253 ****
* the scalar operation is applied to elements taken from input vectors at the
* same lane, and if appropriate applied to the result vector at the same lane.
* A further category of operation is a cross-lane vector operation where lane
* access is defined by the arguments to the operation. Cross-lane operations
* generally rearrange lane elements, for example by permutation (commonly
! * controlled by a {@link VectorShuffle}) or by blending (commonly controlled by a
! * {@link VectorMask}). Such an operation explicitly specifies how it rearranges lane
* elements.
* </ul>
*
- * If a vector operation is represented as an instance method then first input
- * vector corresponds to {@code this} vector and subsequent input vectors are
- * arguments of the method. Otherwise, if the an operation is represented as a
- * static method then all input vectors are arguments of the method.
* <p>
* If a vector operation does not belong to one of the above categories then
* the operation explicitly specifies how it processes the lane elements of
! * input vectors, and where appropriate expresses the behaviour using
* pseudocode.
*
* <p>
* Many vector operations provide an additional {@link VectorMask mask} accepting
* variant.
* The mask controls which lanes are selected for application of the scalar
* operation. Masks are a key component for the support of control flow in
* vector computations.
* <p>
* For certain operation categories the mask accepting variants can be specified
* in generic terms. If a lane of the mask is set then the scalar operation is
* applied to corresponding lane elements, otherwise if a lane of a mask is not
* set then a default scalar operation is applied and its result is placed into
! * the vector result at the same lane. The default operation is specified for
! * the following operation categories:
* <ul>
* <li>
! * For a vector n-ary operation the default operation is a function that returns
! * it's first argument, specifically a lane element of the first input vector.
* <li>
* For an associative vector reduction operation the default operation is a
* function that returns the identity value.
* <li>
! * For vector binary test operation the default operation is a function that
* returns false.
! *</ul>
* Otherwise, the mask accepting variant of the operation explicitly specifies
* how it processes the lane elements of input vectors, and where appropriate
! * expresses the behaviour using pseudocode.
*
* <p>
! * For convenience many vector operations, of arity greater than one, provide
! * an additional scalar accepting variant. This variant accepts compatible
* scalar values instead of vectors for the second and subsequent input vectors,
* if any.
* Unless otherwise specified the scalar variant behaves as if each scalar value
! * is transformed to a vector using the vector species
! * {@code broadcast} operation, and
* then the vector accepting vector operation is applied using the transformed
* values.
*
* <p>
* This is a value-based
--- 192,253 ----
* the scalar operation is applied to elements taken from input vectors at the
* same lane, and if appropriate applied to the result vector at the same lane.
* A further category of operation is a cross-lane vector operation where lane
* access is defined by the arguments to the operation. Cross-lane operations
* generally rearrange lane elements, for example by permutation (commonly
! * controlled by a {@link jdk.incubator.vector.VectorShuffle}) or by blending (commonly controlled by a
! * {@link jdk.incubator.vector.VectorMask}). Such an operation explicitly specifies how it rearranges lane
* elements.
* </ul>
*
* <p>
* If a vector operation does not belong to one of the above categories then
* the operation explicitly specifies how it processes the lane elements of
! * input vectors, and where appropriate expresses the behavior using
* pseudocode.
*
* <p>
* Many vector operations provide an additional {@link VectorMask mask} accepting
* variant.
* The mask controls which lanes are selected for application of the scalar
* operation. Masks are a key component for the support of control flow in
* vector computations.
* <p>
+ * Many vector operations provide an additional {@link jdk.incubator.vector.VectorMask mask}-accepting
+ * variant.
+ * The mask controls which lanes are selected for application of the scalar
+ * operation. Masks are a key component for the support of control flow in
+ * vector computations.
+ * <p>
* For certain operation categories the mask accepting variants can be specified
* in generic terms. If a lane of the mask is set then the scalar operation is
* applied to corresponding lane elements, otherwise if a lane of a mask is not
* set then a default scalar operation is applied and its result is placed into
! * the vector result at the same lane. The default operation is specified as follows:
* <ul>
* <li>
! * For a lane-wise n-ary operation the default operation is a function that returns
! * it's first argument, specifically the lane element of the first input vector.
* <li>
* For an associative vector reduction operation the default operation is a
* function that returns the identity value.
* <li>
! * For lane-wise binary test operation the default operation is a function that
* returns false.
! * </ul>
* Otherwise, the mask accepting variant of the operation explicitly specifies
* how it processes the lane elements of input vectors, and where appropriate
! * expresses the behavior using pseudocode.
*
* <p>
! * For convenience, many vector operations of arity greater than one provide
! * an additional scalar-accepting variant (such as adding a constant scalar
! * value to all lanes of a vector). This variant accepts compatible
* scalar values instead of vectors for the second and subsequent input vectors,
* if any.
* Unless otherwise specified the scalar variant behaves as if each scalar value
! * is transformed to a vector using the appropriate vector {@code broadcast} operation, and
* then the vector accepting vector operation is applied using the transformed
* values.
*
* <p>
* This is a value-based
*** 306,399 ****
//Arithmetic
/**
* Adds this vector to an input vector.
* <p>
! * This is a vector binary operation where the primitive addition operation
! * ({@code +}) is applied to lane elements.
*
* @param v the input vector
* @return the result of adding this vector to the input vector
*/
public abstract Vector<E> add(Vector<E> v);
/**
* Adds this vector to an input vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a vector binary operation where the primitive addition operation
! * ({@code +}) is applied to lane elements.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of adding this vector to the given vector
*/
public abstract Vector<E> add(Vector<E> v, VectorMask<E> m);
/**
* Subtracts an input vector from this vector.
* <p>
! * This is a vector binary operation where the primitive subtraction
! * operation ({@code -}) is applied to lane elements.
*
* @param v the input vector
* @return the result of subtracting the input vector from this vector
*/
public abstract Vector<E> sub(Vector<E> v);
/**
* Subtracts an input vector from this vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a vector binary operation where the primitive subtraction
! * operation ({@code -}) is applied to lane elements.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of subtracting the input vector from this vector
*/
public abstract Vector<E> sub(Vector<E> v, VectorMask<E> m);
/**
* Multiplies this vector with an input vector.
* <p>
! * This is a vector binary operation where the primitive multiplication
! * operation ({@code *}) is applied to lane elements.
*
* @param v the input vector
* @return the result of multiplying this vector with the input vector
*/
public abstract Vector<E> mul(Vector<E> v);
/**
* Multiplies this vector with an input vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a vector binary operation where the primitive multiplication
! * operation ({@code *}) is applied to lane elements.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of multiplying this vector with the input vector
*/
public abstract Vector<E> mul(Vector<E> v, VectorMask<E> m);
/**
* Negates this vector.
* <p>
! * This is a vector unary operation where the primitive negation operation
! * ({@code -}) is applied to lane elements.
*
* @return the negation this vector
*/
public abstract Vector<E> neg();
/**
* Negates this vector, selecting lane elements controlled by a mask.
* <p>
! * This is a vector unary operation where the primitive negation operation
! * ({@code -})is applied to lane elements.
*
* @param m the mask controlling lane selection
* @return the negation this vector
*/
public abstract Vector<E> neg(VectorMask<E> m);
--- 306,399 ----
//Arithmetic
/**
* Adds this vector to an input vector.
* <p>
! * This is a lane-wise binary operation which applies the primitive addition operation
! * ({@code +}) to each lane.
*
* @param v the input vector
* @return the result of adding this vector to the input vector
*/
public abstract Vector<E> add(Vector<E> v);
/**
* Adds this vector to an input vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a lane-wise binary operation which applies the primitive addition operation
! * ({@code +}) to each lane.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of adding this vector to the given vector
*/
public abstract Vector<E> add(Vector<E> v, VectorMask<E> m);
/**
* Subtracts an input vector from this vector.
* <p>
! * This is a lane-wise binary operation which applies the primitive subtraction
! * operation ({@code -}) to each lane.
*
* @param v the input vector
* @return the result of subtracting the input vector from this vector
*/
public abstract Vector<E> sub(Vector<E> v);
/**
* Subtracts an input vector from this vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a lane-wise binary operation which applies the primitive subtraction
! * operation ({@code -}) to each lane.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of subtracting the input vector from this vector
*/
public abstract Vector<E> sub(Vector<E> v, VectorMask<E> m);
/**
* Multiplies this vector with an input vector.
* <p>
! * This is a lane-wise binary operation which applies the primitive multiplication
! * operation ({@code *}) to each lane.
*
* @param v the input vector
* @return the result of multiplying this vector with the input vector
*/
public abstract Vector<E> mul(Vector<E> v);
/**
* Multiplies this vector with an input vector, selecting lane elements
* controlled by a mask.
* <p>
! * This is a lane-wise binary operation which applies the primitive multiplication
! * operation ({@code *}) to each lane.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of multiplying this vector with the input vector
*/
public abstract Vector<E> mul(Vector<E> v, VectorMask<E> m);
/**
* Negates this vector.
* <p>
! * This is a lane-wise unary operation which applies the primitive negation operation
! * ({@code -}) to each lane.
*
* @return the negation this vector
*/
public abstract Vector<E> neg();
/**
* 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.
*
* @param m the mask controlling lane selection
* @return the negation this vector
*/
public abstract Vector<E> neg(VectorMask<E> m);
*** 401,470 ****
// Maths from java.math
/**
* Returns the modulus of this vector.
* <p>
! * This is a vector unary operation where the operation
! * {@code (a) -> (a < 0) ? -a : a} is applied to lane elements.
*
* @return the modulus this vector
*/
public abstract Vector<E> abs();
/**
* Returns the modulus of this vector, selecting lane elements controlled by
* a mask.
* <p>
! * This is a vector unary operation where the operation
! * {@code (a) -> (a < 0) ? -a : a} is applied to lane elements.
*
* @param m the mask controlling lane selection
* @return the modulus this vector
*/
public abstract Vector<E> abs(VectorMask<E> m);
/**
* Returns the minimum of this vector and an input vector.
* <p>
! * This is a vector binary operation where the operation
! * {@code (a, b) -> a < b ? a : b} is applied to lane elements.
*
* @param v the input vector
* @return the minimum of this vector and the input vector
*/
public abstract Vector<E> min(Vector<E> v);
/**
* Returns the minimum of this vector and an input vector,
* selecting lane elements controlled by a mask.
* <p>
! * This is a vector binary operation where the operation
! * {@code (a, b) -> a < b ? a : b} is applied to lane elements.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the minimum of this vector and the input vector
*/
public abstract Vector<E> min(Vector<E> v, VectorMask<E> m);
/**
* Returns the maximum of this vector and an input vector.
* <p>
! * This is a vector binary operation where the operation
! * {@code (a, b) -> a > b ? a : b} is applied to lane elements.
*
* @param v the input vector
* @return the maximum of this vector and the input vector
*/
public abstract Vector<E> max(Vector<E> v);
/**
* Returns the maximum of this vector and an input vector,
* selecting lane elements controlled by a mask.
* <p>
! * This is a vector binary operation where the operation
! * {@code (a, b) -> a > b ? a : b} is applied to lane elements.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the maximum of this vector and the input vector
*/
--- 401,470 ----
// Maths from java.math
/**
* Returns the modulus of this vector.
* <p>
! * This is a lane-wise unary operation which applies the operation
! * {@code (a) -> (a < 0) ? -a : a} to each lane.
*
* @return the modulus this vector
*/
public abstract Vector<E> abs();
/**
* Returns the modulus of this vector, selecting lane elements controlled by
* a mask.
* <p>
! * This is a lane-wise unary operation which applies the operation
! * {@code (a) -> (a < 0) ? -a : a} to each lane.
*
* @param m the mask controlling lane selection
* @return the modulus this vector
*/
public abstract Vector<E> abs(VectorMask<E> m);
/**
* Returns the minimum of this vector and an input vector.
* <p>
! * This is a lane-wise binary operation which applies the operation
! * {@code (a, b) -> a < b ? a : b} to each lane.
*
* @param v the input vector
* @return the minimum of this vector and the input vector
*/
public abstract Vector<E> min(Vector<E> v);
/**
* Returns the minimum of this vector and an input vector,
* selecting lane elements controlled by a mask.
* <p>
! * This is a lane-wise binary operation which applies the operation
! * {@code (a, b) -> a < b ? a : b} to each lane.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the minimum of this vector and the input vector
*/
public abstract Vector<E> min(Vector<E> v, VectorMask<E> m);
/**
* Returns the maximum of this vector and an input vector.
* <p>
! * This is a lane-wise binary operation which applies the operation
! * {@code (a, b) -> a > b ? a : b} to each lane.
*
* @param v the input vector
* @return the maximum of this vector and the input vector
*/
public abstract Vector<E> max(Vector<E> v);
/**
* Returns the maximum of this vector and an input vector,
* selecting lane elements controlled by a mask.
* <p>
! * This is a lane-wise binary operation which applies the operation
! * {@code (a, b) -> a > b ? a : b} to each lane.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the maximum of this vector and the input vector
*/
*** 473,544 ****
// Comparisons
/**
* Tests if this vector is equal to an input vector.
* <p>
! * This is a vector binary test operation where the primitive equals
! * operation ({@code ==}) is applied to lane elements.
*
* @param v the input vector
* @return the result mask of testing if this vector is equal to the input
* vector
*/
public abstract VectorMask<E> equal(Vector<E> v);
/**
* Tests if this vector is not equal to an input vector.
* <p>
! * This is a vector binary test operation where the primitive not equals
! * operation ({@code !=}) is applied to lane elements.
*
* @param v the input vector
* @return the result mask of testing if this vector is not equal to the
* input vector
*/
public abstract VectorMask<E> notEqual(Vector<E> v);
/**
* Tests if this vector is less than an input vector.
* <p>
! * This is a vector binary test operation where the primitive less than
! * operation ({@code <}) is applied to lane elements.
*
* @param v the input vector
* @return the mask result of testing if this vector is less than the input
* vector
*/
public abstract VectorMask<E> lessThan(Vector<E> v);
/**
* Tests if this vector is less or equal to an input vector.
* <p>
! * This is a vector binary test operation where the primitive less than
! * or equal to operation ({@code <=}) is applied to lane elements.
*
* @param v the input vector
* @return the mask result of testing if this vector is less than or equal
* to the input vector
*/
public abstract VectorMask<E> lessThanEq(Vector<E> v);
/**
* Tests if this vector is greater than an input vector.
* <p>
! * This is a vector binary test operation where the primitive greater than
! * operation ({@code >}) is applied to lane elements.
*
* @param v the input vector
* @return the mask result of testing if this vector is greater than the
* input vector
*/
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 vector binary test operation where the primitive greater than
! * or equal to operation ({@code >=}) is applied to lane elements.
*
* @param v the input vector
* @return the mask result of testing if this vector is greater than or
* equal to the given vector
*/
--- 473,544 ----
// Comparisons
/**
* Tests if this vector is equal to an input vector.
* <p>
! * This is a lane-wise binary test operation where 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
*/
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
! * 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
*/
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
! * 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
*/
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
! * 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
*/
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
! * 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
*/
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
! * 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
*/
*** 551,562 ****
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* vector.
* For each lane of the input vector, at lane index {@code N}, the lane
! * element is placed into to the result vector at lane index
! * {@code (i + N) % this.length()}.
*
* @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
*/
--- 551,562 ----
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* 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 + i) % length()}.
*
* @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
*/
*** 565,576 ****
/**
* Rotates right the lane elements of this vector by the given number of
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
! * vector and behaves as if rotating left the lane elements by
! * {@code this.length() - (i % this.length())} lanes.
*
* @param i the number of lanes to rotate left
* @return the result of rotating right lane elements of this vector by the
* given number of lanes
*/
--- 565,578 ----
/**
* Rotates right the lane elements of this vector by the given number of
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
! * 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
* @return the result of rotating right lane elements of this vector by the
* given number of lanes
*/
*** 581,591 ****
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* vector and behaves as if rotating left the lane elements by {@code i},
* and then the zero value is placed into the result vector at lane indexes
! * less than {@code i % this.length()}.
*
* @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}.
--- 583,593 ----
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* vector and behaves as if rotating left the lane elements by {@code i},
* and then the zero value is placed into the result vector at lane indexes
! * less than {@code i % length()}.
*
* @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}.
*** 597,610 ****
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* vector and behaves as if rotating right the lane elements by {@code i},
* and then the zero value is placed into the result vector at lane indexes
! * greater or equal to {@code this.length() - (i % this.length())}.
*
! * @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> shiftER(int i);
--- 599,612 ----
* lanes, {@code i}, modulus the vector length.
* <p>
* This is a cross-lane operation that permutes the lane elements of this
* vector and behaves as if rotating right the lane elements by {@code i},
* and then the zero value is placed into the result vector at lane indexes
! * greater or equal to {@code length() - (i % length())}.
*
! * @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);
*** 613,623 ****
* selecting lanes controlled by a mask.
* <p>
* For each lane of the mask, at lane index {@code N}, if the mask lane
* is set then the lane element at {@code N} from the input vector is
* selected and placed into the resulting vector at {@code N},
! * otherwise the the lane element at {@code N} from this input vector is
* selected and placed into the resulting vector at {@code N}.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of blending the lane elements of this vector with
--- 615,625 ----
* selecting lanes controlled by a mask.
* <p>
* For each lane of the mask, at lane index {@code N}, if the mask lane
* is set then the lane element at {@code N} from the input vector is
* selected and placed into the resulting vector at {@code N},
! * otherwise the lane element at {@code N} from this input vector is
* selected and placed into the resulting vector at {@code N}.
*
* @param v the input vector
* @param m the mask controlling lane selection
* @return the result of blending the lane elements of this vector with
*** 710,720 ****
* byte array with values {0,1,2,3} and reshaping to int, leads to bytes
* being composed in order 0x3 0x2 0x1 0x0 which is decimal value 50462976.
* 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 behaviour:
* <pre>{@code
* int blen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
* ByteBuffer bb = ByteBuffer.allocate(blen).order(ByteOrder.nativeOrder());
* this.intoByteBuffer(bb, 0);
* return $type$Vector.fromByteBuffer(s, bb, 0);
--- 712,722 ----
* byte array with values {0,1,2,3} and reshaping to int, leads to bytes
* being composed in order 0x3 0x2 0x1 0x0 which is decimal value 50462976.
* 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());
* this.intoByteBuffer(bb, 0);
* return $type$Vector.fromByteBuffer(s, bb, 0);
*** 761,771 ****
* vector's length, or appended to with default element values if this
* vector's length is less than desired vector's length.
* <p>
* The method behaves as if this vector is stored into a byte array
* and then the returned vector is loaded from the byte array.
! * The following pseudocode expresses the behaviour:
* <pre>{@code
* int alen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
* byte[] a = new byte[alen];
* this.intoByteArray(a, 0);
* return $type$Vector.fromByteArray(s, a, 0);
--- 763,773 ----
* vector's length, or appended to with default element values if this
* vector's length is less than desired vector's length.
* <p>
* The method behaves as if this vector is stored into a byte array
* and then the returned vector is loaded from the byte array.
! * The following pseudocode expresses the behavior:
* <pre>{@code
* int alen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
* byte[] a = new byte[alen];
* this.intoByteArray(a, 0);
* return $type$Vector.fromByteArray(s, a, 0);
*** 875,893 ****
* This method behaves as if the byte buffer is viewed as a primitive
* {@link java.nio.Buffer buffer} for the primitive element type,
* according to the native byte order of the underlying platform, and
* the lane elements of this vector are put into the buffer if the
* corresponding mask lane is set.
! * The following pseudocode expresses the behaviour, where
* {@coce EBuffer} is the primitive buffer type, {@code e} is the
! * primitive element type, and {@code EVector<S>} is the primitive
* vector type for this vector:
* <pre>{@code
* EBuffer eb = b.duplicate().
* order(ByteOrder.nativeOrder()).position(i).
* asEBuffer();
! * e[] es = ((EVector<S>)this).toArray();
* for (int n = 0; n < t.length; n++) {
* if (m.isSet(n)) {
* eb.put(n, es[n]);
* }
* }
--- 877,895 ----
* This method behaves as if the byte buffer is viewed as a primitive
* {@link java.nio.Buffer buffer} for the primitive element type,
* according to the native byte order of the underlying platform, and
* the lane elements of this vector are put into the buffer if the
* corresponding mask lane is set.
! * The following pseudocode expresses the behavior, where
* {@coce EBuffer} is the primitive buffer type, {@code e} is the
! * primitive element type, and {@code EVector} is the primitive
* vector type for this vector:
* <pre>{@code
* EBuffer eb = b.duplicate().
* order(ByteOrder.nativeOrder()).position(i).
* asEBuffer();
! * e[] es = ((EVector)this).toArray();
* for (int n = 0; n < t.length; n++) {
* if (m.isSet(n)) {
* eb.put(n, es[n]);
* }
* }
< prev index next >