Skip to content

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) == 1

layout(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 union

layout(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 == 24

Auto-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 == 16

Size 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) == 32

Compile-Time Introspection

sizeof(Type)

Returns the total size of a type in bytes.

return sizeof(int32); // 4
return sizeof(Point); // 16 (two ints with alignment)

alignof(Type)

Returns the alignment of a type in bytes.

return alignof(int32); // 4
return alignof(int64); // 8
return alignof(int8); // 1
// Struct alignment
type 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); // 1
return alignof(A); // 64

offsetof(Type, field)

Returns the byte offset of a field within a struct.

type Point { int32 x; int32 y; }
return offsetof(Point, x); // 0
return 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 block
layout(packed) type Foo { int x; }
// OK
unsafe {
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