Interface MemoryLayout.PathElement

Enclosing interface:: MemoryLayout

public static sealed interface MemoryLayout.PathElement

Instances of this class are used to form layout paths. There are two kinds of path elements: group path elements and sequence path elements. Group path elements are used to select a given named member layout within a GroupLayout. Sequence path elements are used to select a sequence element layout within a SequenceLayout; selection of sequence element layout can be explicit (see sequenceElement(long)) or implicit (see sequenceElement()). When a path uses one or more implicit sequence path elements, it acquires additional free dimensions.

Non-platform classes should not implement MemoryLayout.PathElement directly.

Unless otherwise specified, passing a null argument, or an array argument containing one or more null elements to a method in this class causes a NullPointerException to be thrown.

Implementation Requirements:: Implementations of this interface are immutable and thread-safe.

Method Summary

Modifier and Type	Method	Description
`static MemoryLayout.PathElement`	`groupElement(String name)`	Returns a path element which selects a member layout with given name from a given group layout.
`static MemoryLayout.PathElement`	`sequenceElement()`	Returns a path element which selects an unspecified element layout from a given sequence layout.
`static MemoryLayout.PathElement`	`sequenceElement(long index)`	Returns a path element which selects the element layout at the specified position in a given the sequence layout.
`static MemoryLayout.PathElement`	`sequenceElement(long start, long step)`	Returns a path element which selects the element layout in a range of positions in a given the sequence layout, where the range is expressed as a pair of starting index (inclusive) `S` and step factor (which can also be negative) `F`.

Method Details

groupElement

static MemoryLayout.PathElement groupElement(String name)

Returns a path element which selects a member layout with given name from a given group layout. The path element returned by this method does not alter the number of free dimensions of any path that is combined with such element.

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 lowest offset from current path is selected.
Parameters:: name - the name of the group element to be selected.
Returns:: a path element which selects the group element with given name.

sequenceElement

static MemoryLayout.PathElement sequenceElement(long index)

Returns a path element which selects the element layout at the specified position in a given the sequence layout. The path element returned by this method does not alter the number of free dimensions of any path that is combined with such element.

Parameters:: index - the index of the sequence element to be selected.
Returns:: a path element which selects the sequence element layout with given index.
Throws:: IllegalArgumentException - if index < 0.

sequenceElement

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

Returns a path element which selects the element layout in a range of positions in a given the sequence layout, where the range is expressed as a pair of starting index (inclusive) S and step factor (which can also be negative) F. If a path with free dimensions n is combined with the path element returned by this method, the number of free dimensions of the resulting path will be 1 + n. If the free dimension associated with this path is bound by an index I, the resulting accessed offset can be obtained with the following formula:


E * (S + I * F)

where E is the size (in bytes) of the sequence element layout.

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 given index.
Throws:: IllegalArgumentException - if start < 0, or step == 0.

sequenceElement

static MemoryLayout.PathElement sequenceElement()

Returns a path element which selects an unspecified element layout from a given sequence layout. If a path with free dimensions n is combined with the path element returned by this method, the number of free dimensions of the resulting path will be 1 + n.

Returns:: a path element which selects an unspecified sequence element layout.

© 1993, 2021, 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.
https://docs.oracle.com/en/java/javase/17/docs/api/jdk.incubator.foreign/jdk/incubator/foreign/MemoryLayout.PathElement.html