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

Interface MemoryLayout.PathElement

Enclosing interface:
MemoryLayout
public static 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.

API Note:
In the future, if the Java language permits, MemoryLayout.PathElement may become a sealed interface, which would prohibit subclassing except by explicitly permitted types.
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.
      Throws:
      NullPointerException - if the specified group element name is null.

    • 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.