模块 java.base
包 java.lang.foreign

接口 MemoryLayout.PathElement

封闭接口：
MemoryLayoutPREVIEW
public static sealed interface MemoryLayout.PathElement
PathElement 是 Java 平台的预览 API。
程序只能在启用预览功能时使用 PathElement。
预览功能可能会在未来的版本中删除，或升级为 Java 平台的永久功能。
layout path 中的一个元素。有两种路径元素：group path elements 和 sequence path elements。组路径元素用于在 GroupLayout 中选择命名成员布局PREVIEW .序列路径元素用于在 SequenceLayout 中选择序列元素布局PREVIEW ;序列元素布局的选择可以是explicit（参见sequenceElement(long) ）或implicit（参见sequenceElement() ）。当路径使用一个或多个隐式序列路径元素时，它会获取额外的 free dimensions 。
实现要求：
此接口的实现是不可变的、线程安全的和 value-based 。
自从：
19

  • 方法详情

    • groupElement

      static MemoryLayout.PathElement PREVIEW  groupElement(String  name)
      返回一个路径元素，该元素在组布局中选择具有给定名称的成员布局。此方法返回的路径元素不会改变与此类元素组合的任何路径的自由维数。
      实现要求：
      如果存在多个具有匹配名称的组元素，则此方法返回的路径元素将选择第一个；也就是说，选择与当前路径偏移量最小的组元素。
      参数：
      name - 要选择的组元素的名称。
      返回：
      选择具有给定名称的组元素的路径元素。

    • sequenceElement

      static MemoryLayout.PathElement PREVIEW  sequenceElement(long index)
      返回一个路径元素，它选择序列布局中指定位置的元素布局。此方法返回的路径元素不会改变与此类元素组合的任何路径的自由维数。
      参数：
      index - 要选择的序列元素的索引。
      返回：
      选择具有给定索引的序列元素布局的路径元素。
      抛出：
      IllegalArgumentException - 如果是 index < 0。

    • sequenceElement

      static MemoryLayout.PathElement PREVIEW  sequenceElement(long start, long step)
      返回一个路径元素，该元素在序列布局的 range 个位置中选择元素布局。范围表示为一对起始索引（含）S和步长因子（也可以为负）F。

      如果具有自由维度 n 的路径与此方法返回的路径元素组合，则生成的路径的自由维度数将为 1 + n 。如果与此路径关联的自由维度由索引 I 绑定，则可以使用以下公式获得所得到的访问偏移量：

      
 E * (S + I * F)
      其中 E 是序列元素布局的大小（以字节为单位）。

      此外，如果 C 是序列元素计数，则它遵循 0 <= I < B ，其中 B 计算如下：

      • 如果 F > 0 ，则 B = ceilDiv(C - S, F)
      • 如果 F < 0 ，则 B = ceilDiv(-(S + 1), -F)
      参数：
      start - 要选择的第一个序列元素的索引。
      step - 选择子序列元素的步长因子。
      返回：
      选择具有给定索引的序列元素布局的路径元素。
      抛出：
      IllegalArgumentException - 如果是 start < 0 或 step == 0。

    • sequenceElement

      static MemoryLayout.PathElement PREVIEW  sequenceElement()
      返回一个路径元素，它在序列布局中选择一个未指定的元素布局。

      如果具有自由维度 n 的路径与此方法返回的路径元素组合，则生成的路径的自由维度数将为 1 + n 。如果与此路径关联的自由维度由索引 I 绑定，则可以使用以下公式获得所得到的访问偏移量：

      
 E * I
      其中 E 是序列元素布局的大小（以字节为单位）。

      此外，如果 C 是序列元素计数，则它遵循 0 <= I < C 。

      返回：
      选择未指定序列元素布局的路径元素。