Module java.base
Package java.lang.foreign

# Interface ValueLayout

All Superinterfaces:
  `MemoryLayoutPREVIEW`

All Known Subinterfaces:
  `ValueLayout.OfAddressPREVIEW`, `ValueLayout.OfBooleanPREVIEW`, `ValueLayout.OfBytePREVIEW`, `ValueLayout.OfCharPREVIEW`, `ValueLayout.OfDoublePREVIEW`, `ValueLayout.OfFloatPREVIEW`, `ValueLayout.OfIntPREVIEW`, `ValueLayout.OfLongPREVIEW`, `ValueLayout.OfShortPREVIEW`

public sealed interface ValueLayout extends MemoryLayoutPREVIEW permits ValueLayout.OfBytePREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfAddressPREVIEW
`ValueLayout` is a preview API of the Java platform.
Programs can only use `ValueLayout` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A layout that models values of basic data types. Examples of values modelled by a value layout are integral values (either signed or unsigned), floating-point values and address values.

Each value layout has a size, an alignment (in bits), a byte order, and a carrier, that is, the Java type that should be used when accessingPREVIEW a region of memory using the value layout.

This class defines useful value layout constants for Java primitive types and addresses. The layout constants in this class make implicit alignment and byte-ordering assumption: all layout constants in this class are byte-aligned, and their byte order is set to the platform default, thus making it easy to work with other APIs, such as arrays and `ByteBuffer`.

Implementation Requirements:
  implementing classes and subclasses are immutable, thread-safe and value-based.
Since:
  19

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `ValueLayout.OfAddressPREVIEW`
  Preview.
  A value layout whose carrier is `MemorySegment.class`.
  `static interface`
  `ValueLayout.OfBooleanPREVIEW`
  Preview.
  A value layout whose carrier is `boolean.class`.
  `static interface`
  `ValueLayout.OfBytePREVIEW`
  Preview.
  A value layout whose carrier is `byte.class`.
  `static interface`
  `ValueLayout.OfCharPREVIEW`
  Preview.
  A value layout whose carrier is `char.class`.
  `static interface`
  `ValueLayout.OfDoublePREVIEW`
  Preview.
  A value layout whose carrier is `double.class`.
  `static interface`
  `ValueLayout.OfFloatPREVIEW`
  Preview.
  A value layout whose carrier is `float.class`.
  `static interface`
  `ValueLayout.OfIntPREVIEW`
  Preview.
  A value layout whose carrier is `int.class`.
  `static interface`
  `ValueLayout.OfLongPREVIEW`
  Preview.
  A value layout whose carrier is `long.class`.
  `static interface`
  `ValueLayout.OfShortPREVIEW`
  Preview.
  A value layout whose carrier is `short.class`.

  ## Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEW

  `MemoryLayout.PathElementPREVIEW`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ValueLayout.OfAddressPREVIEW`
  `ADDRESS`
  A value layout constant whose size is the same as that of a machine address (`size_t`), bit alignment set to `sizeof(size_t) * 8`, byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfAddressPREVIEW`
  `ADDRESS_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a machine address (`size_t`), and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfBooleanPREVIEW`
  `JAVA_BOOLEAN`
  A value layout constant whose size is the same as that of a Java `boolean`, bit alignment set to 8, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfBytePREVIEW`
  `JAVA_BYTE`
  A value layout constant whose size is the same as that of a Java `byte`, bit alignment set to 8, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfCharPREVIEW`
  `JAVA_CHAR`
  A value layout constant whose size is the same as that of a Java `char`, bit alignment set to 16, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfCharPREVIEW`
  `JAVA_CHAR_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `char` and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfDoublePREVIEW`
  `JAVA_DOUBLE`
  A value layout constant whose size is the same as that of a Java `double`, bit alignment set to 64, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfDoublePREVIEW`
  `JAVA_DOUBLE_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `double` and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfFloatPREVIEW`
  `JAVA_FLOAT`
  A value layout constant whose size is the same as that of a Java `float`, bit alignment set to 32, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfFloatPREVIEW`
  `JAVA_FLOAT_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `float` and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfIntPREVIEW`
  `JAVA_INT`
  A value layout constant whose size is the same as that of a Java `int`, bit alignment set to 32, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfIntPREVIEW`
  `JAVA_INT_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `int` and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfLongPREVIEW`
  `JAVA_LONG`
  A value layout constant whose size is the same as that of a Java `long`, bit alignment set to 64, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfLongPREVIEW`
  `JAVA_LONG_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `long` and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfShortPREVIEW`
  `JAVA_SHORT`
  A value layout constant whose size is the same as that of a Java `short`, bit alignment set to 16, and byte order set to `ByteOrder.nativeOrder()`.
  `static final ValueLayout.OfShortPREVIEW`
  `JAVA_SHORT_UNALIGNED`
  An unaligned value layout constant whose size is the same as that of a Java `short` and byte order set to `ByteOrder.nativeOrder()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `VarHandle`
  `arrayElementVarHandle(int... shape)`
  Creates a strided var handle that can be used to access a memory segment as multi-dimensional array.
  `Class<?>`
  `carrier()`
  Returns the carrier associated with this value layout.
  `ByteOrder`
  `order()`
  Returns the value's byte order.
  `ValueLayoutPREVIEW`
  `withBitAlignment(long bitAlignment)`
  Returns a memory layout of the same type with the same size and name as this layout, but with the specified alignment constraint (in bits).
  `ValueLayoutPREVIEW`
  `withName(String name)`
  Returns a memory layout of the same type with the same size and alignment constraint as this layout, but with the specified name.
  `ValueLayoutPREVIEW`
  `withOrder(ByteOrder order)`
  Returns a value layout with the same carrier, alignment constraint and name as this value layout, but with the specified byte order.

  ### Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEW

  `bitAlignment, bitOffset, bitOffsetHandle, bitSize, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle`

- ## Field Details

  - ### ADDRESS

    static final ValueLayout.OfAddressPREVIEW ADDRESS
    A value layout constant whose size is the same as that of a machine address (`size_t`), bit alignment set to `sizeof(size_t) * 8`, byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(MemorySegment.class, ByteOrder.nativeOrder());

  - ### JAVA_BYTE

    static final ValueLayout.OfBytePREVIEW JAVA_BYTE
    A value layout constant whose size is the same as that of a Java `byte`, bit alignment set to 8, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder());

  - ### JAVA_BOOLEAN

    static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN
    A value layout constant whose size is the same as that of a Java `boolean`, bit alignment set to 8, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder());

  - ### JAVA_CHAR

    static final ValueLayout.OfCharPREVIEW JAVA_CHAR
    A value layout constant whose size is the same as that of a Java `char`, bit alignment set to 16, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder());

  - ### JAVA_SHORT

    static final ValueLayout.OfShortPREVIEW JAVA_SHORT
    A value layout constant whose size is the same as that of a Java `short`, bit alignment set to 16, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder());

  - ### JAVA_INT

    static final ValueLayout.OfIntPREVIEW JAVA_INT
    A value layout constant whose size is the same as that of a Java `int`, bit alignment set to 32, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder());

  - ### JAVA_LONG

    static final ValueLayout.OfLongPREVIEW JAVA_LONG
    A value layout constant whose size is the same as that of a Java `long`, bit alignment set to 64, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder());

  - ### JAVA_FLOAT

    static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT
    A value layout constant whose size is the same as that of a Java `float`, bit alignment set to 32, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(32);

  - ### JAVA_DOUBLE

    static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
    A value layout constant whose size is the same as that of a Java `double`, bit alignment set to 64, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder());

  - ### ADDRESS_UNALIGNED

    static final ValueLayout.OfAddressPREVIEW ADDRESS_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a machine address (`size_t`), and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        ADDRESS.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_CHAR_UNALIGNED

    static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `char` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_CHAR.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_SHORT_UNALIGNED

    static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `short` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_SHORT.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_INT_UNALIGNED

    static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `int` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_INT.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_LONG_UNALIGNED

    static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `long` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_LONG.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_FLOAT_UNALIGNED

    static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `float` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_FLOAT.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

  - ### JAVA_DOUBLE_UNALIGNED

    static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED
    An unaligned value layout constant whose size is the same as that of a Java `double` and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        JAVA_DOUBLE.withBitAlignment(8);

    API Note:
      Care should be taken when using unaligned value layouts as they may induce performance and portability issues.

- ## Method Details

  - ### order

    ByteOrder order()
    Returns the value's byte order.
    Returns:
      the value's byte order

  - ### withOrder

    ValueLayoutPREVIEW withOrder(ByteOrder order)
    Returns a value layout with the same carrier, alignment constraint and name as this value layout, but with the specified byte order.
    Parameters:
      `order` - the desired byte order.
    Returns:
      a value layout with the given byte order.

  - ### arrayElementVarHandle

    VarHandle arrayElementVarHandle(int... shape)
    Creates a strided var handle that can be used to access a memory segment as multi-dimensional array. The layout of this array is a sequence layout with `shape.length` nested sequence layouts. The element layout of the sequence layout at depth `shape.length` is this value layout. As a result, if `shape.length == 0`, the array layout will feature only one dimension.

    The resulting var handle will feature `sizes.length + 1` coordinates of type `long`, which are used as indices into a multi-dimensional array.

    For instance, the following method call:

        VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);

    Can be used to access a multi-dimensional array whose layout is as follows:

         SequenceLayout arrayLayout = MemoryLayout.sequenceLayout(
                                              MemoryLayout.sequenceLayout(10,
                                                          MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));

    The resulting var handle `arrayHandle` will feature 3 coordinates of type `long`; each coordinate is interpreted as an index into the corresponding sequence layout. If we refer to the var handle coordinates, from left to right, as `x`, `y` and `z` respectively, the final offset accessed by the var handle can be computed with the following formula:

    >      offset = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)

    Additionally, the values of `x`, `y` and `z` are constrained as follows:
    - `0 <= x < arrayLayout.elementCount()`
    - `0 <= y < 10`
    - `0 <= z < 20`

    Consider the following access expressions:

        int value1 = arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176
        int value2 = arrayHandle.get(0, 0, 30); // out of bounds value for z

    In the first case, access is well-formed, as the values for `x`, `y` and `z` conform to the bounds specified above. In the second case, access fails with `IndexOutOfBoundsException`, as the value for `z` is outside its specified bounds.
    Parameters:
      `shape` - the size of each nested array dimension.
    Returns:
      a var handle which can be used to access a memory segment as a multi-dimensional array, featuring `shape.length + 1` `long` coordinates.
    Throws:
      `IllegalArgumentException` - if `shape[i] < 0`, for at least one index `i`.
      `UnsupportedOperationException` - if `bitAlignment() > bitSize()`.
    See Also:
      - `MethodHandles.memorySegmentViewVarHandle(java.lang.foreign.ValueLayout)`PREVIEW
      - `MemoryLayout.varHandle(PathElement...)`PREVIEW
      - `SequenceLayout`PREVIEW

  - ### carrier

    Class<?> carrier()
    Returns the carrier associated with this value layout.
    Returns:
      the carrier associated with this value layout

  - ### withName

    ValueLayoutPREVIEW withName(String name)
    Returns a memory layout of the same type with the same size and alignment constraint as this layout, but with the specified name.
    Specified by:
      `withName` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `name` - the layout name.
    Returns:
      a memory layout with the given name.
    See Also:
      - `MemoryLayout.name()`PREVIEW

  - ### withBitAlignment

    ValueLayoutPREVIEW withBitAlignment(long bitAlignment)
    Returns a memory layout of the same type with the same size and name as this layout, but with the specified alignment constraint (in bits).
    Specified by:
      `withBitAlignment` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `bitAlignment` - the layout alignment constraint, expressed in bits.
    Returns:
      a memory layout with the given alignment constraint.