- All Superinterfaces:
MemoryLayoutPREVIEW
SequenceLayout
is a preview API of the Java platform.
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:
is equivalent to the following layout:
MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
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
-
Nested Class Summary
Nested classes/interfaces inherited from interface java.lang.foreign.MemoryLayoutPREVIEW
MemoryLayout.PathElementPREVIEW
-
Method Summary
Modifier and TypeMethodDescriptionlong
Returns the element count of this sequence layout.Returns the element layout associated with this sequence layout.flatten()
Returns a flattened sequence layout.reshape
(long... elementCounts) Re-arrange the elements in this sequence layout into a multi-dimensional sequence layout.withBitAlignment
(long bitAlignment) 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).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.Returns a memory layout of the same type with the same size and alignment constraint as this layout, but with the specified name.Returns a memory layout of the same type with the same size and alignment constraint as this layout, but without a name.Methods inherited from interface java.lang.foreign.MemoryLayoutPREVIEW
bitAlignment, bitOffset, bitOffsetHandle, bitSize, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle
-
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
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
- ifelementCount < 0
.
-
reshape
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 (seeflatten()
) 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));
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 abovereshapeSeq
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));
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
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 interfaceMemoryLayoutPREVIEW
- Parameters:
name
- the layout name.- Returns:
- a memory layout with the given name.
- See Also:
-
withoutName
MemoryLayoutPREVIEW withoutName()Returns a memory layout of the same type with the same size and alignment constraint as this layout, but without a name.This can be useful to compare two layouts that have different names, but are otherwise equal.
- Specified by:
withoutName
in interfaceMemoryLayoutPREVIEW
- Returns:
- a memory layout without a name.
- See Also:
-
withBitAlignment
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 interfaceMemoryLayoutPREVIEW
- Parameters:
bitAlignment
- the layout alignment constraint, expressed in bits.- Returns:
- a memory layout with the given alignment constraint.
-
SequenceLayout
when preview features are enabled.