Struct.md

Struct API (Struct, StructLayout, StructBuilder)

The Struct API allows you to model custom C structures in memory, compile their layouts, and mutate fields dynamically by names instead of tracking byte offsets.

Classes

• StructBuilder: Declare named fields (int32, float64, pointer, etc.) and padding.
• StructLayout: Houses the final java.lang.foreign.StructLayout and compiled VarHandle accessors.
• Struct: A live instance of a struct located in a memory segment.
• @Struct + Structs: Annotation-driven POJO mapping (field layouts follow the global type mappers).

Field type layouts (@Struct)

Java field type	Native layout
byte / short / int / long / float / double	matching primitive
boolean	1-byte C _Bool (0/1)
char	1-byte C char
CChar / WChar	via registered mappers
MemorySegment	address / pointer
nested @Struct	inline nested layout
primitive arrays	fixed-length sequence of the element layout

See NativeTypes.md for details.

Usage Example

import io.github.undeffineddev.ffmkit.memory.MemoryScope;
import io.github.undeffineddev.ffmkit.struct.Struct;
import io.github.undeffineddev.ffmkit.struct.StructLayout;

// 1. Define the Struct Layout
StructLayout pointLayout = Struct.builder()
        .int32("x")
        .int32("y")
        .float64("z")
        .build();

try (MemoryScope scope = MemoryScope.open()) {
    // 2. Allocate the struct in a memory scope
    Struct point = pointLayout.allocate(scope);
    
    // 3. Set values by name
    point.setInt("x", 10);
    point.setInt("y", 20);
    point.setDouble("z", 5.5);
    
    // 4. Retrieve values by name
    System.out.println(point.getInt("x"));   // 10
    System.out.println(point.getDouble("z")); // 5.5
}