Module java.base
Package java.lang.foreign

Interface SequenceLayout

所有超级接口:
MemoryLayout预览
public sealed interface SequenceLayout extends MemoryLayoutPREVIEW
SequenceLayout 是Java平台的预览API。
仅当启用预览功能时，程序才能使用SequenceLayout。
预览功能可能会在将来的版本中被移除，或升级为Java平台的永久功能。
表示给定元素布局的同质重复的复合布局。重复计数被称为序列布局的元素计数。序列布局可以被视为一个结构布局，其中序列布局的元素布局重复了与序列布局的元素计数相等的次数。换句话说，这个布局： 
MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
等同于以下布局： 
MemoryLayout.structLayout(
    ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
    ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
    ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
实现要求:
此类是不可变的、线程安全的，并且基于值。
自:
19

  • Method Details

    • elementLayout

      MemoryLayoutPREVIEW elementLayout()
      返回此序列布局的元素布局。
      返回:
      此序列布局的元素布局

    • elementCount

      long elementCount()
      返回此序列布局的元素计数。
      返回:
      此序列布局的元素计数

    • withElementCount

      SequenceLayoutPREVIEW withElementCount(long elementCount)
      返回具有与此布局相同特征的序列布局，但具有给定的元素计数。
      参数:
      elementCount - 新的元素计数。
      返回:
      具有与此布局相同特征的序列布局，但具有给定的元素计数
      抛出:
      IllegalArgumentException - 如果elementCount为负数。
      IllegalArgumentException - 如果elementLayout.bitSize() * elementCount溢出。

    • reshape

      SequenceLayoutPREVIEW reshape(long... elementCounts)
      将此序列布局中的元素重新排列为多维序列布局。结果布局是一个序列布局，其中在此序列布局的扁平化投影中的元素布局根据提供的元素计数重新排列为一个或多个嵌套序列布局。此转换保留布局大小；也就是说，将所提供的元素计数相乘必须产生与此序列布局的扁平化投影相同的元素计数。

      例如，给定以下类型的序列布局：

      var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
      调用seq.reshape(2, 6)将产生以下序列布局： 
      var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));

      如果所提供的元素计数中有一个特殊值-1，则该位置上的元素计数将从剩余元素计数和此布局的扁平化投影的元素计数中推断出。例如，等同于上述reshapeSeq的布局也可以通过以下方式计算：

      var reshapeSeqImplicit1 = seq.reshape(-1, 6);
var reshapeSeqImplicit2 = seq.reshape(2, -1);
      参数:
      elementCounts - 一个元素计数数组，其中最多可以有一个-1。
      返回:
      一个序列布局，其中此序列布局的扁平化投影中的元素布局（参见flatten()）被重新排列为一个或多个嵌套序列布局。
      抛出:
      IllegalArgumentException - 如果两个或更多元素计数设置为-1，或者一个或多个元素计数为<= 0（但不是-1），或者在任何必要的推断后，将元素计数相乘不会产生与此序列布局的扁平化投影相同的元素计数。

    • flatten

      SequenceLayoutPREVIEW flatten()
      返回一个扁平化的序列布局。返回的序列布局的元素布局是通过检查（如果需要，递归地）此序列布局的元素布局找到的第一个非序列布局： 
      MemoryLayout flatElementLayout(SequenceLayout sequenceLayout) {
   return switch (sequenceLayout.elementLayout()) {
       case SequenceLayout nestedSequenceLayout -> flatElementLayout(nestedSequenceLayout);
       case MemoryLayout layout -> layout;
   };
}

      此转换保留布局大小；此序列布局中的嵌套序列布局将被丢弃，它们的元素计数将合并到返回的序列布局中。例如，给定以下类型的序列布局：

      var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
      调用seq.flatten()将产生以下序列布局： 
      var flattenedSeq = MemoryLayout.sequenceLayout(12, ValueLayout.JAVA_INT);
      返回:
      一个具有与此布局相同大小（但可能具有不同元素计数）的序列布局，其元素布局不是序列布局。

    • withName

      SequenceLayoutPREVIEW withName(String name)
      返回具有与此布局相同特征的内存布局，但具有给定的名称。
      指定者:
      withName 在接口 MemoryLayout预览中
      参数:
      name - 布局名称。
      返回:
      一个具有与此布局相同特征的内存布局，但具有给定的名称
      参见:

    • withByteAlignment

      SequenceLayoutPREVIEW withByteAlignment(long byteAlignment)
      返回具有与此布局相同特征的内存布局，但具有给定的对齐约束（以字节为单位）。
      指定者:
      withByteAlignment 在接口 MemoryLayout预览中
      参数:
      byteAlignment - 布局对齐约束，以字节表示。
      返回:
      一个具有与此布局相同特征的内存布局，但具有给定的对齐约束（以字节为单位）
      抛出:
      IllegalArgumentException - 如果byteAlignment不是2的幂。
      IllegalArgumentException - 如果byteAlignment < elementLayout().byteAlignment()。