Package Summary Overview Summary

Module java.base
Package java.lang.foreign

# Class GroupLayout

java.lang.Object
java.lang.foreign.GroupLayout

All Implemented Interfaces:
  `MemoryLayoutPREVIEW`

public final class GroupLayout extends Object implements MemoryLayoutPREVIEW
`GroupLayout` is a preview API of the Java platform.
Programs can only use `GroupLayout` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A compound layout that aggregates multiple member layouts . There are two ways in which member layouts can be combined: if member layouts are laid out one after the other, the resulting group layout is said to be a struct (see `MemoryLayout.structLayout(MemoryLayout...)`PREVIEW); conversely, if all member layouts are laid out at the same starting offset, the resulting group layout is said to be a union (see `MemoryLayout.unionLayout(MemoryLayout...)`PREVIEW).

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

- ## Nested Class Summary

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

  `MemoryLayout.PathElementPREVIEW`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `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.
  `boolean`
  `isStruct()`
  Returns `true`, if this group layout is a struct layout.
  `boolean`
  `isUnion()`
  Returns `true`, if this group layout is a union layout.
  `List<MemoryLayoutPREVIEW>`
  `memberLayouts()`
  Returns the member layouts associated with this group.
  `final Optional<String>`
  `name()`
  Returns the name (if any) associated with this layout.
  `String`
  `toString()`
  Returns the string representation of this layout.
  `GroupLayoutPREVIEW`
  `withBitAlignment (long alignmentBits)`
  Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).
  `GroupLayoutPREVIEW`
  `withName (String name)`
  Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.

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

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

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

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

- ## Method Details

  - ### memberLayouts

    public List<MemoryLayoutPREVIEW> memberLayouts()
    Returns the member layouts associated with this group.
    API Note:
      the order in which member layouts are returned is the same order in which member layouts have been passed to one of the group layout factory methods (see `MemoryLayout.structLayout(MemoryLayout...)`PREVIEW, `MemoryLayout.unionLayout(MemoryLayout...)`PREVIEW).
    Returns:
      the member layouts associated with this group.

  - ### toString

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

  - ### isStruct

    public boolean isStruct()
    Returns `true`, if this group layout is a struct layout.
    Returns:
      `true`, if this group layout is a struct layout

  - ### isUnion

    public boolean isUnion()
    Returns `true`, if this group layout is a union layout.
    Returns:
      `true`, if this group layout is a union 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 `ValueLayout.order()`PREVIEW)
    - 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 `isStruct()`, `isUnion()`) and if their member layouts (see `memberLayouts()`) 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`

  - ### 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 GroupLayoutPREVIEW 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 GroupLayoutPREVIEW 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