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

# Interface GroupLayout

All Superinterfaces:
  `MemoryLayout`

All Known Subinterfaces:
  `StructLayout, UnionLayout`

public sealed interface GroupLayout extends MemoryLayout permits StructLayout, UnionLayout
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 layout; conversely, if all member layouts are laid out at the same starting offset, the resulting group layout is a union layout.

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

- ## Nested Class Summary

  ### Nested classes/interfaces declared in interface MemoryLayout

  `MemoryLayout.PathElement`
  Modifier and Type
  Interface
  Description
  `static interface`
  `MemoryLayout.PathElement`
  An element in a layout path.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `List<MemoryLayout>`
  `memberLayouts()`
  Returns the member layouts of this group layout.
  `GroupLayout`
  `withByteAlignment(long byteAlignment)`
  Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
  `GroupLayout`
  `withName(String name)`
  Returns a memory layout with the same characteristics as this layout, but with the given name.
  `GroupLayout`
  `withoutName()`
  Returns a memory layout with the same characteristics as this layout, but with no name.

  ### Methods declared in interface MemoryLayout

  `arrayElementVarHandle, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, scale, scaleHandle, select, sliceHandle, toString, varHandle`
  Modifier and Type
  Method
  Description
  `VarHandle`
  `arrayElementVarHandle(MemoryLayout.PathElement... elements)`
  Creates a var handle that accesses adjacent elements in a memory segment at offsets selected by the given layout path, where the accessed elements have this layout, and where the initial layout in the path is this layout.
  `long`
  `byteAlignment()`
  Returns the alignment constraint associated with this layout, expressed in bytes.
  `long`
  `byteOffset(MemoryLayout.PathElement... elements)`
  Computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
  `MethodHandle`
  `byteOffsetHandle(MemoryLayout.PathElement... elements)`
  Creates a method handle that computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.
  `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.
  `Optional<String>`
  `name()`
  Returns the name (if any) associated with this layout.
  `long`
  `scale(long offset, long index)`
  Returns `offset + (byteSize() * index)`.
  `MethodHandle`
  `scaleHandle()`
  Returns a method handle that can be used to invoke `MemoryLayout.scale(long, long)` on this layout.
  `MemoryLayout`
  `select(MemoryLayout.PathElement... elements)`
  Returns the layout selected from the provided path, where the initial layout in the path is this layout.
  `MethodHandle`
  `sliceHandle(MemoryLayout.PathElement... elements)`
  Creates a method handle which, given a memory segment, returns a slice corresponding to the layout selected by the given layout path, where the initial layout in the path is this layout.
  `String`
  `toString()`
  Returns the string representation of this layout.
  `VarHandle`
  `varHandle(MemoryLayout.PathElement... elements)`
  Creates a var handle that accesses a memory segment at the offset selected by the given layout path, where the initial layout in the path is this layout.

- ## Method Details

  - ### memberLayouts

    List<MemoryLayout> 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...)` and `MemoryLayout.unionLayout(MemoryLayout...)`).
    Returns:
      the member layouts of this group layout

  - ### withName

    GroupLayout withName(String name)
    Returns a memory layout with the same characteristics as this layout, but with the given name.
    Specified by:
      `withName` in interface `MemoryLayout`
    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()`

  - ### withoutName

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

  - ### withByteAlignment

    GroupLayout 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 `MemoryLayout`
    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