Layout Control
The layout attribute controls struct memory layout: field alignment, padding, size, and explicit field offsets. All layout attributes require an unsafe block.
Layout Modes
layout(default)
The default layout. Fields are placed sequentially with natural alignment (up to 8-byte). Equivalent to omitting layout(...).
unsafe { layout(default) type Foo { int32 a; int32 b; }}// Same as: type Foo { int32 a; int32 b; }layout(packed)
No alignment padding between fields. Struct alignment is 1. Fields are placed back-to-back.
unsafe { layout(packed) type Packed { int8 a; int32 b; int64 c; }}// sizeof(Packed) == 13 (1+4+8, no padding)// alignof(Packed) == 1layout(explicit)
All non-static fields must have layout(offset: x) or the compiler emits an error. Allows overlapping fields (union-like patterns).
unsafe { layout(explicit) type Union { layout(offset: 0) int number; layout(offset: 0) float numberAsFloat; }}// Both fields at offset 0 — overlapping like a C unionlayout(auto)
Sequential layout like default, but honors layout(offset: x) on individual fields. Fields without explicit offsets are placed sequentially.
unsafe { layout(auto) type Custom { layout(offset: 0) int32 a; layout(offset: 16) int32 b; }}// a@0, b@16, sizeof == 24Auto-Promotion
A type with any field annotated with layout(offset: x) automatically promotes to layout(auto) if it doesn’t already have an explicit layout mode:
unsafe { type AutoPromoted { layout(offset: 0) int32 a; layout(offset: 8) int32 b; }}// Implicitly layout(auto) — sizeof == 16Size and Alignment Overrides
Use size: and align: to override the struct’s total size and alignment. These can be combined with any layout mode.
unsafe { layout(size: 64) type Big { int x; } // sizeof(Big) == 64
layout(size: 64, align: 64) type CacheLine { int x; int y; } // sizeof == 64, alignof == 64
layout(explicit, size: 8) type IntFloat { layout(offset: 0) int value; }}Field-Level layout(offset: x)
Set a field’s byte offset explicitly. Requires unsafe.
unsafe { layout(explicit) type Mapped { layout(offset: 0) int32 a; layout(offset: 32) int32 b; }}// offsetof(Mapped, b) == 32Compile-Time Introspection
sizeof(Type)
Returns the total size of a type in bytes.
return sizeof(int32); // 4return sizeof(Point); // 16 (two ints with alignment)alignof(Type)
Returns the alignment of a type in bytes.
return alignof(int32); // 4return alignof(int64); // 8return alignof(int8); // 1
// Struct alignmenttype Foo { int x; }return alignof(Foo); // 8
unsafe { layout(packed) type P { int8 a; int32 b; } layout(align: 64) type A { int x; }}return alignof(P); // 1return alignof(A); // 64offsetof(Type, field)
Returns the byte offset of a field within a struct.
type Point { int32 x; int32 y; }return offsetof(Point, x); // 0return offsetof(Point, y); // 4
type Mixed { int8 a; int32 b; int64 c; }return offsetof(Mixed, c); // 8 (after alignment padding)
unsafe { layout(packed) type Packed { int8 a; int32 b; int64 c; }}return offsetof(Packed, b); // 1 (no padding)Safety
All layout attributes require an unsafe block:
// ERROR: 'layout' attribute requires an unsafe blocklayout(packed) type Foo { int x; }
// OKunsafe { layout(packed) type Foo { int x; }}layout(explicit) requires all non-static fields to have layout(offset: x):
unsafe { // ERROR: field 'x' must have layout(offset: x) layout(explicit) type Bad { int x; }}Minimum Size
All types have a minimum size of 8 bytes, even packed types with small fields. This ensures stack alignment safety.
unsafe { layout(packed) type Small { int8 a; int8 b; int8 c; }}// sizeof(Small) == 8 (minimum), not 3