Module java.base
Package java.lang.foreign

# Interface ValueLayout

All Superinterfaces:
  `MemoryLayoutPREVIEW`

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

public sealed interface ValueLayout extends MemoryLayoutPREVIEW permits ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, AddressLayoutPREVIEW
`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 (both expressed in bytes), 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.

API Note:
  Some characteristics of the Java layout constants are platform-dependent. For instance, the byte order of these constants is set to the native byte order, thus making it easy to work with other APIs, such as arrays and `ByteBuffer`. Moreover, the alignment constraint of `JAVA_LONG` and `JAVA_DOUBLE` is set to 8 bytes on 64-bit platforms, but only to 4 bytes on 32-bit platforms.
Implementation Requirements:
  implementing classes and subclasses are immutable, thread-safe and value-based.
Sealed Class Hierarchy Graph:
Since:
  19

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`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 AddressLayoutPREVIEW`
`ADDRESS`
An address layout constant whose size is the same as that of a machine address (`size_t`), byte alignment set to `sizeof(size_t)`, byte order set to `ByteOrder.nativeOrder()`.
`static final AddressLayoutPREVIEW`
`ADDRESS_UNALIGNED`
An unaligned address 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`, byte alignment set to 1, 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`, byte alignment set to 1, 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`, byte alignment set to 2, 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`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, 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`, byte alignment set to 4, 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`, byte alignment set to 4, 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`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, 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`, byte alignment set to 2, 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`
`withByteAlignment(long byteAlignment)`
Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
`ValueLayoutPREVIEW`
`withName(String name)`
Returns a memory layout with the same characteristics as this layout, but with the given name.
`ValueLayoutPREVIEW`
`withOrder(ByteOrder order)`
Returns a value layout with the same characteristics as this layout, but with the given byte order.
`ValueLayoutPREVIEW`
`withoutName()`
Returns a memory layout with the same characteristics as this layout, but with no name.

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

`byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle`

## Field Details

### ADDRESS

static final AddressLayoutPREVIEW ADDRESS
An address layout constant whose size is the same as that of a machine address (`size_t`), byte alignment set to `sizeof(size_t)`, byte order set to `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`, byte alignment set to 1, and byte order set to `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`, byte alignment set to 1, and byte order set to `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`, byte alignment set to 2, and byte order set to `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`, byte alignment set to 2, and byte order set to `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`, byte alignment set to 4, and byte order set to `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`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, and byte order set to `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`, byte alignment set to 4, and byte order set to `ByteOrder.nativeOrder()`.

### JAVA_DOUBLE

static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE
A value layout constant whose size is the same as that of a Java `double`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, and byte order set to `ByteOrder.nativeOrder()`.

### ADDRESS_UNALIGNED

static final AddressLayoutPREVIEW ADDRESS_UNALIGNED
An unaligned address 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.withByteAlignment(1);

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.withByteAlignment(1);

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.withByteAlignment(1);

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.withByteAlignment(1);

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.withByteAlignment(1);

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.withByteAlignment(1);

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.withByteAlignment(1);

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 characteristics as this layout, but with the given byte order.

Parameters:
  `order` - the desired byte order.
Returns:
  a value layout with the same characteristics as this layout, but with the given byte order

### withoutName

ValueLayoutPREVIEW withoutName()
Returns a memory layout with the same characteristics as this layout, but with no name.

Specified by:
  `withoutName` in interface `MemoryLayoutPREVIEW`
Returns:
  a memory layout with the same characteristics as this layout, but with no name
See Also:
  - `MemoryLayout.name()`PREVIEW

### arrayElementVarHandle

VarHandle arrayElementVarHandle(int... shape)
Creates a strided var handle that can be used to access a memory segment as multi-dimensional array. This array has a notional sequence layout featuring `shape.length` nested sequence layouts. The element layout of the innermost sequence layout in the notional sequence layout is this value layout. The resulting var handle is obtained as if calling the `MemoryLayout.varHandle(PathElement...)`PREVIEW method on the notional layout, with a layout path containing exactly `shape.length + 1` open sequence layout path elementsPREVIEW.

For instance, the following method call:

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

Is equivalent to the following code:

     SequenceLayout notionalLayout = MemoryLayout.sequenceLayout(
                                             MemoryLayout.sequenceLayout(10, MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
     VarHandle arrayHandle = notionalLayout.varHandle(PathElement.sequenceElement(),
                                                      PathElement.sequenceElement(),
                                                      PathElement.sequenceElement());

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 < notionalLayout.elementCount()`
- `0 <= y < 10`
- `0 <= z < 20`

Consider the following access expressions:

    int value1 = (int) arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176
    int value2 = (int) 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 `byteAlignment() > byteSize()`.
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 with the same characteristics as this layout, but with the given name.

Specified by:
  `withName` in interface `MemoryLayoutPREVIEW`
Parameters:
  `name` - the layout name.
Returns:
  a memory layout with the same characteristics as this layout, but with the given name
See Also:
  - `MemoryLayout.name()`PREVIEW

### withByteAlignment

ValueLayoutPREVIEW withByteAlignment(long byteAlignment)
Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).

Specified by:
  `withByteAlignment` in interface `MemoryLayoutPREVIEW`
Parameters:
  `byteAlignment` - the layout alignment constraint, expressed in bytes.
Returns:
  a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes)
Throws:
  `IllegalArgumentException` - if `byteAlignment` is not a power of two.