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 two kinds of path elements: group path elements and sequence path elements. Group path elements are used to select a named member layout within a GroupLayoutPREVIEW. Sequence path elements are used to select a sequence element layout within a SequenceLayoutPREVIEW; 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.
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. 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 the lowest offset from current path is selected. In such cases, using groupElement(long) might be preferable.
      Parameters:
      name - the name of the group element to be selected.
      Returns:
      a path element which selects the group element 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. 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 group element to be selected.
      Returns:
      a path element which selects the group element 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. 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 the given index.
      Throws:
      IllegalArgumentException - if index < 0.

    • sequenceElement

      static MemoryLayout.PathElementPREVIEW sequenceElement(long start, long step)
      Returns a 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.

      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.

      Additionally, 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 a path element which selects an unspecified element layout in a 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. 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 * I
      where E is the size (in bytes) of the sequence element layout.

      Additionally, 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). The path element returned by this method does not alter the number of free dimensions of any path that is combined with such element. Using this path layout to dereference an address layout that has no target layout results in an IllegalArgumentException (e.g. when a var handle is obtainedPREVIEW).
      Returns:
      a path element which dereferences an address layout.