- Enclosing interface:
MemoryLayoutPREVIEW
public static sealed interface MemoryLayout.PathElement
PathElement
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.
An element in a layout path. There
are three kinds of path elements:
- group path elements, used to select a member layout within a
GroupLayout
PREVIEW, either by name or by index; - sequence path elements, used to select one or more sequence element layouts within a
SequenceLayout
PREVIEW; and - dereference path elements, used to dereference an address layout as its target layout.
- Implementation Requirements:
- Implementations of this interface are immutable, thread-safe and value-based.
- Since:
- 19
-
Method Summary
Modifier and TypeMethodDescriptionReturns a path element which dereferences an address layout as its target layoutPREVIEW (where set).groupElement
(long index) Returns a path element which selects a member layout with the given index in a group layout.groupElement
(String name) Returns a path element which selects a member layout with the given name in a group layout.Returns an open path element which selects an unspecified element layout in a sequence layout.sequenceElement
(long index) Returns a path element which selects the element layout at the specified position in a sequence layout.sequenceElement
(long start, long step) Returns an open path element which selects the element layout in a range of positions in a sequence layout.
-
Method Details
-
groupElement
Returns a path element which selects a member layout with the given name in a group layout.- Implementation Requirements:
- in case multiple group elements with a matching name exist, the path element returned by this
method will select the first one; that is, the group element with the lowest offset from current path is selected.
In such cases, using
groupElement(long)
might be preferable. - Parameters:
name
- the name of the member layout to be selected.- Returns:
- a path element which selects the group member layout with the given name.
-
groupElement
Returns a path element which selects a member layout with the given index in a group layout.- Parameters:
index
- the index of the member layout element to be selected.- Returns:
- a path element which selects the group member layout with the given index.
- Throws:
IllegalArgumentException
- ifindex < 0
.
-
sequenceElement
Returns a path element which selects the element layout at the specified position in a sequence layout.- Parameters:
index
- the index of the sequence element to be selected.- Returns:
- a path element which selects the sequence element layout with the given index.
- Throws:
IllegalArgumentException
- ifindex < 0
.
-
sequenceElement
Returns an open path element which selects the element layout in a range of positions in a sequence layout. The range is expressed as a pair of starting index (inclusive)S
and step factor (which can also be negative)F
.The exact sequence element selected by this layout is expressed as an index
I
. IfC
is the sequence element count, it follows that0 <= I < B
, whereB
is computed as follows:- if
F > 0
, thenB = ceilDiv(C - S, F)
- if
F < 0
, thenB = ceilDiv(-(S + 1), -F)
- Parameters:
start
- the index of the first sequence element to be selected.step
- the step factor at which subsequence sequence elements are to be selected.- Returns:
- a path element which selects the sequence element layout with the given index.
- Throws:
IllegalArgumentException
- ifstart < 0
, orstep == 0
.
- if
-
sequenceElement
Returns an open path element which selects an unspecified element layout in a sequence layout.The exact sequence element selected by this layout is expressed as an index
I
. IfC
is the sequence element count, it follows that0 <= I < C
.- Returns:
- a path element which selects an unspecified sequence element layout.
-
dereferenceElement
Returns a path element which dereferences an address layout as its target layoutPREVIEW (where set).- Returns:
- a path element which dereferences an address layout.
-
PathElement
when preview features are enabled.