Module jdk.incubator.foreign
Package jdk.incubator.foreign

# 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

Static Methods
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.