Often when writing code you want to create similar classes or functions that differ only in the type that they operate on. The classic example of this is collection classes. You want to be able to create an Array that can hold objects of a particular type without creating an IntArray, StringArray, etc. This is where generics step in.

Generic Classes

A generic class is a class that can have parameters, much like a method has parameters. The parameters for a generic class are types. Parameters are introduced to a class using square brackets.

Take the following example of a non-generic class:

  1. class Foo
  2.   var _c: U32
  4.   new create(c: U32) =>
  5.     _c = c
  7.   fun get(): U32 => _c
  9.   fun ref set(c: U32) => _c = c
  11. actor Main
  12.   new create(env:Env) =>
  13.     let a = Foo(42)
  14.     env.out.print(a.get().string())
  15.     a.set(21)
  16.     env.out.print(a.get().string())

This class only works for the type U32, a 32 bit unsigned integer. We can make this work over other types by making the type a parameter to the class. For this example it looks like:

  1. class Foo[A: Any val]
  2.   var _c: A
  4.   new create(c: A) =>
  5.     _c = c
  7.   fun get(): A => _c
  9.   fun ref set(c: A) => _c = c
  11. actor Main
  12.   new create(env:Env) =>
  13.     let a = Foo[U32](42)
  14.     env.out.print(a.get().string())
  15.     a.set(21)
  17.     env.out.print(a.get().string())
  18.     let b = Foo[F32](1.5)
  19.     env.out.print(b.get().string())
  21.     let c = Foo[String]("Hello")
  22.     env.out.print(c.get().string())

The first thing to note here is that the Foo class now takes a type parameter in square brackets, [A: Any val]. That syntax for the type parameter is:

  1. Name: Constraint ReferenceCapability

In this case, the name is A, the constraint is Any and the reference capability is val. Any is used to mean that the type can be any type - it is not constrained. The remainder of the class definition replaces U32 with the type name A.

The user of the class must provide a type when referencing the class name. This is done when creating it:

  1. let a = Foo[U32](42)
  2. let b = Foo[F32](1.5)
  3. let c = Foo[String]("Hello")

That tells the compiler what specific class to create, replacing A with the type provided. For example, a Foo[String] usage becomes equivalent to:

  1. class FooString
  2.   var _c: String val
  4.   new create(c: String val) =>
  5.     _c = c
  7.   fun get(): String val => _c
  9.   fun ref set(c: String val) => _c = c

Generic Methods

Methods can be generic too. They are defined in the same way as normal methods but have type parameters inside square brackets after the method name:

  1. primitive Foo
  2.   fun bar[A: Stringable val](a: A): String =>
  3.     a.string()
  5. actor Main
  6.   new create(env:Env) =>
  7.     let a = Foo.bar[U32](10)
  8.     env.out.print(a.string())
  10.     let b = Foo.bar[String]("Hello")
  11.     env.out.print(b.string())

This example shows a constraint other than Any. The Stringable type is any type with a string() method to convert to a String.

These examples show the basic idea behind generics and how to use them. Real world usage gets quite a bit more complex and the following sections will dive deeper into how to use them.