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 }