ValueLayout (Java SE 14 & JDK 14)
Description: declaration: module: jdk.incubator.foreign, package: jdk.incubator.foreign, class: ValueLayout
Keywords: jdk.incubator.foreign.ValueLayout class

Module jdk.incubator.foreign
Package jdk.incubator.foreign

# Class ValueLayout

java.lang.Object
jdk.incubator.foreign.ValueLayout

All Implemented Interfaces:
  `Constable`, `MemoryLayout`

    public final class ValueLayout
    extends Object
    implements MemoryLayout

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 and a byte order (see `ByteOrder`).

This is a value-based class; use of identity-sensitive operations (including reference equality (`==`), identity hash code, or synchronization) on instances of `ValueLayout` may have unpredictable results and should be avoided. The `equals` method should be used for comparisons.

Implementation Requirements:
  This class is immutable and thread-safe.

- ## Nested Class Summary

  ## Nested classes/interfaces declared in interface jdk.incubator.foreign.MemoryLayout

  `MemoryLayout.PathElement`

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `long` | `bitAlignment()` | Returns the alignment constraint associated with this layout, expressed in bits.
  `long` | `bitSize()` | Computes the layout size, in bits.
  `Optional<DynamicConstantDesc<ValueLayout>>` | `describeConstable()` | Returns an `Optional` containing the nominal descriptor for this layout, if one can be constructed, or an empty `Optional` if one cannot be constructed.
  `boolean` | `hasSize()` | Does this layout have a specified size?
  `Optional<String>` | `name()` | Return the name (if any) associated with this layout.
  `ByteOrder` | `order()` | Returns the value's byte order.
  `ValueLayout` | `withBitAlignment​(long alignmentBits)` | Creates a new layout which features the desired alignment constraint.
  `ValueLayout` | `withName​(String name)` | Creates a new layout which features the desired layout name.
  `ValueLayout` | `withOrder​(ByteOrder order)` | Returns a new value layout with given byte order.

  ### Methods declared in class java.lang.Object

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

  ### Methods declared in interface jdk.incubator.foreign.MemoryLayout

  `bitAlignment, bitSize, byteAlignment, byteSize, equals, hashCode, hasSize, map, name, offset, select, toString, varHandle`

- ## Method Details

  - ### order

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

  - ### withOrder

    public ValueLayout withOrder​(ByteOrder order)
    Returns a new value layout with given byte order.
    Parameters:
      `order` - the desired byte order.
    Returns:
      a new value layout with given byte order.

  - ### describeConstable

    public Optional<DynamicConstantDesc<ValueLayout>> describeConstable()
    Description copied from interface: `MemoryLayout`
    Returns an `Optional` containing the nominal descriptor for this layout, if one can be constructed, or an empty `Optional` if one cannot be constructed.
    Specified by:
      `describeConstable` in interface `Constable`
    Specified by:
      `describeConstable` in interface `MemoryLayout`
    Returns:
      An `Optional` containing the resulting nominal descriptor, or an empty `Optional` if one cannot be constructed.

  - ### withName

    public ValueLayout withName​(String name)
    Creates a new layout which features the desired layout name.
    Specified by:
      `withName` in interface `MemoryLayout`
    Parameters:
      `name` - the layout name.
    Returns:
      a new layout which is the same as this layout, except for the name associated to it.
    See Also:
      `MemoryLayout.name()`

  - ### withBitAlignment

    public ValueLayout withBitAlignment​(long alignmentBits)
    Creates a new layout which features the desired alignment constraint.
    Specified by:
      `withBitAlignment` in interface `MemoryLayout`
    Parameters:
      `alignmentBits` - the layout alignment constraint, expressed in bits.
    Returns:
      a new layout which is the same as this layout, except for the alignment constraint associated to it.

  - ### name

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

  - ### 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)`), then this method returns the natural alignment constraint (in bits) associated with this layout.
    Specified by:
      `bitAlignment` in interface `MemoryLayout`
    Returns:
      the layout alignment constraint, in bits.

  - ### hasSize

    public boolean hasSize()
    Description copied from interface: `MemoryLayout`
    Does this layout have a specified size? A layout does not have a specified size if it is (or contains) a sequence layout whose size is unspecified (see `SequenceLayout.elementCount()`). Value layouts (see `ValueLayout`) and padding layouts (see `MemoryLayout.ofPaddingBits(long)`) always have a specified size, therefore this method always returns `true` in these cases.
    Specified by:
      `hasSize` in interface `MemoryLayout`
    Returns:
      `true`, if this layout has a specified size.

  - ### bitSize

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