Module java.base
Package java.lang.foreign

# Class ValueLayout

java.lang.Object
java.lang.foreign.ValueLayout

All Implemented Interfaces:
  `MemoryLayoutPREVIEW`

Direct Known Subclasses:
  `ValueLayout.OfAddressPREVIEW`, `ValueLayout.OfBooleanPREVIEW`, `ValueLayout.OfBytePREVIEW`, `ValueLayout.OfCharPREVIEW`, `ValueLayout.OfDoublePREVIEW`, `ValueLayout.OfFloatPREVIEW`, `ValueLayout.OfIntPREVIEW`, `ValueLayout.OfLongPREVIEW`, `ValueLayout.OfShortPREVIEW`

public sealed class ValueLayout extends Object implements 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 value layout. A value layout is used to model the memory layout associated with values of basic data types, such as integral types (either signed or unsigned) and floating-point types. 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 memory region 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`.

Since:
  19
Implementation Requirements:
  This class and its subclasses are immutable, thread-safe and value-based.

- ## Nested Class Summary

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

  ## Nested classes/interfaces inherited from 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`, 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.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.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.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.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.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()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `VarHandle`
  `arrayElementVarHandle(int... shape)`
  Creates a strided access var handle that can be used to dereference a multi-dimensional array.
  `final long`
  `bitAlignment()`
  Returns the alignment constraint associated with this layout, expressed in bits.
  `long`
  `bitSize()`
  Returns the layout size, in bits.
  `long`
  `byteSize()`
  Returns the layout size, in bytes.
  `Class<?>`
  `carrier()`
  Returns the carrier associated with this value layout.
  `boolean`
  `equals(Object other)`
  Compares the specified object with this layout for equality.
  `int`
  `hashCode()`
  Returns the hash code value for this layout.
  `boolean`
  `isPadding()`
  Returns true, if this layout is a padding layout.
  `final Optional<String>`
  `name()`
  Returns the name (if any) associated with this layout.
  `ByteOrder`
  `order()`
  Returns the value's byte order.
  `String`
  `toString()`
  Returns the string representation of this layout.
  `ValueLayoutPREVIEW`
  `withBitAlignment(long alignmentBits)`
  Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).
  `ValueLayoutPREVIEW`
  `withName(String name)`
  Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.
  `ValueLayoutPREVIEW`
  `withOrder(ByteOrder order)`
  Returns a value layout with the same carrier, alignment constraints and name as this value layout, but with the specified byte order.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.lang.foreign.MemoryLayoutPREVIEW

  `bitAlignment, bitOffset, bitOffsetHandle, bitSize, byteAlignment, byteOffset, byteOffsetHandle, byteSize, isPadding, name, select, sliceHandle, varHandle`

- ## Field Details

  - ### ADDRESS

    public 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`, and byte order set to `ByteOrder.nativeOrder()`. Equivalent to the following code:

        MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder())
                    .withBitAlignment(<address size>);

  - ### JAVA_BYTE

    public 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()).withBitAlignment(8);

  - ### JAVA_BOOLEAN

    public 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()).withBitAlignment(8);

  - ### JAVA_CHAR

    public 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()).withBitAlignment(16);

  - ### JAVA_SHORT

    public 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()).withBitAlignment(16);

  - ### JAVA_INT

    public 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()).withBitAlignment(32);

  - ### JAVA_LONG

    public 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()).withBitAlignment(64);

  - ### JAVA_FLOAT

    public 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

    public 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()).withBitAlignment(64);

- ## Method Details

  - ### order

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

  - ### withOrder

    public ValueLayoutPREVIEW withOrder(ByteOrder order)
    Returns a value layout with the same carrier, alignment constraints 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.

  - ### toString

    public String toString()
    Returns the string representation of this layout.
    Specified by:
      `toString` in interface `MemoryLayoutPREVIEW`
    Returns:
      the string representation of this layout

  - ### equals

    public boolean equals(Object other)
    Compares the specified object with this layout for equality. Returns `true` if and only if the specified object is also a layout, and it is equal to this layout. Two layouts are considered equal if they are of the same kind, have the same size, name and alignment constraints. Furthermore, depending on the layout kind, additional conditions must be satisfied:
    - two value layouts are considered equal if they have the same byte order (see `order()`)
    - two sequence layouts are considered equal if they have the same element count (see `SequenceLayout.elementCount()`PREVIEW), and if their element layouts (see `SequenceLayout.elementLayout()`PREVIEW) are also equal
    - two group layouts are considered equal if they are of the same kind (see `GroupLayout.isStruct()`PREVIEW, `GroupLayout.isUnion()`PREVIEW) and if their member layouts (see `GroupLayout.memberLayouts()`PREVIEW) are also equal
    Specified by:
      `equals` in interface `MemoryLayoutPREVIEW`
    Parameters:
      `other` - the object to be compared for equality with this layout.
    Returns:
      `true` if the specified object is equal to this layout.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### arrayElementVarHandle

    public VarHandle arrayElementVarHandle(int... shape)
    Creates a strided access var handle that can be used to dereference a 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:

        MemoryLayout arrayLayout = MemoryLayout.sequenceLayout(-1,
                                             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 dereferenced by the var handle can be computed with the following formula:

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

    Parameters:
      `shape` - the size of each nested array dimension.
    Returns:
      a var handle which can be used to dereference a multi-dimensional array, featuring `shape.length + 1` `long` coordinates.
    Throws:
      `IllegalArgumentException` - if `shape[i] < 0`, for at least one index `i`.
      `UnsupportedOperationException` - if the layout path has one or more elements with incompatible alignment constraints.
    See Also:
      - `MethodHandles.memorySegmentViewVarHandle(java.lang.foreign.ValueLayout)`PREVIEW
      - `MemoryLayout.varHandle(PathElement...)`PREVIEW
      - `SequenceLayout`PREVIEW

  - ### carrier

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

  - ### hashCode

    public int hashCode()
    Returns the hash code value for this layout.
    Specified by:
      `hashCode` in interface `MemoryLayoutPREVIEW`
    Returns:
      the hash code value for this layout
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`

  - ### withName

    public ValueLayoutPREVIEW withName(String name)
    Returns a memory layout with the same size and alignment constraints 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

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

  - ### name

    public final Optional<String> name()
    Description copied from interface: `MemoryLayout`
    Returns the name (if any) associated with this layout.
    Specified by:
      `name` in interface `MemoryLayoutPREVIEW`
    Returns:
      the name (if any) associated with this layout
    See Also:
      - `MemoryLayout.withName(String)`PREVIEW

  - ### bitAlignment

    public final long bitAlignment()
    Description copied from interface: `MemoryLayout`
    Returns the alignment constraint associated with this layout, expressed in bits. Layout alignment defines a power of two `A` which is the bit-wise alignment of the layout. If `A <= 8` then `A/8` is the number of bytes that must be aligned for any pointer that correctly points to this layout. Thus:
    - `A=8` means unaligned (in the usual sense), which is common in packets.
    - `A=64` means word aligned (on LP64), `A=32` int aligned, `A=16` short aligned, etc.
    - `A=512` is the most strict alignment required by the x86/SV ABI (for AVX-512 data).
    If no explicit alignment constraint was set on this layout (see `MemoryLayout.withBitAlignment(long)`PREVIEW), then this method returns the natural alignment constraint (in bits) associated with this layout.
    Specified by:
      `bitAlignment` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout alignment constraint, in bits.

  - ### byteSize

    public long byteSize()
    Description copied from interface: `MemoryLayout`
    Returns the layout size, in bytes.
    Specified by:
      `byteSize` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout size, in bytes

  - ### bitSize

    public long bitSize()
    Description copied from interface: `MemoryLayout`
    Returns the layout size, in bits.
    Specified by:
      `bitSize` in interface `MemoryLayoutPREVIEW`
    Returns:
      the layout size, in bits

  - ### isPadding

    public boolean isPadding()
    Description copied from interface: `MemoryLayout`
    Returns true, if this layout is a padding layout.
    Specified by:
      `isPadding` in interface `MemoryLayoutPREVIEW`
    Returns:
      true, if this layout is a padding layout