Module java.base
Package java.lang.foreign

# Class SequenceLayout

java.lang.Object
java.lang.foreign.SequenceLayout

All Implemented Interfaces:
  `MemoryLayoutPREVIEW`

public final class SequenceLayout extends Object implements MemoryLayoutPREVIEW
`SequenceLayout` is a preview API of the Java platform.
Programs can only use `SequenceLayout` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A compound layout that denotes a repetition of a given element layout. The repetition count is said to be the sequence layout's element count. A finite sequence can be thought of as a group layout where the sequence layout's element layout is repeated a number of times that is equal to the sequence layout's element count. In other words this layout:

    MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));

is equivalent to the following layout:

    MemoryLayout.structLayout(
        ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
        ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
        ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));

Since:
  19
Implementation Requirements:
  This class is immutable, thread-safe and value-based.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface java.lang.foreign.MemoryLayoutPREVIEW

  `MemoryLayout.PathElementPREVIEW`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final long`
  `bitAlignment()`
  Returns the alignment constraint associated with this layout, expressed in bits.
  `long`
  `bitSize()`
  Returns the layout size, in bits.
  `long`
  `byteSize()`
  Returns the layout size, in bytes.
  `long`
  `elementCount()`
  Returns the element count of this sequence layout.
  `MemoryLayoutPREVIEW`
  `elementLayout()`
  Returns the element layout associated with this sequence layout.
  `boolean`
  `equals(Object other)`
  Compares the specified object with this layout for equality.
  `SequenceLayoutPREVIEW`
  `flatten()`
  Returns a flattened sequence layout.
  `int`
  `hashCode()`
  Returns the hash code value for this layout.
  `boolean`
  `isPadding()`
  Returns true, if this layout is a padding layout.
  `final Optional<String>`
  `name()`
  Returns the name (if any) associated with this layout.
  `SequenceLayoutPREVIEW`
  `reshape(long... elementCounts)`
  Re-arrange the elements in this sequence layout into a multi-dimensional sequence layout.
  `String`
  `toString()`
  Returns the string representation of this layout.
  `SequenceLayoutPREVIEW`
  `withBitAlignment(long alignmentBits)`
  Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).
  `SequenceLayoutPREVIEW`
  `withElementCount(long elementCount)`
  Returns a sequence layout with the same element layout, alignment constraints and name as this sequence layout, but with the specified element count.
  `SequenceLayoutPREVIEW`
  `withName(String name)`
  Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.foreign.MemoryLayoutPREVIEW

  `bitAlignment, bitOffset, bitOffsetHandle, bitSize, byteAlignment, byteOffset, byteOffsetHandle, byteSize, isPadding, name, select, sliceHandle, varHandle`

- ## Method Details

  - ### elementLayout

    public MemoryLayoutPREVIEW elementLayout()
    Returns the element layout associated with this sequence layout.
    Returns:
      the element layout associated with this sequence layout

  - ### elementCount

    public long elementCount()
    Returns the element count of this sequence layout.
    Returns:
      the element count of this sequence layout

  - ### withElementCount

    public SequenceLayoutPREVIEW withElementCount(long elementCount)
    Returns a sequence layout with the same element layout, alignment constraints and name as this sequence layout, but with the specified element count.
    Parameters:
      `elementCount` - the new element count.
    Returns:
      a sequence layout with the given element count.
    Throws:
      `IllegalArgumentException` - if `elementCount < 0`.

  - ### reshape

    public SequenceLayoutPREVIEW reshape(long... elementCounts)
    Re-arrange the elements in this sequence layout into a multi-dimensional sequence layout. The resulting layout is a sequence layout where element layouts in the flattened projection of this sequence layout (see `flatten()`) are re-arranged into one or more nested sequence layouts according to the provided element counts. This transformation preserves the layout size; that is, multiplying the provided element counts must yield the same element count as the flattened projection of this sequence layout.

    For instance, given a sequence layout of the kind:

        var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));

    calling `seq.reshape(2, 6)` will yield the following sequence layout:

        var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));

    If one of the provided element count is the special value `-1`, then the element count in that position will be inferred from the remaining element counts and the element count of the flattened projection of this layout. For instance, a layout equivalent to the above `reshapeSeq` can also be computed in the following ways:

        var reshapeSeqImplicit1 = seq.reshape(-1, 6);
        var reshapeSeqImplicit2 = seq.reshape(2, -1);

    Parameters:
      `elementCounts` - an array of element counts, of which at most one can be `-1`.
    Returns:
      a sequence layout where element layouts in the flattened projection of this sequence layout (see `flatten()`) are re-arranged into one or more nested sequence layouts.
    Throws:
      `UnsupportedOperationException` - if this sequence layout does not have an element count.
      `IllegalArgumentException` - if two or more element counts are set to `-1`, or if one or more element count is `<= 0` (but other than `-1`) or, if, after any required inference, multiplying the element counts does not yield the same element count as the flattened projection of this sequence layout.

  - ### flatten

    public SequenceLayoutPREVIEW flatten()
    Returns a flattened sequence layout. The element layout of the returned sequence layout is the first non-sequence element layout found by recursively traversing the element layouts of this sequence layout. This transformation preserves the layout size; nested sequence layout in this sequence layout will be dropped and their element counts will be incorporated into that of the returned sequence layout. For instance, given a sequence layout of the kind:

        var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));

    calling `seq.flatten()` will yield the following sequence layout:

        var flattenedSeq = MemoryLayout.sequenceLayout(12, ValueLayout.JAVA_INT);

    Returns:
      a sequence layout with the same size as this layout (but, possibly, with different element count), whose element layout is not a sequence layout.
    Throws:
      `UnsupportedOperationException` - if this sequence layout, or one of the nested sequence layouts being flattened, does not have an element count.

  - ### toString

    public String toString()
    Returns the string representation of this layout.
    Specified by:
      `toString` in interface `MemoryLayoutPREVIEW`
    Returns:
      the string representation of this layout

  - ### equals

    public boolean equals(Object other)
    Compares the specified object with this layout for equality. Returns `true` if and only if the specified object is also a layout, and it is equal to this layout. Two layouts are considered equal if they are of the same kind, have the same size, name and alignment constraints. Furthermore, depending on the layout kind, additional conditions must be satisfied:
    - two value layouts are considered equal if they have the same byte order (see `ValueLayout.order()`PREVIEW)
    - two sequence layouts are considered equal if they have the same element count (see `elementCount()`), and if their element layouts (see `elementLayout()`) are also equal
    - two group layouts are considered equal if they are of the same kind (see `GroupLayout.isStruct()`PREVIEW, `GroupLayout.isUnion()`PREVIEW) and if their member layouts (see `GroupLayout.memberLayouts()`PREVIEW) are also equal
    Specified by:
      `equals` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `other` - the object to be compared for equality with this layout.
    Returns:
      `true` if the specified object is equal to this layout.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    public int hashCode()
    Returns the hash code value for this layout.
    Specified by:
      `hashCode` in interface `MemoryLayoutPREVIEW`
    Returns:
      the hash code value for this layout
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`

  - ### withName

    public SequenceLayoutPREVIEW withName(String name)
    Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.
    Specified by:
      `withName` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `name` - the layout name.
    Returns:
      a memory layout with the given name.
    See Also:
      - `MemoryLayout.name()`PREVIEW

  - ### withBitAlignment

    public SequenceLayoutPREVIEW withBitAlignment(long alignmentBits)
    Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).
    Specified by:
      `withBitAlignment` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `alignmentBits` - the layout alignment constraint, expressed in bits.
    Returns:
      a memory layout with the given alignment constraints.

  - ### name

    public final Optional<String> name()
    Description copied from interface: `MemoryLayout`
    Returns the name (if any) associated with this layout.
    Specified by:
      `name` in interface `MemoryLayoutPREVIEW`
    Returns:
      the name (if any) associated with this layout
    See Also:
      - `MemoryLayout.withName(String)`PREVIEW

  - ### bitAlignment

    public final long bitAlignment()
    Description copied from interface: `MemoryLayout`
    Returns the alignment constraint associated with this layout, expressed in bits. Layout alignment defines a power of two `A` which is the bit-wise alignment of the layout. If `A <= 8` then `A/8` is the number of bytes that must be aligned for any pointer that correctly points to this layout. Thus:
    - `A=8` means unaligned (in the usual sense), which is common in packets.
    - `A=64` means word aligned (on LP64), `A=32` int aligned, `A=16` short aligned, etc.
    - `A=512` is the most strict alignment required by the x86/SV ABI (for AVX-512 data).
    If no explicit alignment constraint was set on this layout (see `MemoryLayout.withBitAlignment(long)`PREVIEW), then this method returns the natural alignment constraint (in bits) associated with this layout.
    Specified by:
      `bitAlignment` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout alignment constraint, in bits.

  - ### byteSize

    public long byteSize()
    Description copied from interface: `MemoryLayout`
    Returns the layout size, in bytes.
    Specified by:
      `byteSize` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout size, in bytes

  - ### bitSize

    public long bitSize()
    Description copied from interface: `MemoryLayout`
    Returns the layout size, in bits.
    Specified by:
      `bitSize` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout size, in bits

  - ### isPadding

    public boolean isPadding()
    Description copied from interface: `MemoryLayout`
    Returns true, if this layout is a padding layout.
    Specified by:
      `isPadding` in interface `MemoryLayoutPREVIEW`
    Returns:
      true, if this layout is a padding layout