< prev index next >
src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java
Print this page
*** 136,146 ****
* 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,
* 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>,
--- 136,146 ----
* 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 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,183 ****
* <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
* 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.
*
--- 173,183 ----
* <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, {@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,218 ****
* 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
* 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
* 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)
--- 201,216 ----
* 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> 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 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,315 ****
* <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
* 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.
--- 303,313 ----
* <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 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,360 ****
* 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}:
*
* <pre>{@code
* IntVector a = ...;
* int VLENGTH = a.length();
* VectorShape VSHAPE = a.shape();
--- 348,358 ----
* 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}, retaining lower lanes to maintain shape-invariance:
*
* <pre>{@code
* IntVector a = ...;
* int VLENGTH = a.length();
* VectorShape VSHAPE = a.shape();
*** 423,433 ****
* 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
* 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
--- 421,431 ----
* 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
* 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,491 ****
* 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
* 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
--- 479,489 ----
* 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
* 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,704 ****
* 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
* (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.
*
--- 692,702 ----
* 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 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,742 ****
* 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)}
* 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,
*
--- 730,740 ----
* 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=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,1166 ****
/// Arithmetic
/**
* Operates on the lane values of this vector.
*
! * This is a lane-wise binary operation which applies
* the selected operation to each lane.
*
* <p>FIXME: Write about the unary operators here.
*
* @apiNote
--- 1154,1164 ----
/// Arithmetic
/**
* Operates on the lane values of this vector.
*
! * 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,1189 ****
*
* @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.Binary,Vector)
! * @see #lanewise(VectorOperators.Ternary,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
* the selected operation to each lane.
*
* @apiNote
* Subtypes improve on this method by sharpening
* the method return type.
--- 1167,1187 ----
*
* @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,VectorMask)
* @see #lanewise(VectorOperators.Binary,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 unary operation which applies
* the selected operation to each lane.
*
* @apiNote
* Subtypes improve on this method by sharpening
* the method return type.
*** 1191,1201 ****
* @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)
*/
public abstract Vector<E> lanewise(VectorOperators.Unary op,
VectorMask<E> m);
/**
--- 1189,1199 ----
* @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)
*/
public abstract Vector<E> lanewise(VectorOperators.Unary op,
VectorMask<E> m);
/**
*** 1221,1232 ****
* @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)
*/
public abstract Vector<E> lanewise(VectorOperators.Binary op,
Vector<E> v);
/**
--- 1219,1230 ----
* @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)
! * @see #lanewise(VectorOperators.Ternary,Vector, Vector)
*/
public abstract Vector<E> lanewise(VectorOperators.Binary op,
Vector<E> v);
/**
*** 1341,1351 ****
* @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.Binary,Vector)
* @see #lanewise(VectorOperators.Ternary,Vector,Vector,VectorMask)
*/
public abstract Vector<E> lanewise(VectorOperators.Ternary op,
Vector<E> v1,
--- 1339,1349 ----
* @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)
* @see #lanewise(VectorOperators.Binary,Vector)
* @see #lanewise(VectorOperators.Ternary,Vector,Vector,VectorMask)
*/
public abstract Vector<E> lanewise(VectorOperators.Ternary op,
Vector<E> v1,
*** 1671,1694 ****
* 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)
* lanewise}{@code (}{@link VectorOperators#NEG
! * MIN}{@code)}.
*
* @apiNote
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
! * {@linkplain #lanewise(VectorOperators.Unary,Vector,VectorMask)
* lanewise method}.
*
* @return the negation of this vector
* @see VectorOperators#NEG
! * @see #lanewise(VectorOperators.Unary,Vector)
! * @see #lanewise(VectorOperators.Unary,Vector,VectorMask)
*/
public abstract Vector<E> neg();
/**
* Returns the absolute value of this vector.
--- 1669,1692 ----
* 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)
* lanewise}{@code (}{@link VectorOperators#NEG
! * NEG}{@code)}.
*
* @apiNote
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
! * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
* lanewise method}.
*
* @return the negation of this vector
* @see VectorOperators#NEG
! * @see #lanewise(VectorOperators.Unary)
! * @see #lanewise(VectorOperators.Unary,VectorMask)
*/
public abstract Vector<E> neg();
/**
* Returns the absolute value of this vector.
*** 1696,1719 ****
* 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)
* lanewise}{@code (}{@link VectorOperators#ABS
! * MIN}{@code)}.
*
! * <p>
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
! * {@linkplain #lanewise(VectorOperators.Unary,Vector,VectorMask)
* lanewise method}.
*
* @return the absolute value of this vector
* @see VectorOperators#ABS
! * @see #lanewise(VectorOperators.Unary,Vector)
! * @see #lanewise(VectorOperators.Unary,Vector,VectorMask)
*/
public abstract Vector<E> abs();
/// Non-full-service binary ops: MIN, MAX
--- 1694,1717 ----
* 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)
* lanewise}{@code (}{@link VectorOperators#ABS
! * ABS}{@code)}.
*
! * @apiNote
* This method has no masked variant, but the corresponding
* masked operation can be obtained from the
! * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
* lanewise method}.
*
* @return the absolute value of this vector
* @see VectorOperators#ABS
! * @see #lanewise(VectorOperators.Unary)
! * @see #lanewise(VectorOperators.Unary,VectorMask)
*/
public abstract Vector<E> abs();
/// Non-full-service binary ops: MIN, MAX
*** 1727,1737 ****
* This method is also equivalent to the expression
* {@link #lanewise(VectorOperators.Binary,Vector)
* lanewise}{@code (}{@link VectorOperators#MIN
* MIN}{@code , v)}.
*
! * <p>
* 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
--- 1725,1735 ----
* This method is also equivalent to the expression
* {@link #lanewise(VectorOperators.Binary,Vector)
* lanewise}{@code (}{@link VectorOperators#MIN
* MIN}{@code , v)}.
*
! * @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,1856 ****
* 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}.
* <li>
* If the operation is {@code MIN},
! * 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}.
* </ul>
*
* @apiNote
* If the {@code ETYPE} is {@code float} or {@code double},
--- 1838,1854 ----
* 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.MIN_VALUE}.
* <li>
* If the operation is {@code MIN},
! * 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 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,1938 ****
*
* @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 VectorOperators.Comparison
* @see #compare(VectorOperators.Comparison, Vector, VectorMask)
*/
public abstract VectorMask<E> compare(VectorOperators.Comparison op,
Vector<E> v);
--- 1925,1936 ----
*
* @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 #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,2180 ****
* respectively.
*
* @apiNote
*
* This method may be regarded as the inverse of
! * {@code #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
--- 2168,2178 ----
* respectively.
*
* @apiNote
*
* This method may be regarded as the inverse of
! * {@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,2482 ****
* 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
* source indexes in the shuffle
* @see #rearrange(VectorShuffle,VectorMask)
* @see #rearrange(VectorShuffle,Vector)
* @see VectorShuffle#laneIsValid()
*/
--- 2470,2480 ----
* 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
! * @throws IndexOutOfBoundsException if there are any exceptional
* source indexes in the shuffle
* @see #rearrange(VectorShuffle,VectorMask)
* @see #rearrange(VectorShuffle,Vector)
* @see VectorShuffle#laneIsValid()
*/
*** 2496,2512 ****
* 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());
* }</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
* source indexes in the shuffle where the mask is set
* @see #rearrange(VectorShuffle)
* @see #rearrange(VectorShuffle,Vector)
* @see VectorShuffle#laneIsValid()
*/
--- 2494,2512 ----
* 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());
! * 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
! * @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,2750 ****
* 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.
*
* @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
--- 2740,2750 ----
* 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-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,2778 ****
* 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 VectorSpecies#withLanes(Class)
*/
public abstract ByteVector reinterpretAsBytes();
/**
--- 2767,2778 ----
* 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 IntVector#intoByteArray(byte[], int)
! * @see FloatVector#intoByteArray(byte[], int)
* @see VectorSpecies#withLanes(Class)
*/
public abstract ByteVector reinterpretAsBytes();
/**
*** 2849,2859 ****
* {@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 VectorOperators.Conversion.ofReinterpret(E.class,F.class)},
* and {@code F} is the non-floating-point type of the
* same size as {@code E}.
*
* @apiNote
--- 2849,2859 ----
* {@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,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,2888 ****
*
* 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 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
--- 2878,2888 ----
*
* 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,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,2958 ****
* 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
* 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).
--- 2948,2958 ----
* 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 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,3054 ****
* {@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 #convertShape(VectorOperators.Conversion,VectorSpecies,int)
* @see #reinterpretShape(VectorSpecies,int)
*/
public abstract <F> Vector<F> convert(VectorOperators.Conversion<E,F> conv, int part);
--- 3043,3054 ----
* {@code part} is negative and greater {@code -M}
*
* @see VectorOperators#I2L
* @see VectorOperators.Conversion#ofCast(Class,Class)
* @see VectorSpecies#partLimit(VectorSpecies,boolean)
! * @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 >