Class Vector<E>

  • Type Parameters:
    E - the boxed element type of elements in this vector
    Direct Known Subclasses:
    ByteVector, DoubleVector, FloatVector, IntVector, LongVector, ShortVector

    public abstract class Vector<E>
    extends Object
    A Vector is designed for use in computations that can be transformed by a runtime compiler, on supported hardware, to Single Instruction Multiple Data (SIMD) computations leveraging vector hardware registers and vector hardware instructions. Such SIMD computations exploit data parallelism to perform the same operation on multiple data points simultaneously in a faster time it would ordinarily take to perform the same operation sequentially on each data point.

    A Vector represents an ordered immutable sequence of values of the same element type e that is one of the following primitive types byte, short, int, long, float, or double). The type variable E corresponds to the boxed element type, specifically the class that wraps a value of e in an object (such the Integer class that wraps a value of int}. A Vector has a shape S, extending type Shape, that governs the total size in bits of the sequence of values.

    The number of values in the sequence is referred to as the Vector length. The length also corresponds to the number of Vector lanes. The lane element at lane index N (from 0, inclusive, to length, exclusive) corresponds to the N + 1'th value in the sequence. Note: this arrangement of Vector bit size, Vector length, element bit size, and lane element index has no bearing on how a Vector instance and its sequence of elements may be arranged in memory or represented as a value in a vector hardware register.

    Vector declares a set of vector operations (methods) that are common to all element types (such as addition). Sub-classes of Vector with a concrete boxed element type declare further operations that are specific to that element type (such as access to element values in lanes, logical operations on values of integral elements types, or transcendental operations on values of floating point element types). There are six sub-classes of Vector corresponding to the supported set of element types, ByteVector, ShortVector, IntVector LongVector, FloatVector, and DoubleVector.

    Vector values, instances of Vector, are created from a special kind of factory called a Species. A Species has an element type and shape and creates Vector values of the same element type and shape. A species can be Species.of(Class, Shape) obtained} given an element type and shape, or a preferred species can be Species.ofPreferred(Class) obtained} given just an element type where the most optimal shape is selected for the current platform. It is recommended that Species instances be held in static final fields for optimal creation and usage of Vector values by the runtime compiler.

    Vector operations can be grouped into various categories and their behaviour generally specified as follows:

    • A vector unary operation (1-ary) operates on one input vector to produce a result vector. For each lane of the input vector the lane element is operated on using the specified scalar unary operation and the element result is placed into the vector result at the same lane. The following pseudocode expresses the behaviour of this operation category, where e is the element type and EVector corresponds to the primitive Vector type:
      
       EVector<S> a = ...;
       e[] ar = new e[a.length()];
       for (int i = 0; i < a.length(); i++) {
           ar[i] = scalar_unary_op(a.get(i));
       }
       EVector<S> r = a.species().fromArray(ar, 0);
       
      Unless otherwise specified the input and result vectors will have the same element type and shape.
    • A vector binary operation (2-ary) operates on two input vectors to produce a result vector. For each lane of the two input vectors, a and b say, the corresponding lane elements from a and b are operated on using the specified scalar binary operation and the element result is placed into the vector result at the same lane. The following pseudocode expresses the behaviour of this operation category:
      
       EVector<S> a = ...;
       EVector<S> b = ...;
       e[] ar = new e[a.length()];
       for (int i = 0; i < a.length(); i++) {
           ar[i] = scalar_binary_op(a.get(i), b.get(i));
       }
       EVector<S> r = a.species().fromArray(ar, 0);
       
      Unless otherwise specified the two input and result vectors will have the same element type and shape.
    • Generalizing from unary (1-ary) and binary (2-ary) operations, a vector n-ary operation operates in n input vectors to produce a result vector. N lane elements from each input vector are operated on using the specified n-ary scalar operation and the element result is placed into the vector result at the same lane. Unless otherwise specified the n input and result vectors will have the same element type and shape.
    • A vector reduction operation operates on all the lane elements of an input vector. An accumulation function is applied to all the lane elements to produce a scalar result. If the reduction operation is associative then the result may be accumulated by operating on the lane elements in any order using a specified associative scalar binary operation and identity value. Otherwise, the reduction operation specifies the behaviour of the accumulation function. The following pseudocode expresses the behaviour of this operation category if it is associative:
      
       EVector<S> a = ...;
       e r = <identity value>;
       for (int i = 0; i < a.length(); i++) {
           r = assoc_scalar_binary_op(r, a.get(i));
       }
       
      Unless otherwise specified the scalar result type and element type will be the same.
    • A vector binary test operation operates on two input vectors to produce a result mask. For each lane of the two input vectors, a and b say, the the corresponding lane elements from a and b are operated on using the specified scalar binary test operation and the boolean result is placed into the mask at the same lane. The following pseudocode expresses the behaviour of this operation category:
      
       EVector<S> a = ...;
       EVector<S> b = ...;
       boolean[] ar = new boolean[a.length()];
       for (int i = 0; i < a.length(); i++) {
           ar[i] = scalar_binary_test_op(a.get(i), b.get(i));
       }
       Mask<E> r = a.species().maskFromArray(ar, 0);
       
      Unless otherwise specified the two input vectors and result mask will have the same element type and shape.
    • The prior categories of operation can be said to operate within the vector lanes, where lane access is uniformly applied to all vectors, specifically the scalar operation is applied to elements taken from input vectors at the same lane, and if appropriate applied to the result vector at the same lane. A further category of operation is a cross-lane vector operation where lane access is defined by the arguments to the operation. Cross-lane operations generally rearrange lane elements, for example by permutation (commonly controlled by a Shuffle) or by blending (commonly controlled by a Mask). Such an operation explicitly specifies how it rearranges lane elements.
    If a vector operation is represented as an instance method then first input vector corresponds to this vector and subsequent input vectors are arguments of the method. Otherwise, if the an operation is represented as a static method then all input vectors are arguments of the method.

    If a vector operation does not belong to one of the above categories then the operation explicitly specifies how it processes the lane elements of input vectors, and where appropriate expresses the behaviour using pseudocode.

    Many vector operations provide an additional mask accepting variant. The mask controls which lanes are selected for application of the scalar operation. Masks are a key component for the support of control flow in vector computations.

    For certain operation categories the mask accepting variants can be specified in generic terms. If a lane of the mask is set then the scalar operation is applied to corresponding lane elements, otherwise if a lane of a mask is not set then a default scalar operation is applied and its result is placed into the vector result at the same lane. The default operation is specified for the following operation categories:

    • For a vector n-ary operation the default operation is a function that returns it's first argument, specifically a lane element of the first input vector.
    • For an associative vector reduction operation the default operation is a function that returns the identity value.
    • For vector binary test operation the default operation is a function that returns false.
    Otherwise, the mask accepting variant of the operation explicitly specifies how it processes the lane elements of input vectors, and where appropriate expresses the behaviour using pseudocode.

    For convenience many vector operations, of arity greater than one, provide an additional scalar accepting variant. This variant accepts compatible scalar values instead of vectors for the second and subsequent input vectors, if any. Unless otherwise specified the scalar variant behaves as if each scalar value is transformed to a vector using the vector Species broadcast operation, and then the vector accepting vector operation is applied using the transformed values.

    This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Vector may have unpredictable results and should be avoided.

    • Method Summary

      Modifier and Type Method Description
      abstract Vector<E> abs()
      Returns the modulus of this vector.
      abstract Vector<E> abs​(Mask<E> m)
      Returns the modulus of this vector, selecting lane elements controlled by a mask.
      abstract Vector<E> add​(Vector<E> v)
      Adds this vector to an input vector.
      abstract Vector<E> add​(Vector<E> v, Mask<E> m)
      Adds this vector to an input vector, selecting lane elements controlled by a mask.
      int bitSize()
      Returns the total vector size, in bits.
      static int bitSizeForVectorLength​(Class<?> c, int numElem)
      Find bit size based on element type and number of elements.
      abstract Vector<E> blend​(Vector<E> v, Mask<E> m)
      Blends the lane elements of this vector with those of an input vector, selecting lanes controlled by a mask.
      abstract <F> Vector<F> cast​(Species<F> s)
      Converts this vector to a vector of the given species element type F.
      int elementSize()
      Returns the element size, in bits, of this vector.
      Class<E> elementType()
      Returns the primitive element type of this vector.
      abstract Mask<E> equal​(Vector<E> v)
      Tests if this vector is equal to an input vector.
      abstract Mask<E> greaterThan​(Vector<E> v)
      Tests if this vector is greater than an input vector.
      abstract Mask<E> greaterThanEq​(Vector<E> v)
      Tests if this vector is greater than or equal to an input vector.
      abstract void intoByteArray​(byte[] a, int i)
      Stores this vector into a byte array starting at an offset.
      abstract void intoByteArray​(byte[] a, int i, Mask<E> m)
      Stores this vector into a byte array starting at an offset and using a mask.
      abstract void intoByteBuffer​(ByteBuffer b, int i)
      Stores this vector into a byte buffer starting at an offset into the byte buffer.
      abstract void intoByteBuffer​(ByteBuffer b, int i, Mask<E> m)
      Stores this vector into a byte buffer starting at an offset into the byte buffer and using a mask.
      int length()
      Returns the number of vector lanes (the length).
      abstract Mask<E> lessThan​(Vector<E> v)
      Tests if this vector is less than an input vector.
      abstract Mask<E> lessThanEq​(Vector<E> v)
      Tests if this vector is less or equal to an input vector.
      abstract Vector<E> max​(Vector<E> v)
      Returns the maximum of this vector and an input vector.
      abstract Vector<E> max​(Vector<E> v, Mask<E> m)
      Returns the maximum of this vector and an input vector, selecting lane elements controlled by a mask.
      abstract Vector<E> min​(Vector<E> v)
      Returns the minimum of this vector and an input vector.
      abstract Vector<E> min​(Vector<E> v, Mask<E> m)
      Returns the minimum of this vector and an input vector, selecting lane elements controlled by a mask.
      abstract Vector<E> mul​(Vector<E> v)
      Multiplies this vector with an input vector.
      abstract Vector<E> mul​(Vector<E> v, Mask<E> m)
      Multiplies this vector with an input vector, selecting lane elements controlled by a mask.
      abstract Vector<E> neg()
      Negates this vector.
      abstract Vector<E> neg​(Mask<E> m)
      Negates this vector, selecting lane elements controlled by a mask.
      abstract Mask<E> notEqual​(Vector<E> v)
      Tests if this vector is not equal to an input vector.
      abstract Vector<E> rearrange​(Shuffle<E> s)
      Rearranges the lane elements of this vector selecting lane indexes controlled by a shuffle.
      abstract Vector<E> rearrange​(Vector<E> v, Shuffle<E> s, Mask<E> m)
      Rearranges the lane elements of this vector and those of an input vector, selecting lane indexes controlled by shuffles and a mask.
      abstract <F> Vector<F> reinterpret​(Species<F> s)
      Transforms this vector to a vector of the given species of element type F.
      abstract Vector<E> reshape​(Species<E> s)
      Transforms this vector to a vector of same element type but different shape identified by species.
      abstract Vector<E> rotateEL​(int i)
      Rotates left the lane elements of this vector by the given number of lanes, i, modulus the vector length.
      abstract Vector<E> rotateER​(int i)
      Rotates right the lane elements of this vector by the given number of lanes, i, modulus the vector length.
      Shape shape()
      Returns the shape of this vector.
      abstract Vector<E> shiftEL​(int i)
      Shift left the lane elements of this vector by the given number of lanes, i, modulus the vector length.
      abstract Vector<E> shiftER​(int i)
      Shift right the lane elements of this vector by the given number of lanes, i, modulus the vector length.
      abstract Species<E> species()
      Returns the species of this vector.
      abstract Vector<E> sub​(Vector<E> v)
      Subtracts an input vector from this vector.
      abstract Vector<E> sub​(Vector<E> v, Mask<E> m)
      Subtracts an input vector from this vector, selecting lane elements controlled by a mask.
      abstract Shuffle<E> toShuffle()
      Converts this vector into a shuffle, creating a shuffle from vector lane elements cast to int then logically AND'ed with the shuffle length minus one.
    • Method Detail

      • species

        public abstract Species<E> species()
        Returns the species of this vector.
        Returns:
        the species of this vector
      • elementType

        public Class<E> elementType()
        Returns the primitive element type of this vector.
        Returns:
        the primitive element type of this vector
      • elementSize

        public int elementSize()
        Returns the element size, in bits, of this vector.
        Returns:
        the element size, in bits
      • shape

        public Shape shape()
        Returns the shape of this vector.
        Returns:
        the shape of this vector
      • length

        public int length()
        Returns the number of vector lanes (the length).
        Returns:
        the number of vector lanes
      • bitSize

        public int bitSize()
        Returns the total vector size, in bits.
        Returns:
        the total vector size, in bits
      • add

        public abstract Vector<E> add​(Vector<E> v)
        Adds this vector to an input vector.

        This is a vector binary operation where the primitive addition operation (+) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the result of adding this vector to the input vector
      • add

        public abstract Vector<E> add​(Vector<E> v,
                                      Mask<E> m)
        Adds this vector to an input vector, selecting lane elements controlled by a mask.

        This is a vector binary operation where the primitive addition operation (+) is applied to lane elements.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the result of adding this vector to the given vector
      • sub

        public abstract Vector<E> sub​(Vector<E> v)
        Subtracts an input vector from this vector.

        This is a vector binary operation where the primitive subtraction operation (-) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the result of subtracting the input vector from this vector
      • sub

        public abstract Vector<E> sub​(Vector<E> v,
                                      Mask<E> m)
        Subtracts an input vector from this vector, selecting lane elements controlled by a mask.

        This is a vector binary operation where the primitive subtraction operation (-) is applied to lane elements.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the result of subtracting the input vector from this vector
      • mul

        public abstract Vector<E> mul​(Vector<E> v)
        Multiplies this vector with an input vector.

        This is a vector binary operation where the primitive multiplication operation (*) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the result of multiplying this vector with the input vector
      • mul

        public abstract Vector<E> mul​(Vector<E> v,
                                      Mask<E> m)
        Multiplies this vector with an input vector, selecting lane elements controlled by a mask.

        This is a vector binary operation where the primitive multiplication operation (*) is applied to lane elements.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the result of multiplying this vector with the input vector
      • neg

        public abstract Vector<E> neg()
        Negates this vector.

        This is a vector unary operation where the primitive negation operation (-) is applied to lane elements.

        Returns:
        the negation this vector
      • neg

        public abstract Vector<E> neg​(Mask<E> m)
        Negates this vector, selecting lane elements controlled by a mask.

        This is a vector unary operation where the primitive negation operation (-)is applied to lane elements.

        Parameters:
        m - the mask controlling lane selection
        Returns:
        the negation this vector
      • abs

        public abstract Vector<E> abs()
        Returns the modulus of this vector.

        This is a vector unary operation where the operation (a) -> (a < 0) ? -a : a is applied to lane elements.

        Returns:
        the modulus this vector
      • abs

        public abstract Vector<E> abs​(Mask<E> m)
        Returns the modulus of this vector, selecting lane elements controlled by a mask.

        This is a vector unary operation where the operation (a) -> (a < 0) ? -a : a is applied to lane elements.

        Parameters:
        m - the mask controlling lane selection
        Returns:
        the modulus this vector
      • min

        public abstract Vector<E> min​(Vector<E> v)
        Returns the minimum of this vector and an input vector.

        This is a vector binary operation where the operation (a, b) -> a < b ? a : b is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the minimum of this vector and the input vector
      • min

        public abstract Vector<E> min​(Vector<E> v,
                                      Mask<E> m)
        Returns the minimum of this vector and an input vector, selecting lane elements controlled by a mask.

        This is a vector binary operation where the operation (a, b) -> a < b ? a : b is applied to lane elements.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the minimum of this vector and the input vector
      • max

        public abstract Vector<E> max​(Vector<E> v)
        Returns the maximum of this vector and an input vector.

        This is a vector binary operation where the operation (a, b) -> a > b ? a : b is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the maximum of this vector and the input vector
      • max

        public abstract Vector<E> max​(Vector<E> v,
                                      Mask<E> m)
        Returns the maximum of this vector and an input vector, selecting lane elements controlled by a mask.

        This is a vector binary operation where the operation (a, b) -> a > b ? a : b is applied to lane elements.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the maximum of this vector and the input vector
      • equal

        public abstract Mask<E> equal​(Vector<E> v)
        Tests if this vector is equal to an input vector.

        This is a vector binary test operation where the primitive equals operation (==) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the result mask of testing if this vector is equal to the input vector
      • notEqual

        public abstract Mask<E> notEqual​(Vector<E> v)
        Tests if this vector is not equal to an input vector.

        This is a vector binary test operation where the primitive not equals operation (!=) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the result mask of testing if this vector is not equal to the input vector
      • lessThan

        public abstract Mask<E> lessThan​(Vector<E> v)
        Tests if this vector is less than an input vector.

        This is a vector binary test operation where the primitive less than operation (<) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the mask result of testing if this vector is less than the input vector
      • lessThanEq

        public abstract Mask<E> lessThanEq​(Vector<E> v)
        Tests if this vector is less or equal to an input vector.

        This is a vector binary test operation where the primitive less than or equal to operation (<=) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the mask result of testing if this vector is less than or equal to the input vector
      • greaterThan

        public abstract Mask<E> greaterThan​(Vector<E> v)
        Tests if this vector is greater than an input vector.

        This is a vector binary test operation where the primitive greater than operation (>) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the mask result of testing if this vector is greater than the input vector
      • greaterThanEq

        public abstract Mask<E> greaterThanEq​(Vector<E> v)
        Tests if this vector is greater than or equal to an input vector.

        This is a vector binary test operation where the primitive greater than or equal to operation (>=) is applied to lane elements.

        Parameters:
        v - the input vector
        Returns:
        the mask result of testing if this vector is greater than or equal to the given vector
      • rotateEL

        public abstract Vector<E> rotateEL​(int i)
        Rotates left the lane elements of this vector by the given number of lanes, i, modulus the vector length.

        This is a cross-lane operation that permutes the lane elements of this vector. For each lane of the input vector, at lane index N, the lane element is placed into to the result vector at lane index (i + N) % this.length().

        Parameters:
        i - the number of lanes to rotate left
        Returns:
        the result of rotating left lane elements of this vector by the given number of lanes
      • rotateER

        public abstract Vector<E> rotateER​(int i)
        Rotates right the lane elements of this vector by the given number of lanes, i, modulus the vector length.

        This is a cross-lane operation that permutes the lane elements of this vector and behaves as if rotating left the lane elements by this.length() - (i % this.length()) lanes.

        Parameters:
        i - the number of lanes to rotate left
        Returns:
        the result of rotating right lane elements of this vector by the given number of lanes
      • shiftEL

        public abstract Vector<E> shiftEL​(int i)
        Shift left the lane elements of this vector by the given number of lanes, i, modulus the vector length.

        This is a cross-lane operation that permutes the lane elements of this vector and behaves as if rotating left the lane elements by i, and then the zero value is placed into the result vector at lane indexes less than i % this.length().

        Parameters:
        i - the number of lanes to shift left
        Returns:
        the result of shifting left lane elements of this vector by the given number of lanes
        Throws:
        IllegalArgumentException - if i is < 0.
      • shiftER

        public abstract Vector<E> shiftER​(int i)
        Shift right the lane elements of this vector by the given number of lanes, i, modulus the vector length.

        This is a cross-lane operation that permutes the lane elements of this vector and behaves as if rotating right the lane elements by i, and then the zero value is placed into the result vector at lane indexes greater or equal to this.length() - (i % this.length()).

        Parameters:
        i - the number of lanes to shift left
        Returns:
        the result of shifting left lane elements of this vector by the given number of lanes
        Throws:
        IllegalArgumentException - if i is < 0.
      • blend

        public abstract Vector<E> blend​(Vector<E> v,
                                        Mask<E> m)
        Blends the lane elements of this vector with those of an input vector, selecting lanes controlled by a mask.

        For each lane of the mask, at lane index N, if the mask lane is set then the lane element at N from the input vector is selected and placed into the resulting vector at N, otherwise the the lane element at N from this input vector is selected and placed into the resulting vector at N.

        Parameters:
        v - the input vector
        m - the mask controlling lane selection
        Returns:
        the result of blending the lane elements of this vector with those of an input vector
      • rearrange

        public abstract Vector<E> rearrange​(Vector<E> v,
                                            Shuffle<E> s,
                                            Mask<E> m)
        Rearranges the lane elements of this vector and those of an input vector, selecting lane indexes controlled by shuffles and a mask.

        This is a cross-lane operation that rearranges the lane elements of this vector and the input vector. This method behaves as if it rearranges each vector with the corresponding shuffle and then blends the two results with the mask:

        
         return this.rearrange(s1).blend(v.rearrange(s2), m);
         
        Parameters:
        v - the input vector
        s - the shuffle controlling lane index selection of the input vector if corresponding mask lanes are set, otherwise controlling lane index selection of this vector
        m - the mask controlling shuffled lane selection
        Returns:
        the rearrangement of lane elements of this vector and those of an input vector
      • rearrange

        public abstract Vector<E> rearrange​(Shuffle<E> s)
        Rearranges the lane elements of this vector selecting lane indexes controlled by a shuffle.

        This is a cross-lane operation that rearranges the lane elements of this vector. For each lane of the shuffle, at lane index N with lane element I, the lane element at I from this vector is selected and placed into the resulting vector at N.

        Parameters:
        s - the shuffle controlling lane index selection
        Returns:
        the rearrangement of the lane elements of this vector
      • toShuffle

        public abstract Shuffle<E> toShuffle()
        Converts this vector into a shuffle, creating a shuffle from vector lane elements cast to int then logically AND'ed with the shuffle length minus one.

        This methods behaves as if it returns the result of creating a shuffle given an array of the vector lane elements, as follows:

        
         $type$[] a = this.toArray();
         int[] sa = new int[a.length];
         for (int i = 0; i < a.length; i++) {
             sa[i] = (int) a[i];
         }
         return this.species().shuffleFromValues(sa);
         
        Returns:
        a shuffle representation of this vector
      • reinterpret

        public abstract <F> Vector<F> reinterpret​(Species<F> s)
        Transforms this vector to a vector of the given species of element type F.

        The underlying bits of this vector are copied to the resulting vector without modification, but those bits, before copying, may be truncated if the this vector's bit size is greater than desired vector's bit size, or appended to with zero bits if this vector's bit size is less than desired vector's bit size.

        The method behaves as if this vector is stored into a byte buffer and then the desired vector is loaded from the byte buffer using native byte ordering. The implication is that ByteBuffer reads bytes and then composes them based on the byte ordering so the result depends on this composition.

        For example, on a system with ByteOrder.LITTLE_ENDIAN, loading from byte array with values {0,1,2,3} and reshaping to int, leads to bytes being composed in order 0x3 0x2 0x1 0x0 which is decimal value 50462976. On a system with ByteOrder.BIG_ENDIAN, the value is instead 66051 because bytes are composed in order 0x0 0x1 0x2 0x3.

        The following pseudocode expresses the behaviour:

        
         int blen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
         ByteBuffer bb = ByteBuffer.allocate(blen).order(ByteOrder.nativeOrder());
         this.intoByteBuffer(bb, 0);
         return s.fromByteBuffer(bb, 0);
         
        Type Parameters:
        F - the boxed element type of the species
        Parameters:
        s - species of desired vector
        Returns:
        a vector transformed, by shape and element type, from this vector
      • reshape

        public abstract Vector<E> reshape​(Species<E> s)
        Transforms this vector to a vector of same element type but different shape identified by species.

        The lane elements of this vector are copied without modification to the resulting vector, but those lane elements, before copying, may be truncated if this vector's length is greater than the desired vector's length, or appended to with default element values if this vector's length is less than desired vector's length.

        The method behaves as if this vector is stored into a byte array and then the returned vector is loaded from the byte array. The following pseudocode expresses the behaviour:

        
         int alen = Math.max(this.bitSize(), s.bitSize()) / Byte.SIZE;
         byte[] a = new byte[alen];
         this.intoByteArray(a, 0);
         return s.fromByteArray(a, 0);
         
        Parameters:
        s - species of the desired vector
        Returns:
        a vector transformed, by shape, from this vector
      • cast

        public abstract <F> Vector<F> cast​(Species<F> s)
        Converts this vector to a vector of the given species element type F.

        For each vector lane up to the length of this vector or desired vector, which ever is the minimum, and where N is the vector lane index, the element at index N of primitive type E is converted, according to primitive conversion rules specified by the Java Language Specification, to a value of primitive type F and placed into the resulting vector at lane index N. If desired vector's length is greater than this vector's length then the default primitive value is placed into subsequent lanes of the resulting vector.

        Type Parameters:
        F - the boxed element type of the species
        Parameters:
        s - species of the desired vector
        Returns:
        a vector converted by shape and element type from this vector
      • intoByteArray

        public abstract void intoByteArray​(byte[] a,
                                           int i)
        Stores this vector into a byte array starting at an offset.

        Bytes are extracted from primitive lane elements according to the native byte order of the underlying platform.

        This method behaves as it calls the byte buffer, offset, and mask accepting method as follows:

        
         return this.intoByteBuffer(ByteBuffer.wrap(a), i, this.maskAllTrue());
         
        Parameters:
        a - the byte array
        i - the offset into the array
        Throws:
        IndexOutOfBoundsException - if i < 0 or i > a.length - (this.length() * this.elementSize() / Byte.SIZE)
      • intoByteArray

        public abstract void intoByteArray​(byte[] a,
                                           int i,
                                           Mask<E> m)
        Stores this vector into a byte array starting at an offset and using a mask.

        Bytes are extracted from primitive lane elements according to the native byte order of the underlying platform.

        This method behaves as it calls the byte buffer, offset, and mask accepting method as follows:

        
         return this.intoByteBuffer(ByteBuffer.wrap(a), i, m);
         
        Parameters:
        a - the byte array
        i - the offset into the array
        m - the mask controlling lane selection
        Throws:
        IndexOutOfBoundsException - if the offset is < 0, or > a.length, for any vector lane index N where the mask at lane N is set i >= a.length - (N * this.elementSize() / Byte.SIZE)
      • intoByteBuffer

        public abstract void intoByteBuffer​(ByteBuffer b,
                                            int i)
        Stores this vector into a byte buffer starting at an offset into the byte buffer.

        Bytes are extracted from primitive lane elements according to the native byte order of the underlying platform.

        This method behaves as if it calls the byte buffer, offset, and mask accepting intoByteBuffer(ByteBuffer, int, Mask) method} as follows:

        
           this.intoByteBuffer(b, i, this.maskAllTrue())
         
        Parameters:
        b - the byte buffer
        i - the offset into the byte buffer
        Throws:
        IndexOutOfBoundsException - if the offset is < 0, or > b.limit(), or if there are fewer than this.length() * this.elementSize() / Byte.SIZE bytes remaining in the byte buffer from the given offset
      • intoByteBuffer

        public abstract void intoByteBuffer​(ByteBuffer b,
                                            int i,
                                            Mask<E> m)
        Stores this vector into a byte buffer starting at an offset into the byte buffer and using a mask.

        This method behaves as if the byte buffer is viewed as a primitive buffer for the primitive element type, according to the native byte order of the underlying platform, and the lane elements of this vector are put into the buffer if the corresponding mask lane is set. The following pseudocode expresses the behaviour, where is the primitive buffer type, e is the primitive element type, and EVector<S> is the primitive vector type for this vector:

        
         EBuffer eb = b.duplicate().
             order(ByteOrder.nativeOrder()).position(i).
             asEBuffer();
         e[] es = ((EVector<S>)this).toArray();
         for (int n = 0; n < t.length; n++) {
             if (m.isSet(n)) {
                 eb.put(n, es[n]);
             }
         }
         
        Parameters:
        b - the byte buffer
        i - the offset into the byte buffer
        m - the mask
        Throws:
        IndexOutOfBoundsException - if the offset is < 0, or > b.limit(), for any vector lane index N where the mask at lane N is set i >= b.limit() - (N * this.elementSize() / Byte.SIZE) bytes
      • bitSizeForVectorLength

        public static int bitSizeForVectorLength​(Class<?> c,
                                                 int numElem)
        Find bit size based on element type and number of elements.
        Parameters:
        c - the element type
        numElem - number of lanes in the vector
        Returns:
        size in bits for vector