1 /*
2 * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package jdk.incubator.vector;
26
27 import jdk.incubator.foreign.MemorySegment;
28
29 import java.nio.ByteOrder;
30 import java.util.Arrays;
31
32 /**
33 * A
34 *
35 * <!-- The following paragraphs are shared verbatim
36 * -- between Vector.java and package-info.java -->
37 * sequence of a fixed number of <em>lanes</em>,
38 * all of some fixed
39 * {@linkplain Vector#elementType() <em>element type</em>}
40 * such as {@code byte}, {@code long}, or {@code float}.
41 * Each lane contains an independent value of the element type.
42 * Operations on vectors are typically
43 * <a href="Vector.html#lane-wise"><em>lane-wise</em></a>,
44 * distributing some scalar operator (such as
45 * {@linkplain Vector#add(Vector) addition})
46 * across the lanes of the participating vectors,
47 * usually generating a vector result whose lanes contain the various
48 * scalar results. When run on a supporting platform, lane-wise
49 * operations can be executed in parallel by the hardware. This style
50 * of parallelism is called <em>Single Instruction Multiple Data</em>
51 * (SIMD) parallelism.
52 *
53 * <p> In the SIMD style of programming, most of the operations within
54 * a vector lane are unconditional, but the effect of conditional
55 * execution may be achieved using
56 * <a href="Vector.html#masking"><em>masked operations</em></a>
57 * such as {@link Vector#blend(Vector,VectorMask) blend()},
58 * under the control of an associated {@link VectorMask}.
59 * Data motion other than strictly lane-wise flow is achieved using
60 * <a href="Vector.html#cross-lane"><em>cross-lane</em></a>
61 * operations, often under the control of an associated
62 * {@link VectorShuffle}.
63 * Lane data and/or whole vectors can be reformatted using various
64 * kinds of lane-wise
65 * {@linkplain Vector#convert(VectorOperators.Conversion,int) conversions},
66 * and byte-wise reformatting
67 * {@linkplain Vector#reinterpretShape(VectorSpecies,int) reinterpretations},
68 * often under the control of a reflective {@link VectorSpecies}
69 * object which selects an alternative vector format different
70 * from that of the input vector.
71 *
72 * <p> {@code Vector<E>} declares a set of vector operations (methods)
73 * that are common to all element types. These common operations
74 * include generic access to lane values, data selection and movement,
75 * reformatting, and certain arithmetic and logical operations (such as addition
76 * or comparison) that are common to all primitive types.
77 *
78 * <p> <a href="Vector.html#subtypes">Public subtypes of {@code Vector}</a>
79 * correspond to specific
80 * element types. These declare further operations that are specific
81 * to that element type, including unboxed access to lane values,
82 * bitwise operations on values of integral element types, or
83 * transcendental operations on values of floating point element
84 * types.
85 *
86 * <p> Some lane-wise operations, such as the {@code add} operator, are defined as
87 * a full-service named operation, where a corresponding method on {@code Vector}
88 * comes in masked and unmasked overloadings, and (in subclasses) also comes in
89 * covariant overrides (returning the subclass) and additional scalar-broadcast
90 * overloadings (both masked and unmasked).
91 *
92 * Other lane-wise operations, such as the {@code min} operator, are defined as a
93 * partially serviced (not a full-service) named operation, where a corresponding
94 * method on {@code Vector} and/or a subclass provide some but all possible
95 * overloadings and overrides (commonly the unmasked varient with scalar-broadcast
96 * overloadings).
97 *
98 * Finally, all lane-wise operations (those named as previously described,
99 * or otherwise unnamed method-wise) have a corresponding
100 * {@link VectorOperators.Operator operator token}
101 * declared as a static constant on {@link VectorOperators}.
102 * Each operator token defines a symbolic Java expression for the operation,
103 * such as {@code a + b} for the
104 * {@link VectorOperators#ADD ADD} operator token.
105 * General lane-wise operation-token accepting methods, such as for a
106 * {@linkplain Vector#lanewise(VectorOperators.Unary) unary lane-wise}
107 * operation, are provided on {@code Vector} and come in the same variants as
108 * a full-service named operation.
109 *
110 * <p>This package contains a public subtype of {@link Vector}
111 * corresponding to each supported element type:
112 * {@link ByteVector}, {@link ShortVector},
113 * {@link IntVector}, {@link LongVector},
114 * {@link FloatVector}, and {@link DoubleVector}.
115 *
116 * <!-- The preceding paragraphs are shared verbatim
117 * -- between Vector.java and package-info.java -->
118 *
119 * <p><a id="ETYPE"></a> The {@linkplain #elementType element type} of a vector,
120 * referred to as {@code ETYPE}, is one of the primitive types
121 * {@code byte}, {@code short}, {@code int}, {@code long}, {@code
122 * float}, or {@code double}.
123 *
124 * <p> The type {@code E} in {@code Vector<E>} is the <em>boxed</em> version
125 * of {@code ETYPE}. For example, in the type {@code Vector<Integer>}, the {@code E}
126 * parameter is {@code Integer} and the {@code ETYPE} is {@code int}. In such a
127 * vector, each lane carries a primitive {@code int} value. This pattern continues
128 * for the other primitive types as well. (See also sections {@jls 5.1.7} and
129 * {@jls 5.1.8} of the <cite>The Java Language Specification</cite>.)
130 *
131 * <p><a id="VLENGTH"></a> The {@linkplain #length() length} of a vector
132 * is the lane count, the number of lanes it contains.
133 *
134 * This number is also called {@code VLENGTH} when the context makes
135 * clear which vector it belongs to. Each vector has its own fixed
136 * {@code VLENGTH} but different instances of vectors may have
137 * different lengths. {@code VLENGTH} is an important number, because
138 * it estimates the SIMD performance gain of a single vector operation
139 * as compared to scalar execution of the {@code VLENGTH} scalar
140 * operators which underly the vector operation.
141 *
142 * <h2><a id="species"></a>Shapes and species</h2>
143 *
144 * The information capacity of a vector is determined by its
145 * {@linkplain #shape() <em>vector shape</em>}, also called its
146 * {@code VSHAPE}. Each possible {@code VSHAPE} is represented by
147 * a member of the {@link VectorShape} enumeration, and represents
148 * an implementation format shared in common by all vectors of
149 * that shape. Thus, the {@linkplain #bitSize() size in bits} of
150 * of a vector is determined by appealing to its vector shape.
151 *
152 * <p> Some Java platforms give special support to only one shape,
153 * while others support several. A typical platform is not likely
154 * to support all the shapes described by this API. For this reason,
155 * most vector operations work on a single input shape and
156 * produce the same shape on output. Operations which change
157 * shape are clearly documented as such <em>shape-changing</em>,
158 * while the majority of operations are <em>shape-invariant</em>,
159 * to avoid disadvantaging platforms which support only one shape.
160 * There are queries to discover, for the current Java platform,
161 * the {@linkplain VectorShape#preferredShape() preferred shape}
162 * for general SIMD computation, or the
163 * {@linkplain VectorShape#largestShapeFor(Class) largest
164 * available shape} for any given lane type. To be portable,
165 * code using this API should start by querying a supported
166 * shape, and then process all data with shape-invariant
167 * operations, within the selected shape.
168 *
169 * <p> Each unique combination of element type and vector shape
170 * determines a unique
171 * {@linkplain #species() <em>vector species</em>}.
172 * A vector species is represented by a fixed instance of
173 * {@link VectorSpecies VectorSpecies<E>}
174 * shared in common by all vectors of the same shape and
175 * {@code ETYPE}.
176 *
177 * <p> Unless otherwise documented, lane-wise vector operations
178 * require that all vector inputs have exactly the same {@code VSHAPE}
179 * and {@code VLENGTH}, which is to say that they must have exactly
180 * the same species. This allows corresponding lanes to be paired
181 * unambiguously. The {@link #check(VectorSpecies) check()} method
182 * provides an easy way to perform this check explicitly.
183 *
184 * <p> Vector shape, {@code VLENGTH}, and {@code ETYPE} are all
185 * mutually constrained, so that {@code VLENGTH} times the
186 * {@linkplain #elementSize() bit-size of each lane}
187 * must always match the bit-size of the vector's shape.
188 *
189 * Thus, {@linkplain #reinterpretShape(VectorSpecies,int) reinterpreting} a
190 * vector may double its length if and only if it either halves the lane size,
191 * or else changes the shape. Likewise, reinterpreting a vector may double the
192 * lane size if and only if it either halves the length, or else changes the
193 * shape of the vector.
194 *
195 * <h2><a id="subtypes"></a>Vector subtypes</h2>
196 *
197 * Vector declares a set of vector operations (methods) that are common to all
198 * element types (such as addition). Sub-classes of Vector with a concrete
199 * element type declare further operations that are specific to that
200 * element type (such as access to element values in lanes, logical operations
201 * on values of integral elements types, or transcendental operations on values
202 * of floating point element types).
203 * There are six abstract sub-classes of Vector corresponding to the supported set
204 * of element types, {@link ByteVector}, {@link ShortVector},
205 * {@link IntVector}, {@link LongVector}, {@link FloatVector}, and
206 * {@link DoubleVector}. Along with type-specific operations these classes
207 * support creation of vector values (instances of Vector).
208 * They expose static constants corresponding to the supported species,
209 * and static methods on these types generally take a species as a parameter.
210 * For example,
211 * {@link FloatVector#fromArray(VectorSpecies, float[], int) FloatVector.fromArray}
212 * creates and returns a float vector of the specified species, with elements
213 * loaded from the specified float array.
214 * It is recommended that Species instances be held in {@code static final}
215 * fields for optimal creation and usage of Vector values by the runtime compiler.
216 *
217 * <p> As an example of static constants defined by the typed vector classes,
218 * constant {@link FloatVector#SPECIES_256 FloatVector.SPECIES_256}
219 * is the unique species whose lanes are {@code float}s and whose
220 * vector size is 256 bits. Again, the constant
221 * {@link FloatVector#SPECIES_PREFERRED} is the species which
222 * best supports processing of {@code float} vector lanes on
223 * the currently running Java platform.
224 *
225 * <p> As another example, a broadcast scalar value of
226 * {@code (double)0.5} can be obtained by calling
227 * {@link DoubleVector#broadcast(VectorSpecies,double)
228 * DoubleVector.broadcast(dsp, 0.5)}, but the argument {@code dsp} is
229 * required to select the species (and hence the shape and length) of
230 * the resulting vector.
231 *
232 * <h2><a id="lane-wise"></a>Lane-wise operations</h2>
233 *
234 * We use the term <em>lanes</em> when defining operations on
235 * vectors. The number of lanes in a vector is the number of scalar
236 * elements it holds. For example, a vector of type {@code float} and
237 * shape {@code S_256_BIT} has eight lanes, since {@code 32*8=256}.
238 *
239 * <p> Most operations on vectors are lane-wise, which means the operation
240 * is composed of an underlying scalar operator, which is repeated for
241 * each distinct lane of the input vector. If there are additional
242 * vector arguments of the same type, their lanes are aligned with the
243 * lanes of the first input vector. (They must all have a common
244 * {@code VLENGTH}.) For most lane-wise operations, the output resulting
245 * from a lane-wise operation will have a {@code VLENGTH} which is equal to
246 * the {@code VLENGTH} of the input(s) to the operation. Thus, such lane-wise
247 * operations are <em>length-invariant</em>, in their basic definitions.
248 *
249 * <p> The principle of length-invariance is combined with another
250 * basic principle, that most length-invariant lane-wise operations are also
251 * <em>shape-invariant</em>, meaning that the inputs and the output of
252 * a lane-wise operation will have a common {@code VSHAPE}. When the
253 * principles conflict, because a logical result (with an invariant
254 * {@code VLENGTH}), does not fit into the invariant {@code VSHAPE},
255 * the resulting expansions and contractions are handled explicitly
256 * with
257 * <a href="Vector.html#expansion">special conventions</a>.
258 *
259 * <p> Vector operations can be grouped into various categories and
260 * their behavior can be generally specified in terms of underlying
261 * scalar operators. In the examples below, {@code ETYPE} is the
262 * element type of the operation (such as {@code int.class}) and
263 * {@code EVector} is the corresponding concrete vector type (such as
264 * {@code IntVector.class}).
265 *
266 * <ul>
267 * <li>
268 * A <em>lane-wise unary</em> operation, such as
269 * {@code w = v0.}{@link Vector#neg() neg}{@code ()},
270 * takes one input vector,
271 * distributing a unary scalar operator across the lanes,
272 * and produces a result vector of the same type and shape.
273 *
274 * For each lane of the input vector {@code a},
275 * the underlying scalar operator is applied to the lane value.
276 * The result is placed into the vector result in the same lane.
277 * The following pseudocode illustrates the behavior of this operation
278 * category:
279 *
280 * <pre>{@code
281 * ETYPE scalar_unary_op(ETYPE s);
282 * EVector a = ...;
283 * VectorSpecies<E> species = a.species();
284 * ETYPE[] ar = new ETYPE[a.length()];
285 * for (int i = 0; i < ar.length; i++) {
286 * ar[i] = scalar_unary_op(a.lane(i));
287 * }
288 * EVector r = EVector.fromArray(species, ar, 0);
289 * }</pre>
290 *
291 * <li>
292 * A <em>lane-wise binary</em> operation, such as
293 * {@code w = v0.}{@link Vector#add(Vector) add}{@code (v1)},
294 * takes two input vectors,
295 * distributing a binary scalar operator across the lanes,
296 * and produces a result vector of the same type and shape.
297 *
298 * For each lane of the two input vectors {@code a} and {@code b},
299 * the underlying scalar operator is applied to the lane values.
300 * The result is placed into the vector result in the same lane.
301 * The following pseudocode illustrates the behavior of this operation
302 * category:
303 *
304 * <pre>{@code
305 * ETYPE scalar_binary_op(ETYPE s, ETYPE t);
306 * EVector a = ...;
307 * VectorSpecies<E> species = a.species();
308 * EVector b = ...;
309 * b.check(species); // must have same species
310 * ETYPE[] ar = new ETYPE[a.length()];
311 * for (int i = 0; i < ar.length; i++) {
312 * ar[i] = scalar_binary_op(a.lane(i), b.lane(i));
313 * }
314 * EVector r = EVector.fromArray(species, ar, 0);
315 * }</pre>
316 * </li>
317 *
318 * <li>
319 * Generalizing from unary and binary operations,
320 * a <em>lane-wise n-ary</em> operation takes {@code N} input vectors {@code v[j]},
321 * distributing an n-ary scalar operator across the lanes,
322 * and produces a result vector of the same type and shape.
323 * Except for a few ternary operations, such as
324 * {@code w = v0.}{@link FloatVector#fma(Vector,Vector) fma}{@code (v1,v2)},
325 * this API has no support for
326 * lane-wise n-ary operations.
327 *
328 * For each lane of all of the input vectors {@code v[j]},
329 * the underlying scalar operator is applied to the lane values.
330 * The result is placed into the vector result in the same lane.
331 * The following pseudocode illustrates the behavior of this operation
332 * category:
333 *
334 * <pre>{@code
335 * ETYPE scalar_nary_op(ETYPE... args);
336 * EVector[] v = ...;
337 * int N = v.length;
338 * VectorSpecies<E> species = v[0].species();
339 * for (EVector arg : v) {
340 * arg.check(species); // all must have same species
341 * }
342 * ETYPE[] ar = new ETYPE[a.length()];
343 * for (int i = 0; i < ar.length; i++) {
344 * ETYPE[] args = new ETYPE[N];
345 * for (int j = 0; j < N; j++) {
346 * args[j] = v[j].lane(i);
347 * }
348 * ar[i] = scalar_nary_op(args);
349 * }
350 * EVector r = EVector.fromArray(species, ar, 0);
351 * }</pre>
352 * </li>
353 *
354 * <li>
355 * A <em>lane-wise conversion</em> operation, such as
356 * {@code w0 = v0.}{@link
357 * Vector#convert(VectorOperators.Conversion,int)
358 * convert}{@code (VectorOperators.I2D, 0)},
359 * takes one input vector,
360 * distributing a unary scalar conversion operator across the lanes,
361 * and produces a logical result of the converted values. The logical
362 * result (or at least a part of it) is presented in a vector of the
363 * same shape as the input vector.
364 *
365 * <p> Unlike other lane-wise operations, conversions can change lane
366 * type, from the input (domain) type to the output (range) type. The
367 * lane size may change along with the type. In order to manage the
368 * size changes, lane-wise conversion methods can product <em>partial
369 * results</em>, under the control of a {@code part} parameter, which
370 * is <a href="Vector.html#expansion">explained elsewhere</a>.
371 * (Following the example above, the second group of converted lane
372 * values could be obtained as
373 * {@code w1 = v0.convert(VectorOperators.I2D, 1)}.)
374 *
375 * <p> The following pseudocode illustrates the behavior of this
376 * operation category in the specific example of a conversion from
377 * {@code int} to {@code double}, retaining either lower or upper
378 * lanes (depending on {@code part}) to maintain shape-invariance:
379 *
380 * <pre>{@code
381 * IntVector a = ...;
382 * int VLENGTH = a.length();
383 * int part = ...; // 0 or 1
384 * VectorShape VSHAPE = a.shape();
385 * double[] arlogical = new double[VLENGTH];
386 * for (int i = 0; i < limit; i++) {
387 * int e = a.lane(i);
388 * arlogical[i] = (double) e;
389 * }
390 * VectorSpecies<Double> rs = VSHAPE.withLanes(double.class);
391 * int M = Double.BITS / Integer.BITS; // expansion factor
392 * int offset = part * (VLENGTH / M);
393 * DoubleVector r = DoubleVector.fromArray(rs, arlogical, offset);
394 * assert r.length() == VLENGTH / M;
395 * }</pre>
396 * </li>
397 *
398 * <li>
399 * A <em>cross-lane reduction</em> operation, such as
400 * {@code e = v0.}{@link
401 * IntVector#reduceLanes(VectorOperators.Associative)
402 * reduceLanes}{@code (VectorOperators.ADD)},
403 * operates on all
404 * the lane elements of an input vector.
405 * An accumulation function is applied to all the
406 * lane elements to produce a scalar result.
407 * If the reduction operation is associative then the result may be accumulated
408 * by operating on the lane elements in any order using a specified associative
409 * scalar binary operation and identity value. Otherwise, the reduction
410 * operation specifies the order of accumulation.
411 * The following pseudocode illustrates the behavior of this operation category
412 * if it is associative:
413 * <pre>{@code
414 * ETYPE assoc_scalar_binary_op(ETYPE s, ETYPE t);
415 * EVector a = ...;
416 * ETYPE r = <identity value>;
417 * for (int i = 0; i < a.length(); i++) {
418 * r = assoc_scalar_binary_op(r, a.lane(i));
419 * }
420 * }</pre>
421 * </li>
422 *
423 * <li>
424 * A <em>cross-lane movement</em> operation, such as
425 * {@code w = v0.}{@link
426 * Vector#rearrange(VectorShuffle) rearrange}{@code (shuffle)}
427 * operates on all
428 * the lane elements of an input vector and moves them
429 * in a data-dependent manner into <em>different lanes</em>
430 * in an output vector.
431 * The movement is steered by an auxiliary datum, such as
432 * a {@link VectorShuffle} or a scalar index defining the
433 * origin of the movement.
434 * The following pseudocode illustrates the behavior of this
435 * operation category, in the case of a shuffle:
436 * <pre>{@code
437 * EVector a = ...;
438 * Shuffle<E> s = ...;
439 * ETYPE[] ar = new ETYPE[a.length()];
440 * for (int i = 0; i < ar.length; i++) {
441 * int source = s.laneSource(i);
442 * ar[i] = a.lane(source);
443 * }
444 * EVector r = EVector.fromArray(a.species(), ar, 0);
445 * }</pre>
446 * </li>
447 *
448 * <li>
449 * A <em>masked operation</em> is one which is a variation on one of the
450 * previous operations (either lane-wise or cross-lane), where
451 * the operation takes an extra trailing {@link VectorMask} argument.
452 * In lanes the mask is set, the operation behaves as if the mask
453 * argument were absent, but in lanes where the mask is unset, the
454 * underlying scalar operation is suppressed.
455 * Masked operations are explained in
456 * <a href="Vector.html#masking">greater detail elsewhere</a>.
457 * </li>
458 *
459 * <li>
460 * A very special case of a masked lane-wise binary operation is a
461 * {@linkplain #blend(Vector,VectorMask) blend}, which operates
462 * lane-wise on two input vectors {@code a} and {@code b}, selecting lane
463 * values from one input or the other depending on a mask {@code m}.
464 * In lanes where {@code m} is set, the corresponding value from
465 * {@code b} is selected into the result; otherwise the value from
466 * {@code a} is selected. Thus, a blend acts as a vectorized version
467 * of Java's ternary selection expression {@code m?b:a}:
468 * <pre>{@code
469 * ETYPE[] ar = new ETYPE[a.length()];
470 * for (int i = 0; i < ar.length; i++) {
471 * boolean isSet = m.laneIsSet(i);
472 * ar[i] = isSet ? b.lane(i) : a.lane(i);
473 * }
474 * EVector r = EVector.fromArray(species, ar, 0);
475 * }</pre>
476 * </li>
477 *
478 * <li>
479 * A <em>lane-wise binary test</em> operation, such as
480 * {@code m = v0.}{@link Vector#lt(Vector) lt}{@code (v1)},
481 * takes two input vectors,
482 * distributing a binary scalar comparison across the lanes,
483 * and produces, not a vector of booleans, but rather a
484 * {@linkplain VectorMask vector mask}.
485 *
486 * For each lane of the two input vectors {@code a} and {@code b},
487 * the underlying scalar comparison operator is applied to the lane values.
488 * The resulting boolean is placed into the vector mask result in the same lane.
489 * The following pseudocode illustrates the behavior of this operation
490 * category:
491 * <pre>{@code
492 * boolean scalar_binary_test_op(ETYPE s, ETYPE t);
493 * EVector a = ...;
494 * VectorSpecies<E> species = a.species();
495 * EVector b = ...;
496 * b.check(species); // must have same species
497 * boolean[] mr = new boolean[a.length()];
498 * for (int i = 0; i < mr.length; i++) {
499 * mr[i] = scalar_binary_test_op(a.lane(i), b.lane(i));
500 * }
501 * VectorMask<E> m = VectorMask.fromArray(species, mr, 0);
502 * }</pre>
503 * </li>
504 *
505 * <li>
506 * Similarly to a binary comparison, a <em>lane-wise unary test</em>
507 * operation, such as
508 * {@code m = v0.}{@link Vector#test(VectorOperators.Test)
509 * test}{@code (IS_FINITE)},
510 * takes one input vector, distributing a scalar predicate
511 * (a test function) across the lanes, and produces a
512 * {@linkplain VectorMask vector mask}.
513 * </li>
514 *
515 * </ul>
516 *
517 * <p>
518 * If a vector operation does not belong to one of the above categories then
519 * the method documentation explicitly specifies how it processes the lanes of
520 * input vectors, and where appropriate illustrates the behavior using
521 * pseudocode.
522 *
523 * <p>
524 * Most lane-wise binary and comparison operations offer convenience
525 * overloadings which accept a scalar as the second input, in place of a
526 * vector. In this case the scalar value is promoted to a vector by
527 * {@linkplain Vector#broadcast(long) broadcasting it}
528 * into the same lane structure as the first input.
529 *
530 * For example, to multiply all lanes of a {@code double} vector by
531 * a scalar value {@code 1.1}, the expression {@code v.mul(1.1)} is
532 * easier to work with than an equivalent expression with an explicit
533 * broadcast operation, such as {@code v.mul(v.broadcast(1.1))}
534 * or {@code v.mul(DoubleVector.broadcast(v.species(), 1.1))}.
535 *
536 * Unless otherwise specified the scalar variant always behaves as if
537 * each scalar value is first transformed to a vector of the same
538 * species as the first vector input, using the appropriate
539 * {@code broadcast} operation.
540 *
541 * <h2><a id="masking"></a>Masked operations</h2>
542 *
543 * <p> Many vector operations accept an optional
544 * {@link VectorMask mask} argument, selecting which lanes participate
545 * in the underlying scalar operator. If present, the mask argument
546 * appears at the end of the method argument list.
547 *
548 * <p> Each lane of the mask argument is a boolean which is either in
549 * the <em>set</em> or <em>unset</em> state. For lanes where the mask
550 * argument is unset, the underlying scalar operator is suppressed.
551 * In this way, masks allow vector operations to emulate scalar
552 * control flow operations, without losing SIMD parallelism, except
553 * where the mask lane is unset.
554 *
555 * <p> An operation suppressed by a mask will never cause an exception
556 * or side effect of any sort, even if the underlying scalar operator
557 * can potentially do so. For example, an unset lane that seems to
558 * access an out of bounds array element or divide an integral value
559 * by zero will simply be ignored. Values in suppressed lanes never
560 * participate or appear in the result of the overall operation.
561 *
562 * <p> Result lanes corresponding to a suppressed operation will be
563 * filled with a default value which depends on the specific
564 * operation, as follows:
565 *
566 * <ul>
567 *
568 * <li>If the masked operation is a unary, binary, or n-ary arithmetic or
569 * logical operation, suppressed lanes are filled from the first
570 * vector operand (i.e., the vector receiving the method call), as if
571 * by a {@linkplain #blend(Vector,VectorMask) blend}.</li>
572 *
573 * <li>If the masked operation is a memory load or a {@code slice()} from
574 * another vector, suppressed lanes are not loaded, and are filled
575 * with the default value for the {@code ETYPE}, which in every case
576 * consists of all zero bits. An unset lane can never cause an
577 * exception, even if the hypothetical corresponding memory location
578 * does not exist (because it is out of an array's index range).</li>
579 *
580 * <li>If the operation is a cross-lane operation with an operand
581 * which supplies lane indexes (of type {@code VectorShuffle} or
582 * {@code Vector}, suppressed lanes are not computed, and are filled
583 * with the zero default value. Normally, invalid lane indexes elicit
584 * an {@code IndexOutOfBoundsException}, but if a lane is unset, the
585 * zero value is quietly substituted, regardless of the index. This
586 * rule is similar to the previous rule, for masked memory loads.</li>
587 *
588 * <li>If the masked operation is a memory store or an {@code unslice()} into
589 * another vector, suppressed lanes are not stored, and the
590 * corresponding memory or vector locations (if any) are unchanged.
591 *
592 * <p> (Note: Memory effects such as race conditions never occur for
593 * suppressed lanes. That is, implementations will not secretly
594 * re-write the existing value for unset lanes. In the Java Memory
595 * Model, reassigning a memory variable to its current value is not a
596 * no-op; it may quietly undo a racing store from another
597 * thread.)</p>
598 * </li>
599 *
600 * <li>If the masked operation is a reduction, suppressed lanes are ignored
601 * in the reduction. If all lanes are suppressed, a suitable neutral
602 * value is returned, depending on the specific reduction operation,
603 * and documented by the masked variant of that method. (This means
604 * that users can obtain the neutral value programmatically by
605 * executing the reduction on a dummy vector with an all-unset mask.)
606 *
607 * <li>If the masked operation is a comparison operation, suppressed output
608 * lanes in the resulting mask are themselves unset, as if the
609 * suppressed comparison operation returned {@code false} regardless
610 * of the suppressed input values. In effect, it is as if the
611 * comparison operation were performed unmasked, and then the
612 * result intersected with the controlling mask.</li>
613 *
614 * <li>In other cases, such as masked
615 * <a href="Vector.html#cross-lane"><em>cross-lane movements</em></a>,
616 * the specific effects of masking are documented by the masked
617 * variant of the method.
618 *
619 * </ul>
620 *
621 * <p> As an example, a masked binary operation on two input vectors
622 * {@code a} and {@code b} suppresses the binary operation for lanes
623 * where the mask is unset, and retains the original lane value from
624 * {@code a}. The following pseudocode illustrates this behavior:
625 * <pre>{@code
626 * ETYPE scalar_binary_op(ETYPE s, ETYPE t);
627 * EVector a = ...;
628 * VectorSpecies<E> species = a.species();
629 * EVector b = ...;
630 * b.check(species); // must have same species
631 * VectorMask<E> m = ...;
632 * m.check(species); // must have same species
633 * boolean[] ar = new boolean[a.length()];
634 * for (int i = 0; i < ar.length; i++) {
635 * if (m.laneIsSet(i)) {
636 * ar[i] = scalar_binary_op(a.lane(i), b.lane(i));
637 * } else {
638 * ar[i] = a.lane(i); // from first input
639 * }
640 * }
641 * EVector r = EVector.fromArray(species, ar, 0);
642 * }</pre>
643 *
644 * <h2><a id="lane-order"></a>Lane order and byte order</h2>
645 *
646 * The number of lane values stored in a given vector is referred to
647 * as its {@linkplain #length() vector length} or {@code VLENGTH}.
648 *
649 * It is useful to consider vector lanes as ordered
650 * <em>sequentially</em> from first to last, with the first lane
651 * numbered {@code 0}, the next lane numbered {@code 1}, and so on to
652 * the last lane numbered {@code VLENGTH-1}. This is a temporal
653 * order, where lower-numbered lanes are considered earlier than
654 * higher-numbered (later) lanes. This API uses these terms
655 * in preference to spatial terms such as "left", "right", "high",
656 * and "low".
657 *
658 * <p> Temporal terminology works well for vectors because they
659 * (usually) represent small fixed-sized segments in a long sequence
660 * of workload elements, where the workload is conceptually traversed
661 * in time order from beginning to end. (This is a mental model: it
662 * does not exclude multicore divide-and-conquer techniques.) Thus,
663 * when a scalar loop is transformed into a vector loop, adjacent
664 * scalar items (one earlier, one later) in the workload end up as
665 * adjacent lanes in a single vector (again, one earlier, one later).
666 * At a vector boundary, the last lane item in the earlier vector is
667 * adjacent to (and just before) the first lane item in the
668 * immediately following vector.
669 *
670 * <p> Vectors are also sometimes thought of in spatial terms, where
671 * the first lane is placed at an edge of some virtual paper, and
672 * subsequent lanes are presented in order next to it. When using
673 * spatial terms, all directions are equally plausible: Some vector
674 * notations present lanes from left to right, and others from right
675 * to left; still others present from top to bottom or vice versa.
676 * Using the language of time (before, after, first, last) instead of
677 * space (left, right, high, low) is often more likely to avoid
678 * misunderstandings.
679 *
680 * <p> As second reason to prefer temporal to spatial language about
681 * vector lanes is the fact that the terms "left", "right", "high" and
682 * "low" are widely used to describe the relations between bits in
683 * scalar values. The leftmost or highest bit in a given type is
684 * likely to be a sign bit, while the rightmost or lowest bit is
685 * likely to be the arithmetically least significant, and so on.
686 * Applying these terms to vector lanes risks confusion, however,
687 * because it is relatively rare to find algorithms where, given two
688 * adjacent vector lanes, one lane is somehow more arithmetically
689 * significant than its neighbor, and even in those cases, there is no
690 * general way to know which neighbor is the the more significant.
691 *
692 * <p> Putting the terms together, we view the information structure
693 * of a vector as a temporal sequence of lanes ("first", "next",
694 * "earlier", "later", "last", etc.) of bit-strings which are
695 * internally ordered spatially (either "low" to "high" or "right" to
696 * "left"). The primitive values in the lanes are decoded from these
697 * bit-strings, in the usual way. Most vector operations, like most
698 * Java scalar operators, treat primitive values as atomic values, but
699 * some operations reveal the internal bit-string structure.
700 *
701 * <p> When a vector is loaded from or stored into memory, the order
702 * of vector lanes is <em>always consistent </em> with the inherent
703 * ordering of the memory container. This is true whether or not
704 * individual lane elements are subject to "byte swapping" due to
705 * details of byte order. Thus, while the scalar lane elements of
706 * vector might be "byte swapped", the lanes themselves are never
707 * reordered, except by an explicit method call that performs
708 * cross-lane reordering.
709 *
710 * <p> When vector lane values are stored to Java variables of the
711 * same type, byte swapping is performed if and only if the
712 * implementation of the vector hardware requires such swapping. It
713 * is therefore unconditional and invisible.
714 *
715 * <p> As a useful fiction, this API presents a consistent illusion
716 * that vector lane bytes are composed into larger lane scalars in
717 * <em>little endian order</em>. This means that storing a vector
718 * into a Java byte array will reveal the successive bytes of the
719 * vector lane values in little-endian order on all platforms,
720 * regardless of native memory order, and also regardless of byte
721 * order (if any) within vector unit registers.
722 *
723 * <p> This hypothetical little-endian ordering also appears when a
724 * {@linkplain #reinterpretShape(VectorSpecies,int) reinterpretation cast} is
725 * applied in such a way that lane boundaries are discarded and
726 * redrawn differently, while maintaining vector bits unchanged. In
727 * such an operation, two adjacent lanes will contribute bytes to a
728 * single new lane (or vice versa), and the sequential order of the
729 * two lanes will determine the arithmetic order of the bytes in the
730 * single lane. In this case, the little-endian convention provides
731 * portable results, so that on all platforms earlier lanes tend to
732 * contribute lower (rightward) bits, and later lanes tend to
733 * contribute higher (leftward) bits. The {@linkplain #reinterpretAsBytes()
734 * reinterpretation casts} between {@link ByteVector}s and the
735 * other non-byte vectors use this convention to clarify their
736 * portable semantics.
737 *
738 * <p> The little-endian fiction for relating lane order to per-lane
739 * byte order is slightly preferable to an equivalent big-endian
740 * fiction, because some related formulas are much simpler,
741 * specifically those which renumber bytes after lane structure
742 * changes. The earliest byte is invariantly earliest across all lane
743 * structure changes, but only if little-endian convention are used.
744 * The root cause of this is that bytes in scalars are numbered from
745 * the least significant (rightmost) to the most significant
746 * (leftmost), and almost never vice-versa. If we habitually numbered
747 * sign bits as zero (as on some computers) then this API would reach
748 * for big-endian fictions to create unified addressing of vector
749 * bytes.
750 *
751 * <h2><a id="memory"></a>Memory operations</h2>
752 *
753 * As was already mentioned, vectors can be loaded from memory and
754 * stored back. An optional mask can control which individual memory
755 * locations are read from or written to. The shape of a vector
756 * determines how much memory it will occupy.
757 *
758 * An implementation typically has the property, in the absence of
759 * masking, that lanes are stored as a dense sequence of back-to-back
760 * values in memory, the same as a dense (gap-free) series of single
761 * scalar values in an array of the scalar type.
762 *
763 * In such cases memory order corresponds exactly to lane order. The
764 * first vector lane value occupies the first position in memory, and so on,
765 * up to the length of the vector. Further, the memory order of stored
766 * vector lanes corresponds to increasing index values in a Java array or
767 * in a {@link jdk.incubator.foreign.MemorySegment}.
768 *
769 * <p> Byte order for lane storage is chosen such that the stored
770 * vector values can be read or written as single primitive values,
771 * within the array or segment that holds the vector, producing the
772 * same values as the lane-wise values within the vector.
773 * This fact is independent of the convenient fiction that lane values
774 * inside of vectors are stored in little-endian order.
775 *
776 * <p> For example,
777 * {@link FloatVector#fromArray(VectorSpecies, float[], int)
778 * FloatVector.fromArray(fsp,fa,i)}
779 * creates and returns a float vector of some particular species {@code fsp},
780 * with elements loaded from some float array {@code fa}.
781 * The first lane is loaded from {@code fa[i]} and the last lane
782 * is initialized loaded from {@code fa[i+VL-1]}, where {@code VL}
783 * is the length of the vector as derived from the species {@code fsp}.
784 * Then, {@link FloatVector#add(Vector) fv=fv.add(fv2)}
785 * will produce another float vector of that species {@code fsp},
786 * given a vector {@code fv2} of the same species {@code fsp}.
787 * Next, {@link FloatVector#compare(VectorOperators.Comparison,float)
788 * mnz=fv.compare(NE, 0.0f)} tests whether the result is zero,
789 * yielding a mask {@code mnz}. The non-zero lanes (and only those
790 * lanes) can then be stored back into the original array elements
791 * using the statement
792 * {@link FloatVector#intoArray(float[],int,VectorMask) fv.intoArray(fa,i,mnz)}.
793 *
794 * <h2><a id="expansion"></a>Expansions, contractions, and partial results</h2>
795 *
796 * Since vectors are fixed in size, occasions often arise where the
797 * logical result of an operation is not the same as the physical size
798 * of the proposed output vector. To encourage user code that is as
799 * portable and predictable as possible, this API has a systematic
800 * approach to the design of such <em>resizing</em> vector operations.
801 *
802 * <p> As a basic principle, lane-wise operations are
803 * <em>length-invariant</em>, unless clearly marked otherwise.
804 * Length-invariance simply means that
805 * if {@code VLENGTH} lanes go into an operation, the same number
806 * of lanes come out, with nothing discarded and no extra padding.
807 *
808 * <p> As a second principle, sometimes in tension with the first,
809 * lane-wise operations are also <em>shape-invariant</em>, unless
810 * clearly marked otherwise.
811 *
812 * Shape-invariance means that {@code VSHAPE} is constant for typical
813 * computations. Keeping the same shape throughout a computation
814 * helps ensure that scarce vector resources are efficiently used.
815 * (On some hardware platforms shape changes could cause unwanted
816 * effects like extra data movement instructions, round trips through
817 * memory, or pipeline bubbles.)
818 *
819 * <p> Tension between these principles arises when an operation
820 * produces a <em>logical result</em> that is too large for the
821 * required output {@code VSHAPE}. In other cases, when a logical
822 * result is smaller than the capacity of the output {@code VSHAPE},
823 * the positioning of the logical result is open to question, since
824 * the physical output vector must contain a mix of logical result and
825 * padding.
826 *
827 * <p> In the first case, of a too-large logical result being crammed
828 * into a too-small output {@code VSHAPE}, we say that data has
829 * <em>expanded</em>. In other words, an <em>expansion operation</em>
830 * has caused the output shape to overflow. Symmetrically, in the
831 * second case of a small logical result fitting into a roomy output
832 * {@code VSHAPE}, the data has <em>contracted</em>, and the
833 * <em>contraction operation</em> has required the output shape to pad
834 * itself with extra zero lanes.
835 *
836 * <p> In both cases we can speak of a parameter {@code M} which
837 * measures the <em>expansion ratio</em> or <em>contraction ratio</em>
838 * between the logical result size (in bits) and the bit-size of the
839 * actual output shape. When vector shapes are changed, and lane
840 * sizes are not, {@code M} is just the integral ratio of the output
841 * shape to the logical result. (With the possible exception of
842 * the {@linkplain VectorShape#S_Max_BIT maximum shape}, all vector
843 * sizes are powers of two, and so the ratio {@code M} is always
844 * an integer. In the hypothetical case of a non-integral ratio,
845 * the value {@code M} would be rounded up to the next integer,
846 * and then the same general considerations would apply.)
847 *
848 * <p> If the logical result is larger than the physical output shape,
849 * such a shape change must inevitably drop result lanes (all but
850 * {@code 1/M} of the logical result). If the logical size is smaller
851 * than the output, the shape change must introduce zero-filled lanes
852 * of padding (all but {@code 1/M} of the physical output). The first
853 * case, with dropped lanes, is an expansion, while the second, with
854 * padding lanes added, is a contraction.
855 *
856 * <p> Similarly, consider a lane-wise conversion operation which
857 * leaves the shape invariant but changes the lane size by a ratio of
858 * {@code M}. If the logical result is larger than the output (or
859 * input), this conversion must reduce the {@code VLENGTH} lanes of the
860 * output by {@code M}, dropping all but {@code 1/M} of the logical
861 * result lanes. As before, the dropping of lanes is the hallmark of
862 * an expansion. A lane-wise operation which contracts lane size by a
863 * ratio of {@code M} must increase the {@code VLENGTH} by the same
864 * factor {@code M}, filling the extra lanes with a zero padding
865 * value; because padding must be added this is a contraction.
866 *
867 * <p> It is also possible (though somewhat confusing) to change both
868 * lane size and container size in one operation which performs both
869 * lane conversion <em>and</em> reshaping. If this is done, the same
870 * rules apply, but the logical result size is the product of the
871 * input size times any expansion or contraction ratio from the lane
872 * change size.
873 *
874 * <p> For completeness, we can also speak of <em>in-place
875 * operations</em> for the frequent case when resizing does not occur.
876 * With an in-place operation, the data is simply copied from logical
877 * output to its physical container with no truncation or padding.
878 * The ratio parameter {@code M} in this case is unity.
879 *
880 * <p> Note that the classification of contraction vs. expansion
881 * depends on the relative sizes of the logical result and the
882 * physical output container. The size of the input container may be
883 * larger or smaller than either of the other two values, without
884 * changing the classification. For example, a conversion from a
885 * 128-bit shape to a 256-bit shape will be a contraction in many
886 * cases, but it would be an expansion if it were combined with a
887 * conversion from {@code byte} to {@code long}, since in that case
888 * the logical result would be 1024 bits in size. This example also
889 * illustrates that a logical result does not need to correspond to
890 * any particular platform-supported vector shape.
891 *
892 * <p> Although lane-wise masked operations can be viewed as producing
893 * partial operations, they are not classified (in this API) as
894 * expansions or contractions. A masked load from an array surely
895 * produces a partial vector, but there is no meaningful "logical
896 * output vector" that this partial result was contracted from.
897 *
898 * <p> Some care is required with these terms, because it is the
899 * <em>data</em>, not the <em>container size</em>, that is expanding
900 * or contracting, relative to the size of its output container.
901 * Thus, resizing a 128-bit input into 512-bit vector has the effect
902 * of a <em>contraction</em>. Though the 128 bits of payload hasn't
903 * changed in size, we can say it "looks smaller" in its new 512-bit
904 * home, and this will capture the practical details of the situation.
905 *
906 * <p> If a vector method might expand its data, it accepts an extra
907 * {@code int} parameter called {@code part}, or the "part number".
908 * The part number must be in the range {@code [0..M-1]}, where
909 * {@code M} is the expansion ratio. The part number selects one
910 * of {@code M} contiguous disjoint equally-sized blocks of lanes
911 * from the logical result and fills the physical output vector
912 * with this block of lanes.
913 *
914 * <p> Specifically, the lanes selected from the logical result of an
915 * expansion are numbered in the range {@code [R..R+L-1]}, where
916 * {@code L} is the {@code VLENGTH} of the physical output vector, and
917 * the origin of the block, {@code R}, is {@code part*L}.
918 *
919 * <p> A similar convention applies to any vector method that might
920 * contract its data. Such a method also accepts an extra part number
921 * parameter (again called {@code part}) which steers the contracted
922 * data lanes one of {@code M} contiguous disjoint equally-sized
923 * blocks of lanes in the physical output vector. The remaining lanes
924 * are filled with zero, or as specified by the method.
925 *
926 * <p> Specifically, the data is steered into the lanes numbered in the
927 * range {@code [R..R+L-1]}, where {@code L} is the {@code VLENGTH} of
928 * the logical result vector, and the origin of the block, {@code R},
929 * is again a multiple of {@code L} selected by the part number,
930 * specifically {@code |part|*L}.
931 *
932 * <p> In the case of a contraction, the part number must be in the
933 * non-positive range {@code [-M+1..0]}. This convention is adopted
934 * because some methods can perform both expansions and contractions,
935 * in a data-dependent manner, and the extra sign on the part number
936 * serves as an error check. If vector method takes a part number and
937 * is invoked to perform an in-place operation (neither contracting
938 * nor expanding), the {@code part} parameter must be exactly zero.
939 * Part numbers outside the allowed ranges will elicit an indexing
940 * exception. Note that in all cases a zero part number is valid, and
941 * corresponds to an operation which preserves as many lanes as
942 * possible from the beginning of the logical result, and places them
943 * into the beginning of the physical output container. This is
944 * often a desirable default, so a part number of zero is safe
945 * in all cases and useful in most cases.
946 *
947 * <p> The various resizing operations of this API contract or expand
948 * their data as follows:
949 * <ul>
950 *
951 * <li>
952 * {@link Vector#convert(VectorOperators.Conversion,int) Vector.convert()}
953 * will expand (respectively, contract) its operand by ratio
954 * {@code M} if the
955 * {@linkplain #elementSize() element size} of its output is
956 * larger (respectively, smaller) by a factor of {@code M}.
957 * If the element sizes of input and output are the same,
958 * then {@code convert()} is an in-place operation.
959 *
960 * <li>
961 * {@link Vector#convertShape(VectorOperators.Conversion,VectorSpecies,int) Vector.convertShape()}
962 * will expand (respectively, contract) its operand by ratio
963 * {@code M} if the bit-size of its logical result is
964 * larger (respectively, smaller) than the bit-size of its
965 * output shape.
966 * The size of the logical result is defined as the
967 * {@linkplain #elementSize() element size} of the output,
968 * times the {@code VLENGTH} of its input.
969 *
970 * Depending on the ratio of the changed lane sizes, the logical size
971 * may be (in various cases) either larger or smaller than the input
972 * vector, independently of whether the operation is an expansion
973 * or contraction.
974 *
975 * <li>
976 * Since {@link Vector#castShape(VectorSpecies,int) Vector.castShape()}
977 * is a convenience method for {@code convertShape()}, its classification
978 * as an expansion or contraction is the same as for {@code convertShape()}.
979 *
980 * <li>
981 * {@link Vector#reinterpretShape(VectorSpecies,int) Vector.reinterpretShape()}
982 * is an expansion (respectively, contraction) by ratio {@code M} if the
983 * {@linkplain #bitSize() vector bit-size} of its input is
984 * crammed into a smaller (respectively, dropped into a larger)
985 * output container by a factor of {@code M}.
986 * Otherwise it is an in-place operation.
987 *
988 * Since this method is a reinterpretation cast that can erase and
989 * redraw lane boundaries as well as modify shape, the input vector's
990 * lane size and lane count are irrelevant to its classification as
991 * expanding or contracting.
992 *
993 * <li>
994 * The {@link #unslice(int,Vector,int) unslice()} methods expand
995 * by a ratio of {@code M=2}, because the single input slice is
996 * positioned and inserted somewhere within two consecutive background
997 * vectors. The part number selects the first or second background
998 * vector, as updated by the inserted slice.
999 * Note that the corresponding
1000 * {@link #slice(int,Vector) slice()} methods, although inverse
1001 * to the {@code unslice()} methods, do not contract their data
1002 * and thus require no part number. This is because
1003 * {@code slice()} delivers a slice of exactly {@code VLENGTH}
1004 * lanes extracted from two input vectors.
1005 * </ul>
1006 *
1007 * The method {@link VectorSpecies#partLimit(VectorSpecies,boolean)
1008 * partLimit()} on {@link VectorSpecies} can be used, before any
1009 * expanding or contracting operation is performed, to query the
1010 * limiting value on a part parameter for a proposed expansion
1011 * or contraction. The value returned from {@code partLimit()} is
1012 * positive for expansions, negative for contractions, and zero for
1013 * in-place operations. Its absolute value is the parameter {@code
1014 * M}, and so it serves as an exclusive limit on valid part number
1015 * arguments for the relevant methods. Thus, for expansions, the
1016 * {@code partLimit()} value {@code M} is the exclusive upper limit
1017 * for part numbers, while for contractions the {@code partLimit()}
1018 * value {@code -M} is the exclusive <em>lower</em> limit.
1019 *
1020 * <h2><a id="cross-lane"></a>Moving data across lane boundaries</h2>
1021 * The cross-lane methods which do not redraw lanes or change species
1022 * are more regularly structured and easier to reason about.
1023 * These operations are:
1024 * <ul>
1025 *
1026 * <li>The {@link #slice(int,Vector) slice()} family of methods,
1027 * which extract contiguous slice of {@code VLENGTH} fields from
1028 * a given origin point within a concatenated pair of vectors.
1029 *
1030 * <li>The {@link #unslice(int,Vector,int) unslice()} family of
1031 * methods, which insert a contiguous slice of {@code VLENGTH} fields
1032 * into a concatenated pair of vectors at a given origin point.
1033 *
1034 * <li>The {@link #rearrange(VectorShuffle) rearrange()} family of
1035 * methods, which select an arbitrary set of {@code VLENGTH} lanes
1036 * from one or two input vectors, and assemble them in an arbitrary
1037 * order. The selection and order of lanes is controlled by a
1038 * {@code VectorShuffle} object, which acts as an routing table
1039 * mapping source lanes to destination lanes. A {@code VectorShuffle}
1040 * can encode a mathematical permutation as well as many other
1041 * patterns of data movement.
1042 *
1043 * <li>The {@link #compress(VectorMask)} and {@link #expand(VectorMask)}
1044 * methods, which select up to {@code VLENGTH} lanes from an
1045 * input vector, and assemble them in lane order. The selection of lanes
1046 * is controlled by a {@code VectorMask}, with set lane elements mapping, by
1047 * compression or expansion in lane order, source lanes to destination lanes.
1048 *
1049 * </ul>
1050 * <p> Some vector operations are not lane-wise, but rather move data
1051 * across lane boundaries. Such operations are typically rare in SIMD
1052 * code, though they are sometimes necessary for specific algorithms
1053 * that manipulate data formats at a low level, and/or require SIMD
1054 * data to move in complex local patterns. (Local movement in a small
1055 * window of a large array of data is relatively unusual, although
1056 * some highly patterned algorithms call for it.) In this API such
1057 * methods are always clearly recognizable, so that simpler lane-wise
1058 * reasoning can be confidently applied to the rest of the code.
1059 *
1060 * <p> In some cases, vector lane boundaries are discarded and
1061 * "redrawn from scratch", so that data in a given input lane might
1062 * appear (in several parts) distributed through several output lanes,
1063 * or (conversely) data from several input lanes might be consolidated
1064 * into a single output lane. The fundamental method which can redraw
1065 * lanes boundaries is
1066 * {@link #reinterpretShape(VectorSpecies,int) reinterpretShape()}.
1067 * Built on top of this method, certain convenience methods such
1068 * as {@link #reinterpretAsBytes() reinterpretAsBytes()} or
1069 * {@link #reinterpretAsInts() reinterpretAsInts()} will
1070 * (potentially) redraw lane boundaries, while retaining the
1071 * same overall vector shape.
1072 *
1073 * <p> Operations which produce or consume a scalar result can be
1074 * viewed as very simple cross-lane operations. Methods in the
1075 * {@link #reduceLanesToLong(VectorOperators.Associative)
1076 * reduceLanes()} family fold together all lanes (or mask-selected
1077 * lanes) of a method and return a single result. As an inverse, the
1078 * {@link #broadcast(long) broadcast} family of methods can be thought
1079 * of as crossing lanes in the other direction, from a scalar to all
1080 * lanes of the output vector. Single-lane access methods such as
1081 * {@code lane(I)} or {@code withLane(I,E)} might also be regarded as
1082 * very simple cross-lane operations.
1083 *
1084 * <p> Likewise, a method which moves a non-byte vector to or from a
1085 * byte array could be viewed as a cross-lane operation, because the
1086 * vector lanes must be distributed into separate bytes, or (in the
1087 * other direction) consolidated from array bytes.
1088 *
1089 * @implNote
1090 *
1091 * <h2>Hardware platform dependencies and limitations</h2>
1092 *
1093 * The Vector API is to accelerate computations in style of Single
1094 * Instruction Multiple Data (SIMD), using available hardware
1095 * resources such as vector hardware registers and vector hardware
1096 * instructions. The API is designed to make effective use of
1097 * multiple SIMD hardware platforms.
1098 *
1099 * <p> This API will also work correctly even on Java platforms which
1100 * do not include specialized hardware support for SIMD computations.
1101 * The Vector API is not likely to provide any special performance
1102 * benefit on such platforms.
1103 *
1104 * <p> Currently the implementation is optimized to work best on:
1105 *
1106 * <ul>
1107 *
1108 * <li> Intel x64 platforms supporting at least AVX2 up to AVX-512.
1109 * Masking using mask registers and mask accepting hardware
1110 * instructions on AVX-512 are not currently supported.
1111 *
1112 * <li> ARM AArch64 platforms supporting NEON. Although the API has
1113 * been designed to ensure ARM SVE instructions can be supported
1114 * (vector sizes between 128 to 2048 bits) there is currently no
1115 * implementation of such instructions and the general masking
1116 * capability.
1117 *
1118 * </ul>
1119 * The implementation currently supports masked lane-wise operations
1120 * in a cross-platform manner by composing the unmasked lane-wise
1121 * operation with {@link #blend(Vector, VectorMask) blend} as in
1122 * the expression {@code a.blend(a.lanewise(op, b), m)}, where
1123 * {@code a} and {@code b} are vectors, {@code op} is the vector
1124 * operation, and {@code m} is the mask.
1125 *
1126 * <p> The implementation does not currently support optimal
1127 * vectorized instructions for floating point transcendental
1128 * functions (such as operators {@link VectorOperators#SIN SIN}
1129 * and {@link VectorOperators#LOG LOG}).
1130 *
1131 * <h2>No boxing of primitives</h2>
1132 *
1133 * Although a vector type like {@code Vector<Integer>} may seem to
1134 * work with boxed {@code Integer} values, the overheads associated
1135 * with boxing are avoided by having each vector subtype work
1136 * internally on lane values of the actual {@code ETYPE}, such as
1137 * {@code int}.
1138 *
1139 * <h2>Value-based classes and identity operations</h2>
1140 *
1141 * {@code Vector}, along with all of its subtypes and many of its
1142 * helper types like {@code VectorMask} and {@code VectorShuffle}, is a
1143 * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
1144 * class.
1145 *
1146 * <p> Once created, a vector is never mutated, not even if only
1147 * {@linkplain IntVector#withLane(int,int) a single lane is changed}.
1148 * A new vector is always created to hold a new configuration
1149 * of lane values. The unavailability of mutative methods is a
1150 * necessary consequence of suppressing the object identity of
1151 * all vectors, as value-based classes.
1152 *
1153 * <p> With {@code Vector},
1154 *
1155 * <!-- The following paragraph is shared verbatim
1156 * -- between Vector.java and package-info.java -->
1157 * identity-sensitive operations such as {@code ==} may yield
1158 * unpredictable results, or reduced performance. Oddly enough,
1159 * {@link Vector#equals(Object) v.equals(w)} is likely to be faster
1160 * than {@code v==w}, since {@code equals} is <em>not</em> an identity
1161 * sensitive method.
1162 *
1163 * Also, these objects can be stored in locals and parameters and as
1164 * {@code static final} constants, but storing them in other Java
1165 * fields or in array elements, while semantically valid, may incur
1166 * performance penalties.
1167 * <!-- The preceding paragraph is shared verbatim
1168 * -- between Vector.java and package-info.java -->
1169 *
1170 * @param <E> the boxed version of {@code ETYPE},
1171 * the element type of a vector
1172 *
1173 */
1174 @SuppressWarnings("exports")
1175 public abstract class Vector<E> extends jdk.internal.vm.vector.VectorSupport.Vector<E> {
1176
1177 // This type is sealed within its package.
1178 // Users cannot roll their own vector types.
1179 Vector(Object bits) {
1180 super(bits);
1181 }
1182
1183 /**
1184 * Returns the species of this vector.
1185 *
1186 * @return the species of this vector
1187 */
1188 public abstract VectorSpecies<E> species();
1189
1190 /**
1191 * Returns the primitive <a href="Vector.html#ETYPE">element type</a>
1192 * ({@code ETYPE}) of this vector.
1193 *
1194 * @implSpec
1195 * This is the same value as {@code this.species().elementType()}.
1196 *
1197 * @return the primitive element type of this vector
1198 */
1199 public abstract Class<E> elementType();
1200
1201 /**
1202 * Returns the size of each lane, in bits, of this vector.
1203 *
1204 * @implSpec
1205 * This is the same value as {@code this.species().elementSize()}.
1206 *
1207 * @return the lane size, in bits, of this vector
1208 */
1209 public abstract int elementSize();
1210
1211 /**
1212 * Returns the shape of this vector.
1213 *
1214 * @implSpec
1215 * This is the same value as {@code this.species().vectorShape()}.
1216 *
1217 * @return the shape of this vector
1218 */
1219 public abstract VectorShape shape();
1220
1221 /**
1222 * Returns the lane count, or <a href="Vector.html#VLENGTH">vector length</a>
1223 * ({@code VLENGTH}).
1224 *
1225 * @return the lane count
1226 */
1227 public abstract int length();
1228
1229 /**
1230 * Returns the total size, in bits, of this vector.
1231 *
1232 * @implSpec
1233 * This is the same value as {@code this.shape().vectorBitSize()}.
1234 *
1235 * @return the total size, in bits, of this vector
1236 */
1237 public abstract int bitSize();
1238
1239 /**
1240 * Returns the total size, in bytes, of this vector.
1241 *
1242 * @implSpec
1243 * This is the same value as {@code this.bitSize()/Byte.SIZE}.
1244 *
1245 * @return the total size, in bytes, of this vector
1246 */
1247 public abstract int byteSize();
1248
1249 /// Arithmetic
1250
1251 /**
1252 * Operates on the lane values of this vector.
1253 *
1254 * This is a <a href="Vector.html#lane-wise">lane-wise</a>
1255 * unary operation which applies
1256 * the selected operation to each lane.
1257 *
1258 * @apiNote
1259 * Subtypes improve on this method by sharpening
1260 * the method return type.
1261 *
1262 * @param op the operation used to process lane values
1263 * @return the result of applying the operation lane-wise
1264 * to the input vector
1265 * @throws UnsupportedOperationException if this vector does
1266 * not support the requested operation
1267 * @see VectorOperators#NEG
1268 * @see VectorOperators#NOT
1269 * @see VectorOperators#SIN
1270 * @see #lanewise(VectorOperators.Unary,VectorMask)
1271 * @see #lanewise(VectorOperators.Binary,Vector)
1272 * @see #lanewise(VectorOperators.Ternary,Vector,Vector)
1273 */
1274 public abstract Vector<E> lanewise(VectorOperators.Unary op);
1275
1276 /**
1277 * Operates on the lane values of this vector,
1278 * with selection of lane elements controlled by a mask.
1279 *
1280 * This is a lane-wise unary operation which applies
1281 * the selected operation to each lane.
1282 *
1283 * @apiNote
1284 * Subtypes improve on this method by sharpening
1285 * the method return type.
1286 *
1287 * @param op the operation used to process lane values
1288 * @param m the mask controlling lane selection
1289 * @return the result of applying the operation lane-wise
1290 * to the input vector
1291 * @throws UnsupportedOperationException if this vector does
1292 * not support the requested operation
1293 * @see #lanewise(VectorOperators.Unary)
1294 */
1295 public abstract Vector<E> lanewise(VectorOperators.Unary op,
1296 VectorMask<E> m);
1297
1298 /**
1299 * Combines the corresponding lane values of this vector
1300 * with those of a second input vector.
1301 *
1302 * This is a <a href="Vector.html#lane-wise">lane-wise</a>
1303 * binary operation which applies
1304 * the selected operation to each lane.
1305 *
1306 * @apiNote
1307 * Subtypes improve on this method by sharpening
1308 * the method return type.
1309 *
1310 * @param op the operation used to combine lane values
1311 * @param v the input vector
1312 * @return the result of applying the operation lane-wise
1313 * to the two input vectors
1314 * @throws UnsupportedOperationException if this vector does
1315 * not support the requested operation
1316 * @see VectorOperators#ADD
1317 * @see VectorOperators#XOR
1318 * @see VectorOperators#ATAN2
1319 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1320 * @see #lanewise(VectorOperators.Unary)
1321 * @see #lanewise(VectorOperators.Ternary,Vector, Vector)
1322 */
1323 public abstract Vector<E> lanewise(VectorOperators.Binary op,
1324 Vector<E> v);
1325
1326 /**
1327 * Combines the corresponding lane values of this vector
1328 * with those of a second input vector,
1329 * with selection of lane elements controlled by a mask.
1330 *
1331 * This is a lane-wise binary operation which applies
1332 * the selected operation to each lane.
1333 *
1334 * @apiNote
1335 * Subtypes improve on this method by sharpening
1336 * the method return type.
1337 *
1338 * @param op the operation used to combine lane values
1339 * @param v the second input vector
1340 * @param m the mask controlling lane selection
1341 * @return the result of applying the operation lane-wise
1342 * to the two input vectors
1343 * @throws UnsupportedOperationException if this vector does
1344 * not support the requested operation
1345 * @see #lanewise(VectorOperators.Binary,Vector)
1346 */
1347 public abstract Vector<E> lanewise(VectorOperators.Binary op,
1348 Vector<E> v, VectorMask<E> m);
1349
1350 /**
1351 * Combines the lane values of this vector
1352 * with the value of a broadcast scalar.
1353 *
1354 * This is a lane-wise binary operation which applies
1355 * the selected operation to each lane.
1356 * The return value will be equal to this expression:
1357 * {@code this.lanewise(op, this.broadcast(e))}.
1358 *
1359 * @apiNote
1360 * The {@code long} value {@code e} must be accurately
1361 * representable by the {@code ETYPE} of this vector's species,
1362 * so that {@code e==(long)(ETYPE)e}. This rule is enforced
1363 * by the implicit call to {@code broadcast()}.
1364 * <p>
1365 * Subtypes improve on this method by sharpening
1366 * the method return type and
1367 * the type of the scalar parameter {@code e}.
1368 *
1369 * @param op the operation used to combine lane values
1370 * @param e the input scalar
1371 * @return the result of applying the operation lane-wise
1372 * to the input vector and the scalar
1373 * @throws UnsupportedOperationException if this vector does
1374 * not support the requested operation
1375 * @throws IllegalArgumentException
1376 * if the given {@code long} value cannot
1377 * be represented by the right operand type
1378 * of the vector operation
1379 * @see #broadcast(long)
1380 * @see #lanewise(VectorOperators.Binary,long,VectorMask)
1381 */
1382 public abstract Vector<E> lanewise(VectorOperators.Binary op,
1383 long e);
1384
1385 /**
1386 * Combines the corresponding lane values of this vector
1387 * with those of a second input vector,
1388 * with selection of lane elements controlled by a mask.
1389 *
1390 * This is a lane-wise binary operation which applies
1391 * the selected operation to each lane.
1392 * The second operand is a broadcast integral value.
1393 * The return value will be equal to this expression:
1394 * {@code this.lanewise(op, this.broadcast(e), m)}.
1395 *
1396 * @apiNote
1397 * The {@code long} value {@code e} must be accurately
1398 * representable by the {@code ETYPE} of this vector's species,
1399 * so that {@code e==(long)(ETYPE)e}. This rule is enforced
1400 * by the implicit call to {@code broadcast()}.
1401 * <p>
1402 * Subtypes improve on this method by sharpening
1403 * the method return type and
1404 * the type of the scalar parameter {@code e}.
1405 *
1406 * @param op the operation used to combine lane values
1407 * @param e the input scalar
1408 * @param m the mask controlling lane selection
1409 * @return the result of applying the operation lane-wise
1410 * to the input vector and the scalar
1411 * @throws UnsupportedOperationException if this vector does
1412 * not support the requested operation
1413 * @throws IllegalArgumentException
1414 * if the given {@code long} value cannot
1415 * be represented by the right operand type
1416 * of the vector operation
1417 * @see #broadcast(long)
1418 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1419 */
1420 public abstract Vector<E> lanewise(VectorOperators.Binary op,
1421 long e, VectorMask<E> m);
1422
1423 /**
1424 * Combines the corresponding lane values of this vector
1425 * with the lanes of a second and a third input vector.
1426 *
1427 * This is a <a href="Vector.html#lane-wise">lane-wise</a>
1428 * ternary operation which applies
1429 * the selected operation to each lane.
1430 *
1431 * @apiNote
1432 * Subtypes improve on this method by sharpening
1433 * the method return type.
1434 *
1435 * @param op the operation used to combine lane values
1436 * @param v1 the second input vector
1437 * @param v2 the third input vector
1438 * @return the result of applying the operation lane-wise
1439 * to the three input vectors
1440 * @throws UnsupportedOperationException if this vector does
1441 * not support the requested operation
1442 * @see VectorOperators#BITWISE_BLEND
1443 * @see VectorOperators#FMA
1444 * @see #lanewise(VectorOperators.Unary)
1445 * @see #lanewise(VectorOperators.Binary,Vector)
1446 * @see #lanewise(VectorOperators.Ternary,Vector,Vector,VectorMask)
1447 */
1448 public abstract Vector<E> lanewise(VectorOperators.Ternary op,
1449 Vector<E> v1,
1450 Vector<E> v2);
1451
1452 /**
1453 * Combines the corresponding lane values of this vector
1454 * with the lanes of a second and a third input vector,
1455 * with selection of lane elements controlled by a mask.
1456 *
1457 * This is a lane-wise ternary operation which applies
1458 * the selected operation to each lane.
1459 *
1460 * @apiNote
1461 * Subtypes improve on this method by sharpening
1462 * the method return type.
1463 *
1464 * @param op the operation used to combine lane values
1465 * @param v1 the second input vector
1466 * @param v2 the third input vector
1467 * @param m the mask controlling lane selection
1468 * @return the result of applying the operation lane-wise
1469 * to the three input vectors
1470 * @throws UnsupportedOperationException if this vector does
1471 * not support the requested operation
1472 * @see #lanewise(VectorOperators.Ternary,Vector,Vector)
1473 */
1474 public abstract Vector<E> lanewise(VectorOperators.Ternary op,
1475 Vector<E> v1, Vector<E> v2,
1476 VectorMask<E> m);
1477
1478 // Note: lanewise(Binary) has two rudimentary broadcast
1479 // operations from an approximate scalar type (long).
1480 // We do both with that, here, for lanewise(Ternary).
1481 // The vector subtypes supply a full suite of
1482 // broadcasting and masked lanewise operations
1483 // for their specific ETYPEs:
1484 // lanewise(Unary, [mask])
1485 // lanewise(Binary, [e | v], [mask])
1486 // lanewise(Ternary, [e1 | v1], [e2 | v2], [mask])
1487
1488 /// Full-service binary ops: ADD, SUB, MUL, DIV
1489
1490 // Full-service functions support all four variations
1491 // of vector vs. broadcast scalar, and mask vs. not.
1492 // The lanewise generic operator is (by this definition)
1493 // also a full-service function.
1494
1495 // Other named functions handle just the one named
1496 // variation. Most lanewise operations are *not* named,
1497 // and are reached only by lanewise.
1498
1499 /**
1500 * Adds this vector to a second input vector.
1501 *
1502 * This is a lane-wise binary operation which applies
1503 * the primitive addition operation ({@code +})
1504 * to each pair of corresponding lane values.
1505 *
1506 * This method is also equivalent to the expression
1507 * {@link #lanewise(VectorOperators.Binary,Vector)
1508 * lanewise}{@code (}{@link VectorOperators#ADD
1509 * ADD}{@code , v)}.
1510 *
1511 * <p>
1512 * As a full-service named operation, this method
1513 * comes in masked and unmasked overloadings, and
1514 * (in subclasses) also comes in scalar-broadcast
1515 * overloadings (both masked and unmasked).
1516 *
1517 * @param v a second input vector
1518 * @return the result of adding this vector to the second input vector
1519 * @see #add(Vector,VectorMask)
1520 * @see IntVector#add(int)
1521 * @see VectorOperators#ADD
1522 * @see #lanewise(VectorOperators.Binary,Vector)
1523 * @see IntVector#lanewise(VectorOperators.Binary,int)
1524 */
1525 public abstract Vector<E> add(Vector<E> v);
1526
1527 /**
1528 * Adds this vector to a second input vector, selecting lanes
1529 * under the control of a mask.
1530 *
1531 * This is a masked lane-wise binary operation which applies
1532 * the primitive addition operation ({@code +})
1533 * to each pair of corresponding lane values.
1534 *
1535 * For any lane unset in the mask, the primitive operation is
1536 * suppressed and this vector retains the original value stored in
1537 * that lane.
1538 *
1539 * This method is also equivalent to the expression
1540 * {@link #lanewise(VectorOperators.Binary,Vector,VectorMask)
1541 * lanewise}{@code (}{@link VectorOperators#ADD
1542 * ADD}{@code , v, m)}.
1543 *
1544 * <p>
1545 * As a full-service named operation, this method
1546 * comes in masked and unmasked overloadings, and
1547 * (in subclasses) also comes in scalar-broadcast
1548 * overloadings (both masked and unmasked).
1549 *
1550 * @param v the second input vector
1551 * @param m the mask controlling lane selection
1552 * @return the result of adding this vector to the given vector
1553 * @see #add(Vector)
1554 * @see IntVector#add(int,VectorMask)
1555 * @see VectorOperators#ADD
1556 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1557 * @see IntVector#lanewise(VectorOperators.Binary,int,VectorMask)
1558 */
1559 public abstract Vector<E> add(Vector<E> v, VectorMask<E> m);
1560
1561 /**
1562 * Subtracts a second input vector from this vector.
1563 *
1564 * This is a lane-wise binary operation which applies
1565 * the primitive subtraction operation ({@code -})
1566 * to each pair of corresponding lane values.
1567 *
1568 * This method is also equivalent to the expression
1569 * {@link #lanewise(VectorOperators.Binary,Vector)
1570 * lanewise}{@code (}{@link VectorOperators#SUB
1571 * SUB}{@code , v)}.
1572 *
1573 * <p>
1574 * As a full-service named operation, this method
1575 * comes in masked and unmasked overloadings, and
1576 * (in subclasses) also comes in scalar-broadcast
1577 * overloadings (both masked and unmasked).
1578 *
1579 * @param v a second input vector
1580 * @return the result of subtracting the second input vector from this vector
1581 * @see #sub(Vector,VectorMask)
1582 * @see IntVector#sub(int)
1583 * @see VectorOperators#SUB
1584 * @see #lanewise(VectorOperators.Binary,Vector)
1585 * @see IntVector#lanewise(VectorOperators.Binary,int)
1586 */
1587 public abstract Vector<E> sub(Vector<E> v);
1588
1589 /**
1590 * Subtracts a second input vector from this vector
1591 * under the control of a mask.
1592 *
1593 * This is a masked lane-wise binary operation which applies
1594 * the primitive subtraction operation ({@code -})
1595 * to each pair of corresponding lane values.
1596 *
1597 * For any lane unset in the mask, the primitive operation is
1598 * suppressed and this vector retains the original value stored in
1599 * that lane.
1600 *
1601 * This method is also equivalent to the expression
1602 * {@link #lanewise(VectorOperators.Binary,Vector,VectorMask)
1603 * lanewise}{@code (}{@link VectorOperators#SUB
1604 * SUB}{@code , v, m)}.
1605 *
1606 * <p>
1607 * As a full-service named operation, this method
1608 * comes in masked and unmasked overloadings, and
1609 * (in subclasses) also comes in scalar-broadcast
1610 * overloadings (both masked and unmasked).
1611 *
1612 * @param v the second input vector
1613 * @param m the mask controlling lane selection
1614 * @return the result of subtracting the second input vector from this vector
1615 * @see #sub(Vector)
1616 * @see IntVector#sub(int,VectorMask)
1617 * @see VectorOperators#SUB
1618 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1619 * @see IntVector#lanewise(VectorOperators.Binary,int,VectorMask)
1620 */
1621 public abstract Vector<E> sub(Vector<E> v, VectorMask<E> m);
1622
1623 /**
1624 * Multiplies this vector by a second input vector.
1625 *
1626 * This is a lane-wise binary operation which applies
1627 * the primitive multiplication operation ({@code *})
1628 * to each pair of corresponding lane values.
1629 *
1630 * This method is also equivalent to the expression
1631 * {@link #lanewise(VectorOperators.Binary,Vector)
1632 * lanewise}{@code (}{@link VectorOperators#MUL
1633 * MUL}{@code , v)}.
1634 *
1635 * <p>
1636 * As a full-service named operation, this method
1637 * comes in masked and unmasked overloadings, and
1638 * (in subclasses) also comes in scalar-broadcast
1639 * overloadings (both masked and unmasked).
1640 *
1641 * @param v a second input vector
1642 * @return the result of multiplying this vector by the second input vector
1643 * @see #mul(Vector,VectorMask)
1644 * @see IntVector#mul(int)
1645 * @see VectorOperators#MUL
1646 * @see #lanewise(VectorOperators.Binary,Vector)
1647 * @see IntVector#lanewise(VectorOperators.Binary,int)
1648 */
1649 public abstract Vector<E> mul(Vector<E> v);
1650
1651 /**
1652 * Multiplies this vector by a second input vector
1653 * under the control of a mask.
1654 *
1655 * This is a lane-wise binary operation which applies
1656 * the primitive multiplication operation ({@code *})
1657 * to each pair of corresponding lane values.
1658 *
1659 * For any lane unset in the mask, the primitive operation is
1660 * suppressed and this vector retains the original value stored in
1661 * that lane.
1662 *
1663 * This method is also equivalent to the expression
1664 * {@link #lanewise(VectorOperators.Binary,Vector,VectorMask)
1665 * lanewise}{@code (}{@link VectorOperators#MUL
1666 * MUL}{@code , v, m)}.
1667 *
1668 * <p>
1669 * As a full-service named operation, this method
1670 * comes in masked and unmasked overloadings, and
1671 * (in subclasses) also comes in scalar-broadcast
1672 * overloadings (both masked and unmasked).
1673 *
1674 * @param v the second input vector
1675 * @param m the mask controlling lane selection
1676 * @return the result of multiplying this vector by the given vector
1677 * @see #mul(Vector)
1678 * @see IntVector#mul(int,VectorMask)
1679 * @see VectorOperators#MUL
1680 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1681 * @see IntVector#lanewise(VectorOperators.Binary,int,VectorMask)
1682 */
1683 public abstract Vector<E> mul(Vector<E> v, VectorMask<E> m);
1684
1685 /**
1686 * Divides this vector by a second input vector.
1687 *
1688 * This is a lane-wise binary operation which applies
1689 * the primitive division operation ({@code /})
1690 * to each pair of corresponding lane values.
1691 *
1692 * This method is also equivalent to the expression
1693 * {@link #lanewise(VectorOperators.Binary,Vector)
1694 * lanewise}{@code (}{@link VectorOperators#DIV
1695 * DIV}{@code , v)}.
1696 *
1697 * <p>
1698 * As a full-service named operation, this method
1699 * comes in masked and unmasked overloadings, and
1700 * (in subclasses) also comes in scalar-broadcast
1701 * overloadings (both masked and unmasked).
1702 *
1703 * @apiNote If the underlying scalar operator does not support
1704 * division by zero, but is presented with a zero divisor,
1705 * an {@code ArithmeticException} will be thrown.
1706 *
1707 * @param v a second input vector
1708 * @return the result of dividing this vector by the second input vector
1709 * @throws ArithmeticException if any lane
1710 * in {@code v} is zero
1711 * and {@code ETYPE} is not {@code float} or {@code double}.
1712 * @see #div(Vector,VectorMask)
1713 * @see DoubleVector#div(double)
1714 * @see VectorOperators#DIV
1715 * @see #lanewise(VectorOperators.Binary,Vector)
1716 * @see IntVector#lanewise(VectorOperators.Binary,int)
1717 */
1718 public abstract Vector<E> div(Vector<E> v);
1719
1720 /**
1721 * Divides this vector by a second input vector
1722 * under the control of a mask.
1723 *
1724 * This is a lane-wise binary operation which applies
1725 * the primitive division operation ({@code /})
1726 * to each pair of corresponding lane values.
1727 *
1728 * For any lane unset in the mask, the primitive operation is
1729 * suppressed and this vector retains the original value stored in
1730 * that lane.
1731 *
1732 * This method is also equivalent to the expression
1733 * {@link #lanewise(VectorOperators.Binary,Vector,VectorMask)
1734 * lanewise}{@code (}{@link VectorOperators#DIV
1735 * DIV}{@code , v, m)}.
1736 *
1737 * <p>
1738 * As a full-service named operation, this method
1739 * comes in masked and unmasked overloadings, and
1740 * (in subclasses) also comes in scalar-broadcast
1741 * overloadings (both masked and unmasked).
1742 *
1743 * @apiNote If the underlying scalar operator does not support
1744 * division by zero, but is presented with a zero divisor,
1745 * an {@code ArithmeticException} will be thrown.
1746 *
1747 * @param v a second input vector
1748 * @param m the mask controlling lane selection
1749 * @return the result of dividing this vector by the second input vector
1750 * @throws ArithmeticException if any lane selected by {@code m}
1751 * in {@code v} is zero
1752 * and {@code ETYPE} is not {@code float} or {@code double}.
1753 * @see #div(Vector)
1754 * @see DoubleVector#div(double,VectorMask)
1755 * @see VectorOperators#DIV
1756 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1757 * @see DoubleVector#lanewise(VectorOperators.Binary,double,VectorMask)
1758 */
1759 public abstract Vector<E> div(Vector<E> v, VectorMask<E> m);
1760
1761 /// END OF FULL-SERVICE BINARY METHODS
1762
1763 /// Non-full-service unary ops: NEG, ABS
1764
1765 /**
1766 * Negates this vector.
1767 *
1768 * This is a lane-wise unary operation which applies
1769 * the primitive negation operation ({@code -x})
1770 * to each input lane.
1771 *
1772 * This method is also equivalent to the expression
1773 * {@link #lanewise(VectorOperators.Unary)
1774 * lanewise}{@code (}{@link VectorOperators#NEG
1775 * NEG}{@code )}.
1776 *
1777 * @apiNote
1778 * This method has no masked variant, but the corresponding
1779 * masked operation can be obtained from the
1780 * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
1781 * lanewise method}.
1782 *
1783 * @return the negation of this vector
1784 * @see VectorOperators#NEG
1785 * @see #lanewise(VectorOperators.Unary)
1786 * @see #lanewise(VectorOperators.Unary,VectorMask)
1787 */
1788 public abstract Vector<E> neg();
1789
1790 /**
1791 * Returns the absolute value of this vector.
1792 *
1793 * This is a lane-wise unary operation which applies
1794 * the method {@code Math.abs}
1795 * to each input lane.
1796 *
1797 * This method is also equivalent to the expression
1798 * {@link #lanewise(VectorOperators.Unary)
1799 * lanewise}{@code (}{@link VectorOperators#ABS
1800 * ABS}{@code )}.
1801 *
1802 * @apiNote
1803 * This method has no masked variant, but the corresponding
1804 * masked operation can be obtained from the
1805 * {@linkplain #lanewise(VectorOperators.Unary,VectorMask)
1806 * lanewise method}.
1807 *
1808 * @return the absolute value of this vector
1809 * @see VectorOperators#ABS
1810 * @see #lanewise(VectorOperators.Unary)
1811 * @see #lanewise(VectorOperators.Unary,VectorMask)
1812 */
1813 public abstract Vector<E> abs();
1814
1815 /// Non-full-service binary ops: MIN, MAX
1816
1817 /**
1818 * Computes the smaller of this vector and a second input vector.
1819 *
1820 * This is a lane-wise binary operation which applies the
1821 * operation {@code Math.min()} to each pair of
1822 * corresponding lane values.
1823 *
1824 * This method is also equivalent to the expression
1825 * {@link #lanewise(VectorOperators.Binary,Vector)
1826 * lanewise}{@code (}{@link VectorOperators#MIN
1827 * MIN}{@code , v)}.
1828 *
1829 * @apiNote
1830 * This is not a full-service named operation like
1831 * {@link #add(Vector) add()}. A masked version of
1832 * this operation is not directly available
1833 * but may be obtained via the masked version of
1834 * {@code lanewise}. Subclasses define an additional
1835 * scalar-broadcast overloading of this method.
1836 *
1837 * @param v a second input vector
1838 * @return the lanewise minimum of this vector and the second input vector
1839 * @see IntVector#min(int)
1840 * @see VectorOperators#MIN
1841 * @see #lanewise(VectorOperators.Binary,Vector)
1842 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1843 */
1844 public abstract Vector<E> min(Vector<E> v);
1845
1846 /**
1847 * Computes the larger of this vector and a second input vector.
1848 *
1849 * This is a lane-wise binary operation which applies the
1850 * operation {@code Math.max()} to each pair of
1851 * corresponding lane values.
1852 *
1853 * This method is also equivalent to the expression
1854 * {@link #lanewise(VectorOperators.Binary,Vector)
1855 * lanewise}{@code (}{@link VectorOperators#MAX
1856 * MAX}{@code , v)}.
1857 *
1858 * <p>
1859 * This is not a full-service named operation like
1860 * {@link #add(Vector) add()}. A masked version of
1861 * this operation is not directly available
1862 * but may be obtained via the masked version of
1863 * {@code lanewise}. Subclasses define an additional
1864 * scalar-broadcast overloading of this method.
1865 *
1866 * @param v a second input vector
1867 * @return the lanewise maximum of this vector and the second input vector
1868 * @see IntVector#max(int)
1869 * @see VectorOperators#MAX
1870 * @see #lanewise(VectorOperators.Binary,Vector)
1871 * @see #lanewise(VectorOperators.Binary,Vector,VectorMask)
1872 */
1873 public abstract Vector<E> max(Vector<E> v);
1874
1875 // Reductions
1876
1877 /**
1878 * Returns a value accumulated from all the lanes of this vector.
1879 *
1880 * This is an associative cross-lane reduction operation which
1881 * applies the specified operation to all the lane elements.
1882 * The return value will be equal to this expression:
1883 * {@code (long) ((EVector)this).reduceLanes(op)}, where {@code EVector}
1884 * is the vector class specific to this vector's element type
1885 * {@code ETYPE}.
1886 * <p>
1887 * In the case of operations {@code ADD} and {@code MUL},
1888 * when {@code ETYPE} is {@code float} or {@code double},
1889 * the precise result, before casting, will reflect the choice
1890 * of an arbitrary order of operations, which may even vary over time.
1891 * For further details see the section
1892 * <a href="VectorOperators.html#fp_assoc">Operations on floating point vectors</a>.
1893 *
1894 * @apiNote
1895 * If the {@code ETYPE} is {@code float} or {@code double},
1896 * this operation can lose precision and/or range, as a
1897 * normal part of casting the result down to {@code long}.
1898 *
1899 * Usually
1900 * {@linkplain IntVector#reduceLanes(VectorOperators.Associative)
1901 * strongly typed access}
1902 * is preferable, if you are working with a vector
1903 * subtype that has a known element type.
1904 *
1905 * @param op the operation used to combine lane values
1906 * @return the accumulated result, cast to {@code long}
1907 * @throws UnsupportedOperationException if this vector does
1908 * not support the requested operation
1909 * @see #reduceLanesToLong(VectorOperators.Associative,VectorMask)
1910 * @see IntVector#reduceLanes(VectorOperators.Associative)
1911 * @see FloatVector#reduceLanes(VectorOperators.Associative)
1912 */
1913 public abstract long reduceLanesToLong(VectorOperators.Associative op);
1914
1915 /**
1916 * Returns a value accumulated from selected lanes of this vector,
1917 * controlled by a mask.
1918 *
1919 * This is an associative cross-lane reduction operation which
1920 * applies the specified operation to the selected lane elements.
1921 * The return value will be equal to this expression:
1922 * {@code (long) ((EVector)this).reduceLanes(op, m)}, where {@code EVector}
1923 * is the vector class specific to this vector's element type
1924 * {@code ETYPE}.
1925 * <p>
1926 * If no elements are selected, an operation-specific identity
1927 * value is returned.
1928 * <ul>
1929 * <li>
1930 * If the operation is {@code ADD}, {@code XOR}, or {@code OR},
1931 * then the identity value is zero.
1932 * <li>
1933 * If the operation is {@code MUL},
1934 * then the identity value is one.
1935 * <li>
1936 * If the operation is {@code AND},
1937 * then the identity value is minus one (all bits set).
1938 * <li>
1939 * If the operation is {@code MAX},
1940 * then the identity value is the {@code MIN_VALUE}
1941 * of the vector's native {@code ETYPE}.
1942 * (In the case of floating point types, the value
1943 * {@code NEGATIVE_INFINITY} is used, and will appear
1944 * after casting as {@code Long.MIN_VALUE}.
1945 * <li>
1946 * If the operation is {@code MIN},
1947 * then the identity value is the {@code MAX_VALUE}
1948 * of the vector's native {@code ETYPE}.
1949 * (In the case of floating point types, the value
1950 * {@code POSITIVE_INFINITY} is used, and will appear
1951 * after casting as {@code Long.MAX_VALUE}.
1952 * </ul>
1953 * <p>
1954 * In the case of operations {@code ADD} and {@code MUL},
1955 * when {@code ETYPE} is {@code float} or {@code double},
1956 * the precise result, before casting, will reflect the choice
1957 * of an arbitrary order of operations, which may even vary over time.
1958 * For further details see the section
1959 * <a href="VectorOperators.html#fp_assoc">Operations on floating point vectors</a>.
1960 *
1961 * @apiNote
1962 * If the {@code ETYPE} is {@code float} or {@code double},
1963 * this operation can lose precision and/or range, as a
1964 * normal part of casting the result down to {@code long}.
1965 *
1966 * Usually
1967 * {@linkplain IntVector#reduceLanes(VectorOperators.Associative,VectorMask)
1968 * strongly typed access}
1969 * is preferable, if you are working with a vector
1970 * subtype that has a known element type.
1971 *
1972 * @param op the operation used to combine lane values
1973 * @param m the mask controlling lane selection
1974 * @return the reduced result accumulated from the selected lane values
1975 * @throws UnsupportedOperationException if this vector does
1976 * not support the requested operation
1977 * @see #reduceLanesToLong(VectorOperators.Associative)
1978 * @see IntVector#reduceLanes(VectorOperators.Associative,VectorMask)
1979 * @see FloatVector#reduceLanes(VectorOperators.Associative,VectorMask)
1980 */
1981 public abstract long reduceLanesToLong(VectorOperators.Associative op,
1982 VectorMask<E> m);
1983
1984 // Lanewise unary tests
1985
1986 /**
1987 * Tests the lanes of this vector
1988 * according to the given operation.
1989 *
1990 * This is a lane-wise unary test operation which applies
1991 * the given test operation
1992 * to each lane value.
1993 * @param op the operation used to test lane values
1994 * @return the mask result of testing the lanes of this vector,
1995 * according to the selected test operator
1996 * @see VectorOperators.Comparison
1997 * @see #test(VectorOperators.Test, VectorMask)
1998 * @see #compare(VectorOperators.Comparison, Vector)
1999 */
2000 public abstract VectorMask<E> test(VectorOperators.Test op);
2001
2002 /**
2003 * Test selected lanes of this vector,
2004 * according to the given operation.
2005 *
2006 * This is a masked lane-wise unary test operation which applies
2007 * the given test operation
2008 * to each lane value.
2009 *
2010 * The returned result is equal to the expression
2011 * {@code test(op).and(m)}.
2012 *
2013 * @param op the operation used to test lane values
2014 * @param m the mask controlling lane selection
2015 * @return the mask result of testing the lanes of this vector,
2016 * according to the selected test operator,
2017 * and only in the lanes selected by the mask
2018 * @see #test(VectorOperators.Test)
2019 */
2020 public abstract VectorMask<E> test(VectorOperators.Test op,
2021 VectorMask<E> m);
2022
2023 // Comparisons
2024
2025 /**
2026 * Tests if this vector is equal to another input vector.
2027 *
2028 * This is a lane-wise binary test operation which applies
2029 * the primitive equals operation ({@code ==})
2030 * to each pair of corresponding lane values.
2031 * The result is the same as {@code compare(VectorOperators.EQ, v)}.
2032 *
2033 * @param v a second input vector
2034 * @return the mask result of testing lane-wise if this vector
2035 * equal to the second input vector
2036 * @see #compare(VectorOperators.Comparison,Vector)
2037 * @see VectorOperators#EQ
2038 * @see #equals
2039 */
2040 public abstract VectorMask<E> eq(Vector<E> v);
2041
2042 /**
2043 * Tests if this vector is less than another input vector.
2044 *
2045 * This is a lane-wise binary test operation which applies
2046 * the primitive less-than operation ({@code <}) to each lane.
2047 * The result is the same as {@code compare(VectorOperators.LT, v)}.
2048 *
2049 * @param v a second input vector
2050 * @return the mask result of testing lane-wise if this vector
2051 * is less than the second input vector
2052 * @see #compare(VectorOperators.Comparison,Vector)
2053 * @see VectorOperators#LT
2054 */
2055 public abstract VectorMask<E> lt(Vector<E> v);
2056
2057 /**
2058 * Tests this vector by comparing it with another input vector,
2059 * according to the given comparison operation.
2060 *
2061 * This is a lane-wise binary test operation which applies
2062 * the given comparison operation
2063 * to each pair of corresponding lane values.
2064 *
2065 * @param op the operation used to compare lane values
2066 * @param v a second input vector
2067 * @return the mask result of testing lane-wise if this vector
2068 * compares to the input, according to the selected
2069 * comparison operator
2070 * @see #eq(Vector)
2071 * @see #lt(Vector)
2072 * @see VectorOperators.Comparison
2073 * @see #compare(VectorOperators.Comparison, Vector, VectorMask)
2074 * @see #test(VectorOperators.Test)
2075 */
2076 public abstract VectorMask<E> compare(VectorOperators.Comparison op,
2077 Vector<E> v);
2078
2079 /**
2080 * Tests this vector by comparing it with another input vector,
2081 * according to the given comparison operation,
2082 * in lanes selected by a mask.
2083 *
2084 * This is a masked lane-wise binary test operation which applies
2085 * the given comparison operation
2086 * to each pair of corresponding lane values.
2087 *
2088 * The returned result is equal to the expression
2089 * {@code compare(op,v).and(m)}.
2090 *
2091 * @param op the operation used to compare lane values
2092 * @param v a second input vector
2093 * @param m the mask controlling lane selection
2094 * @return the mask result of testing lane-wise if this vector
2095 * compares to the input, according to the selected
2096 * comparison operator,
2097 * and only in the lanes selected by the mask
2098 * @see #compare(VectorOperators.Comparison, Vector)
2099 */
2100 public abstract VectorMask<E> compare(VectorOperators.Comparison op,
2101 Vector<E> v,
2102 VectorMask<E> m);
2103
2104 /**
2105 * Tests this vector by comparing it with an input scalar,
2106 * according to the given comparison operation.
2107 *
2108 * This is a lane-wise binary test operation which applies
2109 * the given comparison operation
2110 * to each lane value, paired with the broadcast value.
2111 *
2112 * <p>
2113 * The result is the same as
2114 * {@code this.compare(op, this.broadcast(e))}.
2115 * That is, the scalar may be regarded as broadcast to
2116 * a vector of the same species, and then compared
2117 * against the original vector, using the selected
2118 * comparison operation.
2119 *
2120 * @apiNote
2121 * The {@code long} value {@code e} must be accurately
2122 * representable by the {@code ETYPE} of this vector's species,
2123 * so that {@code e==(long)(ETYPE)e}. This rule is enforced
2124 * by the implicit call to {@code broadcast()}.
2125 * <p>
2126 * Subtypes improve on this method by sharpening
2127 * the type of the scalar parameter {@code e}.
2128 *
2129 * @param op the operation used to compare lane values
2130 * @param e the input scalar
2131 * @return the mask result of testing lane-wise if this vector
2132 * compares to the input, according to the selected
2133 * comparison operator
2134 * @throws IllegalArgumentException
2135 * if the given {@code long} value cannot
2136 * be represented by the vector's {@code ETYPE}
2137 * @see #broadcast(long)
2138 * @see #compare(VectorOperators.Comparison,Vector)
2139 */
2140 public abstract VectorMask<E> compare(VectorOperators.Comparison op,
2141 long e);
2142
2143 /**
2144 * Tests this vector by comparing it with an input scalar,
2145 * according to the given comparison operation,
2146 * in lanes selected by a mask.
2147 *
2148 * This is a masked lane-wise binary test operation which applies
2149 * the given comparison operation
2150 * to each lane value, paired with the broadcast value.
2151 *
2152 * The returned result is equal to the expression
2153 * {@code compare(op,e).and(m)}.
2154 *
2155 * @apiNote
2156 * The {@code long} value {@code e} must be accurately
2157 * representable by the {@code ETYPE} of this vector's species,
2158 * so that {@code e==(long)(ETYPE)e}. This rule is enforced
2159 * by the implicit call to {@code broadcast()}.
2160 * <p>
2161 * Subtypes improve on this method by sharpening
2162 * the type of the scalar parameter {@code e}.
2163 *
2164 * @param op the operation used to compare lane values
2165 * @param e the input scalar
2166 * @param m the mask controlling lane selection
2167 * @return the mask result of testing lane-wise if this vector
2168 * compares to the input, according to the selected
2169 * comparison operator,
2170 * and only in the lanes selected by the mask
2171 * @throws IllegalArgumentException
2172 * if the given {@code long} value cannot
2173 * be represented by the vector's {@code ETYPE}
2174 * @see #broadcast(long)
2175 * @see #compare(VectorOperators.Comparison,Vector)
2176 */
2177 public abstract VectorMask<E> compare(VectorOperators.Comparison op,
2178 long e,
2179 VectorMask<E> m);
2180
2181 /**
2182 * Replaces selected lanes of this vector with
2183 * corresponding lanes from a second input vector
2184 * under the control of a mask.
2185 *
2186 * This is a masked lane-wise binary operation which
2187 * selects each lane value from one or the other input.
2188 *
2189 * <ul>
2190 * <li>
2191 * For any lane <em>set</em> in the mask, the new lane value
2192 * is taken from the second input vector, and replaces
2193 * whatever value was in the that lane of this vector.
2194 * <li>
2195 * For any lane <em>unset</em> in the mask, the replacement is
2196 * suppressed and this vector retains the original value stored in
2197 * that lane.
2198 * </ul>
2199 *
2200 * The following pseudocode illustrates this behavior:
2201 * <pre>{@code
2202 * Vector<E> a = ...;
2203 * VectorSpecies<E> species = a.species();
2204 * Vector<E> b = ...;
2205 * b.check(species);
2206 * VectorMask<E> m = ...;
2207 * ETYPE[] ar = a.toArray();
2208 * for (int i = 0; i < ar.length; i++) {
2209 * if (m.laneIsSet(i)) {
2210 * ar[i] = b.lane(i);
2211 * }
2212 * }
2213 * return EVector.fromArray(s, ar, 0);
2214 * }</pre>
2215 *
2216 * @param v the second input vector, containing replacement lane values
2217 * @param m the mask controlling lane selection from the second input vector
2218 * @return the result of blending the lane elements of this vector with
2219 * those of the second input vector
2220 */
2221 public abstract Vector<E> blend(Vector<E> v, VectorMask<E> m);
2222
2223 /**
2224 * Replaces selected lanes of this vector with
2225 * a scalar value
2226 * under the control of a mask.
2227 *
2228 * This is a masked lane-wise binary operation which
2229 * selects each lane value from one or the other input.
2230 *
2231 * The returned result is equal to the expression
2232 * {@code blend(broadcast(e),m)}.
2233 *
2234 * @apiNote
2235 * The {@code long} value {@code e} must be accurately
2236 * representable by the {@code ETYPE} of this vector's species,
2237 * so that {@code e==(long)(ETYPE)e}. This rule is enforced
2238 * by the implicit call to {@code broadcast()}.
2239 * <p>
2240 * Subtypes improve on this method by sharpening
2241 * the type of the scalar parameter {@code e}.
2242 *
2243 * @param e the input scalar, containing the replacement lane value
2244 * @param m the mask controlling lane selection of the scalar
2245 * @return the result of blending the lane elements of this vector with
2246 * the scalar value
2247 */
2248 public abstract Vector<E> blend(long e, VectorMask<E> m);
2249
2250 /**
2251 * Adds the lanes of this vector to their corresponding
2252 * lane numbers, scaled by a given constant.
2253 *
2254 * This is a lane-wise unary operation which, for
2255 * each lane {@code N}, computes the scaled index value
2256 * {@code N*scale} and adds it to the value already
2257 * in lane {@code N} of the current vector.
2258 *
2259 * <p> The scale must not be so large, and the element size must
2260 * not be so small, that that there would be an overflow when
2261 * computing any of the {@code N*scale} or {@code VLENGTH*scale},
2262 * when the the result is represented using the vector
2263 * lane type {@code ETYPE}.
2264 *
2265 * <p>
2266 * The following pseudocode illustrates this behavior:
2267 * <pre>{@code
2268 * Vector<E> a = ...;
2269 * VectorSpecies<E> species = a.species();
2270 * ETYPE[] ar = a.toArray();
2271 * for (int i = 0; i < ar.length; i++) {
2272 * long d = (long)i * scale;
2273 * if (d != (ETYPE) d) throw ...;
2274 * ar[i] += (ETYPE) d;
2275 * }
2276 * long d = (long)ar.length * scale;
2277 * if (d != (ETYPE) d) throw ...;
2278 * return EVector.fromArray(s, ar, 0);
2279 * }</pre>
2280 *
2281 * @param scale the number to multiply by each lane index
2282 * {@code N}, typically {@code 1}
2283 * @return the result of incrementing each lane element by its
2284 * corresponding lane index {@code N}, scaled by {@code scale}
2285 * @throws IllegalArgumentException
2286 * if the values in the interval
2287 * {@code [0..VLENGTH*scale]}
2288 * are not representable by the {@code ETYPE}
2289 */
2290 public abstract Vector<E> addIndex(int scale);
2291
2292 // Slicing segments of adjacent lanes
2293
2294 /**
2295 * Slices a segment of adjacent lanes, starting at a given
2296 * {@code origin} lane in the current vector, and continuing (as
2297 * needed) into an immediately following vector. The block of
2298 * {@code VLENGTH} lanes is extracted into its own vector and
2299 * returned.
2300 *
2301 * <p> This is a cross-lane operation that shifts lane elements
2302 * to the front, from the current vector and the second vector.
2303 * Both vectors can be viewed as a combined "background" of length
2304 * {@code 2*VLENGTH}, from which a slice is extracted.
2305 *
2306 * The lane numbered {@code N} in the output vector is copied
2307 * from lane {@code origin+N} of the input vector, if that
2308 * lane exists, else from lane {@code origin+N-VLENGTH} of
2309 * the second vector (which is guaranteed to exist).
2310 *
2311 * <p> The {@code origin} value must be in the inclusive range
2312 * {@code 0..VLENGTH}. As limiting cases, {@code v.slice(0,w)}
2313 * and {@code v.slice(VLENGTH,w)} return {@code v} and {@code w},
2314 * respectively.
2315 *
2316 * @apiNote
2317 *
2318 * This method may be regarded as the inverse of
2319 * {@link #unslice(int,Vector,int) unslice()},
2320 * in that the sliced value could be unsliced back into its
2321 * original position in the two input vectors, without
2322 * disturbing unrelated elements, as in the following
2323 * pseudocode:
2324 * <pre>{@code
2325 * EVector slice = v1.slice(origin, v2);
2326 * EVector w1 = slice.unslice(origin, v1, 0);
2327 * EVector w2 = slice.unslice(origin, v2, 1);
2328 * assert v1.equals(w1);
2329 * assert v2.equals(w2);
2330 * }</pre>
2331 *
2332 * <p> This method also supports a variety of cross-lane shifts and
2333 * rotates as follows:
2334 * <ul>
2335 *
2336 * <li>To shift lanes forward to the front of the vector, supply a
2337 * zero vector for the second operand and specify the shift count
2338 * as the origin. For example: {@code v.slice(shift, v.broadcast(0))}.
2339 *
2340 * <li>To shift lanes backward to the back of the vector, supply a
2341 * zero vector for the <em>first</em> operand, and specify the
2342 * negative shift count as the origin (modulo {@code VLENGTH}.
2343 * For example: {@code v.broadcast(0).slice(v.length()-shift, v)}.
2344 *
2345 * <li>To rotate lanes forward toward the front end of the vector,
2346 * cycling the earliest lanes around to the back, supply the same
2347 * vector for both operands and specify the rotate count as the
2348 * origin. For example: {@code v.slice(rotate, v)}.
2349 *
2350 * <li>To rotate lanes backward toward the back end of the vector,
2351 * cycling the latest lanes around to the front, supply the same
2352 * vector for both operands and specify the negative of the rotate
2353 * count (modulo {@code VLENGTH}) as the origin. For example:
2354 * {@code v.slice(v.length() - rotate, v)}.
2355 *
2356 * <li>
2357 * Since {@code origin} values less then zero or more than
2358 * {@code VLENGTH} will be rejected, if you need to rotate
2359 * by an unpredictable multiple of {@code VLENGTH}, be sure
2360 * to reduce the origin value into the required range.
2361 * The {@link VectorSpecies#loopBound(int) loopBound()}
2362 * method can help with this. For example:
2363 * {@code v.slice(rotate - v.species().loopBound(rotate), v)}.
2364 *
2365 * </ul>
2366 *
2367 * @param origin the first input lane to transfer into the slice
2368 * @param v1 a second vector logically concatenated with the first,
2369 * before the slice is taken (if omitted it defaults to zero)
2370 * @return a contiguous slice of {@code VLENGTH} lanes, taken from
2371 * this vector starting at the indicated origin, and
2372 * continuing (as needed) into the second vector
2373 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2374 * is negative or greater than {@code VLENGTH}
2375 * @see #slice(int,Vector,VectorMask)
2376 * @see #slice(int)
2377 * @see #unslice(int,Vector,int)
2378 */
2379 public abstract Vector<E> slice(int origin, Vector<E> v1);
2380
2381 /**
2382 * Slices a segment of adjacent lanes
2383 * under the control of a mask,
2384 * starting at a given
2385 * {@code origin} lane in the current vector, and continuing (as
2386 * needed) into an immediately following vector. The block of
2387 * {@code VLENGTH} lanes is extracted into its own vector and
2388 * returned.
2389 *
2390 * The resulting vector will be zero in all lanes unset in the
2391 * given mask. Lanes set in the mask will contain data copied
2392 * from selected lanes of {@code this} or {@code v1}.
2393 *
2394 * <p> This is a cross-lane operation that shifts lane elements
2395 * to the front, from the current vector and the second vector.
2396 * Both vectors can be viewed as a combined "background" of length
2397 * {@code 2*VLENGTH}, from which a slice is extracted.
2398 *
2399 * The returned result is equal to the expression
2400 * {@code broadcast(0).blend(slice(origin,v1),m)}.
2401 *
2402 * @apiNote
2403 * This method may be regarded as the inverse of
2404 * {@code #unslice(int,Vector,int,VectorMask) unslice()},
2405 * in that the sliced value could be unsliced back into its
2406 * original position in the two input vectors, without
2407 * disturbing unrelated elements, as in the following
2408 * pseudocode:
2409 * <pre>{@code
2410 * EVector slice = v1.slice(origin, v2, m);
2411 * EVector w1 = slice.unslice(origin, v1, 0, m);
2412 * EVector w2 = slice.unslice(origin, v2, 1, m);
2413 * assert v1.equals(w1);
2414 * assert v2.equals(w2);
2415 * }</pre>
2416 *
2417 * @param origin the first input lane to transfer into the slice
2418 * @param v1 a second vector logically concatenated with the first,
2419 * before the slice is taken (if omitted it defaults to zero)
2420 * @param m the mask controlling lane selection into the resulting vector
2421 * @return a contiguous slice of {@code VLENGTH} lanes, taken from
2422 * this vector starting at the indicated origin, and
2423 * continuing (as needed) into the second vector
2424 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2425 * is negative or greater than {@code VLENGTH}
2426 * @see #slice(int,Vector)
2427 * @see #unslice(int,Vector,int,VectorMask)
2428 */
2429 // This doesn't pull its weight, but its symmetrical with
2430 // masked unslice, and might cause questions if missing.
2431 // It could make for clearer code.
2432 public abstract Vector<E> slice(int origin, Vector<E> v1, VectorMask<E> m);
2433
2434 /**
2435 * Slices a segment of adjacent lanes, starting at a given
2436 * {@code origin} lane in the current vector. A block of
2437 * {@code VLENGTH} lanes, possibly padded with zero lanes, is
2438 * extracted into its own vector and returned.
2439 *
2440 * This is a convenience method which slices from a single
2441 * vector against an extended background of zero lanes.
2442 * It is equivalent to
2443 * {@link #slice(int,Vector) slice}{@code
2444 * (origin, }{@link #broadcast(long) broadcast}{@code (0))}.
2445 * It may also be viewed simply as a cross-lane shift
2446 * from later to earlier lanes, with zeroes filling
2447 * in the vacated lanes at the end of the vector.
2448 * In this view, the shift count is {@code origin}.
2449 *
2450 * @param origin the first input lane to transfer into the slice
2451 * @return the last {@code VLENGTH-origin} input lanes,
2452 * placed starting in the first lane of the ouput,
2453 * padded at the end with zeroes
2454 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2455 * is negative or greater than {@code VLENGTH}
2456 * @see #slice(int,Vector)
2457 * @see #unslice(int,Vector,int)
2458 */
2459 // This API point pulls its weight as a teaching aid,
2460 // though it's a one-off and broadcast(0) is easy.
2461 public abstract Vector<E> slice(int origin);
2462
2463 /**
2464 * Reverses a {@linkplain #slice(int,Vector) slice()}, inserting
2465 * the current vector as a slice within another "background" input
2466 * vector, which is regarded as one or the other input to a
2467 * hypothetical subsequent {@code slice()} operation.
2468 *
2469 * <p> This is a cross-lane operation that permutes the lane
2470 * elements of the current vector toward the back and inserts them
2471 * into a logical pair of background vectors. Only one of the
2472 * pair will be returned, however. The background is formed by
2473 * duplicating the second input vector. (However, the output will
2474 * never contain two duplicates from the same input lane.)
2475 *
2476 * The lane numbered {@code N} in the input vector is copied into
2477 * lane {@code origin+N} of the first background vector, if that
2478 * lane exists, else into lane {@code origin+N-VLENGTH} of the
2479 * second background vector (which is guaranteed to exist).
2480 *
2481 * The first or second background vector, updated with the
2482 * inserted slice, is returned. The {@code part} number of zero
2483 * or one selects the first or second updated background vector.
2484 *
2485 * <p> The {@code origin} value must be in the inclusive range
2486 * {@code 0..VLENGTH}. As limiting cases, {@code v.unslice(0,w,0)}
2487 * and {@code v.unslice(VLENGTH,w,1)} both return {@code v}, while
2488 * {@code v.unslice(0,w,1)} and {@code v.unslice(VLENGTH,w,0)}
2489 * both return {@code w}.
2490 *
2491 * @apiNote
2492 * This method supports a variety of cross-lane insertion
2493 * operations as follows:
2494 * <ul>
2495 *
2496 * <li>To insert near the end of a background vector {@code w}
2497 * at some offset, specify the offset as the origin and
2498 * select part zero. For example: {@code v.unslice(offset, w, 0)}.
2499 *
2500 * <li>To insert near the end of a background vector {@code w},
2501 * but capturing the overflow into the next vector {@code x},
2502 * specify the offset as the origin and select part one.
2503 * For example: {@code v.unslice(offset, x, 1)}.
2504 *
2505 * <li>To insert the last {@code N} items near the beginning
2506 * of a background vector {@code w}, supply a {@code VLENGTH-N}
2507 * as the origin and select part one.
2508 * For example: {@code v.unslice(v.length()-N, w)}.
2509 *
2510 * </ul>
2511 *
2512 * @param origin the first output lane to receive the slice
2513 * @param w the background vector that (as two copies) will receive
2514 * the inserted slice
2515 * @param part the part number of the result (either zero or one)
2516 * @return either the first or second part of a pair of
2517 * background vectors {@code w}, updated by inserting
2518 * this vector at the indicated origin
2519 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2520 * is negative or greater than {@code VLENGTH},
2521 * or if {@code part} is not zero or one
2522 * @see #slice(int,Vector)
2523 * @see #unslice(int,Vector,int,VectorMask)
2524 */
2525 public abstract Vector<E> unslice(int origin, Vector<E> w, int part);
2526
2527 /**
2528 * Reverses a {@linkplain #slice(int,Vector) slice()}, inserting
2529 * (under the control of a mask)
2530 * the current vector as a slice within another "background" input
2531 * vector, which is regarded as one or the other input to a
2532 * hypothetical subsequent {@code slice()} operation.
2533 *
2534 * <p> This is a cross-lane operation that permutes the lane
2535 * elements of the current vector forward and inserts its lanes
2536 * (when selected by the mask) into a logical pair of background
2537 * vectors. As with the
2538 * {@linkplain #unslice(int,Vector,int) unmasked version} of this method,
2539 * only one of the pair will be returned, as selected by the
2540 * {@code part} number.
2541 *
2542 * For each lane {@code N} selected by the mask, the lane value
2543 * is copied into
2544 * lane {@code origin+N} of the first background vector, if that
2545 * lane exists, else into lane {@code origin+N-VLENGTH} of the
2546 * second background vector (which is guaranteed to exist).
2547 * Background lanes retain their original values if the
2548 * corresponding input lanes {@code N} are unset in the mask.
2549 *
2550 * The first or second background vector, updated with set lanes
2551 * of the inserted slice, is returned. The {@code part} number of
2552 * zero or one selects the first or second updated background
2553 * vector.
2554 *
2555 * @param origin the first output lane to receive the slice
2556 * @param w the background vector that (as two copies) will receive
2557 * the inserted slice, if they are set in {@code m}
2558 * @param part the part number of the result (either zero or one)
2559 * @param m the mask controlling lane selection from the current vector
2560 * @return either the first or second part of a pair of
2561 * background vectors {@code w}, updated by inserting
2562 * selected lanes of this vector at the indicated origin
2563 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2564 * is negative or greater than {@code VLENGTH},
2565 * or if {@code part} is not zero or one
2566 * @see #unslice(int,Vector,int)
2567 * @see #slice(int,Vector)
2568 */
2569 public abstract Vector<E> unslice(int origin, Vector<E> w, int part, VectorMask<E> m);
2570
2571 /**
2572 * Reverses a {@linkplain #slice(int) slice()}, inserting
2573 * the current vector as a slice within a "background" input
2574 * of zero lane values. Compared to other {@code unslice()}
2575 * methods, this method only returns the first of the
2576 * pair of background vectors.
2577 *
2578 * This is a convenience method which returns the result of
2579 * {@link #unslice(int,Vector,int) unslice}{@code
2580 * (origin, }{@link #broadcast(long) broadcast}{@code (0), 0)}.
2581 * It may also be viewed simply as a cross-lane shift
2582 * from earlier to later lanes, with zeroes filling
2583 * in the vacated lanes at the beginning of the vector.
2584 * In this view, the shift count is {@code origin}.
2585 *
2586 * @param origin the first output lane to receive the slice
2587 * @return the first {@code VLENGTH-origin} input lanes,
2588 * placed starting at the given origin,
2589 * padded at the beginning with zeroes
2590 * @throws ArrayIndexOutOfBoundsException if {@code origin}
2591 * is negative or greater than {@code VLENGTH}
2592 * @see #unslice(int,Vector,int)
2593 * @see #slice(int)
2594 */
2595 // This API point pulls its weight as a teaching aid,
2596 // though it's a one-off and broadcast(0) is easy.
2597 public abstract Vector<E> unslice(int origin);
2598
2599 // ISSUE: Add a slice which uses a mask instead of an origin?
2600 //public abstract Vector<E> slice(VectorMask<E> support);
2601
2602 // ISSUE: Add some more options for questionable edge conditions?
2603 // We might define enum EdgeOption { ERROR, ZERO, WRAP } for the
2604 // default of throwing AIOOBE, or substituting zeroes, or just
2605 // reducing the out-of-bounds index modulo VLENGTH. Similar
2606 // concerns also apply to general Shuffle operations. For now,
2607 // just support ERROR, since that is safest.
2608
2609 /**
2610 * Rearranges the lane elements of this vector, selecting lanes
2611 * under the control of a specific shuffle.
2612 *
2613 * This is a cross-lane operation that rearranges the lane
2614 * elements of this vector.
2615 *
2616 * For each lane {@code N} of the shuffle, and for each lane
2617 * source index {@code I=s.laneSource(N)} in the shuffle,
2618 * the output lane {@code N} obtains the value from
2619 * the input vector at lane {@code I}.
2620 *
2621 * @param s the shuffle controlling lane index selection
2622 * @return the rearrangement of the lane elements of this vector
2623 * @throws IndexOutOfBoundsException if there are any exceptional
2624 * source indexes in the shuffle
2625 * @see #rearrange(VectorShuffle,VectorMask)
2626 * @see #rearrange(VectorShuffle,Vector)
2627 * @see VectorShuffle#laneIsValid()
2628 */
2629 public abstract Vector<E> rearrange(VectorShuffle<E> s);
2630
2631 /**
2632 * Rearranges the lane elements of this vector, selecting lanes
2633 * under the control of a specific shuffle and a mask.
2634 *
2635 * This is a cross-lane operation that rearranges the lane
2636 * elements of this vector.
2637 *
2638 * For each lane {@code N} of the shuffle, and for each lane
2639 * source index {@code I=s.laneSource(N)} in the shuffle,
2640 * the output lane {@code N} obtains the value from
2641 * the input vector at lane {@code I} if the mask is set.
2642 * Otherwise the output lane {@code N} is set to zero.
2643 *
2644 * <p> This method returns the value of this pseudocode:
2645 * <pre>{@code
2646 * Vector<E> r = this.rearrange(s.wrapIndexes());
2647 * VectorMask<E> valid = s.laneIsValid();
2648 * if (m.andNot(valid).anyTrue()) throw ...;
2649 * return broadcast(0).blend(r, m);
2650 * }</pre>
2651 *
2652 * @param s the shuffle controlling lane index selection
2653 * @param m the mask controlling application of the shuffle
2654 * @return the rearrangement of the lane elements of this vector
2655 * @throws IndexOutOfBoundsException if there are any exceptional
2656 * source indexes in the shuffle where the mask is set
2657 * @see #rearrange(VectorShuffle)
2658 * @see #rearrange(VectorShuffle,Vector)
2659 * @see VectorShuffle#laneIsValid()
2660 */
2661 public abstract Vector<E> rearrange(VectorShuffle<E> s, VectorMask<E> m);
2662
2663 /**
2664 * Rearranges the lane elements of two vectors, selecting lanes
2665 * under the control of a specific shuffle, using both normal and
2666 * exceptional indexes in the shuffle to steer data.
2667 *
2668 * This is a cross-lane operation that rearranges the lane
2669 * elements of the two input vectors (the current vector
2670 * and a second vector {@code v}).
2671 *
2672 * For each lane {@code N} of the shuffle, and for each lane
2673 * source index {@code I=s.laneSource(N)} in the shuffle,
2674 * the output lane {@code N} obtains the value from
2675 * the first vector at lane {@code I} if {@code I>=0}.
2676 * Otherwise, the exceptional index {@code I} is wrapped
2677 * by adding {@code VLENGTH} to it and used to index
2678 * the <em>second</em> vector, at index {@code I+VLENGTH}.
2679 *
2680 * <p> This method returns the value of this pseudocode:
2681 * <pre>{@code
2682 * Vector<E> r1 = this.rearrange(s.wrapIndexes());
2683 * // or else: r1 = this.rearrange(s, s.laneIsValid());
2684 * Vector<E> r2 = v.rearrange(s.wrapIndexes());
2685 * return r2.blend(r1,s.laneIsValid());
2686 * }</pre>
2687 *
2688 * @param s the shuffle controlling lane selection from both input vectors
2689 * @param v the second input vector
2690 * @return the rearrangement of lane elements of this vector and
2691 * a second input vector
2692 * @see #rearrange(VectorShuffle)
2693 * @see #rearrange(VectorShuffle,VectorMask)
2694 * @see VectorShuffle#laneIsValid()
2695 * @see #slice(int,Vector)
2696 */
2697 public abstract Vector<E> rearrange(VectorShuffle<E> s, Vector<E> v);
2698
2699 /**
2700 * Compresses the lane elements of this vector selecting lanes
2701 * under the control of a specific mask.
2702 *
2703 * This is a cross-lane operation that compresses the lane
2704 * elements of this vector as selected by the specified mask.
2705 *
2706 * For each lane {@code N} of the mask, if the mask at
2707 * lane {@code N} is set, the element at lane {@code N}
2708 * of input vector is selected and stored into the output
2709 * vector contiguously starting from the lane {@code 0}.
2710 * All the upper remaining lanes, if any, of the output
2711 * vector are set to zero.
2712 *
2713 * @param m the mask controlling the compression
2714 * @return the compressed lane elements of this vector
2715 * @since 19
2716 */
2717 public abstract Vector<E> compress(VectorMask<E> m);
2718
2719 /**
2720 * Expands the lane elements of this vector
2721 * under the control of a specific mask.
2722 *
2723 * This is a cross-lane operation that expands the contiguous lane
2724 * elements of this vector into lanes of an output vector
2725 * as selected by the specified mask.
2726 *
2727 * For each lane {@code N} of the mask, if the mask at
2728 * lane {@code N} is set, the next contiguous element of input vector
2729 * starting from lane {@code 0} is selected and stored into the output
2730 * vector at lane {@code N}.
2731 * All the remaining lanes, if any, of the output vector are set to zero.
2732 *
2733 * @param m the mask controlling the compression
2734 * @return the expanded lane elements of this vector
2735 * @since 19
2736 */
2737 public abstract Vector<E> expand(VectorMask<E> m);
2738
2739 /**
2740 * Using index values stored in the lanes of this vector,
2741 * assemble values stored in second vector {@code v}.
2742 * The second vector thus serves as a table, whose
2743 * elements are selected by indexes in the current vector.
2744 *
2745 * This is a cross-lane operation that rearranges the lane
2746 * elements of the argument vector, under the control of
2747 * this vector.
2748 *
2749 * For each lane {@code N} of this vector, and for each lane
2750 * value {@code I=this.lane(N)} in this vector,
2751 * the output lane {@code N} obtains the value from
2752 * the argument vector at lane {@code I}.
2753 *
2754 * In this way, the result contains only values stored in the
2755 * argument vector {@code v}, but presented in an order which
2756 * depends on the index values in {@code this}.
2757 *
2758 * The result is the same as the expression
2759 * {@code v.rearrange(this.toShuffle())}.
2760 *
2761 * @param v the vector supplying the result values
2762 * @return the rearrangement of the lane elements of {@code v}
2763 * @throws IndexOutOfBoundsException if any invalid
2764 * source indexes are found in {@code this}
2765 * @see #rearrange(VectorShuffle)
2766 */
2767 public abstract Vector<E> selectFrom(Vector<E> v);
2768
2769 /**
2770 * Using index values stored in the lanes of this vector,
2771 * assemble values stored in second vector, under the control
2772 * of a mask.
2773 * Using index values stored in the lanes of this vector,
2774 * assemble values stored in second vector {@code v}.
2775 * The second vector thus serves as a table, whose
2776 * elements are selected by indexes in the current vector.
2777 * Lanes that are unset in the mask receive a
2778 * zero rather than a value from the table.
2779 *
2780 * This is a cross-lane operation that rearranges the lane
2781 * elements of the argument vector, under the control of
2782 * this vector and the mask.
2783 *
2784 * The result is the same as the expression
2785 * {@code v.rearrange(this.toShuffle(), m)}.
2786 *
2787 * @param v the vector supplying the result values
2788 * @param m the mask controlling selection from {@code v}
2789 * @return the rearrangement of the lane elements of {@code v}
2790 * @throws IndexOutOfBoundsException if any invalid
2791 * source indexes are found in {@code this},
2792 * in a lane which is set in the mask
2793 * @see #selectFrom(Vector)
2794 * @see #rearrange(VectorShuffle,VectorMask)
2795 */
2796 public abstract Vector<E> selectFrom(Vector<E> v, VectorMask<E> m);
2797
2798 // Conversions
2799
2800 /**
2801 * Returns a vector of the same species as this one
2802 * where all lane elements are set to
2803 * the primitive value {@code e}.
2804 *
2805 * The contents of the current vector are discarded;
2806 * only the species is relevant to this operation.
2807 *
2808 * <p> This method returns the value of this expression:
2809 * {@code EVector.broadcast(this.species(), (ETYPE)e)}, where
2810 * {@code EVector} is the vector class specific to this
2811 * vector's element type {@code ETYPE}.
2812 *
2813 * <p>
2814 * The {@code long} value {@code e} must be accurately
2815 * representable by the {@code ETYPE} of this vector's species,
2816 * so that {@code e==(long)(ETYPE)e}.
2817 *
2818 * If this rule is violated the problem is not detected
2819 * statically, but an {@code IllegalArgumentException} is thrown
2820 * at run-time. Thus, this method somewhat weakens the static
2821 * type checking of immediate constants and other scalars, but it
2822 * makes up for this by improving the expressiveness of the
2823 * generic API. Note that an {@code e} value in the range
2824 * {@code [-128..127]} is always acceptable, since every
2825 * {@code ETYPE} will accept every {@code byte} value.
2826 *
2827 * @apiNote
2828 * Subtypes improve on this method by sharpening
2829 * the method return type and
2830 * and the type of the scalar parameter {@code e}.
2831 *
2832 * @param e the value to broadcast
2833 * @return a vector where all lane elements are set to
2834 * the primitive value {@code e}
2835 * @throws IllegalArgumentException
2836 * if the given {@code long} value cannot
2837 * be represented by the vector's {@code ETYPE}
2838 * @see VectorSpecies#broadcast(long)
2839 * @see IntVector#broadcast(int)
2840 * @see FloatVector#broadcast(float)
2841 */
2842 public abstract Vector<E> broadcast(long e);
2843
2844 /**
2845 * Returns a mask of same species as this vector,
2846 * where each lane is set or unset according to given
2847 * single boolean, which is broadcast to all lanes.
2848 * <p>
2849 * This method returns the value of this expression:
2850 * {@code species().maskAll(bit)}.
2851 *
2852 * @param bit the given mask bit to be replicated
2853 * @return a mask where each lane is set or unset according to
2854 * the given bit
2855 * @see VectorSpecies#maskAll(boolean)
2856 */
2857 public abstract VectorMask<E> maskAll(boolean bit);
2858
2859 /**
2860 * Converts this vector into a shuffle, converting the lane values
2861 * to {@code int} and regarding them as source indexes.
2862 * <p>
2863 * This method behaves as if it returns the result of creating a shuffle
2864 * given an array of the vector elements, as follows:
2865 * <pre>{@code
2866 * long[] a = this.toLongArray();
2867 * int[] sa = new int[a.length];
2868 * for (int i = 0; i < a.length; i++) {
2869 * sa[i] = (int) a[i];
2870 * }
2871 * return VectorShuffle.fromValues(this.species(), sa);
2872 * }</pre>
2873 *
2874 * @return a shuffle representation of this vector
2875 * @see VectorShuffle#fromValues(VectorSpecies,int...)
2876 */
2877 public abstract VectorShuffle<E> toShuffle();
2878
2879 // Bitwise preserving
2880
2881 /**
2882 * Transforms this vector to a vector of the given species of
2883 * element type {@code F}, reinterpreting the bytes of this
2884 * vector without performing any value conversions.
2885 *
2886 * <p> Depending on the selected species, this operation may
2887 * either <a href="Vector.html#expansion">expand or contract</a>
2888 * its logical result, in which case a non-zero {@code part}
2889 * number can further control the selection and steering of the
2890 * logical result into the physical output vector.
2891 *
2892 * <p>
2893 * The underlying bits of this vector are copied to the resulting
2894 * vector without modification, but those bits, before copying,
2895 * may be truncated if the this vector's bit-size is greater than
2896 * desired vector's bit size, or filled with zero bits if this
2897 * vector's bit-size is less than desired vector's bit-size.
2898 *
2899 * <p> If the old and new species have different shape, this is a
2900 * <em>shape-changing</em> operation, and may have special
2901 * implementation costs.
2902 *
2903 * <p> The method behaves as if this vector is stored into a byte
2904 * array using little-endian byte ordering and then the desired vector is loaded from the same byte
2905 * array using the same ordering.
2906 *
2907 * <p> The following pseudocode illustrates the behavior:
2908 * <pre>{@code
2909 * int domSize = this.byteSize();
2910 * int ranSize = species.vectorByteSize();
2911 * int M = (domSize > ranSize ? domSize / ranSize : ranSize / domSize);
2912 * assert Math.abs(part) < M;
2913 * assert (part == 0) || (part > 0) == (domSize > ranSize);
2914 * MemorySegment ms = MemorySegment.ofArray(new byte[Math.max(domSize, ranSize)]);
2915 * if (domSize > ranSize) { // expansion
2916 * this.intoMemorySegment(ms, 0, ByteOrder.native());
2917 * int origin = part * ranSize;
2918 * return species.fromMemorySegment(ms, origin, ByteOrder.native());
2919 * } else { // contraction or size-invariant
2920 * int origin = (-part) * domSize;
2921 * this.intoMemorySegment(ms, origin, ByteOrder.native());
2922 * return species.fromMemorySegment(ms, 0, ByteOrder.native());
2923 * }
2924 * }</pre>
2925 *
2926 * @apiNote Although this method is defined as if the vectors in
2927 * question were loaded or stored into memory, memory semantics
2928 * has little to do or nothing with the actual implementation.
2929 * The appeal to little-endian ordering is simply a shorthand
2930 * for what could otherwise be a large number of detailed rules
2931 * concerning the mapping between lane-structured vectors and
2932 * byte-structured vectors.
2933 *
2934 * @param species the desired vector species
2935 * @param part the <a href="Vector.html#expansion">part number</a>
2936 * of the result, or zero if neither expanding nor contracting
2937 * @param <F> the boxed element type of the species
2938 * @return a vector transformed, by shape and element type, from this vector
2939 * @see Vector#convertShape(VectorOperators.Conversion,VectorSpecies,int)
2940 * @see Vector#castShape(VectorSpecies,int)
2941 * @see VectorSpecies#partLimit(VectorSpecies,boolean)
2942 */
2943 public abstract <F> Vector<F> reinterpretShape(VectorSpecies<F> species, int part);
2944
2945 /**
2946 * Views this vector as a vector of the same shape
2947 * and contents but a lane type of {@code byte},
2948 * where the bytes are extracted from the lanes
2949 * according to little-endian order.
2950 * It is a convenience method for the expression
2951 * {@code reinterpretShape(species().withLanes(byte.class))}.
2952 * It may be considered an inverse to the various
2953 * methods which consolidate bytes into larger lanes
2954 * within the same vector, such as
2955 * {@link Vector#reinterpretAsInts()}.
2956 *
2957 * @return a {@code ByteVector} with the same shape and information content
2958 * @see Vector#reinterpretShape(VectorSpecies,int)
2959 * @see IntVector#intoMemorySegment(jdk.incubator.foreign.MemorySegment, long, java.nio.ByteOrder)
2960 * @see FloatVector#intoMemorySegment(jdk.incubator.foreign.MemorySegment, long, java.nio.ByteOrder)
2961 * @see VectorSpecies#withLanes(Class)
2962 */
2963 public abstract ByteVector reinterpretAsBytes();
2964
2965 /**
2966 * Reinterprets this vector as a vector of the same shape
2967 * and contents but a lane type of {@code short},
2968 * where the lanes are assembled from successive bytes
2969 * according to little-endian order.
2970 * It is a convenience method for the expression
2971 * {@code reinterpretShape(species().withLanes(short.class))}.
2972 * It may be considered an inverse to {@link Vector#reinterpretAsBytes()}.
2973 *
2974 * @return a {@code ShortVector} with the same shape and information content
2975 */
2976 public abstract ShortVector reinterpretAsShorts();
2977
2978 /**
2979 * Reinterprets this vector as a vector of the same shape
2980 * and contents but a lane type of {@code int},
2981 * where the lanes are assembled from successive bytes
2982 * according to little-endian order.
2983 * It is a convenience method for the expression
2984 * {@code reinterpretShape(species().withLanes(int.class))}.
2985 * It may be considered an inverse to {@link Vector#reinterpretAsBytes()}.
2986 *
2987 * @return a {@code IntVector} with the same shape and information content
2988 */
2989 public abstract IntVector reinterpretAsInts();
2990
2991 /**
2992 * Reinterprets this vector as a vector of the same shape
2993 * and contents but a lane type of {@code long},
2994 * where the lanes are assembled from successive bytes
2995 * according to little-endian order.
2996 * It is a convenience method for the expression
2997 * {@code reinterpretShape(species().withLanes(long.class))}.
2998 * It may be considered an inverse to {@link Vector#reinterpretAsBytes()}.
2999 *
3000 * @return a {@code LongVector} with the same shape and information content
3001 */
3002 public abstract LongVector reinterpretAsLongs();
3003
3004 /**
3005 * Reinterprets this vector as a vector of the same shape
3006 * and contents but a lane type of {@code float},
3007 * where the lanes are assembled from successive bytes
3008 * according to little-endian order.
3009 * It is a convenience method for the expression
3010 * {@code reinterpretShape(species().withLanes(float.class))}.
3011 * It may be considered an inverse to {@link Vector#reinterpretAsBytes()}.
3012 *
3013 * @return a {@code FloatVector} with the same shape and information content
3014 */
3015 public abstract FloatVector reinterpretAsFloats();
3016
3017 /**
3018 * Reinterprets this vector as a vector of the same shape
3019 * and contents but a lane type of {@code double},
3020 * where the lanes are assembled from successive bytes
3021 * according to little-endian order.
3022 * It is a convenience method for the expression
3023 * {@code reinterpretShape(species().withLanes(double.class))}.
3024 * It may be considered an inverse to {@link Vector#reinterpretAsBytes()}.
3025 *
3026 * @return a {@code DoubleVector} with the same shape and information content
3027 */
3028 public abstract DoubleVector reinterpretAsDoubles();
3029
3030 /**
3031 * Views this vector as a vector of the same shape, length, and
3032 * contents, but a lane type that is not a floating-point type.
3033 *
3034 * This is a lane-wise reinterpretation cast on the lane values.
3035 * As such, this method does not change {@code VSHAPE} or
3036 * {@code VLENGTH}, and there is no change to the bitwise contents
3037 * of the vector. If the vector's {@code ETYPE} is already an
3038 * integral type, the same vector is returned unchanged.
3039 *
3040 * This method returns the value of this expression:
3041 * {@code convert(conv,0)}, where {@code conv} is
3042 * {@code VectorOperators.Conversion.ofReinterpret(E.class,F.class)},
3043 * and {@code F} is the non-floating-point type of the
3044 * same size as {@code E}.
3045 *
3046 * @apiNote
3047 * Subtypes improve on this method by sharpening
3048 * the return type.
3049 *
3050 * @return the original vector, reinterpreted as non-floating point
3051 * @see VectorOperators.Conversion#ofReinterpret(Class,Class)
3052 * @see Vector#convert(VectorOperators.Conversion,int)
3053 */
3054 public abstract Vector<?> viewAsIntegralLanes();
3055
3056 /**
3057 * Views this vector as a vector of the same shape, length, and
3058 * contents, but a lane type that is a floating-point type.
3059 *
3060 * This is a lane-wise reinterpretation cast on the lane values.
3061 * As such, there this method does not change {@code VSHAPE} or
3062 * {@code VLENGTH}, and there is no change to the bitwise contents
3063 * of the vector. If the vector's {@code ETYPE} is already a
3064 * float-point type, the same vector is returned unchanged.
3065 *
3066 * If the vector's element size does not match any floating point
3067 * type size, an {@code IllegalArgumentException} is thrown.
3068 *
3069 * This method returns the value of this expression:
3070 * {@code convert(conv,0)}, where {@code conv} is
3071 * {@code VectorOperators.Conversion.ofReinterpret(E.class,F.class)},
3072 * and {@code F} is the floating-point type of the
3073 * same size as {@code E}, if any.
3074 *
3075 * @apiNote
3076 * Subtypes improve on this method by sharpening
3077 * the return type.
3078 *
3079 * @return the original vector, reinterpreted as floating point
3080 * @throws UnsupportedOperationException if there is no floating point
3081 * type the same size as the lanes of this vector
3082 * @see VectorOperators.Conversion#ofReinterpret(Class,Class)
3083 * @see Vector#convert(VectorOperators.Conversion,int)
3084 */
3085 public abstract Vector<?> viewAsFloatingLanes();
3086
3087 /**
3088 * Convert this vector to a vector of the same shape and a new
3089 * element type, converting lane values from the current {@code ETYPE}
3090 * to a new lane type (called {@code FTYPE} here) according to the
3091 * indicated {@linkplain VectorOperators.Conversion conversion}.
3092 *
3093 * This is a lane-wise shape-invariant operation which copies
3094 * {@code ETYPE} values from the input vector to corresponding
3095 * {@code FTYPE} values in the result. Depending on the selected
3096 * conversion, this operation may either
3097 * <a href="Vector.html#expansion">expand or contract</a> its
3098 * logical result, in which case a non-zero {@code part} number
3099 * can further control the selection and steering of the logical
3100 * result into the physical output vector.
3101 *
3102 * <p> Each specific conversion is described by a conversion
3103 * constant in the class {@link VectorOperators}. Each conversion
3104 * operator has a specified {@linkplain
3105 * VectorOperators.Conversion#domainType() domain type} and
3106 * {@linkplain VectorOperators.Conversion#rangeType() range type}.
3107 * The domain type must exactly match the lane type of the input
3108 * vector, while the range type determines the lane type of the
3109 * output vectors.
3110 *
3111 * <p> A conversion operator may be classified as (respectively)
3112 * in-place, expanding, or contracting, depending on whether the
3113 * bit-size of its domain type is (respectively) equal, less than,
3114 * or greater than the bit-size of its range type.
3115 *
3116 * <p> Independently, conversion operations can also be classified
3117 * as reinterpreting or value-transforming, depending on whether
3118 * the conversion copies representation bits unchanged, or changes
3119 * the representation bits in order to retain (part or all of)
3120 * the logical value of the input value.
3121 *
3122 * <p> If a reinterpreting conversion contracts, it will truncate the
3123 * upper bits of the input. If it expands, it will pad upper bits
3124 * of the output with zero bits, when there are no corresponding
3125 * input bits.
3126 *
3127 * <p> An expanding conversion such as {@code S2I} ({@code short}
3128 * value to {@code int}) takes a scalar value and represents it
3129 * in a larger format (always with some information redundancy).
3130 *
3131 * A contracting conversion such as {@code D2F} ({@code double}
3132 * value to {@code float}) takes a scalar value and represents it
3133 * in a smaller format (always with some information loss).
3134 *
3135 * Some in-place conversions may also include information loss,
3136 * such as {@code L2D} ({@code long} value to {@code double})
3137 * or {@code F2I} ({@code float} value to {@code int}).
3138 *
3139 * Reinterpreting in-place conversions are not lossy, unless the
3140 * bitwise value is somehow not legal in the output type.
3141 * Converting the bit-pattern of a {@code NaN} may discard bits
3142 * from the {@code NaN}'s significand.
3143 *
3144 * <p> This classification is important, because, unless otherwise
3145 * documented, conversion operations <em>never change vector
3146 * shape</em>, regardless of how they may change <em>lane sizes</em>.
3147 *
3148 * Therefore an <em>expanding</em> conversion cannot store all of its
3149 * results in its output vector, because the output vector has fewer
3150 * lanes of larger size, in order to have the same overall bit-size as
3151 * its input.
3152 *
3153 * Likewise, a contracting conversion must store its relatively small
3154 * results into a subset of the lanes of the output vector, defaulting
3155 * the unused lanes to zero.
3156 *
3157 * <p> As an example, a conversion from {@code byte} to {@code long}
3158 * ({@code M=8}) will discard 87.5% of the input values in order to
3159 * convert the remaining 12.5% into the roomy {@code long} lanes of
3160 * the output vector. The inverse conversion will convert back all of
3161 * the large results, but will waste 87.5% of the lanes in the output
3162 * vector.
3163 *
3164 * <em>In-place</em> conversions ({@code M=1}) deliver all of
3165 * their results in one output vector, without wasting lanes.
3166 *
3167 * <p> To manage the details of these
3168 * <a href="Vector.html#expansion">expansions and contractions</a>,
3169 * a non-zero {@code part} parameter selects partial results from
3170 * expansions, or steers the results of contractions into
3171 * corresponding locations, as follows:
3172 *
3173 * <ul>
3174 * <li> expanding by {@code M}: {@code part} must be in the range
3175 * {@code [0..M-1]}, and selects the block of {@code VLENGTH/M} input
3176 * lanes starting at the <em>origin lane</em> at {@code part*VLENGTH/M}.
3177
3178 * <p> The {@code VLENGTH/M} output lanes represent a partial
3179 * slice of the whole logical result of the conversion, filling
3180 * the entire physical output vector.
3181 *
3182 * <li> contracting by {@code M}: {@code part} must be in the range
3183 * {@code [-M+1..0]}, and steers all {@code VLENGTH} input lanes into
3184 * the output located at the <em>origin lane</em> {@code -part*VLENGTH}.
3185 * There is a total of {@code VLENGTH*M} output lanes, and those not
3186 * holding converted input values are filled with zeroes.
3187 *
3188 * <p> A group of such output vectors, with logical result parts
3189 * steered to disjoint blocks, can be reassembled using the
3190 * {@linkplain VectorOperators#OR bitwise or} or (for floating
3191 * point) the {@link VectorOperators#FIRST_NONZERO FIRST_NONZERO}
3192 * operator.
3193 *
3194 * <li> in-place ({@code M=1}): {@code part} must be zero.
3195 * Both vectors have the same {@code VLENGTH}. The result is
3196 * always positioned at the <em>origin lane</em> of zero.
3197 *
3198 * </ul>
3199 *
3200 * <p> This method is a restricted version of the more general
3201 * but less frequently used <em>shape-changing</em> method
3202 * {@link #convertShape(VectorOperators.Conversion,VectorSpecies,int)
3203 * convertShape()}.
3204 * The result of this method is the same as the expression
3205 * {@code this.convertShape(conv, rsp, this.broadcast(part))},
3206 * where the output species is
3207 * {@code rsp=this.species().withLanes(FTYPE.class)}.
3208 *
3209 * @param conv the desired scalar conversion to apply lane-wise
3210 * @param part the <a href="Vector.html#expansion">part number</a>
3211 * of the result, or zero if neither expanding nor contracting
3212 * @param <F> the boxed element type of the species
3213 * @return a vector converted by shape and element type from this vector
3214 * @throws ArrayIndexOutOfBoundsException unless {@code part} is zero,
3215 * or else the expansion ratio is {@code M} and
3216 * {@code part} is positive and less than {@code M},
3217 * or else the contraction ratio is {@code M} and
3218 * {@code part} is negative and greater {@code -M}
3219 *
3220 * @see VectorOperators#I2L
3221 * @see VectorOperators.Conversion#ofCast(Class,Class)
3222 * @see VectorSpecies#partLimit(VectorSpecies,boolean)
3223 * @see #viewAsFloatingLanes()
3224 * @see #viewAsIntegralLanes()
3225 * @see #convertShape(VectorOperators.Conversion,VectorSpecies,int)
3226 * @see #reinterpretShape(VectorSpecies,int)
3227 */
3228 public abstract <F> Vector<F> convert(VectorOperators.Conversion<E,F> conv, int part);
3229
3230 /**
3231 * Converts this vector to a vector of the given species, shape and
3232 * element type, converting lane values from the current {@code ETYPE}
3233 * to a new lane type (called {@code FTYPE} here) according to the
3234 * indicated {@linkplain VectorOperators.Conversion conversion}.
3235 *
3236 * This is a lane-wise operation which copies {@code ETYPE} values
3237 * from the input vector to corresponding {@code FTYPE} values in
3238 * the result.
3239 *
3240 * <p> If the old and new species have the same shape, the behavior
3241 * is exactly the same as the simpler, shape-invariant method
3242 * {@link #convert(VectorOperators.Conversion,int) convert()}.
3243 * In such cases, the simpler method {@code convert()} should be
3244 * used, to make code easier to reason about.
3245 * Otherwise, this is a <em>shape-changing</em> operation, and may
3246 * have special implementation costs.
3247 *
3248 * <p> As a combined effect of shape changes and lane size changes,
3249 * the input and output species may have different lane counts, causing
3250 * <a href="Vector.html#expansion">expansion or contraction</a>.
3251 * In this case a non-zero {@code part} parameter selects
3252 * partial results from an expanded logical result, or steers
3253 * the results of a contracted logical result into a physical
3254 * output vector of the required output species.
3255 *
3256 * <p >The following pseudocode illustrates the behavior of this
3257 * method for in-place, expanding, and contracting conversions.
3258 * (This pseudocode also applies to the shape-invariant method,
3259 * but with shape restrictions on the output species.)
3260 * Note that only one of the three code paths is relevant to any
3261 * particular combination of conversion operator and shapes.
3262 *
3263 * <pre>{@code
3264 * FTYPE scalar_conversion_op(ETYPE s);
3265 * EVector a = ...;
3266 * VectorSpecies<F> rsp = ...;
3267 * int part = ...;
3268 * VectorSpecies<E> dsp = a.species();
3269 * int domlen = dsp.length();
3270 * int ranlen = rsp.length();
3271 * FTYPE[] logical = new FTYPE[domlen];
3272 * for (int i = 0; i < domlen; i++) {
3273 * logical[i] = scalar_conversion_op(a.lane(i));
3274 * }
3275 * FTYPE[] physical;
3276 * if (domlen == ranlen) { // in-place
3277 * assert part == 0; //else AIOOBE
3278 * physical = logical;
3279 * } else if (domlen > ranlen) { // expanding
3280 * int M = domlen / ranlen;
3281 * assert 0 <= part && part < M; //else AIOOBE
3282 * int origin = part * ranlen;
3283 * physical = Arrays.copyOfRange(logical, origin, origin + ranlen);
3284 * } else { // (domlen < ranlen) // contracting
3285 * int M = ranlen / domlen;
3286 * assert 0 >= part && part > -M; //else AIOOBE
3287 * int origin = -part * domlen;
3288 * System.arraycopy(logical, 0, physical, origin, domlen);
3289 * }
3290 * return FVector.fromArray(ran, physical, 0);
3291 * }</pre>
3292 *
3293 * @param conv the desired scalar conversion to apply lane-wise
3294 * @param rsp the desired output species
3295 * @param part the <a href="Vector.html#expansion">part number</a>
3296 * of the result, or zero if neither expanding nor contracting
3297 * @param <F> the boxed element type of the output species
3298 * @return a vector converted by element type from this vector
3299 * @see #convert(VectorOperators.Conversion,int)
3300 * @see #castShape(VectorSpecies,int)
3301 * @see #reinterpretShape(VectorSpecies,int)
3302 */
3303 public abstract <F> Vector<F> convertShape(VectorOperators.Conversion<E,F> conv, VectorSpecies<F> rsp, int part);
3304
3305 /**
3306 * Convenience method for converting a vector from one lane type
3307 * to another, reshaping as needed when lane sizes change.
3308 *
3309 * This method returns the value of this expression:
3310 * {@code convertShape(conv,rsp,part)}, where {@code conv} is
3311 * {@code VectorOperators.Conversion.ofCast(E.class,F.class)}.
3312 *
3313 * <p> If the old and new species have different shape, this is a
3314 * <em>shape-changing</em> operation, and may have special
3315 * implementation costs.
3316 *
3317 * @param rsp the desired output species
3318 * @param part the <a href="Vector.html#expansion">part number</a>
3319 * of the result, or zero if neither expanding nor contracting
3320 * @param <F> the boxed element type of the output species
3321 * @return a vector converted by element type from this vector
3322 * @see VectorOperators.Conversion#ofCast(Class,Class)
3323 * @see Vector#convertShape(VectorOperators.Conversion,VectorSpecies,int)
3324 */
3325 // Does this carry its weight?
3326 public abstract <F> Vector<F> castShape(VectorSpecies<F> rsp, int part);
3327
3328 /**
3329 * Checks that this vector has the given element type,
3330 * and returns this vector unchanged.
3331 * The effect is similar to this pseudocode:
3332 * {@code elementType == species().elementType()
3333 * ? this
3334 * : throw new ClassCastException()}.
3335 *
3336 * @param elementType the required lane type
3337 * @param <F> the boxed element type of the required lane type
3338 * @return the same vector
3339 * @throws ClassCastException if the vector has the wrong element type
3340 * @see VectorSpecies#check(Class)
3341 * @see VectorMask#check(Class)
3342 * @see Vector#check(VectorSpecies)
3343 * @see VectorShuffle#check(VectorSpecies)
3344 */
3345 public abstract <F> Vector<F> check(Class<F> elementType);
3346
3347 /**
3348 * Checks that this vector has the given species,
3349 * and returns this vector unchanged.
3350 * The effect is similar to this pseudocode:
3351 * {@code species == species()
3352 * ? this
3353 * : throw new ClassCastException()}.
3354 *
3355 * @param species the required species
3356 * @param <F> the boxed element type of the required species
3357 * @return the same vector
3358 * @throws ClassCastException if the vector has the wrong species
3359 * @see Vector#check(Class)
3360 * @see VectorMask#check(VectorSpecies)
3361 * @see VectorShuffle#check(VectorSpecies)
3362 */
3363 public abstract <F> Vector<F> check(VectorSpecies<F> species);
3364
3365 //Array stores
3366
3367 /**
3368 * Stores this vector into a {@linkplain MemorySegment memory segment}
3369 * starting at an offset using explicit byte order.
3370 * <p>
3371 * Bytes are extracted from primitive lane elements according
3372 * to the specified byte ordering.
3373 * The lanes are stored according to their
3374 * <a href="Vector.html#lane-order">memory ordering</a>.
3375 * <p>
3376 * This method behaves as if it calls
3377 * {@link #intoMemorySegment(MemorySegment,long,ByteOrder,VectorMask)
3378 * intoMemorySegment()} as follows:
3379 * <pre>{@code
3380 * var m = maskAll(true);
3381 * intoMemorySegment(ms, offset, bo, m);
3382 * }</pre>
3383 *
3384 * @param ms the memory segment
3385 * @param offset the offset into the memory segment
3386 * @param bo the intended byte order
3387 * @throws IndexOutOfBoundsException
3388 * if {@code offset+N*ESIZE < 0}
3389 * or {@code offset+(N+1)*ESIZE > ms.byteSize()}
3390 * for any lane {@code N} in the vector
3391 * @throws UnsupportedOperationException
3392 * if the memory segment is read-only
3393 * @throws IllegalArgumentException if the memory segment is a heap segment that is
3394 * not backed by a {@code byte[]} array.
3395 * @throws IllegalStateException if the memory segment's session is not alive,
3396 * or if access occurs from a thread other than the thread owning the session.
3397 * @since 19
3398 */
3399 public abstract void intoMemorySegment(MemorySegment ms, long offset, ByteOrder bo);
3400
3401 /**
3402 * Stores this vector into a {@linkplain MemorySegment memory segment}
3403 * starting at an offset using explicit byte order and a mask.
3404 * <p>
3405 * Bytes are extracted from primitive lane elements according
3406 * to the specified byte ordering.
3407 * The lanes are stored according to their
3408 * <a href="Vector.html#lane-order">memory ordering</a>.
3409 * <p>
3410 * The following pseudocode illustrates the behavior, where
3411 * {@code JAVA_E} is the layout of the primitive element type, {@code ETYPE} is the
3412 * primitive element type, and {@code EVector} is the primitive
3413 * vector type for this vector:
3414 * <pre>{@code
3415 * ETYPE[] a = this.toArray();
3416 * var slice = ms.asSlice(offset)
3417 * for (int n = 0; n < a.length; n++) {
3418 * if (m.laneIsSet(n)) {
3419 * slice.setAtIndex(ValueLayout.JAVA_E.withBitAlignment(8), n);
3420 * }
3421 * }
3422 * }</pre>
3423 *
3424 * @implNote
3425 * This operation is likely to be more efficient if
3426 * the specified byte order is the same as
3427 * {@linkplain ByteOrder#nativeOrder()
3428 * the platform native order},
3429 * since this method will not need to reorder
3430 * the bytes of lane values.
3431 * In the special case where {@code ETYPE} is
3432 * {@code byte}, the byte order argument is
3433 * ignored.
3434 *
3435 * @param ms the memory segment
3436 * @param offset the offset into the memory segment
3437 * @param bo the intended byte order
3438 * @param m the mask controlling lane selection
3439 * @throws IndexOutOfBoundsException
3440 * if {@code offset+N*ESIZE < 0}
3441 * or {@code offset+(N+1)*ESIZE > ms.byteSize()}
3442 * for any lane {@code N} in the vector
3443 * where the mask is set
3444 * @throws UnsupportedOperationException
3445 * if the memory segment is read-only
3446 * @throws IllegalArgumentException if the memory segment is a heap segment that is
3447 * not backed by a {@code byte[]} array.
3448 * @throws IllegalStateException if the memory segment's session is not alive,
3449 * or if access occurs from a thread other than the thread owning the session.
3450 * @since 19
3451 */
3452 public abstract void intoMemorySegment(MemorySegment ms, long offset,
3453 ByteOrder bo, VectorMask<E> m);
3454
3455 /**
3456 * Returns a packed array containing all the lane values.
3457 * The array length is the same as the vector length.
3458 * The element type of the array is the same as the element
3459 * type of the vector.
3460 * The array elements are stored in lane order.
3461 * Overrides of this method on subtypes of {@code Vector}
3462 * which specify the element type have an accurately typed
3463 * array result.
3464 *
3465 * @apiNote
3466 * Usually {@linkplain FloatVector#toArray() strongly typed access}
3467 * is preferable, if you are working with a vector
3468 * subtype that has a known element type.
3469 *
3470 * @return an accurately typed array containing
3471 * the lane values of this vector
3472 * @see ByteVector#toArray()
3473 * @see IntVector#toArray()
3474 * @see DoubleVector#toArray()
3475 */
3476 public abstract Object toArray();
3477
3478 /**
3479 * Returns an {@code int[]} array containing all
3480 * the lane values, converted to the type {@code int}.
3481 * The array length is the same as the vector length.
3482 * The array elements are converted as if by casting
3483 * and stored in lane order.
3484 *
3485 * This operation may fail if the vector element type is {@code
3486 * float} or {@code double}, when lanes contain fractional or
3487 * out-of-range values. If any vector lane value is not
3488 * representable as an {@code int}, an exception is thrown.
3489 *
3490 * @apiNote
3491 * Usually {@linkplain FloatVector#toArray() strongly typed access}
3492 * is preferable, if you are working with a vector
3493 * subtype that has a known element type.
3494 *
3495 * @return an {@code int[]} array containing
3496 * the lane values of this vector
3497 * @throws UnsupportedOperationException
3498 * if any lane value cannot be represented as an
3499 * {@code int} array element
3500 * @see #toArray()
3501 * @see #toLongArray()
3502 * @see #toDoubleArray()
3503 * @see IntVector#toArray()
3504 */
3505 public abstract int[] toIntArray();
3506
3507 /**
3508 * Returns a {@code long[]} array containing all
3509 * the lane values, converted to the type {@code long}.
3510 * The array length is the same as the vector length.
3511 * The array elements are converted as if by casting
3512 * and stored in lane order.
3513 *
3514 * This operation may fail if the vector element type is {@code
3515 * float} or {@code double}, when lanes contain fractional or
3516 * out-of-range values. If any vector lane value is not
3517 * representable as a {@code long}, an exception is thrown.
3518 *
3519 * @apiNote
3520 * Usually {@linkplain FloatVector#toArray() strongly typed access}
3521 * is preferable, if you are working with a vector
3522 * subtype that has a known element type.
3523 *
3524 * @return a {@code long[]} array containing
3525 * the lane values of this vector
3526 * @throws UnsupportedOperationException
3527 * if any lane value cannot be represented as a
3528 * {@code long} array element
3529 * @see #toArray()
3530 * @see #toIntArray()
3531 * @see #toDoubleArray()
3532 * @see LongVector#toArray()
3533 */
3534 public abstract long[] toLongArray();
3535
3536 /**
3537 * Returns a {@code double[]} array containing all
3538 * the lane values, converted to the type {@code double}.
3539 * The array length is the same as the vector length.
3540 * The array elements are converted as if by casting
3541 * and stored in lane order.
3542 * This operation can lose precision
3543 * if the vector element type is {@code long}.
3544 *
3545 * @apiNote
3546 * Usually {@link FloatVector#toArray() strongly typed access}
3547 * is preferable, if you are working with a vector
3548 * subtype that has a known element type.
3549 *
3550 * @return a {@code double[]} array containing
3551 * the lane values of this vector,
3552 * possibly rounded to representable
3553 * {@code double} values
3554 * @see #toArray()
3555 * @see #toIntArray()
3556 * @see #toLongArray()
3557 * @see DoubleVector#toArray()
3558 */
3559 public abstract double[] toDoubleArray();
3560
3561 /**
3562 * Returns a string representation of this vector, of the form
3563 * {@code "[0,1,2...]"}, reporting the lane values of this
3564 * vector, in lane order.
3565 *
3566 * The string is produced as if by a call to
3567 * {@link Arrays#toString(int[]) Arrays.toString()},
3568 * as appropriate to the array returned by
3569 * {@link #toArray() this.toArray()}.
3570 *
3571 * @return a string of the form {@code "[0,1,2...]"}
3572 * reporting the lane values of this vector
3573 */
3574 @Override
3575 public abstract String toString();
3576
3577 /**
3578 * Indicates whether this vector is identical to some other object.
3579 * Two vectors are identical only if they have the same species
3580 * and same lane values, in the same order.
3581 * <p>The comparison of lane values is produced as if by a call to
3582 * {@link Arrays#equals(int[],int[]) Arrays.equals()},
3583 * as appropriate to the arrays returned by
3584 * {@link #toArray toArray()} on both vectors.
3585 *
3586 * @return whether this vector is identical to some other object
3587 * @see #eq
3588 */
3589 @Override
3590 public abstract boolean equals(Object obj);
3591
3592 /**
3593 * Returns a hash code value for the vector.
3594 * based on the lane values and the vector species.
3595 *
3596 * @return a hash code value for this vector
3597 */
3598 @Override
3599 public abstract int hashCode();
3600
3601 // ==== JROSE NAME CHANGES ====
3602
3603 // RAISED FROM SUBCLASSES (with generalized type)
3604 // * toArray() -> ETYPE[] <: Object (erased return type for interop)
3605 // * toString(), equals(Object), hashCode() (documented)
3606 // ADDED
3607 // * compare(OP,v) to replace most of the comparison methods
3608 // * maskAll(boolean) to replace maskAllTrue/False
3609 // * toLongArray(), toDoubleArray() (generic unboxed access)
3610 // * check(Class), check(VectorSpecies) (static type-safety checks)
3611 // * enum Comparison (enum of EQ, NE, GT, LT, GE, LE)
3612 // * zero(VS), broadcast(long) (basic factories)
3613 // * reinterpretAsEs(), viewAsXLanes (bytewise reinterpreting views)
3614 // * addIndex(int) (iota function)
3615
3616 }