MemoryLayout.PathElement (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.lang.foreign, interface: MemoryLayout, interface: PathElement
Keywords: java.lang.foreign.MemoryLayout.PathElement interface

# 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. The size of an open path element determines the number of element layouts that can be selected by it.

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 selects the target layout of an address 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)`
    That is, the size of the returned open path element is `B`.
    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`. That is, `C` is the size of the returned open path element.

    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 selects the target layout of an address layout (where set).
    Returns:
      a path element that selects the target layout of an address layout (where set)