Skip to content

Generics

A generic function or type works with many types. The names in <...> stand for types. They are called type parameters. The declaration can use them for its parameters, fields and return type. Each use fills them in with real types.

A generic function lists its type parameters in <...>, before its ordinary parameters. You don’t usually write the types at the call. Nomi works them out from the arguments:

fn pair<T, U>(first: T, second: U) -> (T, U)
    (first, second)
end

fn main()
    dbg pair("age", 30)
end

In this call, T is String and U is Int. Another call can use different types.

Structs, enums, interfaces, distinct types (type Tagged<T> (String, T)), subtypes and type aliases can have type parameters.

struct Box<T>
    value: T
end

fn main()
    box = Box{value: 42}
    dbg box.value
end

Every Box holds one value, of type T. Box<Int> and Box<String> are different types, made from the same definition.

A type parameter can have a default, which a type that leaves the argument out takes: std’s Route<P = Unit> makes a plain Route a Route<Unit>, a route with no path parameters.

A function can store, return and pass along a value of type T. It can’t do anything else with it, such as compare two of them, because T could be any type. A where clause says what T must support. This is called a bound.

Read where T: Comparable as “T must be a type whose values can be compared.” Comparable is an interface. The next chapter explains interfaces.

fn first_two_sorted<T>(xs: List<T>) -> List<T> where T: Comparable
    xs
    |> Iter.sort()
    |> Iter.take(2)
    |> Iter.to_list()
end

fn main()
    first_two_sorted([3, 1, 4, 1, 5, 9, 2, 6])
    |> dbg

    first_two_sorted(["banana", "apple", "cherry"])
    |> dbg
end

Int and String both implement Comparable, so both calls are allowed.

Without the where clause, Iter.sort is an error: `xs` holds values of `T`, and `first_two_sorted` does not require Comparable of `T`.

To require more than one interface, join them with and:

fn largest_label<T>(xs: List<T>) -> String where T: Comparable and Display

T must implement every interface listed.

A type parameter is for a type that comes back, in the result or another parameter, as T does in first_two_sorted. A parameter used only through one interface takes the interface as its type instead, as Interfaces & Dispatch shows.

Types and derives can have a where clause too:

struct Span<T> where T: Comparable
    start: T
    stop:  T
end

derive Display for Box<T> where T: Display

A bound on a type declaration carries into every impl of that type, so an impl for Span<T> can compare start and stop without its own where. A bound on a derive or a function applies only to that one declaration.

Fine print

  • Debug and == need no bound, since every type has them.
  • Bounds join with and only. There is no or.
  • Each type parameter must appear in a parameter’s type, the result, or a bound on one that does. Otherwise no call could decide it: type parameter `U` is not used in the signature of `f`, so no call can determine it.
  • A call whose type doesn’t meet a bound is an error at the call, and the help offers a derive or an impl block to write.
  • A generic function used as a value needs a function type from its position: f = ident alone is an error that asks for an annotation.
  • A generic function that calls itself at a type built from its own parameter, such as Box<T> from T, is an error, since it would need endless instances.

Spec: Bounds and dispatch in generic code, Generics, Function values.

Every example that uses Generics

Next: Interfaces & Dispatch, which also covers bounds that name an interface’s own type parameters.