pack-priv abstract sealed Class AbstractVector<E>

Implements abstract jdk.incubator.vector.Vector.castShape.

Doc from jdk.incubator.vector.Vector.castShape.

Convenience method for converting a vector from one lane type to another, reshaping as needed when lane sizes change. This method returns the value of this expression: convertShape(conv,rsp,part), where conv is VectorOperators.Conversion.ofCast(E.class,F.class).

If the old and new species have different shape, this is a shape-changing operation, and may have special implementation costs.

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.check.

Doc from jdk.incubator.vector.Vector.check.

Checks that this vector has the given species, and returns this vector unchanged. The effect is similar to this pseudocode: species == species() ? this : throw new ClassCastException().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.check.

Doc from jdk.incubator.vector.Vector.check.

Checks that this vector has the given element type, and returns this vector unchanged. The effect is similar to this pseudocode: elementType == species().elementType() ? this : throw new ClassCastException().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.convert.

Doc from jdk.incubator.vector.Vector.convert.

Convert this vector to a vector of the same shape and a new element type, converting lane values from the current ETYPE to a new lane type (called FTYPE here) according to the indicated conversion. This is a lane-wise operation which copies ETYPE values from the input vector to corresponding FTYPE values in the result.

This method is a restricted version of the more general but less frequently used shape-changing method convertShape(). The result of this method is the same as the expression this.convertShape(conv, rsp, part), where the output species is rsp=this.species().withLanes(FTYPE.class).

As a combined effect of shape-invariance and lane size changes, the input and output species may have different lane counts, causing expansion or contraction, and require selection or insertion. Conceptually, the input is lane-wise converted into a logical result that contains all converted elements, leading to a logical expansion ratio ML = |FTYPE|/|ETYPE|. The result is then copied to the output, which may either be an exact fit (in-place), too small (requires selection), or too large (requires insertion).

Logical: Lane-wise Conversion

Each specific conversion is described by a conversion constant in the class VectorOperators. Each conversion operator has a specified domain type and range type. The domain type must exactly match the lane type of the input vector, while the range type determines the lane type of the output vectors.

A lanewise conversion operator may be classified as (respectively) in-place, expanding, or contracting, depending on whether the bit-size of its domain type is (respectively) equal to, less than, or greater than the bit-size of its range type.

Independently, lanewise conversion operations can also be classified as reinterpreting or value-transforming, depending on whether the conversion copies representation bits unchanged, or changes the representation bits in order to retain (part or all of) the logical value of the input value.

If a reinterpreting conversion contracts, it will truncate the upper bits of the input. If it expands, it will pad upper bits of the output with zero bits, when there are no corresponding input bits.

An expanding conversion such as S2I (short value to int) takes a scalar value and represents it in a larger format (always with some information redundancy). A contracting conversion such as D2F (double value to float) takes a scalar value and represents it in a smaller format (always with some information loss). Some in-place conversions may also include information loss, such as L2D (long value to double) or F2I (float value to int). Reinterpreting in-place conversions are not lossy, unless the bitwise value is somehow not legal in the output type. Converting the bit-pattern of a NaN may discard bits from the NaN's significand.

Shape-invariance can lead to Selection or Insertion

This classification of the lanewise operators as in-place, expanding and contracting is important, because, unless otherwise documented, conversion operations never change vector shape, regardless of how they may change lane sizes.

To manage the details of these expansions and contractions, a part parameter selects partial results from expansions, or steers insertion of the results of contractions into the output. For shape-invariant conversions (MP=1), we have the following cases:

• Lanewise in-place conversion operator (|ETYPE|=|FTYPE|): The input, logical result and output have the same number of lanes and size in bits (ML=MP=1). The logical result fits the output exactly, and we always have part=0.

  All conversions are delivered in one output vector, without wasting lanes.

• Lanewise expanding conversion operator (|ETYPE|<|FTYPE|): The logical expansion ML=|FTYPE|/|ETYPE|>1 means the logical result is MS=ML times larger than the output.

  The part number in range [0..MS-1] selects one of the MS distinct blocks of VLENGTH/MS logical result lanes starting at the origin lane at part*VLENGTH/MS. This selected block is copied to the output and fills it exactly. The rest of the logical result is lost.

  A group of such output vectors, with MS disjoint selections of logical results, can (manually) represent the complete logical result of the conversion.

• Lanewise contracting conversion operator (|ETYPE|>|FTYPE|): The logical contraction ML=|FTYPE|/|ETYPE|<1 means the output is MO=1/ML times larger than the logical result.

  The part number in range [-(MO-1)..0] inserts all VLENGTH lanes from the logical result into the output located at the origin lane -part*VLENGTH. There is a total of VLENGTH*MO output lanes, and those not holding converted input values are filled with zero padding.

  A group of such output vectors, with logical result parts steered to MO disjoint blocks, can be (manually) reassembled using the bitwise XOR or (for floating point) the FIRST_NONZERO operator.

As an example, a conversion from byte to long (logical expansion ratio ML=8) will discard 87.5% of the input values in order to select and convert the remaining 12.5% into the roomy long lanes of the output vector. The inverse conversion will convert back all the large results, but will waste 87.5% of the lanes in the output vector, padding excess lanes with zero bits.

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.convertShape.

Doc from jdk.incubator.vector.Vector.convertShape.

Converts this vector to a vector of the given species, shape and element type, converting lane values from the current ETYPE to a new lane type (called FTYPE here) according to the indicated conversion. This is a lane-wise operation which copies ETYPE values from the input vector to corresponding FTYPE values in the result.

If the old and new species have the same shape, the behavior is exactly the same as the simpler, shape-invariant method convert(). In such cases, the simpler method convert() should be used, to make code easier to reason about. Otherwise, this is a shape-changing operation, and may have special implementation costs.

As a combined effect of shape changes and lane size changes, the input and output species may have different lane counts, causing expansion or contraction, and require selection or insertion. Conceptually, the input is lane-wise converted into a logical result that contains all converted elements, leading to a logical expansion ratio ML = |FTYPE|/|ETYPE|. The result is then copied to the output, which may either be an exact fit (in-place), too small (requires selection), or too large (requires insertion).

• Exact fit (in-place): the expansion or contraction of the physical shape matches the expansion or contraction of the elements (MP=ML). We must have part=0.
• Logical result is MS>1 times larger than the output shape (selection): The part number in range [0..MS-1] determines which of the MS distinct parts from the logical result is selected for the output. The rest of the logical result is lost.
• Output shape is MO>1 times larger than the logical result (insertion): The part number in range [-(MO-1)..0] determines to which of the MO distinct positions of the output the logical result is inserted. The rest of the output is padded with zero bits.

The following pseudocode illustrates the behavior of this method for in-place conversions, and those with selection or insertion. (This pseudocode also applies to the shape-invariant method, but with shape restrictions on the output species.) Note that only one of the three code paths is relevant to any particular combination of conversion operator and shapes.

FTYPE scalar_conversion_op(ETYPE s);
EVector a = ...;
VectorSpecies<F> rsp = ...;
int part = ...;
VectorSpecies<E> dsp = a.species();
int domlen = dsp.length();
int ranlen = rsp.length();
FTYPE[] logical = new FTYPE[domlen];
for (int i = 0; i < domlen; i++) {
  logical[i] = scalar_conversion_op(a.lane(i));
}
FTYPE[] physical;
if (domlen == ranlen) { // MS=MO=1 => in-place
    assert part == 0; //else AIOOBE
    physical = logical;
} else if (domlen > ranlen) { // MS>1 => selection
    int MS = domlen / ranlen;
    assert 0 <= part && part < MS; //else AIOOBE
    int origin = part * ranlen;
    physical = Arrays.copyOfRange(logical, origin, origin + ranlen);
} else { // (domlen < ranlen) // MO>1 => insertion, padding
    int MO = ranlen / domlen;
    assert 0 >= part && part > -MO; //else AIOOBE
    int origin = -part * domlen;
    System.arraycopy(logical, 0, physical, origin, domlen);
}
return FVector.fromArray(ran, physical, 0);

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.maskAll.

Doc from jdk.incubator.vector.Vector.maskAll.

Returns a mask of same species as this vector, where each lane is set or unset according to given single boolean, which is broadcast to all lanes.

This method returns the value of this expression: species().maskAll(bit).

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.reinterpretAsDoubles.

Doc from jdk.incubator.vector.Vector.reinterpretAsDoubles.

Reinterprets this vector as a vector of the same shape and contents but a lane type of double, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expression reinterpretShape(species().withLanes(double.class)). It may be considered an inverse to Vector#reinterpretAsBytes().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.reinterpretAsFloats.

Doc from jdk.incubator.vector.Vector.reinterpretAsFloats.

Reinterprets this vector as a vector of the same shape and contents but a lane type of float, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expression reinterpretShape(species().withLanes(float.class)). It may be considered an inverse to Vector#reinterpretAsBytes().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.reinterpretAsInts.

Doc from jdk.incubator.vector.Vector.reinterpretAsInts.

Reinterprets this vector as a vector of the same shape and contents but a lane type of int, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expression reinterpretShape(species().withLanes(int.class)). It may be considered an inverse to Vector#reinterpretAsBytes().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.reinterpretAsLongs.

Doc from jdk.incubator.vector.Vector.reinterpretAsLongs.

Reinterprets this vector as a vector of the same shape and contents but a lane type of long, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expression reinterpretShape(species().withLanes(long.class)). It may be considered an inverse to Vector#reinterpretAsBytes().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.reinterpretAsShorts.

Doc from jdk.incubator.vector.Vector.reinterpretAsShorts.

Reinterprets this vector as a vector of the same shape and contents but a lane type of short, where the lanes are assembled from successive bytes according to little-endian order. It is a convenience method for the expression reinterpretShape(species().withLanes(short.class)). It may be considered an inverse to Vector#reinterpretAsBytes().

Annotations

@Override

@ForceInline

Implements abstract jdk.incubator.vector.Vector.slice.

Doc from jdk.incubator.vector.Vector.slice.

Slices a segment of adjacent lanes, starting at a given origin lane in the current vector, and continuing (as needed) into an immediately following vector. The block of VLENGTH lanes is extracted into its own vector and returned.

This is a cross-lane operation that shifts lane elements to the front, from the current vector and the second vector. Both vectors can be viewed as a combined "background" of length 2*VLENGTH, from which a slice is extracted. The lane numbered N in the output vector is copied from lane origin+N of the input vector, if that lane exists, else from lane origin+N-VLENGTH of the second vector (which is guaranteed to exist).

The origin value must be in the inclusive range 0..VLENGTH. As limiting cases, v.slice(0,w) and v.slice(VLENGTH,w) return v and w, respectively.

Annotations

@Override

Implements abstract jdk.incubator.vector.Vector.slice.

Doc from jdk.incubator.vector.Vector.slice.

Slices a segment of adjacent lanes, starting at a given origin lane in the current vector. A block of VLENGTH lanes, possibly padded with zero lanes, is extracted into its own vector and returned. This is a convenience method which slices from a single vector against an extended background of zero lanes. It is equivalent to slice(origin, broadcast(0)). It may also be viewed simply as a cross-lane shift from later to earlier lanes, with zeroes filling in the vacated lanes at the end of the vector. In this view, the shift count is origin.

Annotations

@Override

Implements abstract jdk.incubator.vector.Vector.species.

Doc from jdk.incubator.vector.Vector.species.

Returns the species of this vector.

Annotations

@Override

@ForceInline