Home / Docs / Language guide / Kinds and types
Constraints on generics
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.
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 == bForms
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.
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:
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:
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:
-- fails with U2026
module shop
pub same[T](a: T, b: T) -> Bool = a == bA 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:
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:
-- 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:
-- fails with U2027
module shop
pub same[T: Hashable](a: T, b: T) -> Bool = a == bKinds take no constraint. Kind[T: Eq] is a syntax error:
-- fails with U0101
module shop
pub kind Box[T: Eq]
value: TNo arithmetic on T. +, -, *, / and mod stay undefined on a type parameter, constrained or not. Convert with to_int() and compute on Int:
-- fails with U2001
module shop
pub add[T: Integer](a: T, b: T) -> T = a + bFurther rules:
- Labels do not count.
secret IntsatisfiesInteger. - Operators keep their meaning.
==is structural equality and<the built-in order, on every type that satisfies the constraint. - Information flow. A comparison on values of
Tcarries the labels of its operands, the symbolic label ofTincluded, a stand-in for whatever label the caller's type carries. Branching on it raises the program counter, the label of the conditions that decide whether a line runs (see Branches and failures: implicit flows). - Verification. In a generic body, the verifier knows nothing about
<on aT: Ordbut its name, so no law such as transitivity (a < bandb < cgivea < c) is assumed. - The prelude. In edition
0.2,min,max,contains,sumandsortare generic over these constraints.
Diagnostics
- U0101: a constraint on a kind's type parameter, or one in edition
0.1. - U2001: arithmetic on values of a type parameter.
- U2025: a type argument that does not satisfy its parameter's constraint.
- U2026: an operator that the parameter's constraint does not allow.
- U2027: an unknown constraint name.
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:
-- edition 0.1
-- fails with U0101
module shop
pub same[T: Eq](a: T, b: T) -> Bool = a == bNormative source
- spec/20 §1: the constraints and rules 1 to 6; spec/20 §2: syntax; spec/20 §3: static semantics; spec/20 §4: information flow; spec/20 §5: verification; spec/20 §6: the prelude.
- spec/03 §2 rule 4: type parameters in edition
0.1.