Learn DodoStep 9 of 10

Generics and reusable behavior

Write type-parameterized functions and structs, constrain them with interfaces, and dispatch through dyn references.

On this page

A generic function or type works with more than one concrete type. Write type parameters in angle brackets, then use those names wherever a type is expected. The compiler specializes generic code for the concrete types your program uses and checks each specialization.

A generic function

package main

fn identity<T>(value: T) -> T {
    value
}

fn main() {
    core.assert_eq(identity(42i32), 42i32)
    core.assert_eq(identity::<u8>(7), 7u8)
    let answer: u32 = identity(42)
    core.assert_eq(answer, 42u32)
}

T is a type parameter. identity(42i32) infers T = i32 from the argument. identity::<u8>(7) provides it explicitly. The expected result type in let answer: u32 = ... also guides inference. Generic calls canonically use ::<...>; generic declarations and type names use <...> without ::.

Inference uses the current expression and its expected type. It does not infer a function’s public signature, or look ahead to later uses of a variable. If a constructor has no argument that determines T, provide explicit arguments or an expected result type. Conflicting type information is an error.

Generic structs and associated functions

package main

struct Slot<T> {
    value: T

    fn new(value: T) -> Self {
        Slot<T> { value }
    }

    fn get(&self) -> &T {
        &self.value
    }
}

fn main() {
    inferred := Slot { value: 42i32 }
    explicit := Slot.new::<u8>(7)
    core.assert_eq(*inferred.get(), 42i32)
    core.assert_eq(*explicit.get(), 7u8)
}

The literal infers its type from the field initializer. Slot<u8> is a concrete type in a type annotation; an explicit associated function call puts its type arguments on the function: Slot.new::<u8>(...). Self inside a generic struct means that struct with its current arguments.

Enums can also declare type parameters, for example enum Choice<T> { Empty, Value(T) }. Different specializations are distinct types: Slot<u8> cannot be assigned to Slot<u32> by an implicit conversion.

Operations are checked for each concrete type

Generic code does not erase types or bypass ownership checks. A generic function that applies + can only be used with types for which that operation exists. An operation that copies T only works when the concrete T is copyable. Likewise, a collection’s element restrictions still apply to every specialization.

For example, this is a useful numeric helper:

package main

fn add<T>(left: T, right: T) -> T {
    left + right
}

fn main() {
    core.assert_eq(add(20u32, 22u32), 42u32)
    core.assert_eq(add(1.25f64, 0.75f64), 2.0f64)
}

It does not make addition available for arbitrary structs. Operators stay compiler-defined; there is no operator overloading, overload resolution, or specialization.

Reusable behavior through public methods

A generic function may call methods on its type parameter. The concrete object supplies that method, and compilation checks the call:

package main

struct Doubler {
    pub fn apply(&self, value: i32) -> i32 {
        value * 2
    }
}

fn transform<F>(operation: &F, value: i32) -> i32 {
    operation.apply(value)
}

fn main() {
    doubler := Doubler {}
    core.assert_eq(transform(&doubler, 21), 42i32)
}

Such an unconstrained parameter accepts any type, and a type without apply is only reported inside transform’s specialized body. A private struct may expose public methods for this purpose without publishing its type name. Across package boundaries the called method must be public. A method object can carry state that outlives the call; for a one-off callback, a closure borrowing local variables is often shorter.

Interfaces

An interface names a set of method signatures. Declaring one documents what a generic function needs and lets the compiler check arguments where they are passed:

package main

interface Shape {
    fn area(&self) -> u32
    fn scale(&mut self, factor: u32)
}

struct Square {
    side: u32

    pub fn area(&self) -> u32 {
        self.side * self.side
    }

    pub fn scale(&mut self, factor: u32) {
        self.side *= factor
    }
}

fn doubled_area<S: Shape>(shape: &mut S) -> u32 {
    shape.scale(2)
    shape.area()
}

fn main() {
    square := Square { side: 3 }
    core.assert_eq(doubled_area(&mut square), 36u32)
}

S: Shape is a bound: every type used for S must implement Shape. Several bounds join with +, as in <T: io.Reader + io.Writer>. Generic structs take bounds the same way: struct Holder<S: Shape> { shape: S }.

Implementation is structural. A type implements an interface when it has, for every method the interface declares, a method with the same name, receiver, and parameter and return types, with Self replaced by that type. Methods used from another package must be pub. There is no separate implementation block, and no runtime cost: bounded calls are specialized exactly like unbounded ones.

When a type does not fit, the error points at the call and explains the difference, instead of failing somewhere inside the generic body. Here a Circle has an area method returning u64 and no scale method:

error: `Circle` does not implement interface `Shape`
 ::: main.dodo:4:5
    |
  4 |     fn area(&self) -> u32
    |     --------------------- required by this interface method
 ::: main.dodo:5:5
    |
  5 |     fn scale(&mut self, factor: u32)
    |     -------------------------------- required by this interface method
 ::: main.dodo:11:5
    |
 11 |     pub fn area(&self) -> u64 {
    |     ------------------------- this method has a different signature
 ::: main.dodo:16:17
    |
 16 | fn doubled_area<S: Shape>(shape: &mut S) -> u32 {
    |                 -------- `doubled_area` requires `S: Shape`
 --> main.dodo:23:14
    |
 23 |     total := doubled_area(&mut circle)
    |              ^^^^^^^^^^^^^^^^^^^^^^^^^ `Circle` is used as `S` here
  = note: method `area` has signature `fn area(&self) -> u64`, but `Shape` requires `fn area(&self) -> u32`
  = note: missing method `fn scale(&mut self, factor: u32)`

A struct may also state what it implements: struct Square: Shape { ... }. The compiler then checks the claim at the declaration, which documents the type and catches a drifted signature before anyone uses it. For a generic struct, each specialization is checked.

An interface can include others. interface Sensor: Named { ... } requires Named’s methods as well as its own, and two interfaces that require the same method name must agree on its signature.

Interface methods may declare unsafe and borrowed-return contracts. A method fn name(&self) -> &str borrows from self, as for any method. An implementation may return a borrow with fewer sources than the interface allows, never more. Interface methods cannot declare stores(...) or requires_plain(...), have type parameters, or be named drop.

Dynamic dispatch with dyn

Generics produce one copy of the code per type. When the type is only known at run time, or one collection holds different types, use a dyn reference instead. &dyn Shape and &mut dyn Shape refer to some value implementing Shape, together with a table of its methods:

package main

interface Sensor {
    fn read(&mut self) -> i32
}

struct Thermometer {
    celsius: i32

    pub fn read(&mut self) -> i32 {
        self.celsius
    }
}

struct Counter {
    count: i32

    pub fn read(&mut self) -> i32 {
        self.count += 1
        self.count
    }
}

// The station does not know, or care, which sensor it polls.
struct Station {
    sensor: &mut dyn Sensor

    fn poll(&mut self) -> i32 {
        self.sensor.read()
    }
}

fn total(sensors: &mut [&mut dyn Sensor]) -> i32 {
    sum := 0i32
    for sensor in sensors {
        sum += sensor.read()
    }
    sum
}

fn main() {
    thermometer := Thermometer { celsius: 21 }
    counter := Counter { count: 0 }
    {
        sensors: [2]&mut dyn Sensor = [&mut thermometer, &mut counter]
        core.assert_eq(total(&mut sensors), 22i32)
    }
    station := Station { sensor: &mut counter }
    core.assert_eq(station.poll(), 2i32)
}

A reference to a concrete type converts to a dyn reference wherever one is expected: arguments, annotated bindings, fields, array elements, and returns. x as &dyn Shape converts explicitly. &mut dyn I also converts to &dyn I, and &dyn I converts to &dyn P when P is I’s first parent interface (or its first parent, and so on), because P’s methods begin I’s method table.

A dyn value has no fixed size, so it only exists behind a reference; dyn Shape alone, an array of dyn Shape, or a raw dyn pointer is an error. The reference is two pointers wide, holding the value’s address and its method table. Method tables are constant data built at compile time, one per type and interface; nothing is allocated. Borrow checking is unchanged: a dyn reference keeps every loan of the reference it was made from.

An interface can be used with dyn when each of its methods takes &self or &mut self and mentions Self nowhere else. Other interfaces, for example with a by-value self or a fn new() -> Self constructor, still work as bounds.

A dyn type also implements its own interface, so bounded generic code accepts it. doubled_area(shape) with shape: &mut dyn Shape specializes S as dyn Shape once and dispatches through the table, which keeps code size small when one generic function serves many types.

Interfaces in the standard library

The standard library declares interfaces for its byte streams and devices: io.Reader, io.Writer, and io.ReadWriter in std/io, and hal.OutputPin, hal.InputPin, hal.Delay, hal.I2c, hal.Spi, hal.PwmOutput, hal.PwmInput, hal.AnalogInput, hal.Can, hal.I2sOutput, hal.I2sInput, their polling and target forms, the DMA protocols, and hal.Registers in std/embedded/hal, with the serial port protocols serial.Port and serial.PollPort in std/embedded/hal/serial. Its helpers are bounded by them, so io.write_all(&mut stream, bytes) reports a stream without the right write method at the call.

Formatters, allocators, hash and equality policies, and callbacks still use unconstrained parameters with documented method signatures. Read each API’s required signature carefully; a similar method name with a different receiver or return type does not satisfy it.

Generic ownership contracts

Returning borrowed data still requires a valid source. from(value) on a generic function refers to the concrete argument’s dependencies: a borrow-free specialization contributes none, while a borrow-carrying specialization retains its sources. A type parameter never permits returning a reference to destroyed local storage.

Allocated container methods may use the narrow requires_plain(T, ...) contract to restrict mutation to borrow-free, Result-free payloads. stores(...) tracks sources deposited into typed storage. These are checked storage effects, not interface bounds; their syntax and rules are in container element safety.

All used generic bodies must be available in the loaded source packages. There are no separately compiled generic interfaces. Recursive expansion is bounded; exceeding the compiler’s limit produces a diagnostic instead of unbounded compilation. For concrete language restrictions and limits, see compiler support.

Search every guide, reference page, and API declaration.