Interface SequenceLayout

All Superinterfaces:
MemoryLayout
public sealed interfaceSequenceLayoutextendsMemoryLayout
A compound layout that denotes a homogeneous repetition of a givenelement layout. The repetition count is said to be the sequence layout'selement count. A sequence layout can be thought of as a struct layout wherethe sequence layout's element layout is repeated a number of times that is equal tothe 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 andvalue-based.
Since:
22

  • Method Details

    • elementLayout

      MemoryLayout elementLayout()
      Returns the element layout of this sequence layout.
      Returns:
      the element layout of this sequence layout

    • elementCount

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

    • withElementCount

      SequenceLayout withElementCount(long elementCount)
      Returns a sequence layout with the same characteristics of this layout, but with the given element count.
      Parameters:
      elementCount - the new element count
      Returns:
      a sequence layout with the same characteristics of this layout, but with the given element count
      Throws:
      IllegalArgumentException - ifelementCount is negative
      IllegalArgumentException - ifelementLayout.bitSize() * elementCount overflows

    • reshape

      SequenceLayout reshape(long... elementCounts)
      Rearranges the elements in this sequence layout into a multidimensional sequencelayout. The resulting layout is a sequence layout where element layouts in theflattened projection of this sequence layout arerearranged into one or more nested sequence layouts according to the providedelement counts. This transformation preserves the layout size;that is, multiplying the provided element counts must yield the same element countas 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));
      callingseq.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 counts is the special value-1, thenthe element count in that position will be inferred from the remaining elementcounts and the element count of the flattened projection of this layout.For instance, a layout equivalent to the abovereshapeSeq can also becomputed 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 theflattened projection of this sequence layout (seeflatten()) 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

      SequenceLayout flatten()
      Returns a flattened sequence layout. The element layout of the returnedsequence layout is the first non-sequence layout found by inspecting(recursively, if needed) the element layout of this sequence layout:
      MemoryLayout flatElementLayout(SequenceLayout sequenceLayout) {   return switch (sequenceLayout.elementLayout()) {       case SequenceLayout nestedSequenceLayout -> flatElementLayout(nestedSequenceLayout);       case MemoryLayout layout -> layout;   };}

      This transformation preserves the layout size; nested sequence layout in thissequence layout will be dropped and their element counts will be incorporatedinto that of the returned sequence layout. For instance, given asequence layout of the kind:

      var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
      callingseq.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

      SequenceLayout withName(String name)
      Returns a memory layout with the same characteristics as this layout, but with the given name.
      Specified by:
      withName in interface MemoryLayout
      Parameters:
      name - the layout name
      Returns:
      a memory layout with the same characteristics as this layout, but with the given name
      See Also:

    • withByteAlignment

      SequenceLayout withByteAlignment(long byteAlignment)
      Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
      Specified by:
      withByteAlignment in interface MemoryLayout
      Parameters:
      byteAlignment - the layout alignment constraint, expressed in bytes
      Returns:
      a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes)
      Throws:
      IllegalArgumentException - ifbyteAlignment is not a power of two
      IllegalArgumentException - ifbyteAlignment < elementLayout().byteAlignment()