Home / Docs / Language guide / Kinds and types

Constraints on generics

Release v0.4.0Edition 0.2 and laterU0101U2001U2025U2026U2027

What it does

From edition 0.2, a type parameter of a function, a placeholder such as T that stands for any type the caller uses, may carry one built-in constraint: Eq, Ord or Integer. A constraint allows operators on values of the parameter, with their built-in meaning, and restricts the types that may instantiate it. There are no user traits and no implementations (ways, in other languages, to declare your own constraints and say which types meet them): a type satisfies a constraint by what it is.

Learn more: Generic kinds and constraints.

una
module shop

pub largest[T: Ord](prices: List[T], floor: T) -> T = prices.fold(initial: floor, step: fn(best, price) -> max(best, b: price))

pub total[T: Integer](prices: List[T]) -> Int = prices.map(each: fn(price) -> price.to_int()).sum()

pub same[T: Eq](a: T, b: T) -> Bool = a == b

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
signature       = lower_ident [ constrained_params ] "(" [ params ] ")" "->" type ;
constrained_params = "[" constrained_param { "," constrained_param } "]" ;
constrained_param  = upper_ident [ ":" upper_ident ] ;

The constraints:

Constraint Allows on values of T Satisfied by
Eq ==, !=, and interpolation every type whose values hold no functions
Ord what Eq allows, and <, <=, >, >= Int, I8 to U64, Text, and sum kinds whose variants have no payload
Integer what Ord allows, and x.to_int() Int, I8 to U64

Ord includes Eq, and Integer includes Ord. A type parameter takes at most one constraint, and only a function's type parameters take one.

Examples

A sum without payloads satisfies Ord, and so does Text:

una
module shop

pub kind Size = Small | Large

pub smaller[T: Ord](a: T, b: T) -> T = if a < b then a else b

pub pick(a: Size, b: Size) -> Size = smaller(a, b: b)

pub texts(a: Text, b: Text) -> Text = smaller(a, b: b)

A private function has the least constraint its body needs inferred. A public function writes it:

una
module shop

same_private[T](a: T, b: T) -> Bool = a == b

pub use_it(a: Int, b: Int) -> Bool = same_private(a, b: b)

An operator on a parameter needs a constraint that allows it, equality included:

una
-- fails with U2026
module shop

pub same[T](a: T, b: T) -> Bool = a == b

A generic function cannot use + on T: the built-in constraints do not include arithmetic. Pass the operation as a function value instead. This states only how to combine two values; it does not promise associativity or any other algebraic law:

una
module shop

pub fold_with[T](items: List[T], initial: T, step: fn(T, T) -> T) -> T = items.fold(initial: initial, step: step)

pub total(items: List[Int]) -> Int = fold_with(items, initial: 0, step: fn(acc, item) -> acc + item)

The runtime case generic_fold_run checks that this explicit operation sums [1, 2, 3] to 6.

Edge cases

Type arguments must satisfy the constraint. A sum whose variants carry payloads does not satisfy Ord:

una
-- fails with U2025
module shop

pub smaller[T: Ord](a: T, b: T) -> T = if a < b then a else b

pub kind Parcel = Tube(length: Int) | Envelope

pub pick(a: Parcel, b: Parcel) -> Parcel = smaller(a, b: b)

Only three constraints exist:

una
-- fails with U2027
module shop

pub same[T: Hashable](a: T, b: T) -> Bool = a == b

Kinds take no constraint. Kind[T: Eq] is a syntax error:

una
-- fails with U0101
module shop

pub kind Box[T: Eq]
  value: T

No arithmetic on T. +, -, *, / and mod stay undefined on a type parameter, constrained or not. Convert with to_int() and compute on Int:

una
-- fails with U2001
module shop

pub add[T: Integer](a: T, b: T) -> T = a + b

Further rules:

Diagnostics

Edition

Constraints exist from edition 0.2 on. In edition 0.1, type parameters are unconstrained, equality on them keeps an inferred bound, and a written constraint is a syntax error:

una
-- edition 0.1
-- fails with U0101
module shop

pub same[T: Eq](a: T, b: T) -> Bool = a == b

Normative source