GroupLayout (Java SE 21 & JDK 21)
Description: declaration: module: java.base, package: java.lang.foreign, interface: GroupLayout
Keywords: java.lang.foreign.GroupLayout interface

Module java.base
Package java.lang.foreign

# Interface GroupLayout

All Superinterfaces:
  `MemoryLayoutPREVIEW`

All Known Subinterfaces:
  `StructLayoutPREVIEW`, `UnionLayoutPREVIEW`

public sealed interface GroupLayout extends MemoryLayoutPREVIEW permits StructLayoutPREVIEW, UnionLayoutPREVIEW
`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 is an aggregation of multiple, heterogeneous 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 a struct layoutPREVIEW; conversely, if all member layouts are laid out at the same starting offset, the resulting group layout is a union layoutPREVIEW.

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

- ## Nested Class Summary

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

  `MemoryLayout.PathElementPREVIEW`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<MemoryLayoutPREVIEW>`
  `memberLayouts()`
  Returns the member layouts of this group layout.
  `GroupLayoutPREVIEW`
  `withByteAlignment(long byteAlignment)`
  Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
  `GroupLayoutPREVIEW`
  `withName(String name)`
  Returns a memory layout with the same characteristics as this layout, but with the given name.
  `GroupLayoutPREVIEW`
  `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`

- ## Method Details

  - ### memberLayouts

    List<MemoryLayoutPREVIEW> memberLayouts()
    Returns the member layouts of this group layout.
    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 of this group layout

  - ### withName

    GroupLayoutPREVIEW 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

  - ### withoutName

    GroupLayoutPREVIEW 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

  - ### withByteAlignment

    GroupLayoutPREVIEW 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.
      `IllegalArgumentException` - if `byteAlignment` is less than `M`, where `M` is the maximum alignment constraint in any of the member layouts associated with this group layout.