Module java.base
Package java.lang.foreign

Interface MemoryLayout.PathElement

Enclosing interface:
MemoryLayoutPREVIEW
public static sealed interface MemoryLayout.PathElement
PathElement is a preview API of the Java platform.
Programs can only use PathElement when preview features are enabled.
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 GroupLayoutPREVIEW, either by name or by index;
  • sequence path elements, used to select one or more sequence element layouts within a SequenceLayoutPREVIEW; 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:
19

  • Method Details

    • groupElement

      static MemoryLayout.PathElementPREVIEW 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 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

      static MemoryLayout.PathElementPREVIEW groupElement(long index)
      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 - if index < 0.

    • sequenceElement

      static MemoryLayout.PathElementPREVIEW sequenceElement(long index)
      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 - if index < 0.

    • sequenceElement

      static MemoryLayout.PathElementPREVIEW sequenceElement(long start, long step)
      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. 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 which selects the sequence element layout with the given index.
      Throws:
      IllegalArgumentException - if start < 0, or step == 0.

    • sequenceElement

      static MemoryLayout.PathElementPREVIEW 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. If C is the sequence element count, it follows that 0 <= I < C.

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

    • dereferenceElement

      static MemoryLayout.PathElementPREVIEW 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.