Module java.base

Package java.lang.foreign

Interface MemoryLayout.PathElement

Enclosing interface:

MemoryLayout

public static sealed interface MemoryLayout.PathElement

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, either by name or by index;
• sequence path elements, used to select one or more sequence element layouts within a SequenceLayout; and
• dereference path elements, used to dereference an address layout as its target layout.

Sequence path elements selecting more than one sequence element layout are called open path elements.

Implementation Requirements:

Implementations of this interface are immutable, thread-safe and value-based.

Since:

22

Method Summary

Static Methods

Modifier and Type	Method	Description
static MemoryLayout.PathElement	dereferenceElement()	Returns a path element that dereferences an address layout as its target layout (where set).
static MemoryLayout.PathElement	groupElement(long index)	Returns a path element that selects a member layout with the given index in a group layout.
static MemoryLayout.PathElement	groupElement(String name)	Returns a path element which selects a member layout with the given name in a group layout.
static MemoryLayout.PathElement	sequenceElement()	Returns an open path element that selects an unspecified element layout in a sequence layout.
static MemoryLayout.PathElement	sequenceElement(long index)	Returns a path element which selects the element layout at the specified index in a sequence layout.
static MemoryLayout.PathElement	sequenceElement(long start, long step)	Returns an open path element that selects the element layout in a range of positions in a sequence layout.

Method Details

groupElement

static MemoryLayout.PathElement groupElement(String name)

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 the 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 a member layout with the given name in a group layout

groupElement

static MemoryLayout.PathElement groupElement(long index)

Returns a path element that 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 that selects a member layout with the given index in a group layout

Throws:

IllegalArgumentException - if index < 0

sequenceElement

static MemoryLayout.PathElement sequenceElement(long index)

Returns a path element which selects the element layout at the specified index in a sequence layout.

Parameters:

index - the index of the sequence element to be selected

Returns:

a path element which selects the element layout at the specified index in a sequence layout

Throws:

IllegalArgumentException - if index < 0

sequenceElement

static MemoryLayout.PathElement sequenceElement(long start,
 long step)

Returns an open path element that 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. If C is the sequence element count, it follows that 0 <= I < B, where B is computed as follows:

• if F > 0, then B = ceilDiv(C - S, F)
• if F < 0, then B = 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 that selects the sequence element layout with the given index.

Throws:

IllegalArgumentException - if start < 0, or step == 0

sequenceElement

static MemoryLayout.PathElement sequenceElement()

Returns an open path element that selects an unspecified element layout in a sequence layout.

The exact sequence element selected by this layout is expressed as an index I. If C is the sequence element count, it follows that 0 <= I < C.

Returns:

an open path element that selects an unspecified element layout in a sequence layout

dereferenceElement

static MemoryLayout.PathElement dereferenceElement()

Returns a path element that dereferences an address layout as its target layout (where set).

Returns:

a path element that dereferences an address layout as its target layout (where set)