v0.4.0

Generics

A generic declaration takes type parameters: names in angle brackets that stand for types the user supplies. A generic function is written once and works for every type it is used with; a generic type is a pattern from which Pair<int32>, Pair<char8[..]> and so on are stamped out. Functions, methods, structures and variants can be generic.

Nothing is decided at run time. The compiler produces a separate instantiation for each distinct set of type arguments a program uses, as if each had been written by hand, with its own layout, its own code and its own symbol.

Generic functions

func Name<T, U, …>(parameters) -> Result { … }
func Name<T: Bound + Bound, U>(parameters) -> Result { … }
func Larger<T>(first: T, second: T) -> T {
    if first > second {
        return first;
    }
    return second;
}

Each type parameter is in scope in the parameter list, the result type and the body. A parameter may carry bounds, interfaces its type arguments must implement.

Type arguments

A call supplies the type arguments explicitly, after the name, or leaves the compiler to infer them from the arguments:

PrintLine("{}", Larger(3, 9));                  // T = int, inferred
PrintLine("{}", Larger(2.5, 1.5));              // T = float64
PrintLine("{}", Larger<uint8>(200, 7) + 50);    // T = uint8: prints 250

An explicit type argument also types the arguments: with <uint8>, the literals 200 and 7 become uint8 values, and so does the result, so the sum is a uint8 too — adding 100 instead would stop the program with Panic: integer overflow in '+'. Without it, unsuffixed literals make T an int.

Inference reads type arguments out of the argument types, wherever the parameter mentions them:

Parameter writtenArgumentInfers
value: T7i32T = int32
value: &T, &var Ta local counter: CounterT = Counter — borrowed
p: *T@counterT = Counter
values: T[..]an int32[3] array or a sliceT = int32
pair: Pair<T>a Pair<int64>T = int64
f: func(T) -> Ua function func(int32) -> boolT = int32, U = bool
value: T?an int32?T = int32
value: &(T?)a local found: int32?T = int32 — borrowed

A type parameter that no argument determines must be written: Size<int16>(). A sum of type parameters is not inferred either, since nothing says which member is T: Side(v) with func Side<T, U>(value: T | U) is refused, and Side<int32, bool>(v) is the call. Inference does not look at the result type or the destination, so let f: int32? = Make(); with func Make<T>() -> T? is function 'Make' requires 1 type argument, but 0 were provided. Inference never relaxes a parameter's other requirements: a &var T parameter still needs a writable argument.

Two arguments that disagree about one parameter are refused — Larger(3, 2.5):

error: argument 1 to 'Larger' has type 'int', but parameter 'first' requires 'T'

Checking a generic body

A generic body is checked in two stages.

At the declaration, everything that does not depend on what T is: names, statements, and every use of T that needs a capability. A method call on a T, or passing a T where an interface is required, needs a bound that provides it:

error: no matching overload for 'PrintLine' with argument types (char8[..], T)

At each instantiation, the operators applied to T. first > second in Larger is checked once T is known, so Larger(3, 9) and Larger('a', 'z') compile and Larger("abc", "abd") does not. The error points into the generic body, and a note names the call responsible:

error: operator '>' is not defined for slice type 'char8[..]'
  note: a slice is a view, so comparing the views would compare addresses rather than elements
  note: in 'Larger' instantiated with T = char8[..] by the call at …

Without a bound, a body may store a T, move it, pass it on, return it, take its size with sizeof(T), and apply operators that every instantiation will have to support. Copying a named T is checked for each instantiation as well, and instantiating such a body with a move-only type reports cannot copy 'Owner', which owns resources at the copy; a T: Copyable bound moves that check to the call, and T: Cloneable allows value.Clone(). See Copy and move.

Generic functions as values

A function value has one concrete signature, and a generic function has one per instantiation, so a generic name used as a value rather than called takes its type arguments from the function type it is assigned, returned or passed as: let double: func(int64) -> int64 = Double; is the int64 instance of func Double<T>(value: T) -> T, and inside a generic function the instance follows that function's own type arguments. With nothing to say what it is instantiated with, the name is an error:

error: generic function 'Double' has no type arguments here

A generic function may also take a function value whose type mentions its parameters, as Apply<T>(value: T, f: func(T) -> T) does, and deduces its type parameters from it.

Overloading

Generic functions overload like any other, by arity and by parameter types. When a generic and a non-generic overload accept a call equally well, the non-generic one wins:

func Describe<T>(value: T) -> char8[..] {
    return "generic";
}

func Describe(value: int32) -> char8[..] {
    return "int32";
}

Describe(5i32) is int32; Describe(true) is generic. See Overloading for the full ranking.

Native forms

Optionals, sums and the unit are built into the language and have no declaring package, so extend cannot give them methods and they implement no interface. Generic functions whose parameters spell the form out take their place, and work for every payload type at once; inference descends through T?, A | B and &(T?):

func ValueOr<T>(value: T?, fallback: T) -> T {
    return value ?? fallback;
}

func Both<T, U>(first: T?, second: U?) -> (T, U)? {
    return (first?, second?);
}

A sum of type parameters collapses when its members coincide: T | U with T = U = int32 is plain int32. A match over a T | U therefore ends in a _ arm, which stays valid for every instantiation, where a second typed arm would be unreachable for the collapsed one.

A typed arm may also name a concrete type, as in n: int32 =>, and each instantiation checks it against its own members. For T = int32, U = bool the arm selects the int32; an instantiation whose sum has no int32, such as T = int64, U = bool, is refused with type 'int32' is not a member or subset of sum 'bool8 | int64'.

Kinds of generic declaration

DeclarationGeneric?Page
functionyesthis page
structure, variantyesGeneric types
methodyes — its own parameters, as well as its type'sGeneric methods
enumno — enum 'Level' cannot declare type parametersEnums
union, type aliasno
interfaceyes — usable only as a boundInterfaces

See also