Data Types

The types you define yourself: structs with methods, enums with payloads, unions, pattern matching with match, and generics.

Structs

A struct groups fields under a single name. Top-level structs are declared via const Name = struct { … };. Field names are field: Type; instances are built with TypeName { field: value, … }: literals always name their type.

const Vec3   = struct { x: f32, y: f32, z: f32 };
const Pixel  = struct { r: u8, g: u8, b: u8 };
const Player = struct { hp: u32, level: u8, alive: bool };

fn main() {
    const v: Vec3 = Vec3 { x: 0.0, y: 100.0, z: 50.0 };
    var px:  Pixel = Pixel { r: 10, g: 20, b: 30 };
    px.r = 100;

    // Nested literals work the same way.
    const Outer = struct { inner: Pixel, c: u8 };
    const x: Outer = Outer {
        inner: Pixel { r: 1, g: 2, b: 3 },
        c: 4,
    };
}

Methods

Functions declared inside a struct body are methods. The first parameter is conventionally self; the parameter mode chooses borrow semantics.

const Counter = struct {
    value: u32,
    sink:  *mut u32,

    fn drop(self: mut Counter) {
        var p: *mut u32 = self.sink;
        p.* = p.* + 1;
    }
};

fn observe() u32 {
    var hits: u32 = 0;
    var c: Counter = Counter { value: 5, sink: &hits };
    return c.value;
    // c.drop() fires automatically here, see Drop, below.
}

A method can also be invoked by-name on the type: Counter.drop(&c) calls it explicitly while c is still in scope (and the automatic drop will still fire at scope exit, calling drop manually is currently a footgun).


Enums

Enums describe a closed set of named variants. The simplest form is payload-less, each variant is a u8 discriminant.

const Color = enum { Red, Green, Blue };

fn classifyColor(c: Color) u8 {
    match (c) {
        Color.Red   { return 100; }
        Color.Green { return 200; }
        Color.Blue  { return 50; }
        _           { return 0; }
    }
    return 99;
}

Discriminant values are assigned in declaration order starting at 0. You can also pin them explicitly:

const Phase = enum { Idle = 0, Running = 5, Stopping = 9 };

fn phaseAsByte(p: Phase) u8 {
    return p as u8;
}

Variants with Payloads (Tagged Unions)

Variants can carry positional fields. Pattern matching destructures them by name.

const Op = enum {
    Nop,
    LdRR(u8, u8),
    Imm(u8),
    Wide(u16),
};

fn srcReg(op: Op) u8 {
    match (op) {
        Op.Nop          { return 0xFF; }
        Op.LdRR(d, s)   { return s; }
        Op.Imm(v)       { return v; }
        Op.Wide(w)      { return 0xEE; }
        _               { return 0xCC; }
    }
    return 0;
}

Payload-carrying enums are how Option(T) and Result(T, E) are built, see Generics.


Unions

A union is untagged, every field shares the same storage. Use it for type punning (read float bits as u32, etc.) and for matching C-side union { … } types at FFI boundaries.

const FloatBits = union {
    i: u32,
    f: f32,
};

fn floatBits(x: f32) u32 {
    var b: FloatBits = FloatBits { f: x };
    return b.i;
}

Unions size to their largest field; alignment is the max of all fields’. Unlike enums, there is no discriminant, the compiler trusts the program to know which field is live.


Pattern Matching

The match expression dispatches on a scrutinee. Patterns include integer literals, enum variants (with or without payloads), and _ as a wildcard.

fn dispatch(x: u8) u8 {
    match (x) {
        0           { return 10; }
        1 | 2 | 3   { return 20; }       // `|`-joined patterns
        4..=9       { return 30; }       // inclusive range
        _           { return 255; }
    }
    return 99;
}

Range bounds are full 64-bit and may be negative (-100..=-1); an inverted range is a compile error. When the scrutinee’s enum type is unambiguous the variant may be written bare: Some(x) instead of Option(i32).Some(x).

A match can also be used as an expression, each arm produces a value, and the result is the value of the matched arm.

fn unwrap(o: Option(i32), fallback: i32) i32 {
    return match (o) {
        Option(i32).Some(x) { x }
        Option(i32).None    { fallback }
    };
}

Arms that bind payload fields introduce those names into the arm’s scope.

A match expression must be exhaustive: cover every variant of the enum or add a _ arm; anything else is a compile error (a fallthrough would leave the result undefined). Statement-position matches keep switch-style fallthrough.


Generics

A generic function takes one or more type parameters declared T: type and returns a type. Calling it with concrete type arguments at compile time produces a concrete type; each distinct argument list yields a fresh struct (or enum).

fn Box(T: type) type {
    return struct {
        value: T,
    };
}

fn Pair(A: type, B: type) type {
    return struct {
        first:  A,
        second: B,
    };
}

fn main() {
    var b: Box(i32)      = Box(i32) { value: 17 };
    var p: Pair(i32, u8) = Pair(i32, u8) { first: 7, second: 35 };
}

A type alias const Name = Generic(arg); registers Name as a synonym, subsequent uses resolve to the same instantiated struct.

const BoxI32 = Box(i32);
var b: BoxI32 = BoxI32 { value: 17 };

Type arguments are not limited to names: structural types work too, in aliases and in calls with T: type parameters.

const Bytes = Box([]u8);
const Ptrs  = Pair(*const u8, [4]u16);

fn sizeOfIt(T: type) u64 { return @sizeOf(T); }
const SLICE_SIZE = sizeOfIt([]u8);    // 16: {ptr, len}

Generic Methods

Methods on generic types are cloned per instantiation. Each instantiation gets its own LLVM symbol with substituted parameter and return types.

fn Holder(T: type) type {
    return struct {
        value: T,
        fn unwrap(self: move Self) T {
            return self.value;
        }
    };
}

Self inside a struct body refers to the enclosing struct type, for a generic, that’s the specific instantiation in play.

Generic Enums

The same mechanism produces tagged unions parameterized by type. The standard library’s Option(T) is built this way:

pub fn Option(T: type) type {
    return enum {
        Some(T),
        None,
    };
}

Construct variants by qualifying with the instantiated type: Option(i32).Some(42), Option(i32).None.

Result(T, E) ships the same way (import("std").result). An instantiation can be bound to a module-scope alias and used like any named type:

const { Result } = import("std").result;

const ParseResult = Result(u64, str);

fn parse(s: []u8) ParseResult {
    if (s.len == 0) {
        return ParseResult.Err("empty input");
    }
    return ParseResult.Ok(s.len);
}