Generics

A type, a locus or a fn can take type parameters in angle brackets, so one declaration serves several types. Each use names its types (Envelope), and the…

A type, a locus or a fn can take type parameters in angle brackets, so one declaration serves several types. Each use names its types (Envelope<Order>), and the compiler builds a separate copy of the declaration for each, so a generic costs nothing at run time.

Hale has no generic container types such as Vec<T> or HashMap<K, V>. A list or a map is a @form locus, or a bounded[T; N] inside a record (Collections).

Generic Records

Section titled “Generic Records”

An API that wraps every response in the same envelope declares the envelope once:

type Order {
id: String;
total: Decimal<2>;
}
type Customer {
id: String;
name: String;
}
// What every endpoint answers with: the payload, and the request id
// a client quotes when it reports a problem.
type Envelope<T> {
data: T;
request_id: String = "";
}
fn order_reply(o: Order, req: String) -> Envelope<Order> {
return Envelope { data: o, request_id: req };
}
fn main() {
let r = order_reply(Order { id: "o-1", total: 19.99d }, "req-81");
println(r.data.id, " ", r.data.total, " (", r.request_id, ")"); // o-1 19.99 (req-81)
let c: Envelope<Customer> = Envelope { data: Customer { id: "c-1", name: "Ada" } };
println(c.data.name); // Ada
}

In Envelope<Order>, data is an Order, so r.data.total is checked as a Decimal<2>; in Envelope<Customer> it is a Customer. Putting a Customer into an Envelope<Order> is a type error at the value.

A parameter can be the element of a list the record holds inline. A paged API reply carries up to a page of whatever the endpoint lists:

type Order {
id: String;
total: Decimal<2>;
}
type Page<T> {
items: bounded[T; 50];
next_cursor: String = "";
}
fn main() {
let p: Page<Order> = Page { items: [Order { id: "o-1", total: 19.99d }], next_cursor: "c-2" };
push(p.items, Order { id: "o-2", total: 5.25d }) or raise;
for o in p.items {
println(o.id, " ", o.total); // o-1 19.99, then o-2 5.25
}
let ids: Page<Int> = Page { items: [7, 8, 9] };
println(count(p.items), " ", count(ids.items), " ", p.next_cursor); // 2 3 c-2
}

Page<Order> holds a bounded[Order; 50] and Page<Int> a bounded[Int; 50]; a locus’s params take bounded[T; N] the same way.

An alias can name an instantiation you use often: type OrderReply = Envelope<Order>;, then let a: OrderReply = Envelope { data: o };. The alias itself cannot take parameters (type Reply<T> = Envelope<T>; is refused).

Generic Loci

Section titled “Generic Loci”

A locus takes type parameters the same way, and its params and methods use them:

type Quote {
symbol: String;
px: Decimal<2>;
}
type Reading {
sensor: String;
celsius: Float;
}
// Keeps the most recent value of one kind, and how many it has seen.
locus Latest<T> {
params {
current: T;
seen: Int = 0;
}
fn put(v: T) {
self.current = v;
self.seen = self.seen + 1;
}
}
fn main() {
let q: Latest<Quote> = Latest { current: Quote { symbol: "ACME", px: 10.00d } };
q.put(Quote { symbol: "ACME", px: 10.25d });
println(q.current.px, " after ", q.seen, " update"); // 10.25 after 1 update
let r: Latest<Reading> = Latest { current: Reading { sensor: "attic", celsius: 21.5 } };
println(r.current.sensor, " ", r.current.celsius); // attic 21.5
}

q.put takes a Quote and r.put a Reading. A method inside a locus cannot declare type parameters of its own (fn put<U>(…) is refused at its name): make the locus the template, as here, or write a free generic fn.

Generic Functions

Section titled “Generic Functions”

A generic fn takes each type argument from the argument in the position that names it:

fn clamp<T: Numeric>(x: T, lo: T, hi: T) -> T {
if x < lo { return lo; }
if x > hi { return hi; }
return x;
}
type Envelope<T> {
data: T;
request_id: String = "";
}
fn reply<T>(data: T, req: String) -> Envelope<T> {
return Envelope { data: data, request_id: req };
}
fn main() {
println(clamp(150, 0, 100), " ", clamp(-0.5, 0.0, 1.0)); // 100 0
let r = reply("pong", "req-9"); // an Envelope<String>
println(r.data, " ", r.request_id); // pong req-9
}

See Functions for everything else about functions.

Rules You Will Hit

Section titled “Rules You Will Hit”

The full rules, including every place that supplies type arguments and which types may be arguments, are in spec/types.md § Generics.

Next: Introduction to Loci.