Module java.base
Package java.lang.foreign

Interface SequenceLayout

All Superinterfaces:
MemoryLayoutPREVIEW
public sealed interface SequenceLayout extends 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));
Implementation Requirements:
This class is immutable, thread-safe and value-based.
Since:
19

  • Method Details

    • elementLayout

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

    • elementCount

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

    • withElementCount

      SequenceLayoutPREVIEW withElementCount(long elementCount)
      Returns a sequence layout with the same element layout, alignment constraint 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

      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:
      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

      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.

    • withName

      SequenceLayoutPREVIEW withName(String name)
      Description copied from interface: MemoryLayout
      Returns a memory layout of the same type with the same size and alignment constraint 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:

    • withBitAlignment

      SequenceLayoutPREVIEW withBitAlignment(long bitAlignment)
      Description copied from interface: MemoryLayout
      Returns a memory layout of the same type with the same size and name as this layout, but with the specified alignment constraint (in bits).
      Specified by:
      withBitAlignment in interface MemoryLayoutPREVIEW
      Parameters:
      bitAlignment - the layout alignment constraint, expressed in bits.
      Returns:
      a memory layout with the given alignment constraint.