模块 java.base
包 java.lang.foreign

接口 ValueLayout

所有父级接口：
MemoryLayoutPREVIEW
所有已知的子接口：
ValueLayout.OfAddressPREVIEW , ValueLayout.OfBooleanPREVIEW , ValueLayout.OfBytePREVIEW , ValueLayout.OfCharPREVIEW , ValueLayout.OfDoublePREVIEW , ValueLayout.OfFloatPREVIEW , ValueLayout.OfIntPREVIEW , ValueLayout.OfLongPREVIEW , ValueLayout.OfShortPREVIEW
public sealed interface ValueLayout extends MemoryLayout PREVIEW permits ValueLayout.OfByte PREVIEW , ValueLayout.OfShort PREVIEW , ValueLayout.OfChar PREVIEW , ValueLayout.OfInt PREVIEW , ValueLayout.OfFloat PREVIEW , ValueLayout.OfLong PREVIEW , ValueLayout.OfDouble PREVIEW , ValueLayout.OfBoolean PREVIEW , ValueLayout.OfAddress PREVIEW
ValueLayout 是 Java 平台的预览 API。
程序只能在启用预览功能时使用 ValueLayout。
预览功能可能会在未来的版本中删除，或升级为 Java 平台的永久功能。
对基本数据类型的值建模的布局。值布局建模的值示例是integral值（有符号或无符号）、floating-point值和address值。

每个值布局都有一个大小、一个对齐方式（以位为单位）、一个 字节顺序 和一个 carrier ，即 访问 时应使用的 Java 类型PREVIEW 使用值布局的内存区域。

此类为 Java 原始类型和地址定义了有用的值布局常量。此类中的布局常量做出隐式对齐和字节顺序假设：此类中的所有布局常量都是字节对齐的，并且它们的字节顺序设置为 平台默认 ，从而可以轻松地与其他 API 一起工作，例如数组和ByteBuffer 。

实现要求：
实现类和子类是不可变的、线程安全的和 value-based 。
自从：
19

  • 字段详细信息

    • ADDRESS

      static final ValueLayout.OfAddress PREVIEW  ADDRESS
      一个值布局常量，其大小与机器地址 (size_t) 的大小相同，位对齐设置为 sizeof(size_t) * 8，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(MemorySegment.class, ByteOrder.nativeOrder());

    • JAVA_BYTE

      static final ValueLayout.OfByte PREVIEW  JAVA_BYTE
      一个值布局常量，其大小与 Java byte 的大小相同，位对齐设置为 8，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder());

    • JAVA_BOOLEAN

      static final ValueLayout.OfBoolean PREVIEW  JAVA_BOOLEAN
      一个值布局常量，其大小与 Java boolean 相同，位对齐设置为 8，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder());

    • JAVA_CHAR

      static final ValueLayout.OfChar PREVIEW  JAVA_CHAR
      一个值布局常量，其大小与 Java char 相同，位对齐设置为 16，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder());

    • JAVA_SHORT

      static final ValueLayout.OfShort PREVIEW  JAVA_SHORT
      一个值布局常量，其大小与 Java short 的大小相同，位对齐设置为 16，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder());

    • JAVA_INT

      static final ValueLayout.OfInt PREVIEW  JAVA_INT
      一个值布局常量，其大小与 Java int 相同，位对齐设置为 32，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder());

    • JAVA_LONG

      static final ValueLayout.OfLong PREVIEW  JAVA_LONG
      一个值布局常量，其大小与 Java long 相同，位对齐设置为 64，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder());

    • JAVA_FLOAT

      static final ValueLayout.OfFloat PREVIEW  JAVA_FLOAT
      一个值布局常量，其大小与 Java float 相同，位对齐设置为 32，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(32);

    • JAVA_DOUBLE

      static final ValueLayout.OfDouble PREVIEW  JAVA_DOUBLE
      一个值布局常量，其大小与 Java double 相同，位对齐设置为 64，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder());

    • ADDRESS_UNALIGNED

      static final ValueLayout.OfAddress PREVIEW  ADDRESS_UNALIGNED
      一个未对齐的值布局常量，其大小与机器地址（size_t）的大小相同，字节顺序设置为ByteOrder.nativeOrder() 。相当于下面的代码： 
      ADDRESS.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_CHAR_UNALIGNED

      static final ValueLayout.OfChar PREVIEW  JAVA_CHAR_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java char 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_CHAR.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_SHORT_UNALIGNED

      static final ValueLayout.OfShort PREVIEW  JAVA_SHORT_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java short 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_SHORT.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_INT_UNALIGNED

      static final ValueLayout.OfInt PREVIEW  JAVA_INT_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java int 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_INT.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_LONG_UNALIGNED

      static final ValueLayout.OfLong PREVIEW  JAVA_LONG_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java long 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_LONG.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_FLOAT_UNALIGNED

      static final ValueLayout.OfFloat PREVIEW  JAVA_FLOAT_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java float 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_FLOAT.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

    • JAVA_DOUBLE_UNALIGNED

      static final ValueLayout.OfDouble PREVIEW  JAVA_DOUBLE_UNALIGNED
      一个未对齐的值布局常量，其大小与 Java double 的大小相同，字节顺序设置为 ByteOrder.nativeOrder() 。相当于下面的代码： 
      JAVA_DOUBLE.withBitAlignment(8);
      API 注意：
      使用未对齐的值布局时应小心，因为它们可能会导致性能和可移植性问题。

  • 方法详情

    • order

      ByteOrder  order()
      返回值的字节顺序。
      返回：
      值的字节顺序

    • withOrder

      ValueLayout PREVIEW  withOrder(ByteOrder  order)
      返回与此值布局具有相同载体、对齐约束和名称但具有指定字节顺序的值布局。
      参数：
      order - 所需的字节顺序。
      返回：
      具有给定字节顺序的值布局。

    • arrayElementVarHandle

      VarHandle  arrayElementVarHandle(int... shape)
      创建一个 strided var 句柄，可用于访问作为多维数组的内存段。该数组的布局是具有shape.length 嵌套序列布局的序列布局。深度shape.length处的序列布局的元素布局就是这个值布局。因此，如果 shape.length == 0 ，数组布局将只有一个维度。

      生成的 var 句柄将具有 long 类型的 sizes.length + 1 坐标，用作多维数组的索引。

      例如，下面的方法调用：

      VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);
      可用于访问一个多维数组，其布局如下： 
       SequenceLayout arrayLayout = MemoryLayout.sequenceLayout(
                   MemoryLayout.sequenceLayout(10,
                         MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
      生成的 var handle arrayHandle 将具有 3 个类型为 long 的坐标；每个坐标都被解释为相应序列布局的索引。如果我们引用 var 句柄坐标，从左到右分别为 x、y 和 z，则 var 句柄访问的最终偏移量可以使用以下公式计算： 
      
 offset = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)
      此外，x、y 和 z 的值受到如下约束：
      • 0 <= x < arrayLayout.elementCount()
      • 0 <= y < 10
      • 0 <= z < 20

      考虑以下访问表达式：

      int value1 = arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176
int value2 = arrayHandle.get(0, 0, 30); // out of bounds value for z
      在第一种情况下，访问是合式的，因为 x、y 和 z 的值符合上面指定的界限。在第二种情况下，访问失败并显示 IndexOutOfBoundsException ，因为 z 的值超出了其指定范围。
      参数：
      shape - 每个嵌套数组维度的大小。
      返回：
      一个 var 句柄，可用于访问作为多维数组的内存段，具有 shape.length + 1 long 坐标。
      抛出：
      IllegalArgumentException - 如果 shape[i] < 0 ，对于至少一个索引 i 。
      UnsupportedOperationException - 如果是 bitAlignment() > bitSize()。
      参见：

    • carrier

      Class <?> carrier()
      返回与此值布局关联的载体。
      返回：
      与此值布局关联的载体

    • withName

      ValueLayout PREVIEW  withName(String  name)
      返回与此布局具有相同大小和对齐约束但具有指定名称的相同类型的内存布局。
      指定者：
      withName 在接口 MemoryLayoutPREVIEW 中
      参数：
      name - 布局名称。
      返回：
      具有给定名称的内存布局。
      参见：

    • withBitAlignment

      ValueLayout PREVIEW  withBitAlignment(long bitAlignment)
      返回与此布局具有相同大小和名称但具有指定对齐约束（以位为单位）的相同类型的内存布局。
      指定者：
      withBitAlignment 在接口 MemoryLayoutPREVIEW 中
      参数：
      bitAlignment - 布局对齐约束，以位表示。
      返回：
      具有给定对齐约束的内存布局。