- Type Parameters:
- E- the boxed version of- ETYPE, the element type of a vector
- Direct Known Subclasses:
- ByteVector,- DoubleVector,- FloatVector,- IntVector,- LongVector,- ShortVector
Vector relies on preview features of the Java platform:
- Vectorrefers to one or more preview APIs:- MemorySegment.
byte, long, or float.
 Each lane contains an independent value of the element type.
 Operations on vectors are typically
 lane-wise,
 distributing some scalar operator (such as
 addition)
 across the lanes of the participating vectors,
 usually generating a vector result whose lanes contain the various
 scalar results.  When run on a supporting platform, lane-wise
 operations can be executed in parallel by the hardware.  This style
 of parallelism is called Single Instruction Multiple Data
 (SIMD) parallelism.
  In the SIMD style of programming, most of the operations within
 a vector lane are unconditional, but the effect of conditional
 execution may be achieved using
 masked operations
 such as blend(),
 under the control of an associated VectorMask.
 Data motion other than strictly lane-wise flow is achieved using
 cross-lane
 operations, often under the control of an associated
 VectorShuffle.
 Lane data and/or whole vectors can be reformatted using various
 kinds of lane-wise
 conversions,
 and byte-wise reformatting
 reinterpretations,
 often under the control of a reflective VectorSpecies
 object which selects an alternative vector format different
 from that of the input vector.
 
 Vector<E> declares a set of vector operations (methods)
 that are common to all element types.  These common operations
 include generic access to lane values, data selection and movement,
 reformatting, and certain arithmetic and logical operations (such as addition
 or comparison) that are common to all primitive types.
 
 Public subtypes of Vector
 correspond to specific
 element types.  These declare further operations that are specific
 to that element type, including unboxed access to lane values,
 bitwise operations on values of integral element types, or
 transcendental operations on values of floating point element
 types.
 
 Some lane-wise operations, such as the add operator, are defined as
 a full-service named operation, where a corresponding method on Vector
 comes in masked and unmasked overloadings, and (in subclasses) also comes in
 covariant overrides (returning the subclass) and additional scalar-broadcast
 overloadings (both masked and unmasked).
 Other lane-wise operations, such as the min operator, are defined as a
 partially serviced (not a full-service) named operation, where a corresponding
 method on Vector and/or a subclass provide some but all possible
 overloadings and overrides (commonly the unmasked variant with scalar-broadcast
 overloadings).
 Finally, all lane-wise operations (those named as previously described,
 or otherwise unnamed method-wise) have a corresponding
 operator token
 declared as a static constant on VectorOperators.
 Each operator token defines a symbolic Java expression for the operation,
 such as a + b for the
 ADD operator token.
 General lane-wise operation-token accepting methods, such as for a
 unary lane-wise
 operation, are provided on Vector and come in the same variants as
 a full-service named operation.
 
This package contains a public subtype of Vector
 corresponding to each supported element type:
 ByteVector, ShortVector,
 IntVector, LongVector,
 FloatVector, and DoubleVector.
 
 
 The element type of a vector,
 referred to as ETYPE, is one of the primitive types
 byte, short, int, long, 
 float, or double.
 
 The type E in Vector<E> is the boxed version
 of ETYPE. For example, in the type Vector<Integer>, the E
 parameter is Integer and the ETYPE is int.  In such a
 vector, each lane carries a primitive int value.  This pattern continues
 for the other primitive types as well. (See also sections 5.1.7 and
 5.1.8 of the The Java Language Specification.)
 
 The length of a vector
 is the lane count, the number of lanes it contains.
 This number is also called VLENGTH when the context makes
 clear which vector it belongs to.  Each vector has its own fixed
 VLENGTH but different instances of vectors may have
 different lengths.  VLENGTH is an important number, because
 it estimates the SIMD performance gain of a single vector operation
 as compared to scalar execution of the VLENGTH scalar
 operators which underly the vector operation.
 
Shapes and species
The information capacity of a vector is determined by its vector shape, also called itsVSHAPE.  Each possible VSHAPE is represented by
 a member of the VectorShape enumeration, and represents
 an implementation format shared in common by all vectors of
 that shape.  Thus, the size in bits of
 of a vector is determined by appealing to its vector shape.
 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 shape-changing, while the majority of operations are shape-invariant, to avoid disadvantaging platforms which support only one shape. There are queries to discover, for the current Java platform, the preferred shape for general SIMD computation, or the largest available shape for any given lane type. To be portable, code using this API should start by querying a supported shape, and then process all data with shape-invariant operations, within the selected shape.
 Each unique combination of element type and vector shape
 determines a unique
 vector species.
 A vector species is represented by a fixed instance of
 VectorSpecies<E>
 shared in common by all vectors of the same shape and
 ETYPE.
 
 Unless otherwise documented, lane-wise vector operations
 require that all vector inputs have exactly the same VSHAPE
 and VLENGTH, which is to say that they must have exactly
 the same species.  This allows corresponding lanes to be paired
 unambiguously.  The check() method
 provides an easy way to perform this check explicitly.
 
 Vector shape, VLENGTH, and ETYPE are all
 mutually constrained, so that VLENGTH times the
 bit-size of each lane
 must always match the bit-size of the vector's shape.
 Thus, reinterpreting a
 vector 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.
 
Vector subtypes
Vector declares a set of vector operations (methods) that are common to all element types (such as addition). Sub-classes of Vector with a concrete 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,ByteVector, ShortVector,
 IntVector, LongVector, FloatVector, and
 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,
 FloatVector.fromArray
 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 static final
 fields for optimal creation and usage of Vector values by the runtime compiler.
  As an example of static constants defined by the typed vector classes,
 constant FloatVector.SPECIES_256
 is the unique species whose lanes are floats and whose
 vector size is 256 bits.  Again, the constant
 FloatVector.SPECIES_PREFERRED is the species which
 best supports processing of float vector lanes on
 the currently running Java platform.
 
 As another example, a broadcast scalar value of
 (double)0.5 can be obtained by calling
 DoubleVector.broadcast(dsp, 0.5), but the argument dsp is
 required to select the species (and hence the shape and length) of
 the resulting vector.
 
Lane-wise operations
We use the term lanes when defining operations on vectors. The number of lanes in a vector is the number of scalar elements it holds. For example, a vector of typefloat and
 shape S_256_BIT has eight lanes, since 32*8=256.
  Most operations on vectors are lane-wise, which means the operation
 is composed of an underlying scalar operator, which is repeated for
 each distinct lane of the input vector.  If there are additional
 vector arguments of the same type, their lanes are aligned with the
 lanes of the first input vector.  (They must all have a common
 VLENGTH.)  For most lane-wise operations, the output resulting
 from a lane-wise operation will have a VLENGTH which is equal to
 the VLENGTH of the input(s) to the operation.  Thus, such lane-wise
 operations are length-invariant, in their basic definitions.
 
 The principle of length-invariance is combined with another
 basic principle, that most length-invariant lane-wise operations are also
 shape-invariant, meaning that the inputs and the output of
 a lane-wise operation will have a common VSHAPE.  When the
 principles conflict, because a logical result (with an invariant
 VLENGTH), does not fit into the invariant VSHAPE,
 the resulting expansions and contractions are handled explicitly
 with
 special conventions.
 
 Vector operations can be grouped into various categories and
 their behavior can be generally specified in terms of underlying
 scalar operators.  In the examples below, ETYPE is the
 element type of the operation (such as int.class) and
 EVector is the corresponding concrete vector type (such as
 IntVector.class).
 
- 
 A lane-wise unary operation, such as
 w = v0.neg(), takes one input vector, distributing a unary scalar operator across the lanes, and produces a result vector of the same type and shape. For each lane of the input vectora, the underlying scalar operator is applied to the lane value. The result is placed into the vector result in the same lane. The following pseudocode illustrates the behavior of this operation category:ETYPE scalar_unary_op(ETYPE s); EVector a = ...; VectorSpecies<E> species = a.species(); ETYPE[] ar = new ETYPE[a.length()]; for (int i = 0; i < ar.length; i++) { ar[i] = scalar_unary_op(a.lane(i)); } EVector r = EVector.fromArray(species, ar, 0);
- 
 A lane-wise binary operation, such as
 w = v0.add(v1), takes two input vectors, distributing a binary scalar operator across the lanes, and produces a result vector of the same type and shape. For each lane of the two input vectorsaandb, the underlying scalar operator is applied to the lane values. The result is placed into the vector result in the same lane. The following pseudocode illustrates the behavior of this operation category:ETYPE scalar_binary_op(ETYPE s, ETYPE t); EVector a = ...; VectorSpecies<E> species = a.species(); EVector b = ...; b.check(species); // must have same species ETYPE[] ar = new ETYPE[a.length()]; for (int i = 0; i < ar.length; i++) { ar[i] = scalar_binary_op(a.lane(i), b.lane(i)); } EVector r = EVector.fromArray(species, ar, 0);
- 
 Generalizing from unary and binary operations,
 a lane-wise n-ary operation takes Ninput vectorsv[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, such asw = v0.fma(v1,v2), this API has no support for lane-wise n-ary operations. For each lane of all of the input vectorsv[j], the underlying scalar operator is applied to the lane values. The result is placed into the vector result in the same lane. The following pseudocode illustrates the behavior of this operation category:ETYPE scalar_nary_op(ETYPE... args); EVector[] v = ...; int N = v.length; VectorSpecies<E> species = v[0].species(); for (EVector arg : v) { arg.check(species); // all must have same species } ETYPE[] ar = new ETYPE[a.length()]; for (int i = 0; i < ar.length; i++) { ETYPE[] args = new ETYPE[N]; for (int j = 0; j < N; j++) { args[j] = v[j].lane(i); } ar[i] = scalar_nary_op(args); } EVector r = EVector.fromArray(species, ar, 0);
- 
 A lane-wise conversion operation, such as
 w0 = v0.convert(VectorOperators.I2D, 0), takes one input vector, distributing a unary scalar conversion operator across the lanes, and produces a logical result of the converted values. The logical result (or at least a part of it) is presented in a vector of the same shape as the input vector.Unlike other lane-wise operations, conversions can change lane type, from the input (domain) type to the output (range) type. The lane size may change along with the type. In order to manage the size changes, lane-wise conversion methods can product partial results, under the control of a partparameter, which is explained elsewhere. (Following the example above, the second group of converted lane values could be obtained asw1 = v0.convert(VectorOperators.I2D, 1).)The following pseudocode illustrates the behavior of this operation category in the specific example of a conversion from inttodouble, retaining either lower or upper lanes (depending onpart) to maintain shape-invariance:IntVector a = ...; int VLENGTH = a.length(); int part = ...; // 0 or 1 VectorShape VSHAPE = a.shape(); double[] arlogical = new double[VLENGTH]; for (int i = 0; i < limit; i++) { int e = a.lane(i); arlogical[i] = (double) e; } VectorSpecies<Double> rs = VSHAPE.withLanes(double.class); int M = Double.BITS / Integer.BITS; // expansion factor int offset = part * (VLENGTH / M); DoubleVector r = DoubleVector.fromArray(rs, arlogical, offset); assert r.length() == VLENGTH / M;
- 
 A cross-lane reduction operation, such as
 e = v0.reduceLanes(VectorOperators.ADD), 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 order of accumulation. The following pseudocode illustrates the behavior of this operation category if it is associative:ETYPE assoc_scalar_binary_op(ETYPE s, ETYPE t); EVector a = ...; ETYPE r = <identity value>; for (int i = 0; i < a.length(); i++) { r = assoc_scalar_binary_op(r, a.lane(i)); }
- 
 A cross-lane movement operation, such as
 w = v0.rearrange(shuffle)operates on all the lane elements of an input vector and moves them in a data-dependent manner into different lanes in an output vector. The movement is steered by an auxiliary datum, such as aVectorShuffleor a scalar index defining the origin of the movement. The following pseudocode illustrates the behavior of this operation category, in the case of a shuffle:EVector a = ...; Shuffle<E> s = ...; ETYPE[] ar = new ETYPE[a.length()]; for (int i = 0; i < ar.length; i++) { int source = s.laneSource(i); ar[i] = a.lane(source); } EVector r = EVector.fromArray(a.species(), ar, 0);
- 
 A masked operation is one which is a variation on one of the
 previous operations (either lane-wise or cross-lane), where
 the operation takes an extra trailing VectorMaskargument. In lanes the mask is set, the operation behaves as if the mask argument were absent, but in lanes where the mask is unset, the underlying scalar operation is suppressed. Masked operations are explained in greater detail elsewhere.
- 
 A very special case of a masked lane-wise binary operation is a
 blend, which operates
 lane-wise on two input vectors aandb, selecting lane values from one input or the other depending on a maskm. In lanes wheremis set, the corresponding value frombis selected into the result; otherwise the value fromais selected. Thus, a blend acts as a vectorized version of Java's ternary selection expressionm?b:a:ETYPE[] ar = new ETYPE[a.length()]; for (int i = 0; i < ar.length; i++) { boolean isSet = m.laneIsSet(i); ar[i] = isSet ? b.lane(i) : a.lane(i); } EVector r = EVector.fromArray(species, ar, 0);
- 
 A lane-wise binary test operation, such as
 m = v0.lt(v1), takes two input vectors, distributing a binary scalar comparison across the lanes, and produces, not a vector of booleans, but rather a vector mask. For each lane of the two input vectorsaandb, the underlying scalar comparison operator is applied to the lane values. The resulting boolean is placed into the vector mask result in the same lane. The following pseudocode illustrates the behavior of this operation category:boolean scalar_binary_test_op(ETYPE s, ETYPE t); EVector a = ...; VectorSpecies<E> species = a.species(); EVector b = ...; b.check(species); // must have same species boolean[] mr = new boolean[a.length()]; for (int i = 0; i < mr.length; i++) { mr[i] = scalar_binary_test_op(a.lane(i), b.lane(i)); } VectorMask<E> m = VectorMask.fromArray(species, mr, 0);
- 
 Similarly to a binary comparison, a lane-wise unary test
 operation, such as
 m = v0.test(IS_FINITE), takes one input vector, distributing a scalar predicate (a test function) across the lanes, and produces a vector mask.
If a vector operation does not belong to one of the above categories then the method documentation explicitly specifies how it processes the lanes of input vectors, and where appropriate illustrates the behavior using pseudocode.
 Most lane-wise binary and comparison operations offer convenience
 overloadings which accept a scalar as the second input, in place of a
 vector.  In this case the scalar value is promoted to a vector by
 broadcasting it
 into the same lane structure as the first input.
 For example, to multiply all lanes of a double vector by
 a scalar value 1.1, the expression v.mul(1.1) is
 easier to work with than an equivalent expression with an explicit
 broadcast operation, such as v.mul(v.broadcast(1.1))
 or v.mul(DoubleVector.broadcast(v.species(), 1.1)).
 Unless otherwise specified the scalar variant always behaves as if
 each scalar value is first transformed to a vector of the same
 species as the first vector input, using the appropriate
 broadcast operation.
 
Masked operations
 Many vector operations accept an optional
 mask argument, selecting which lanes participate
 in the underlying scalar operator.  If present, the mask argument
 appears at the end of the method argument list.
 
Each lane of the mask argument is a boolean which is either in the set or unset state. For lanes where the mask argument is unset, the underlying scalar operator is suppressed. In this way, masks allow vector operations to emulate scalar control flow operations, without losing SIMD parallelism, except where the mask lane is unset.
An operation suppressed by a mask will never cause an exception or side effect of any sort, even if the underlying scalar operator can potentially do so. For example, an unset lane that seems to access an out of bounds array element or divide an integral value by zero will simply be ignored. Values in suppressed lanes never participate or appear in the result of the overall operation.
Result lanes corresponding to a suppressed operation will be filled with a default value which depends on the specific operation, as follows:
- If the masked operation is a unary, binary, or n-ary arithmetic or logical operation, suppressed lanes are filled from the first vector operand (i.e., the vector receiving the method call), as if by a blend.
- If the masked operation is a memory load or a slice()from another vector, suppressed lanes are not loaded, and are filled with the default value for theETYPE, which in every case consists of all zero bits. An unset lane can never cause an exception, even if the hypothetical corresponding memory location does not exist (because it is out of an array's index range).
- If the operation is a cross-lane operation with an operand
 which supplies lane indexes (of type VectorShuffleorVector, suppressed lanes are not computed, and are filled with the zero default value. Normally, invalid lane indexes elicit anIndexOutOfBoundsException, but if a lane is unset, the zero value is quietly substituted, regardless of the index. This rule is similar to the previous rule, for masked memory loads.
- If the masked operation is a memory store or an unslice()into another vector, suppressed lanes are not stored, and the corresponding memory or vector locations (if any) are unchanged.(Note: Memory effects such as race conditions never occur for suppressed lanes. That is, implementations will not secretly re-write the existing value for unset lanes. In the Java Memory Model, reassigning a memory variable to its current value is not a no-op; it may quietly undo a racing store from another thread.) 
- If the masked operation is a reduction, suppressed lanes are ignored in the reduction. If all lanes are suppressed, a suitable neutral value is returned, depending on the specific reduction operation, and documented by the masked variant of that method. (This means that users can obtain the neutral value programmatically by executing the reduction on a dummy vector with an all-unset mask.)
- If the masked operation is a comparison operation, suppressed output
 lanes in the resulting mask are themselves unset, as if the
 suppressed comparison operation returned falseregardless of the suppressed input values. In effect, it is as if the comparison operation were performed unmasked, and then the result intersected with the controlling mask.
- In other cases, such as masked cross-lane movements, the specific effects of masking are documented by the masked variant of the method.
 As an example, a masked binary operation on two input vectors
 a and b suppresses the binary operation for lanes
 where the mask is unset, and retains the original lane value from
 a.  The following pseudocode illustrates this behavior:
 
 ETYPE scalar_binary_op(ETYPE s, ETYPE t);
 EVector a = ...;
 VectorSpecies<E> species = a.species();
 EVector b = ...;
 b.check(species);  // must have same species
 VectorMask<E> m = ...;
 m.check(species);  // must have same species
 boolean[] ar = new boolean[a.length()];
 for (int i = 0; i < ar.length; i++) {
     if (m.laneIsSet(i)) {
         ar[i] = scalar_binary_op(a.lane(i), b.lane(i));
     } else {
         ar[i] = a.lane(i);  // from first input
     }
 }
 EVector r = EVector.fromArray(species, ar, 0);
 Lane order and byte order
The number of lane values stored in a given vector is referred to as its vector length orVLENGTH.
 It is useful to consider vector lanes as ordered
 sequentially from first to last, with the first lane
 numbered 0, the next lane numbered 1, and so on to
 the last lane numbered VLENGTH-1.  This is a temporal
 order, where lower-numbered lanes are considered earlier than
 higher-numbered (later) lanes.  This API uses these terms
 in preference to spatial terms such as "left", "right", "high",
 and "low".
 Temporal terminology works well for vectors because they (usually) represent small fixed-sized segments in a long sequence of workload elements, where the workload is conceptually traversed in time order from beginning to end. (This is a mental model: it does not exclude multicore divide-and-conquer techniques.) Thus, when a scalar loop is transformed into a vector loop, adjacent scalar items (one earlier, one later) in the workload end up as adjacent lanes in a single vector (again, one earlier, one later). At a vector boundary, the last lane item in the earlier vector is adjacent to (and just before) the first lane item in the immediately following vector.
Vectors are also sometimes thought of in spatial terms, where the first lane is placed at an edge of some virtual paper, and subsequent lanes are presented in order next to it. When using spatial terms, all directions are equally plausible: Some vector notations present lanes from left to right, and others from right to left; still others present from top to bottom or vice versa. Using the language of time (before, after, first, last) instead of space (left, right, high, low) is often more likely to avoid misunderstandings.
As second reason to prefer temporal to spatial language about vector lanes is the fact that the terms "left", "right", "high" and "low" are widely used to describe the relations between bits in scalar values. The leftmost or highest bit in a given type is likely to be a sign bit, while the rightmost or lowest bit is likely to be the arithmetically least significant, and so on. Applying these terms to vector lanes risks confusion, however, because it is relatively rare to find algorithms where, given two adjacent vector lanes, one lane is somehow more arithmetically significant than its neighbor, and even in those cases, there is no general way to know which neighbor is the more significant.
Putting the terms together, we view the information structure of a vector as a temporal sequence of lanes ("first", "next", "earlier", "later", "last", etc.) of bit-strings which are internally ordered spatially (either "low" to "high" or "right" to "left"). The primitive values in the lanes are decoded from these bit-strings, in the usual way. Most vector operations, like most Java scalar operators, treat primitive values as atomic values, but some operations reveal the internal bit-string structure.
When a vector is loaded from or stored into memory, the order of vector lanes is always consistent with the inherent ordering of the memory container. This is true whether or not individual lane elements are subject to "byte swapping" due to details of byte order. Thus, while the scalar lane elements of vector might be "byte swapped", the lanes themselves are never reordered, except by an explicit method call that performs cross-lane reordering.
When vector lane values are stored to Java variables of the same type, byte swapping is performed if and only if the implementation of the vector hardware requires such swapping. It is therefore unconditional and invisible.
As a useful fiction, this API presents a consistent illusion that vector lane bytes are composed into larger lane scalars in little endian order. This means that storing a vector into a Java byte array will reveal the successive bytes of the vector lane values in little-endian order on all platforms, regardless of native memory order, and also regardless of byte order (if any) within vector unit registers.
 This hypothetical little-endian ordering also appears when a
 reinterpretation cast is
 applied in such a way that lane boundaries are discarded and
 redrawn differently, while maintaining vector bits unchanged.  In
 such an operation, two adjacent lanes will contribute bytes to a
 single new lane (or vice versa), and the sequential order of the
 two lanes will determine the arithmetic order of the bytes in the
 single lane.  In this case, the little-endian convention provides
 portable results, so that on all platforms earlier lanes tend to
 contribute lower (rightward) bits, and later lanes tend to
 contribute higher (leftward) bits.  The reinterpretation casts between ByteVectors and the
 other non-byte vectors use this convention to clarify their
 portable semantics.
 
The little-endian fiction for relating lane order to per-lane byte order is slightly preferable to an equivalent big-endian 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.
Memory operations
As was already mentioned, vectors can be loaded from memory and stored back. An optional mask can control which individual memory locations are read from or written to. The shape of a vector determines how much memory it will occupy. An implementation typically has the property, in the absence of masking, that lanes are stored as a dense sequence of back-to-back values in memory, the same as a dense (gap-free) series of single scalar values in an array of the scalar type. In such cases memory order corresponds exactly to lane order. The first vector lane value occupies the first position in memory, and so on, up to the length of the vector. Further, the memory order of stored vector lanes corresponds to increasing index values in a Java array or in aMemorySegmentPREVIEW.
 Byte order for lane storage is chosen such that the stored vector values can be read or written as single primitive values, within the array or segment that holds the vector, producing the same values as the lane-wise values within the vector. This fact is independent of the convenient fiction that lane values inside of vectors are stored in little-endian order.
 For example,
 FloatVector.fromArray(fsp,fa,i)
 creates and returns a float vector of some particular species fsp,
 with elements loaded from some float array fa.
 The first lane is loaded from fa[i] and the last lane
 is initialized loaded from fa[i+VL-1], where VL
 is the length of the vector as derived from the species fsp.
 Then, fv=fv.add(fv2)
 will produce another float vector of that species fsp,
 given a vector fv2 of the same species fsp.
 Next, mnz=fv.compare(NE, 0.0f) tests whether the result is zero,
 yielding a mask mnz.  The non-zero lanes (and only those
 lanes) can then be stored back into the original array elements
 using the statement
 fv.intoArray(fa,i,mnz).
 
Expansions, contractions, and partial results
Since vectors are fixed in size, occasions often arise where the logical result of an operation is not the same as the physical size of the proposed output vector. To encourage user code that is as portable and predictable as possible, this API has a systematic approach to the design of such resizing vector operations. As a basic principle, lane-wise operations are
 length-invariant, unless clearly marked otherwise.
 Length-invariance simply means that
 if VLENGTH lanes go into an operation, the same number
 of lanes come out, with nothing discarded and no extra padding.
 
 As a second principle, sometimes in tension with the first,
 lane-wise operations are also shape-invariant, unless
 clearly marked otherwise.
 Shape-invariance means that VSHAPE is constant for typical
 computations.  Keeping the same shape throughout a computation
 helps ensure that scarce vector resources are efficiently used.
 (On some hardware platforms shape changes could cause unwanted
 effects like extra data movement instructions, round trips through
 memory, or pipeline bubbles.)
 
 Tension between these principles arises when an operation
 produces a logical result that is too large for the
 required output VSHAPE.  In other cases, when a logical
 result is smaller than the capacity of the output VSHAPE,
 the positioning of the logical result is open to question, since
 the physical output vector must contain a mix of logical result and
 padding.
 
 In the first case, of a too-large logical result being crammed
 into a too-small output VSHAPE, we say that data has
 expanded.  In other words, an expansion operation
 has caused the output shape to overflow.  Symmetrically, in the
 second case of a small logical result fitting into a roomy output
 VSHAPE, the data has contracted, and the
 contraction operation has required the output shape to pad
 itself with extra zero lanes.
 
 In both cases we can speak of a parameter M which
 measures the expansion ratio or contraction ratio
 between the logical result size (in bits) and the bit-size of the
 actual output shape.  When vector shapes are changed, and lane
 sizes are not, M is just the integral ratio of the output
 shape to the logical result.  (With the possible exception of
 the maximum shape, all vector
 sizes are powers of two, and so the ratio M is always
 an integer.  In the hypothetical case of a non-integral ratio,
 the value M would be rounded up to the next integer,
 and then the same general considerations would apply.)
 
 If the logical result is larger than the physical output shape,
 such a shape change must inevitably drop result lanes (all but
 1/M of the logical result).  If the logical size is smaller
 than the output, the shape change must introduce zero-filled lanes
 of padding (all but 1/M of the physical output).  The first
 case, with dropped lanes, is an expansion, while the second, with
 padding lanes added, is a contraction.
 
 Similarly, consider a lane-wise conversion operation which
 leaves the shape invariant but changes the lane size by a ratio of
 M.  If the logical result is larger than the output (or
 input), this conversion must reduce the VLENGTH lanes of the
 output by M, dropping all but 1/M of the logical
 result lanes.  As before, the dropping of lanes is the hallmark of
 an expansion.  A lane-wise operation which contracts lane size by a
 ratio of M must increase the VLENGTH by the same
 factor M, filling the extra lanes with a zero padding
 value; because padding must be added this is a contraction.
 
It is also possible (though somewhat confusing) to change both lane size and container size in one operation which performs both lane conversion and reshaping. If this is done, the same rules apply, but the logical result size is the product of the input size times any expansion or contraction ratio from the lane change size.
 For completeness, we can also speak of in-place
 operations for the frequent case when resizing does not occur.
 With an in-place operation, the data is simply copied from logical
 output to its physical container with no truncation or padding.
 The ratio parameter M in this case is unity.
 
 Note that the classification of contraction vs. expansion
 depends on the relative sizes of the logical result and the
 physical output container.  The size of the input container may be
 larger or smaller than either of the other two values, without
 changing the classification.  For example, a conversion from a
 128-bit shape to a 256-bit shape will be a contraction in many
 cases, but it would be an expansion if it were combined with a
 conversion from byte to long, since in that case
 the logical result would be 1024 bits in size.  This example also
 illustrates that a logical result does not need to correspond to
 any particular platform-supported vector shape.
 
Although lane-wise masked operations can be viewed as producing partial operations, they are not classified (in this API) as expansions or contractions. A masked load from an array surely produces a partial vector, but there is no meaningful "logical output vector" that this partial result was contracted from.
Some care is required with these terms, because it is the data, not the container size, that is expanding or contracting, relative to the size of its output container. Thus, resizing a 128-bit input into 512-bit vector has the effect of a contraction. Though the 128 bits of payload hasn't changed in size, we can say it "looks smaller" in its new 512-bit home, and this will capture the practical details of the situation.
 If a vector method might expand its data, it accepts an extra
 int parameter called part, or the "part number".
 The part number must be in the range [0..M-1], where
 M is the expansion ratio.  The part number selects one
 of M contiguous disjoint equally-sized blocks of lanes
 from the logical result and fills the physical output vector
 with this block of lanes.
 
 Specifically, the lanes selected from the logical result of an
 expansion are numbered in the range [R..R+L-1], where
 L is the VLENGTH of the physical output vector, and
 the origin of the block, R, is part*L.
 
 A similar convention applies to any vector method that might
 contract its data.  Such a method also accepts an extra part number
 parameter (again called part) which steers the contracted
 data lanes one of M contiguous disjoint equally-sized
 blocks of lanes in the physical output vector.  The remaining lanes
 are filled with zero, or as specified by the method.
 
 Specifically, the data is steered into the lanes numbered in the
 range [R..R+L-1], where L is the VLENGTH of
 the logical result vector, and the origin of the block, R,
 is again a multiple of L selected by the part number,
 specifically |part|*L.
 
 In the case of a contraction, the part number must be in the
 non-positive range [-M+1..0].  This convention is adopted
 because some methods can perform both expansions and contractions,
 in a data-dependent manner, and the extra sign on the part number
 serves as an error check.  If vector method takes a part number and
 is invoked to perform an in-place operation (neither contracting
 nor expanding), the part parameter must be exactly zero.
 Part numbers outside the allowed ranges will elicit an indexing
 exception.  Note that in all cases a zero part number is valid, and
 corresponds to an operation which preserves as many lanes as
 possible from the beginning of the logical result, and places them
 into the beginning of the physical output container.  This is
 often a desirable default, so a part number of zero is safe
 in all cases and useful in most cases.
 
The various resizing operations of this API contract or expand their data as follows:
- 
 Vector.convert()will expand (respectively, contract) its operand by ratioMif the element size of its output is larger (respectively, smaller) by a factor ofM. If the element sizes of input and output are the same, thenconvert()is an in-place operation.
- 
 Vector.convertShape()will expand (respectively, contract) its operand by ratioMif the bit-size of its logical result is larger (respectively, smaller) than the bit-size of its output shape. The size of the logical result is defined as the element size of the output, times theVLENGTHof its input. Depending on the ratio of the changed lane sizes, the logical size may be (in various cases) either larger or smaller than the input vector, independently of whether the operation is an expansion or contraction.
- 
 Since Vector.castShape()is a convenience method forconvertShape(), its classification as an expansion or contraction is the same as forconvertShape().
- 
 Vector.reinterpretShape()is an expansion (respectively, contraction) by ratioMif the vector bit-size of its input is crammed into a smaller (respectively, dropped into a larger) output container by a factor ofM. Otherwise it is an in-place operation. Since this method is a reinterpretation cast that can erase and redraw lane boundaries as well as modify shape, the input vector's lane size and lane count are irrelevant to its classification as expanding or contracting.
- 
 The unslice()methods expand by a ratio ofM=2, because the single input slice is positioned and inserted somewhere within two consecutive background vectors. The part number selects the first or second background vector, as updated by the inserted slice. Note that the correspondingslice()methods, although inverse to theunslice()methods, do not contract their data and thus require no part number. This is becauseslice()delivers a slice of exactlyVLENGTHlanes extracted from two input vectors.
partLimit() on VectorSpecies can be used, before any
 expanding or contracting operation is performed, to query the
 limiting value on a part parameter for a proposed expansion
 or contraction.  The value returned from partLimit() is
 positive for expansions, negative for contractions, and zero for
 in-place operations.  Its absolute value is the parameter 
 M, and so it serves as an exclusive limit on valid part number
 arguments for the relevant methods.  Thus, for expansions, the
 partLimit() value M is the exclusive upper limit
 for part numbers, while for contractions the partLimit()
 value -M is the exclusive lower limit.
 Moving data across lane boundaries
The cross-lane methods which do not redraw lanes or change species are more regularly structured and easier to reason about. These operations are:- The slice()family of methods, which extract contiguous slice ofVLENGTHfields from a given origin point within a concatenated pair of vectors.
- The unslice()family of methods, which insert a contiguous slice ofVLENGTHfields into a concatenated pair of vectors at a given origin point.
- The rearrange()family of methods, which select an arbitrary set ofVLENGTHlanes from one or two input vectors, and assemble them in an arbitrary order. The selection and order of lanes is controlled by aVectorShuffleobject, which acts as an routing table mapping source lanes to destination lanes. AVectorShufflecan encode a mathematical permutation as well as many other patterns of data movement.
- The compress(VectorMask)andexpand(VectorMask)methods, which select up toVLENGTHlanes from an input vector, and assemble them in lane order. The selection of lanes is controlled by aVectorMask, with set lane elements mapping, by compression or expansion in lane order, source lanes to destination lanes.
Some vector operations are not lane-wise, but rather move data across lane boundaries. Such operations are typically rare in SIMD code, though they are sometimes necessary for specific algorithms that manipulate data formats at a low level, and/or require SIMD data to move in complex local patterns. (Local movement in a small window of a large array of data is relatively unusual, although some highly patterned algorithms call for it.) In this API such methods are always clearly recognizable, so that simpler lane-wise reasoning can be confidently applied to the rest of the code.
 In some cases, vector lane boundaries are discarded and
 "redrawn from scratch", so that data in a given input lane might
 appear (in several parts) distributed through several output lanes,
 or (conversely) data from several input lanes might be consolidated
 into a single output lane.  The fundamental method which can redraw
 lanes boundaries is
 reinterpretShape().
 Built on top of this method, certain convenience methods such
 as reinterpretAsBytes() or
 reinterpretAsInts() will
 (potentially) redraw lane boundaries, while retaining the
 same overall vector shape.
 
 Operations which produce or consume a scalar result can be
 viewed as very simple cross-lane operations.  Methods in the
 reduceLanes() family fold together all lanes (or mask-selected
 lanes) of a method and return a single result.  As an inverse, the
 broadcast family of methods can be thought
 of as crossing lanes in the other direction, from a scalar to all
 lanes of the output vector.  Single-lane access methods such as
 lane(I) or withLane(I,E) might also be regarded as
 very simple cross-lane operations.
 
Likewise, a method which moves a non-byte vector to or from a byte array could be viewed as a cross-lane operation, because the vector lanes must be distributed into separate bytes, or (in the other direction) consolidated from array bytes.
- Implementation Note:
- Hardware platform dependencies and limitationsThe Vector API is to accelerate computations in style of Single Instruction Multiple Data (SIMD), using available hardware resources such as vector hardware registers and vector hardware instructions. The API is designed to make effective use of multiple SIMD hardware platforms.- This API will also work correctly even on Java platforms which do not include specialized hardware support for SIMD computations. The Vector API is not likely to provide any special performance benefit on such platforms. - Currently the implementation is optimized to work best on: - Intel x64 platforms supporting at least AVX2 up to AVX-512. Masking using mask registers and mask accepting hardware instructions on AVX-512 are not currently supported.
- ARM AArch64 platforms supporting NEON. Although the API has been designed to ensure ARM SVE instructions can be supported (vector sizes between 128 to 2048 bits) there is currently no implementation of such instructions and the general masking capability.
 - blendas in the expression- a.blend(a.lanewise(op, b), m), where- aand- bare vectors,- opis the vector operation, and- mis the mask.- The implementation does not currently support optimal vectorized instructions for floating point transcendental functions (such as operators - SINand- LOG).- No boxing of primitivesAlthough a vector type like- Vector<Integer>may seem to work with boxed- Integervalues, the overheads associated with boxing are avoided by having each vector subtype work internally on lane values of the actual- ETYPE, such as- int.- Value-based classes and identity operations- Vector, along with all of its subtypes and many of its helper types like- VectorMaskand- VectorShuffle, is a value-based class.- Once created, a vector is never mutated, not even if only a single lane is changed. A new vector is always created to hold a new configuration of lane values. The unavailability of mutative methods is a necessary consequence of suppressing the object identity of all vectors, as value-based classes. - With - Vector, identity-sensitive operations such as- ==may yield unpredictable results, or reduced performance. Oddly enough,- v.equals(w)is likely to be faster than- v==w, since- equalsis not an identity sensitive method. Also, these objects can be stored in locals and parameters and as- static finalconstants, but storing them in other Java fields or in array elements, while semantically valid, may incur performance penalties.
- 
Method SummaryModifier and TypeMethodDescriptionabs()Returns the absolute value of this vector.Adds this vector to a second input vector.add(Vector<E> v, VectorMask<E> m) Adds this vector to a second input vector, selecting lanes under the control of a mask.addIndex(int scale) Adds the lanes of this vector to their corresponding lane numbers, scaled by a given constant.abstract intbitSize()Returns the total size, in bits, of this vector.blend(long e, VectorMask<E> m) Replaces selected lanes of this vector with a scalar value under the control of a mask.blend(Vector<E> v, VectorMask<E> m) Replaces selected lanes of this vector with corresponding lanes from a second input vector under the control of a mask.broadcast(long e) Returns a vector of the same species as this one where all lane elements are set to the primitive valuee.abstract intbyteSize()Returns the total size, in bytes, of this vector.abstract <F> Vector<F> castShape(VectorSpecies<F> rsp, int part) Convenience method for converting a vector from one lane type to another, reshaping as needed when lane sizes change.abstract <F> Vector<F> Checks that this vector has the given element type, and returns this vector unchanged.abstract <F> Vector<F> check(VectorSpecies<F> species) Checks that this vector has the given species, and returns this vector unchanged.abstract VectorMask<E> compare(VectorOperators.Comparison op, long e) Tests this vector by comparing it with an input scalar, according to the given comparison operation.abstract VectorMask<E> compare(VectorOperators.Comparison op, long e, VectorMask<E> m) Tests this vector by comparing it with an input scalar, according to the given comparison operation, in lanes selected by a mask.abstract VectorMask<E> compare(VectorOperators.Comparison op, Vector<E> v) Tests this vector by comparing it with another input vector, according to the given comparison operation.abstract VectorMask<E> compare(VectorOperators.Comparison op, Vector<E> v, VectorMask<E> m) Tests this vector by comparing it with another input vector, according to the given comparison operation, in lanes selected by a mask.compress(VectorMask<E> m) Compresses the lane elements of this vector selecting lanes under the control of a specific mask.abstract <F> Vector<F> convert(VectorOperators.Conversion<E, F> conv, int part) Convert this vector to a vector of the same shape and a new element type, converting lane values from the currentETYPEto a new lane type (calledFTYPEhere) according to the indicated conversion.abstract <F> Vector<F> convertShape(VectorOperators.Conversion<E, F> conv, VectorSpecies<F> rsp, int part) Converts this vector to a vector of the given species, shape and element type, converting lane values from the currentETYPEto a new lane type (calledFTYPEhere) according to the indicated conversion.Divides this vector by a second input vector.div(Vector<E> v, VectorMask<E> m) Divides this vector by a second input vector under the control of a mask.abstract intReturns the size of each lane, in bits, of this vector.Returns the primitive element type (ETYPE) of this vector.abstract VectorMask<E> Tests if this vector is equal to another input vector.abstract booleanIndicates whether this vector is identical to some other object.expand(VectorMask<E> m) Expands the lane elements of this vector under the control of a specific mask.protected final Objectabstract inthashCode()Returns a hash code value for the vector.abstract voidintoMemorySegment(MemorySegmentPREVIEW ms, long offset, ByteOrder bo) Stores this vector into a memory segmentPREVIEW starting at an offset using explicit byte order.abstract voidintoMemorySegment(MemorySegmentPREVIEW ms, long offset, ByteOrder bo, VectorMask<E> m) Stores this vector into a memory segmentPREVIEW starting at an offset using explicit byte order and a mask.lanewise(VectorOperators.Binary op, long e) Combines the lane values of this vector with the value of a broadcast scalar.lanewise(VectorOperators.Binary op, long e, VectorMask<E> m) Combines the corresponding lane values of this vector with those of a second input vector, with selection of lane elements controlled by a mask.lanewise(VectorOperators.Binary op, Vector<E> v) Combines the corresponding lane values of this vector with those of a second input vector.lanewise(VectorOperators.Binary op, Vector<E> v, VectorMask<E> m) Combines the corresponding lane values of this vector with those of a second input vector, with selection of lane elements controlled by a mask.Combines the corresponding lane values of this vector with the lanes of a second and a third input vector.lanewise(VectorOperators.Ternary op, Vector<E> v1, Vector<E> v2, VectorMask<E> m) Combines the corresponding lane values of this vector with the lanes of a second and a third input vector, with selection of lane elements controlled by a mask.Operates on the lane values of this vector.lanewise(VectorOperators.Unary op, VectorMask<E> m) Operates on the lane values of this vector, with selection of lane elements controlled by a mask.abstract intlength()Returns the lane count, or vector length (VLENGTH).abstract VectorMask<E> Tests if this vector is less than another input vector.abstract VectorMask<E> maskAll(boolean bit) Returns a mask of same species as this vector, where each lane is set or unset according to given single boolean, which is broadcast to all lanes.Computes the larger of this vector and a second input vector.Computes the smaller of this vector and a second input vector.Multiplies this vector by a second input vector.mul(Vector<E> v, VectorMask<E> m) Multiplies this vector by a second input vector under the control of a mask.neg()Negates this vector.rearrange(VectorShuffle<E> s) Rearranges the lane elements of this vector, selecting lanes under the control of a specific shuffle.rearrange(VectorShuffle<E> s, Vector<E> v) Rearranges the lane elements of two vectors, selecting lanes under the control of a specific shuffle, using both normal and exceptional indexes in the shuffle to steer data.rearrange(VectorShuffle<E> s, VectorMask<E> m) Rearranges the lane elements of this vector, selecting lanes under the control of a specific shuffle and a mask.abstract longReturns a value accumulated from all the lanes of this vector.abstract longReturns a value accumulated from selected lanes of this vector, controlled by a mask.abstract ByteVectorViews this vector as a vector of the same shape and contents but a lane type ofbyte, where the bytes are extracted from the lanes according to little-endian order.abstract DoubleVectorReinterprets this vector as a vector of the same shape and contents but a lane type ofdouble, where the lanes are assembled from successive bytes according to little-endian order.abstract FloatVectorReinterprets this vector as a vector of the same shape and contents but a lane type offloat, where the lanes are assembled from successive bytes according to little-endian order.abstract IntVectorReinterprets this vector as a vector of the same shape and contents but a lane type ofint, where the lanes are assembled from successive bytes according to little-endian order.abstract LongVectorReinterprets this vector as a vector of the same shape and contents but a lane type oflong, where the lanes are assembled from successive bytes according to little-endian order.abstract ShortVectorReinterprets this vector as a vector of the same shape and contents but a lane type ofshort, where the lanes are assembled from successive bytes according to little-endian order.abstract <F> Vector<F> reinterpretShape(VectorSpecies<F> species, int part) Transforms this vector to a vector of the given species of element typeF, reinterpreting the bytes of this vector without performing any value conversions.selectFrom(Vector<E> v) Using index values stored in the lanes of this vector, assemble values stored in second vectorv.selectFrom(Vector<E> v, VectorMask<E> m) Using index values stored in the lanes of this vector, assemble values stored in second vector, under the control of a mask.abstract VectorShapeshape()Returns the shape of this vector.slice(int origin) Slices a segment of adjacent lanes, starting at a givenoriginlane in the current vector.Slices a segment of adjacent lanes, starting at a givenoriginlane in the current vector, and continuing (as needed) into an immediately following vector.slice(int origin, Vector<E> v1, VectorMask<E> m) Slices a segment of adjacent lanes under the control of a mask, starting at a givenoriginlane in the current vector, and continuing (as needed) into an immediately following vector.abstract VectorSpecies<E> species()Returns the species of this vector.Subtracts a second input vector from this vector.sub(Vector<E> v, VectorMask<E> m) Subtracts a second input vector from this vector under the control of a mask.abstract VectorMask<E> Tests the lanes of this vector according to the given operation.abstract VectorMask<E> test(VectorOperators.Test op, VectorMask<E> m) Test selected lanes of this vector, according to the given operation.abstract ObjecttoArray()Returns a packed array containing all the lane values.abstract double[]Returns adouble[]array containing all the lane values, converted to the typedouble.abstract int[]Returns anint[]array containing all the lane values, converted to the typeint.abstract long[]Returns along[]array containing all the lane values, converted to the typelong.abstract VectorShuffle<E> Converts this vector into a shuffle, converting the lane values tointand regarding them as source indexes.abstract StringtoString()Returns a string representation of this vector, of the form"[0,1,2...]", reporting the lane values of this vector, in lane order.unslice(int origin) Reverses a slice(), inserting the current vector as a slice within a "background" input of zero lane values.Reverses a slice(), inserting the current vector as a slice within another "background" input vector, which is regarded as one or the other input to a hypothetical subsequentslice()operation.unslice(int origin, Vector<E> w, int part, VectorMask<E> m) Reverses a slice(), inserting (under the control of a mask) the current vector as a slice within another "background" input vector, which is regarded as one or the other input to a hypothetical subsequentslice()operation.abstract Vector<?> Views this vector as a vector of the same shape, length, and contents, but a lane type that is a floating-point type.abstract Vector<?> Views this vector as a vector of the same shape, length, and contents, but a lane type that is not a floating-point type.
- 
Method Details- 
speciesReturns the species of this vector.- Returns:
- the species of this vector
 
- 
elementTypeReturns the primitive element type (ETYPE) of this vector.- Implementation Requirements:
- This is the same value as this.species().elementType().
- Returns:
- the primitive element type of this vector
 
- 
elementSizepublic abstract int elementSize()Returns the size of each lane, in bits, of this vector.- Implementation Requirements:
- This is the same value as this.species().elementSize().
- Returns:
- the lane size, in bits, of this vector
 
- 
shapeReturns the shape of this vector.- Implementation Requirements:
- This is the same value as this.species().vectorShape().
- Returns:
- the shape of this vector
 
- 
lengthpublic abstract int length()Returns the lane count, or vector length (VLENGTH).- Returns:
- the lane count
 
- 
bitSizepublic abstract int bitSize()Returns the total size, in bits, of this vector.- Implementation Requirements:
- This is the same value as this.shape().vectorBitSize().
- Returns:
- the total size, in bits, of this vector
 
- 
byteSizepublic abstract int byteSize()Returns the total size, in bytes, of this vector.- Implementation Requirements:
- This is the same value as this.bitSize()/Byte.SIZE.
- Returns:
- the total size, in bytes, of this vector
 
- 
lanewiseOperates on the lane values of this vector. This is a lane-wise unary operation which applies the selected operation to each lane.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to process lane values
- Returns:
- the result of applying the operation lane-wise to the input vector
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- See Also:
 
- 
lanewiseOperates 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.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to process lane values
- m- the mask controlling lane selection
- Returns:
- the result of applying the operation lane-wise to the input vector
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- See Also:
 
- 
lanewiseCombines the corresponding lane values of this vector with those of a second input vector. This is a lane-wise binary operation which applies the selected operation to each lane.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to combine lane values
- v- the input vector
- Returns:
- 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 Also:
 
- 
lanewiseCombines the corresponding lane values of this vector with those of a second input 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.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to combine lane values
- v- the second input vector
- m- the mask controlling lane selection
- Returns:
- 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 Also:
 
- 
lanewiseCombines the lane values of this vector with the value of a broadcast scalar. This is a lane-wise binary operation which applies the selected operation to each lane. The return value will be equal to this expression:this.lanewise(op, this.broadcast(e)).- API Note:
- The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. This rule is enforced by the implicit call tobroadcast().Subtypes improve on this method by sharpening the method return type and the type of the scalar parameter e.
- Parameters:
- op- the operation used to combine lane values
- e- the input scalar
- Returns:
- the result of applying the operation lane-wise to the input vector and the scalar
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- IllegalArgumentException- if the given- longvalue cannot be represented by the right operand type of the vector operation
- See Also:
 
- 
lanewiseCombines the corresponding lane values of this vector with those of a second input 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. The second operand is a broadcast integral value. The return value will be equal to this expression:this.lanewise(op, this.broadcast(e), m).- API Note:
- The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. This rule is enforced by the implicit call tobroadcast().Subtypes improve on this method by sharpening the method return type and the type of the scalar parameter e.
- Parameters:
- op- the operation used to combine lane values
- e- the input scalar
- m- the mask controlling lane selection
- Returns:
- the result of applying the operation lane-wise to the input vector and the scalar
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- IllegalArgumentException- if the given- longvalue cannot be represented by the right operand type of the vector operation
- See Also:
 
- 
lanewiseCombines the corresponding lane values of this vector with the lanes of a second and a third input vector. This is a lane-wise ternary operation which applies the selected operation to each lane.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to combine lane values
- v1- the second input vector
- v2- the third input vector
- Returns:
- 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 Also:
 
- 
lanewisepublic abstract Vector<E> lanewise(VectorOperators.Ternary op, Vector<E> v1, Vector<E> v2, VectorMask<E> m) Combines the corresponding lane values of this vector with the lanes of a second and a third input vector, with selection of lane elements controlled by a mask. This is a lane-wise ternary operation which applies the selected operation to each lane.- API Note:
- Subtypes improve on this method by sharpening the method return type.
- Parameters:
- op- the operation used to combine lane values
- v1- the second input vector
- v2- the third input vector
- m- the mask controlling lane selection
- Returns:
- 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 Also:
 
- 
addAdds this vector to a second input vector. This is a lane-wise binary operation which applies the primitive addition operation (+) to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(ADD, v).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- a second input vector
- Returns:
- the result of adding this vector to the second input vector
- See Also:
 
- 
addAdds this vector to a second input vector, selecting lanes under the control of a mask. This is a masked lane-wise binary operation which applies the primitive addition operation (+) to each pair of corresponding lane values. For any lane unset in the mask, the primitive operation is suppressed and this vector retains the original value stored in that lane. This method is also equivalent to the expressionlanewise(ADD, v, m).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- the second input vector
- m- the mask controlling lane selection
- Returns:
- the result of adding this vector to the given vector
- See Also:
 
- 
subSubtracts a second input vector from this vector. This is a lane-wise binary operation which applies the primitive subtraction operation (-) to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(SUB, v).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- a second input vector
- Returns:
- the result of subtracting the second input vector from this vector
- See Also:
 
- 
subSubtracts a second input vector from this vector under the control of a mask. This is a masked lane-wise binary operation which applies the primitive subtraction operation (-) to each pair of corresponding lane values. For any lane unset in the mask, the primitive operation is suppressed and this vector retains the original value stored in that lane. This method is also equivalent to the expressionlanewise(SUB, v, m).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- the second input vector
- m- the mask controlling lane selection
- Returns:
- the result of subtracting the second input vector from this vector
- See Also:
 
- 
mulMultiplies this vector by a second input vector. This is a lane-wise binary operation which applies the primitive multiplication operation (*) to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(MUL, v).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- a second input vector
- Returns:
- the result of multiplying this vector by the second input vector
- See Also:
 
- 
mulMultiplies this vector by a second input vector under the control of a mask. This is a lane-wise binary operation which applies the primitive multiplication operation (*) to each pair of corresponding lane values. For any lane unset in the mask, the primitive operation is suppressed and this vector retains the original value stored in that lane. This method is also equivalent to the expressionlanewise(MUL, v, m).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - Parameters:
- v- the second input vector
- m- the mask controlling lane selection
- Returns:
- the result of multiplying this vector by the given vector
- See Also:
 
- 
divDivides this vector by a second input vector. This is a lane-wise binary operation which applies the primitive division operation (/) to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(DIV, v).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - API Note:
- If the underlying scalar operator does not support
 division by zero, but is presented with a zero divisor,
 an ArithmeticExceptionwill be thrown.
- Parameters:
- v- a second input vector
- Returns:
- the result of dividing this vector by the second input vector
- Throws:
- ArithmeticException- if any lane in- vis zero and- ETYPEis not- floator- double.
- See Also:
 
- 
divDivides this vector by a second input vector under the control of a mask. This is a lane-wise binary operation which applies the primitive division operation (/) to each pair of corresponding lane values. For any lane unset in the mask, the primitive operation is suppressed and this vector retains the original value stored in that lane. This method is also equivalent to the expressionlanewise(DIV, v, m).As a full-service named operation, this method comes in masked and unmasked overloadings, and (in subclasses) also comes in scalar-broadcast overloadings (both masked and unmasked). - API Note:
- If the underlying scalar operator does not support
 division by zero, but is presented with a zero divisor,
 an ArithmeticExceptionwill be thrown.
- Parameters:
- v- a second input vector
- m- the mask controlling lane selection
- Returns:
- the result of dividing this vector by the second input vector
- Throws:
- ArithmeticException- if any lane selected by- min- vis zero and- ETYPEis not- floator- double.
- See Also:
 
- 
negNegates this vector. This is a lane-wise unary operation which applies the primitive negation operation (-x) to each input lane. This method is also equivalent to the expressionlanewise(NEG).- API Note:
- This method has no masked variant, but the corresponding masked operation can be obtained from the lanewise method.
- Returns:
- the negation of this vector
- See Also:
 
- 
absReturns the absolute value of this vector. This is a lane-wise unary operation which applies the methodMath.absto each input lane. This method is also equivalent to the expressionlanewise(ABS).- API Note:
- This method has no masked variant, but the corresponding masked operation can be obtained from the lanewise method.
- Returns:
- the absolute value of this vector
- See Also:
 
- 
minComputes the smaller of this vector and a second input vector. This is a lane-wise binary operation which applies the operationMath.min()to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(MIN, v).- API Note:
- This is not a full-service named operation like
 add(). A masked version of this operation is not directly available but may be obtained via the masked version oflanewise. Subclasses define an additional scalar-broadcast overloading of this method.
- Parameters:
- v- a second input vector
- Returns:
- the lanewise minimum of this vector and the second input vector
- See Also:
 
- 
maxComputes the larger of this vector and a second input vector. This is a lane-wise binary operation which applies the operationMath.max()to each pair of corresponding lane values. This method is also equivalent to the expressionlanewise(MAX, v).This is not a full-service named operation like add(). A masked version of this operation is not directly available but may be obtained via the masked version oflanewise. Subclasses define an additional scalar-broadcast overloading of this method.- Parameters:
- v- a second input vector
- Returns:
- the lanewise maximum of this vector and the second input vector
- See Also:
 
- 
reduceLanesToLongReturns a value accumulated from all the lanes of this vector. This is an associative cross-lane reduction operation which applies the specified operation to all the lane elements. The return value will be equal to this expression:(long) ((EVector)this).reduceLanes(op), whereEVectoris the vector class specific to this vector's element typeETYPE.In the case of operations ADDandMUL, whenETYPEisfloatordouble, the precise result, before casting, will reflect the choice of an arbitrary order of operations, which may even vary over time. For further details see the section Operations on floating point vectors.- API Note:
- If the ETYPEisfloatordouble, this operation can lose precision and/or range, as a normal part of casting the result down tolong. Usually strongly typed access is preferable, if you are working with a vector subtype that has a known element type.
- Parameters:
- op- the operation used to combine lane values
- Returns:
- the accumulated result, cast to long
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- See Also:
 
- 
reduceLanesToLongReturns a value accumulated from selected lanes of this vector, controlled by a mask. This is an associative cross-lane reduction operation which applies the specified operation to the selected lane elements. The return value will be equal to this expression:(long) ((EVector)this).reduceLanes(op, m), whereEVectoris the vector class specific to this vector's element typeETYPE.If no elements are selected, an operation-specific identity value is returned. - 
 If the operation is ADD,XOR, orOR, then the identity value is zero.
- 
 If the operation is MUL, then the identity value is one.
- 
 If the operation is AND, then the identity value is minus one (all bits set).
- 
 If the operation is MAX, then the identity value is theMIN_VALUEof the vector's nativeETYPE. (In the case of floating point types, the valueNEGATIVE_INFINITYis used, and will appear after casting asLong.MIN_VALUE.
- 
 If the operation is MIN, then the identity value is theMAX_VALUEof the vector's nativeETYPE. (In the case of floating point types, the valuePOSITIVE_INFINITYis used, and will appear after casting asLong.MAX_VALUE.
 In the case of operations ADDandMUL, whenETYPEisfloatordouble, the precise result, before casting, will reflect the choice of an arbitrary order of operations, which may even vary over time. For further details see the section Operations on floating point vectors.- API Note:
- If the ETYPEisfloatordouble, this operation can lose precision and/or range, as a normal part of casting the result down tolong. Usually strongly typed access is preferable, if you are working with a vector subtype that has a known element type.
- Parameters:
- op- the operation used to combine lane values
- m- the mask controlling lane selection
- Returns:
- the reduced result accumulated from the selected lane values
- Throws:
- UnsupportedOperationException- if this vector does not support the requested operation
- See Also:
 
- 
 If the operation is 
- 
testTests the lanes of this vector according to the given operation. This is a lane-wise unary test operation which applies the given test operation to each lane value.- Parameters:
- op- the operation used to test lane values
- Returns:
- the mask result of testing the lanes of this vector, according to the selected test operator
- See Also:
 
- 
testTest selected lanes of this vector, according to the given operation. This is a masked lane-wise unary test operation which applies the given test operation to each lane value. The returned result is equal to the expressiontest(op).and(m).- Parameters:
- op- the operation used to test lane values
- m- the mask controlling lane selection
- Returns:
- the mask result of testing the lanes of this vector, according to the selected test operator, and only in the lanes selected by the mask
- See Also:
 
- 
eqTests if this vector is equal to another input vector. This is a lane-wise binary test operation which applies the primitive equals operation (==) to each pair of corresponding lane values. The result is the same ascompare(VectorOperators.EQ, v).- Parameters:
- v- a second input vector
- Returns:
- the mask result of testing lane-wise if this vector equal to the second input vector
- See Also:
 
- 
ltTests if this vector is less than another input vector. This is a lane-wise binary test operation which applies the primitive less-than operation (<) to each lane. The result is the same ascompare(VectorOperators.LT, v).- Parameters:
- v- a second input vector
- Returns:
- the mask result of testing lane-wise if this vector is less than the second input vector
- See Also:
 
- 
compareTests this vector by comparing it with another input vector, according to the given comparison operation. This is a lane-wise binary test operation which applies the given comparison operation to each pair of corresponding lane values.- Parameters:
- op- the operation used to compare lane values
- v- a second input vector
- Returns:
- the mask result of testing lane-wise if this vector compares to the input, according to the selected comparison operator
- See Also:
 
- 
compareTests this vector by comparing it with another input vector, according to the given comparison operation, in lanes selected by a mask. This is a masked lane-wise binary test operation which applies the given comparison operation to each pair of corresponding lane values. The returned result is equal to the expressioncompare(op,v).and(m).- Parameters:
- op- the operation used to compare lane values
- v- a second input vector
- m- the mask controlling lane selection
- Returns:
- the mask result of testing lane-wise if this vector compares to the input, according to the selected comparison operator, and only in the lanes selected by the mask
- See Also:
 
- 
compareTests this vector by comparing it with an input scalar, according to the given comparison operation. This is a lane-wise binary test operation which applies the given comparison operation to each lane value, paired with the broadcast value.The result is the same as this.compare(op, this.broadcast(e)). That is, the scalar may be regarded as broadcast to a vector of the same species, and then compared against the original vector, using the selected comparison operation.- API Note:
- The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. This rule is enforced by the implicit call tobroadcast().Subtypes improve on this method by sharpening the type of the scalar parameter e.
- Parameters:
- op- the operation used to compare lane values
- e- the input scalar
- Returns:
- the mask result of testing lane-wise if this vector compares to the input, according to the selected comparison operator
- Throws:
- IllegalArgumentException- if the given- longvalue cannot be represented by the vector's- ETYPE
- See Also:
 
- 
compareTests this vector by comparing it with an input scalar, according to the given comparison operation, in lanes selected by a mask. This is a masked lane-wise binary test operation which applies the given comparison operation to each lane value, paired with the broadcast value. The returned result is equal to the expressioncompare(op,e).and(m).- API Note:
- The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. This rule is enforced by the implicit call tobroadcast().Subtypes improve on this method by sharpening the type of the scalar parameter e.
- Parameters:
- op- the operation used to compare lane values
- e- the input scalar
- m- the mask controlling lane selection
- Returns:
- the mask result of testing lane-wise if this vector compares to the input, according to the selected comparison operator, and only in the lanes selected by the mask
- Throws:
- IllegalArgumentException- if the given- longvalue cannot be represented by the vector's- ETYPE
- See Also:
 
- 
blendReplaces selected lanes of this vector with corresponding lanes from a second input vector under the control of a mask. This is a masked lane-wise binary operation which selects each lane value from one or the other input.- For any lane set in the mask, the new lane value is taken from the second input vector, and replaces whatever value was in the that lane of this vector.
- For any lane unset in the mask, the replacement is suppressed and this vector retains the original value stored in that lane.
 Vector<E> a = ...; VectorSpecies<E> species = a.species(); Vector<E> b = ...; b.check(species); VectorMask<E> m = ...; ETYPE[] ar = a.toArray(); for (int i = 0; i < ar.length; i++) { if (m.laneIsSet(i)) { ar[i] = b.lane(i); } } return EVector.fromArray(s, ar, 0);- Parameters:
- v- the second input vector, containing replacement lane values
- m- the mask controlling lane selection from the second input vector
- Returns:
- the result of blending the lane elements of this vector with those of the second input vector
 
- 
blendReplaces selected lanes of this vector with a scalar value under the control of a mask. This is a masked lane-wise binary operation which selects each lane value from one or the other input. The returned result is equal to the expressionblend(broadcast(e),m).- API Note:
- The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. This rule is enforced by the implicit call tobroadcast().Subtypes improve on this method by sharpening the type of the scalar parameter e.
- Parameters:
- e- the input scalar, containing the replacement lane value
- m- the mask controlling lane selection of the scalar
- Returns:
- the result of blending the lane elements of this vector with the scalar value
 
- 
addIndexAdds the lanes of this vector to their corresponding lane numbers, scaled by a given constant. This is a lane-wise unary operation which, for each laneN, computes the scaled index valueN*scaleand adds it to the value already in laneNof the current vector.The scale must not be so large, and the element size must not be so small, that that there would be an overflow when computing any of the N*scaleorVLENGTH*scale, when the result is represented using the vector lane typeETYPE.The following pseudocode illustrates this behavior: Vector<E> a = ...; VectorSpecies<E> species = a.species(); ETYPE[] ar = a.toArray(); for (int i = 0; i < ar.length; i++) { long d = (long)i * scale; if (d != (ETYPE) d) throw ...; ar[i] += (ETYPE) d; } long d = (long)ar.length * scale; if (d != (ETYPE) d) throw ...; return EVector.fromArray(s, ar, 0);- Parameters:
- scale- the number to multiply by each lane index- N, typically- 1
- Returns:
- the result of incrementing each lane element by its
         corresponding lane index N, scaled byscale
- Throws:
- IllegalArgumentException- if the values in the interval- [0..VLENGTH*scale]are not representable by the- ETYPE
 
- 
sliceSlices a segment of adjacent lanes, starting at a givenoriginlane in the current vector, and continuing (as needed) into an immediately following vector. The block ofVLENGTHlanes is extracted into its own vector and returned.This is a cross-lane operation that shifts lane elements to the front, from the current vector and the second vector. Both vectors can be viewed as a combined "background" of length 2*VLENGTH, from which a slice is extracted. The lane numberedNin the output vector is copied from laneorigin+Nof the input vector, if that lane exists, else from laneorigin+N-VLENGTHof the second vector (which is guaranteed to exist).The originvalue must be in the inclusive range0..VLENGTH. As limiting cases,v.slice(0,w)andv.slice(VLENGTH,w)returnvandw, respectively.- API Note:
- This method may be regarded as the inverse of
 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:EVector slice = v1.slice(origin, v2); EVector w1 = slice.unslice(origin, v1, 0); EVector w2 = slice.unslice(origin, v2, 1); assert v1.equals(w1); assert v2.equals(w2);This method also supports a variety of cross-lane shifts and rotates as follows: - To shift lanes forward to the front of the vector, supply a
 zero vector for the second operand and specify the shift count
 as the origin.  For example: v.slice(shift, v.broadcast(0)).
- To shift lanes backward to the back of the vector, supply a
 zero vector for the first operand, and specify the
 negative shift count as the origin (modulo VLENGTH. For example:v.broadcast(0).slice(v.length()-shift, v).
- To rotate lanes forward toward the front end of the vector,
 cycling the earliest lanes around to the back, supply the same
 vector for both operands and specify the rotate count as the
 origin.  For example: v.slice(rotate, v).
- To rotate lanes backward toward the back end of the vector,
 cycling the latest lanes around to the front, supply the same
 vector for both operands and specify the negative of the rotate
 count (modulo VLENGTH) as the origin. For example:v.slice(v.length() - rotate, v).
- 
 Since originvalues less then zero or more thanVLENGTHwill be rejected, if you need to rotate by an unpredictable multiple ofVLENGTH, be sure to reduce the origin value into the required range. TheloopBound()method can help with this. For example:v.slice(rotate - v.species().loopBound(rotate), v).
 
- To shift lanes forward to the front of the vector, supply a
 zero vector for the second operand and specify the shift count
 as the origin.  For example: 
- Parameters:
- origin- the first input lane to transfer into the slice
- v1- a second vector logically concatenated with the first, before the slice is taken (if omitted it defaults to zero)
- Returns:
- a contiguous slice of VLENGTHlanes, taken from this vector starting at the indicated origin, and continuing (as needed) into the second vector
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH
- See Also:
 
- 
sliceSlices a segment of adjacent lanes under the control of a mask, starting at a givenoriginlane in the current vector, and continuing (as needed) into an immediately following vector. The block ofVLENGTHlanes is extracted into its own vector and returned. The resulting vector will be zero in all lanes unset in the given mask. Lanes set in the mask will contain data copied from selected lanes ofthisorv1.This is a cross-lane operation that shifts lane elements to the front, from the current vector and the second vector. Both vectors can be viewed as a combined "background" of length 2*VLENGTH, from which a slice is extracted. The returned result is equal to the expressionbroadcast(0).blend(slice(origin,v1),m).- API Note:
- This method may be regarded as the inverse of
 #unslice(int,Vector,int,VectorMask) 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:EVector slice = v1.slice(origin, v2, m); EVector w1 = slice.unslice(origin, v1, 0, m); EVector w2 = slice.unslice(origin, v2, 1, m); assert v1.equals(w1); assert v2.equals(w2);
- Parameters:
- origin- the first input lane to transfer into the slice
- v1- a second vector logically concatenated with the first, before the slice is taken (if omitted it defaults to zero)
- m- the mask controlling lane selection into the resulting vector
- Returns:
- a contiguous slice of VLENGTHlanes, taken from this vector starting at the indicated origin, and continuing (as needed) into the second vector
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH
- See Also:
 
- 
sliceSlices a segment of adjacent lanes, starting at a givenoriginlane in the current vector. A block ofVLENGTHlanes, possibly padded with zero lanes, is extracted into its own vector and returned. This is a convenience method which slices from a single vector against an extended background of zero lanes. It is equivalent toslice(origin,broadcast(0)). It may also be viewed simply as a cross-lane shift from later to earlier lanes, with zeroes filling in the vacated lanes at the end of the vector. In this view, the shift count isorigin.- Parameters:
- origin- the first input lane to transfer into the slice
- Returns:
- the last VLENGTH-origininput lanes, placed starting in the first lane of the output, padded at the end with zeroes
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH
- See Also:
 
- 
unsliceReverses a slice(), inserting the current vector as a slice within another "background" input vector, which is regarded as one or the other input to a hypothetical subsequentslice()operation.This is a cross-lane operation that permutes the lane elements of the current vector toward the back and inserts them into a logical pair of background vectors. Only one of the pair will be returned, however. The background is formed by duplicating the second input vector. (However, the output will never contain two duplicates from the same input lane.) The lane numbered Nin the input vector is copied into laneorigin+Nof the first background vector, if that lane exists, else into laneorigin+N-VLENGTHof the second background vector (which is guaranteed to exist). The first or second background vector, updated with the inserted slice, is returned. Thepartnumber of zero or one selects the first or second updated background vector.The originvalue must be in the inclusive range0..VLENGTH. As limiting cases,v.unslice(0,w,0)andv.unslice(VLENGTH,w,1)both returnv, whilev.unslice(0,w,1)andv.unslice(VLENGTH,w,0)both returnw.- API Note:
- This method supports a variety of cross-lane insertion
 operations as follows:
 - To insert near the end of a background vector wat some offset, specify the offset as the origin and select part zero. For example:v.unslice(offset, w, 0).
- To insert near the end of a background vector w, but capturing the overflow into the next vectorx, specify the offset as the origin and select part one. For example:v.unslice(offset, x, 1).
- To insert the last Nitems near the beginning of a background vectorw, supply aVLENGTH-Nas the origin and select part one. For example:v.unslice(v.length()-N, w).
 
- To insert near the end of a background vector 
- Parameters:
- origin- the first output lane to receive the slice
- w- the background vector that (as two copies) will receive the inserted slice
- part- the part number of the result (either zero or one)
- Returns:
- either the first or second part of a pair of
         background vectors w, updated by inserting this vector at the indicated origin
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH, or if- partis not zero or one
- See Also:
 
- 
unsliceReverses a slice(), inserting (under the control of a mask) the current vector as a slice within another "background" input vector, which is regarded as one or the other input to a hypothetical subsequentslice()operation.This is a cross-lane operation that permutes the lane elements of the current vector forward and inserts its lanes (when selected by the mask) into a logical pair of background vectors. As with the unmasked version of this method, only one of the pair will be returned, as selected by the partnumber. For each laneNselected by the mask, the lane value is copied into laneorigin+Nof the first background vector, if that lane exists, else into laneorigin+N-VLENGTHof the second background vector (which is guaranteed to exist). Background lanes retain their original values if the corresponding input lanesNare unset in the mask. The first or second background vector, updated with set lanes of the inserted slice, is returned. Thepartnumber of zero or one selects the first or second updated background vector.- Parameters:
- origin- the first output lane to receive the slice
- w- the background vector that (as two copies) will receive the inserted slice, if they are set in- m
- part- the part number of the result (either zero or one)
- m- the mask controlling lane selection from the current vector
- Returns:
- either the first or second part of a pair of
         background vectors w, updated by inserting selected lanes of this vector at the indicated origin
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH, or if- partis not zero or one
- See Also:
 
- 
unsliceReverses a slice(), inserting the current vector as a slice within a "background" input of zero lane values. Compared to otherunslice()methods, this method only returns the first of the pair of background vectors. This is a convenience method which returns the result ofunslice(origin,broadcast(0), 0). It may also be viewed simply as a cross-lane shift from earlier to later lanes, with zeroes filling in the vacated lanes at the beginning of the vector. In this view, the shift count isorigin.- Parameters:
- origin- the first output lane to receive the slice
- Returns:
- the first VLENGTH-origininput lanes, placed starting at the given origin, padded at the beginning with zeroes
- Throws:
- ArrayIndexOutOfBoundsException- if- originis negative or greater than- VLENGTH
- See Also:
 
- 
rearrangeRearranges the lane elements of this vector, selecting lanes under the control of a specific shuffle. This is a cross-lane operation that rearranges the lane elements of this vector. For each laneNof the shuffle, and for each lane source indexI=s.laneSource(N)in the shuffle, the output laneNobtains the value from the input vector at laneI.- Parameters:
- s- the shuffle controlling lane index selection
- Returns:
- the rearrangement of the lane elements of this vector
- Throws:
- IndexOutOfBoundsException- if there are any exceptional source indexes in the shuffle
- See Also:
 
- 
rearrangeRearranges the lane elements of this vector, selecting lanes under the control of a specific shuffle and a mask. This is a cross-lane operation that rearranges the lane elements of this vector. For each laneNof the shuffle, and for each lane source indexI=s.laneSource(N)in the shuffle, the output laneNobtains the value from the input vector at laneIif the mask is set. Otherwise the output laneNis set to zero.This method returns the value of this pseudocode: Vector<E> r = this.rearrange(s.wrapIndexes()); VectorMask<E> valid = s.laneIsValid(); if (m.andNot(valid).anyTrue()) throw ...; return broadcast(0).blend(r, m);- Parameters:
- s- the shuffle controlling lane index selection
- m- the mask controlling application of the shuffle
- Returns:
- 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 Also:
 
- 
rearrangeRearranges the lane elements of two vectors, selecting lanes under the control of a specific shuffle, using both normal and exceptional indexes in the shuffle to steer data. This is a cross-lane operation that rearranges the lane elements of the two input vectors (the current vector and a second vectorv). For each laneNof the shuffle, and for each lane source indexI=s.laneSource(N)in the shuffle, the output laneNobtains the value from the first vector at laneIifI>=0. Otherwise, the exceptional indexIis wrapped by addingVLENGTHto it and used to index the second vector, at indexI+VLENGTH.This method returns the value of this pseudocode: Vector<E> r1 = this.rearrange(s.wrapIndexes()); // or else: r1 = this.rearrange(s, s.laneIsValid()); Vector<E> r2 = v.rearrange(s.wrapIndexes()); return r2.blend(r1,s.laneIsValid());- Parameters:
- s- the shuffle controlling lane selection from both input vectors
- v- the second input vector
- Returns:
- the rearrangement of lane elements of this vector and a second input vector
- See Also:
 
- 
compressCompresses the lane elements of this vector selecting lanes under the control of a specific mask. This is a cross-lane operation that compresses the lane elements of this vector as selected by the specified mask. For each laneNof the mask, if the mask at laneNis set, the element at laneNof input vector is selected and stored into the output vector contiguously starting from the lane0. All the upper remaining lanes, if any, of the output vector are set to zero.- Parameters:
- m- the mask controlling the compression
- Returns:
- the compressed lane elements of this vector
- Since:
- 19
 
- 
expandExpands the lane elements of this vector under the control of a specific mask. This is a cross-lane operation that expands the contiguous lane elements of this vector into lanes of an output vector as selected by the specified mask. For each laneNof the mask, if the mask at laneNis set, the next contiguous element of input vector starting from lane0is selected and stored into the output vector at laneN. All the remaining lanes, if any, of the output vector are set to zero.- Parameters:
- m- the mask controlling the compression
- Returns:
- the expanded lane elements of this vector
- Since:
- 19
 
- 
selectFromUsing index values stored in the lanes of this vector, assemble values stored in second vectorv. The second vector thus serves as a table, whose elements are selected by indexes in the current vector. This is a cross-lane operation that rearranges the lane elements of the argument vector, under the control of this vector. For each laneNof this vector, and for each lane valueI=this.lane(N)in this vector, the output laneNobtains the value from the argument vector at laneI. In this way, the result contains only values stored in the argument vectorv, but presented in an order which depends on the index values inthis. The result is the same as the expressionv.rearrange(this.toShuffle()).- Parameters:
- v- the vector supplying the result values
- Returns:
- the rearrangement of the lane elements of v
- Throws:
- IndexOutOfBoundsException- if any invalid source indexes are found in- this
- See Also:
 
- 
selectFromUsing index values stored in the lanes of this vector, assemble values stored in second vector, under the control of a mask. Using index values stored in the lanes of this vector, assemble values stored in second vectorv. The second vector thus serves as a table, whose elements are selected by indexes in the current vector. Lanes that are unset in the mask receive a zero rather than a value from the table. This is a cross-lane operation that rearranges the lane elements of the argument vector, under the control of this vector and the mask. The result is the same as the expressionv.rearrange(this.toShuffle(), m).- Parameters:
- v- the vector supplying the result values
- m- the mask controlling selection from- v
- Returns:
- the rearrangement of the lane elements of v
- Throws:
- IndexOutOfBoundsException- if any invalid source indexes are found in- this, in a lane which is set in the mask
- See Also:
 
- 
broadcastReturns a vector of the same species as this one where all lane elements are set to the primitive valuee. The contents of the current vector are discarded; only the species is relevant to this operation.This method returns the value of this expression: EVector.broadcast(this.species(), (ETYPE)e), whereEVectoris the vector class specific to this vector's element typeETYPE.The longvalueemust be accurately representable by theETYPEof this vector's species, so thate==(long)(ETYPE)e. If this rule is violated the problem is not detected statically, but anIllegalArgumentExceptionis thrown at run-time. Thus, this method somewhat weakens the static type checking of immediate constants and other scalars, but it makes up for this by improving the expressiveness of the generic API. Note that anevalue in the range[-128..127]is always acceptable, since everyETYPEwill accept everybytevalue.- API Note:
- Subtypes improve on this method by sharpening
 the method return type and
 and the type of the scalar parameter e.
- Parameters:
- e- the value to broadcast
- Returns:
- a vector where all lane elements are set to
         the primitive value e
- Throws:
- IllegalArgumentException- if the given- longvalue cannot be represented by the vector's- ETYPE
- See Also:
 
- 
maskAllReturns a mask of same species as this vector, where each lane is set or unset according to given single boolean, which is broadcast to all lanes.This method returns the value of this expression: species().maskAll(bit).- Parameters:
- bit- the given mask bit to be replicated
- Returns:
- a mask where each lane is set or unset according to the given bit
- See Also:
 
- 
toShuffleConverts this vector into a shuffle, converting the lane values tointand regarding them as source indexes.This method behaves as if it returns the result of creating a shuffle given an array of the vector elements, as follows: long[] a = this.toLongArray(); int[] sa = new int[a.length]; for (int i = 0; i < a.length; i++) { sa[i] = (int) a[i]; } return VectorShuffle.fromValues(this.species(), sa);- Returns:
- a shuffle representation of this vector
- See Also:
 
- 
reinterpretShapeTransforms this vector to a vector of the given species of element typeF, reinterpreting the bytes of this vector without performing any value conversions.Depending on the selected species, this operation may either expand or contract its logical result, in which case a non-zero partnumber can further control the selection and steering of the logical result into the physical output vector.The underlying bits of this vector are copied to the resulting vector without modification, but those bits, before copying, may be truncated if the this vector's bit-size is greater than desired vector's bit size, or filled with zero bits if this vector's bit-size is less than desired vector's bit-size. If the old and new species have different shape, this is a shape-changing operation, and may have special implementation costs. The method behaves as if this vector is stored into a byte array using little-endian byte ordering and then the desired vector is loaded from the same byte array using the same ordering. The following pseudocode illustrates the behavior: int domSize = this.byteSize(); int ranSize = species.vectorByteSize(); int M = (domSize > ranSize ? domSize / ranSize : ranSize / domSize); assert Math.abs(part) < M; assert (part == 0) || (part > 0) == (domSize > ranSize); MemorySegment ms = MemorySegment.ofArray(new byte[Math.max(domSize, ranSize)]); if (domSize > ranSize) { // expansion this.intoMemorySegment(ms, 0, ByteOrder.native()); int origin = part * ranSize; return species.fromMemorySegment(ms, origin, ByteOrder.native()); } else { // contraction or size-invariant int origin = (-part) * domSize; this.intoMemorySegment(ms, origin, ByteOrder.native()); return species.fromMemorySegment(ms, 0, ByteOrder.native()); }- API Note:
- Although this method is defined as if the vectors in 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.
- Type Parameters:
- F- the boxed element type of the species
- Parameters:
- species- the desired vector species
- part- the part number of the result, or zero if neither expanding nor contracting
- Returns:
- a vector transformed, by shape and element type, from this vector
- See Also:
 
- 
reinterpretAsBytesViews this vector as a vector of the same shape and contents but a lane type ofbyte, where the bytes are extracted from the lanes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(byte.class)). It may be considered an inverse to the various methods which consolidate bytes into larger lanes within the same vector, such asreinterpretAsInts().- Returns:
- a ByteVectorwith the same shape and information content
- See Also:
 
- 
reinterpretAsShortsReinterprets this vector as a vector of the same shape and contents but a lane type ofshort, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(short.class)). It may be considered an inverse toreinterpretAsBytes().- Returns:
- a ShortVectorwith the same shape and information content
 
- 
reinterpretAsIntsReinterprets this vector as a vector of the same shape and contents but a lane type ofint, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(int.class)). It may be considered an inverse toreinterpretAsBytes().- Returns:
- a IntVectorwith the same shape and information content
 
- 
reinterpretAsLongsReinterprets this vector as a vector of the same shape and contents but a lane type oflong, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(long.class)). It may be considered an inverse toreinterpretAsBytes().- Returns:
- a LongVectorwith the same shape and information content
 
- 
reinterpretAsFloatsReinterprets this vector as a vector of the same shape and contents but a lane type offloat, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(float.class)). It may be considered an inverse toreinterpretAsBytes().- Returns:
- a FloatVectorwith the same shape and information content
 
- 
reinterpretAsDoublesReinterprets this vector as a vector of the same shape and contents but a lane type ofdouble, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expressionreinterpretShape(species().withLanes(double.class)). It may be considered an inverse toreinterpretAsBytes().- Returns:
- a DoubleVectorwith the same shape and information content
 
- 
viewAsIntegralLanesViews this vector as a vector of the same shape, length, and contents, but a lane type that is not a floating-point type. This is a lane-wise reinterpretation cast on the lane values. As such, this method does not changeVSHAPEorVLENGTH, and there is no change to the bitwise contents of the vector. If the vector'sETYPEis already an integral type, the same vector is returned unchanged. This method returns the value of this expression:convert(conv,0), whereconvisVectorOperators.Conversion.ofReinterpret(E.class,F.class), andFis the non-floating-point type of the same size asE.- API Note:
- Subtypes improve on this method by sharpening the return type.
- Returns:
- the original vector, reinterpreted as non-floating point
- See Also:
 
- 
viewAsFloatingLanesViews this vector as a vector of the same shape, length, and contents, but a lane type that is a floating-point type. This is a lane-wise reinterpretation cast on the lane values. As such, there this method does not changeVSHAPEorVLENGTH, and there is no change to the bitwise contents of the vector. If the vector'sETYPEis already a float-point type, the same vector is returned unchanged. If the vector's element size does not match any floating point type size, anIllegalArgumentExceptionis thrown. This method returns the value of this expression:convert(conv,0), whereconvisVectorOperators.Conversion.ofReinterpret(E.class,F.class), andFis the floating-point type of the same size asE, if any.- API Note:
- Subtypes improve on this method by sharpening the return type.
- Returns:
- the original vector, reinterpreted as floating point
- Throws:
- UnsupportedOperationException- if there is no floating point type the same size as the lanes of this vector
- See Also:
 
- 
convertConvert this vector to a vector of the same shape and a new element type, converting lane values from the currentETYPEto a new lane type (calledFTYPEhere) according to the indicated conversion. This is a lane-wise shape-invariant operation which copiesETYPEvalues from the input vector to correspondingFTYPEvalues in the result. Depending on the selected conversion, this operation may either expand or contract its logical result, in which case a non-zeropartnumber can further control the selection and steering of the logical result into the physical output vector.Each specific conversion is described by a conversion constant in the class VectorOperators. Each conversion operator has a specified domain type and range type. The domain type must exactly match the lane type of the input vector, while the range type determines the lane type of the output vectors.A conversion operator may be classified as (respectively) in-place, expanding, or contracting, depending on whether the bit-size of its domain type is (respectively) equal, less than, or greater than the bit-size of its range type. Independently, conversion operations can also be classified as reinterpreting or value-transforming, depending on whether the conversion copies representation bits unchanged, or changes the representation bits in order to retain (part or all of) the logical value of the input value. If a reinterpreting conversion contracts, it will truncate the upper bits of the input. If it expands, it will pad upper bits of the output with zero bits, when there are no corresponding input bits. An expanding conversion such as S2I(shortvalue toint) takes a scalar value and represents it in a larger format (always with some information redundancy). A contracting conversion such asD2F(doublevalue tofloat) takes a scalar value and represents it in a smaller format (always with some information loss). Some in-place conversions may also include information loss, such asL2D(longvalue todouble) orF2I(floatvalue toint). Reinterpreting in-place conversions are not lossy, unless the bitwise value is somehow not legal in the output type. Converting the bit-pattern of aNaNmay discard bits from theNaN's significand.This classification is important, because, unless otherwise documented, conversion operations never change vector shape, regardless of how they may change lane sizes. Therefore an expanding conversion cannot store all of its results in its output vector, because the output vector has fewer lanes of larger size, in order to have the same overall bit-size as its input. Likewise, a contracting conversion must store its relatively small results into a subset of the lanes of the output vector, defaulting the unused lanes to zero. As an example, a conversion from bytetolong(M=8) will discard 87.5% of the input values in order to convert the remaining 12.5% into the roomylonglanes of the output vector. The inverse conversion will convert back all of the large results, but will waste 87.5% of the lanes in the output vector. In-place conversions (M=1) deliver all of their results in one output vector, without wasting lanes.To manage the details of these expansions and contractions, a non-zero partparameter selects partial results from expansions, or steers the results of contractions into corresponding locations, as follows:-  expanding by M:partmust be in the range[0..M-1], and selects the block ofVLENGTH/Minput lanes starting at the origin lane atpart*VLENGTH/M.The VLENGTH/Moutput lanes represent a partial slice of the whole logical result of the conversion, filling the entire physical output vector.
-  contracting by M:partmust be in the range[-M+1..0], and steers allVLENGTHinput lanes into the output located at the origin lane-part*VLENGTH. There is a total ofVLENGTH*Moutput lanes, and those not holding converted input values are filled with zeroes.A group of such output vectors, with logical result parts steered to disjoint blocks, can be reassembled using the bitwise or or (for floating point) the FIRST_NONZEROoperator.
-  in-place (M=1):partmust be zero. Both vectors have the sameVLENGTH. The result is always positioned at the origin lane of zero.
 This method is a restricted version of the more general but less frequently used shape-changing method convertShape(). The result of this method is the same as the expressionthis.convertShape(conv, rsp, this.broadcast(part)), where the output species isrsp=this.species().withLanes(FTYPE.class).- Type Parameters:
- F- the boxed element type of the species
- Parameters:
- conv- the desired scalar conversion to apply lane-wise
- part- the part number of the result, or zero if neither expanding nor contracting
- Returns:
- a vector converted by shape and element type from this vector
- Throws:
- ArrayIndexOutOfBoundsException- unless- partis zero, or else the expansion ratio is- Mand- partis positive and less than- M, or else the contraction ratio is- Mand- partis negative and greater- -M
- See Also:
 
-  expanding by 
- 
convertShapepublic abstract <F> Vector<F> convertShape(VectorOperators.Conversion<E, F> conv, VectorSpecies<F> rsp, int part) Converts this vector to a vector of the given species, shape and element type, converting lane values from the currentETYPEto a new lane type (calledFTYPEhere) according to the indicated conversion. This is a lane-wise operation which copiesETYPEvalues from the input vector to correspondingFTYPEvalues in the result.If the old and new species have the same shape, the behavior is exactly the same as the simpler, shape-invariant method convert(). In such cases, the simpler methodconvert()should be used, to make code easier to reason about. Otherwise, this is a shape-changing operation, and may have special implementation costs.As a combined effect of shape changes and lane size changes, the input and output species may have different lane counts, causing expansion or contraction. In this case a non-zero partparameter selects partial results from an expanded logical result, or steers the results of a contracted logical result into a physical output vector of the required output species.The following pseudocode illustrates the behavior of this method for in-place, expanding, and contracting conversions. (This pseudocode also applies to the shape-invariant method, but with shape restrictions on the output species.) Note that only one of the three code paths is relevant to any particular combination of conversion operator and shapes. FTYPE scalar_conversion_op(ETYPE s); EVector a = ...; VectorSpecies<F> rsp = ...; int part = ...; VectorSpecies<E> dsp = a.species(); int domlen = dsp.length(); int ranlen = rsp.length(); FTYPE[] logical = new FTYPE[domlen]; for (int i = 0; i < domlen; i++) { logical[i] = scalar_conversion_op(a.lane(i)); } FTYPE[] physical; if (domlen == ranlen) { // in-place assert part == 0; //else AIOOBE physical = logical; } else if (domlen > ranlen) { // expanding int M = domlen / ranlen; assert 0 <= part && part < M; //else AIOOBE int origin = part * ranlen; physical = Arrays.copyOfRange(logical, origin, origin + ranlen); } else { // (domlen < ranlen) // contracting int M = ranlen / domlen; assert 0 >= part && part > -M; //else AIOOBE int origin = -part * domlen; System.arraycopy(logical, 0, physical, origin, domlen); } return FVector.fromArray(ran, physical, 0);- Type Parameters:
- F- the boxed element type of the output species
- Parameters:
- conv- the desired scalar conversion to apply lane-wise
- rsp- the desired output species
- part- the part number of the result, or zero if neither expanding nor contracting
- Returns:
- a vector converted by element type from this vector
- See Also:
 
- 
castShapeConvenience method for converting a vector from one lane type to another, reshaping as needed when lane sizes change. This method returns the value of this expression:convertShape(conv,rsp,part), whereconvisVectorOperators.Conversion.ofCast(E.class,F.class).If the old and new species have different shape, this is a shape-changing operation, and may have special implementation costs. - Type Parameters:
- F- the boxed element type of the output species
- Parameters:
- rsp- the desired output species
- part- the part number of the result, or zero if neither expanding nor contracting
- Returns:
- a vector converted by element type from this vector
- See Also:
 
- 
checkChecks that this vector has the given element type, and returns this vector unchanged. The effect is similar to this pseudocode:elementType == species().elementType() ? this : throw new ClassCastException().- Type Parameters:
- F- the boxed element type of the required lane type
- Parameters:
- elementType- the required lane type
- Returns:
- the same vector
- Throws:
- ClassCastException- if the vector has the wrong element type
- See Also:
 
- 
checkChecks that this vector has the given species, and returns this vector unchanged. The effect is similar to this pseudocode:species == species() ? this : throw new ClassCastException().- Type Parameters:
- F- the boxed element type of the required species
- Parameters:
- species- the required species
- Returns:
- the same vector
- Throws:
- ClassCastException- if the vector has the wrong species
- See Also:
 
- 
intoMemorySegmentStores this vector into a memory segmentPREVIEW starting at an offset using explicit byte order.Bytes are extracted from primitive lane elements according to the specified byte ordering. The lanes are stored according to their memory ordering. This method behaves as if it calls intoMemorySegment()PREVIEW as follows:var m = maskAll(true); intoMemorySegment(ms, offset, bo, m);- Parameters:
- ms- the memory segment
- offset- the offset into the memory segment
- bo- the intended byte order
- Throws:
- IndexOutOfBoundsException- if- offset+N*ESIZE < 0or- offset+(N+1)*ESIZE > ms.byteSize()for any lane- Nin the vector
- UnsupportedOperationException- if the memory segment is read-only
- IllegalArgumentException- if the memory segment is a heap segment that is not backed by a- byte[]array.
- IllegalStateException- if the memory segment's session is not alive, or if access occurs from a thread other than the thread owning the session.
- Since:
- 19
 
- 
intoMemorySegmentpublic abstract void intoMemorySegment(MemorySegmentPREVIEW ms, long offset, ByteOrder bo, VectorMask<E> m) Stores this vector into a memory segmentPREVIEW starting at an offset using explicit byte order and a mask.Bytes are extracted from primitive lane elements according to the specified byte ordering. The lanes are stored according to their memory ordering. The following pseudocode illustrates the behavior, where JAVA_Eis the layout of the primitive element type,ETYPEis the primitive element type, andEVectoris the primitive vector type for this vector:ETYPE[] a = this.toArray(); var slice = ms.asSlice(offset) for (int n = 0; n < a.length; n++) { if (m.laneIsSet(n)) { slice.setAtIndex(ValueLayout.JAVA_E.withBitAlignment(8), n); } }- Implementation Note:
- This operation is likely to be more efficient if
 the specified byte order is the same as
 the platform native order,
 since this method will not need to reorder
 the bytes of lane values.
 In the special case where ETYPEisbyte, the byte order argument is ignored.
- Parameters:
- ms- the memory segment
- offset- the offset into the memory segment
- bo- the intended byte order
- m- the mask controlling lane selection
- Throws:
- IndexOutOfBoundsException- if- offset+N*ESIZE < 0or- offset+(N+1)*ESIZE > ms.byteSize()for any lane- Nin the vector where the mask is set
- UnsupportedOperationException- if the memory segment is read-only
- IllegalArgumentException- if the memory segment is a heap segment that is not backed by a- byte[]array.
- IllegalStateException- if the memory segment's session is not alive, or if access occurs from a thread other than the thread owning the session.
- Since:
- 19
 
- 
toArrayReturns a packed array containing all the lane values. The array length is the same as the vector length. The element type of the array is the same as the element type of the vector. The array elements are stored in lane order. Overrides of this method on subtypes ofVectorwhich specify the element type have an accurately typed array result.- API Note:
- Usually strongly typed access is preferable, if you are working with a vector subtype that has a known element type.
- Returns:
- an accurately typed array containing the lane values of this vector
- See Also:
 
- 
toIntArraypublic abstract int[] toIntArray()Returns anint[]array containing all the lane values, converted to the typeint. The array length is the same as the vector length. The array elements are converted as if by casting and stored in lane order. This operation may fail if the vector element type isfloatordouble, when lanes contain fractional or out-of-range values. If any vector lane value is not representable as anint, an exception is thrown.- API Note:
- Usually strongly typed access is preferable, if you are working with a vector subtype that has a known element type.
- Returns:
- an int[]array containing the lane values of this vector
- Throws:
- UnsupportedOperationException- if any lane value cannot be represented as an- intarray element
- See Also:
 
- 
toLongArraypublic abstract long[] toLongArray()Returns along[]array containing all the lane values, converted to the typelong. The array length is the same as the vector length. The array elements are converted as if by casting and stored in lane order. This operation may fail if the vector element type isfloatordouble, when lanes contain fractional or out-of-range values. If any vector lane value is not representable as along, an exception is thrown.- API Note:
- Usually strongly typed access is preferable, if you are working with a vector subtype that has a known element type.
- Returns:
- a long[]array containing the lane values of this vector
- Throws:
- UnsupportedOperationException- if any lane value cannot be represented as a- longarray element
- See Also:
 
- 
toDoubleArraypublic abstract double[] toDoubleArray()Returns adouble[]array containing all the lane values, converted to the typedouble. The array length is the same as the vector length. The array elements are converted as if by casting and stored in lane order. This operation can lose precision if the vector element type islong.- API Note:
- Usually strongly typed accessis preferable, if you are working with a vector subtype that has a known element type.
- Returns:
- a double[]array containing the lane values of this vector, possibly rounded to representabledoublevalues
- See Also:
 
- 
toStringReturns a string representation of this vector, of the form"[0,1,2...]", reporting the lane values of this vector, in lane order. The string is produced as if by a call toArrays.toString(), as appropriate to the array returned bythis.toArray().
- 
equalsIndicates whether this vector is identical to some other object. Two vectors are identical only if they have the same species and same lane values, in the same order.The comparison of lane values is produced as if by a call to Arrays.equals(), as appropriate to the arrays returned bytoArray()on both vectors.
- 
hashCodepublic abstract int hashCode()Returns a hash code value for the vector. based on the lane values and the vector species.
- 
getPayload
 
- 
Vectorwhen preview features are enabled.