Interface SequenceLayout

All Superinterfaces:: MemoryLayout

public sealed interface SequenceLayout extends MemoryLayout

A compound layout that denotes a homogeneous repetition of a given element layout. The repetition count is said to be the sequence layout's element count. A sequence layout can be thought of as a struct 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:: 22

Nested Class Summary

Nested classes/interfaces declared in interface MemoryLayout

MemoryLayout.PathElement

Modifier and Type	Interface	Description
`static interface`	`MemoryLayout.PathElement`	An element in a layout path.

Method Summary

Modifier and Type	Method	Description
`long`	`elementCount()`	Returns the element count of this sequence layout.
`MemoryLayout`	`elementLayout()`	Returns the element layout of this sequence layout.
`SequenceLayout`	`flatten()`	Returns a flattened sequence layout.
`SequenceLayout`	`reshape(long... elementCounts)`	Rearranges the elements in this sequence layout into a multidimensional sequence layout.
`SequenceLayout`	`withByteAlignment(long byteAlignment)`	Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
`SequenceLayout`	`withElementCount(long elementCount)`	Returns a sequence layout with the same characteristics of this layout, but with the given element count.
`SequenceLayout`	`withName(String name)`	Returns a memory layout with the same characteristics as this layout, but with the given name.

Methods declared in interface MemoryLayout

arrayElementVarHandle, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, scale, scaleHandle, select, sliceHandle, toString, varHandle, withoutName

Modifier and Type	Method	Description
`VarHandle`	`arrayElementVarHandle(MemoryLayout.PathElement... elements)`	Creates a var handle that accesses adjacent elements in a memory segment at offsets selected by the given layout path, where the accessed elements have this layout, and where the initial layout in the path is this layout.
`long`	`byteAlignment()`	Returns the alignment constraint associated with this layout, expressed in bytes.
`long`	`byteOffset(MemoryLayout.PathElement... elements)`	Computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
`MethodHandle`	`byteOffsetHandle(MemoryLayout.PathElement... elements)`	Creates a method handle that computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
`long`	`byteSize()`	Returns the layout size, in bytes.
`boolean`	`equals(Object other)`	Compares the specified object with this layout for equality.
`int`	`hashCode()`	Returns the hash code value for this layout.
`Optional<String>`	`name()`	Returns the name (if any) associated with this layout.
`long`	`scale(long offset, long index)`	Returns `offset + (byteSize() * index)`.
`MethodHandle`	`scaleHandle()`	Returns a method handle that can be used to invoke `MemoryLayout.scale(long, long)` on this layout.
`MemoryLayout`	`select(MemoryLayout.PathElement... elements)`	Returns the layout selected from the provided path, where the initial layout in the path is this layout.
`MethodHandle`	`sliceHandle(MemoryLayout.PathElement... elements)`	Creates a method handle which, given a memory segment, returns a slice corresponding to the layout selected by the given layout path, where the initial layout in the path is this layout.
`String`	`toString()`	Returns the string representation of this layout.
`VarHandle`	`varHandle(MemoryLayout.PathElement... elements)`	Creates a var handle that accesses a memory segment at the offset selected by the given layout path, where the initial layout in the path is this layout.
`MemoryLayout`	`withoutName()`	Returns a memory layout with the same characteristics as this layout, but with no name.

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 - if elementCount is negative; IllegalArgumentException - if elementLayout.bitSize() * elementCount overflows

reshape

SequenceLayout reshape(long... elementCounts)

Rearranges the elements in this sequence layout into a multidimensional sequence layout. The resulting layout is a sequence layout where element layouts in the flattened projection of this sequence layout are rearranged 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 counts 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

SequenceLayout flatten()

Returns a flattened sequence layout. The element layout of the returned sequence 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 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

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 - if byteAlignment is not a power of two; IllegalArgumentException - if byteAlignment < elementLayout().byteAlignment()

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.