Generics, briefly and honestly

Go got generics in 1.18, after a decade of arguing about whether it should. The result is deliberately less powerful than TypeScript's, and the community consensus is that you should use them rarely. This chapter covers enough to read other people's code and to recognise the handful of cases where writing your own is right.

The syntax

Type parameters go in square brackets before the arguments.

func First[T any](items []T) (T, bool) {
    var zero T
    if len(items) == 0 {
        return zero, false
    }
    return items[0], true
}

n, ok := First([]int{1, 2, 3})        // T inferred as int
s, ok := First([]string{"a", "b"})    // T inferred as string

T is a type parameter and any is its constraint, meaning "any type at all". Inference usually works, so you rarely write First[int](...).

Note var zero T. You cannot return nil for an arbitrary T, because Tmight be int. The zero value is the only thing you can produce without knowing the type, and this little declaration appears in almost every generic function.

Constraints are interfaces

A constraint says what you may do with a value of that type.

// Will not compile: you cannot add two values of an arbitrary type.
func Sum[T any](items []T) T {
    var total T
    for _, v := range items {
        // invalid operation: operator + not defined on total
        total += v
    }
    return total
}

You must constrain T to types that support +. Constraints are written as interfaces containing type sets:

type Number interface {
    ~int | ~int64 | ~float64
}

func Sum[T Number](items []T) T {
    var total T
    for _, v := range items {
        total += v
    }
    return total
}

Sum([]int{1, 2, 3})          // 6
Sum([]float64{1.5, 2.5})     // 4.0

The ~ means "any type whose underlying type is this", so a named type still qualifies:

type Celsius float64
Sum([]Celsius{20.5, 21.0})   // works because of ~float64

Without the tilde, Celsius would be rejected, which is almost never what you want. Write ~ unless you have a reason not to.

The constraints you will actually use

Two come from the standard library and cover most cases.

import "cmp"

func Max[T cmp.Ordered](a, b T) T {    // anything with < and >
    if a > b { return a }
    return b
}

cmp.Ordered is every type supporting <, which is the numeric types andstring. comparable is built in and means "supports ==", which is what map keys require:

func Keys[K comparable, V any](m map[K]V) []K {
    out := make([]K, 0, len(m))
    for k := range m {
        out = append(out, k)
    }
    return out
}

Generic types

Types can take parameters too.

type Stack[T any] struct {
    items []T
}

func (s *Stack[T]) Push(v T) {
    s.items = append(s.items, v)
}

func (s *Stack[T]) Pop() (T, bool) {
    var zero T
    if len(s.items) == 0 {
        return zero, false
    }
    v := s.items[len(s.items)-1]
    s.items = s.items[:len(s.items)-1]
    return v, true
}

s := &Stack[string]{}
s.Push("a")
v, ok := s.Pop()

func (s *Stack[T]) Map[U any](f func(T) U) *Stack[U] {   // illegal

func MapStack[T, U any](s *Stack[T], f func(T) U) *Stack[U] { ... }

What the standard library gives you

Since 1.21 there are generic helpers, and you should use these rather than write your own.

import ("slices"; "maps")

slices.Contains(s, v)        // bool
slices.Index(s, v)           // int, -1 if absent
slices.Sort(s)               // for cmp.Ordered
slices.SortFunc(s, cmp)      // for anything
slices.Reverse(s)
slices.Max(s); slices.Min(s)
slices.Clone(s)
slices.Equal(a, b)

maps.Keys(m)                 // an iterator, not a slice
maps.Values(m)
maps.Clone(m)

keys := slices.Collect(maps.Keys(m))

When to write your own, and when not to

The honest guidance, which matches what the Go team says: *write the concrete version first*. Write the generic version when you have written the same function for the third type and the bodies are identical.

Good reasons:

• A container: a stack, a set, a typed cache.
• A function over any slice or map where the body does not care about the type.
• Removing an any and the type assertions that came with it.

Bad reasons:

• "It might be reused later." It usually is not.
• To avoid writing a four-line loop. The loop is clearer.
• To model a hierarchy. Go has interfaces for that, and they are better at it.

Interfaces are still usually the answer

The mistake to avoid is reaching for a type parameter where an interface does the job better.

// Generic: the caller must have a concrete type, and the body can only do
// what the constraint allows.
func PrintAll[T fmt.Stringer](items []T) {
    for _, v := range items {
        fmt.Println(v.String())
    }
}

// Interface: accepts a mixed slice of different types. Usually better.
func PrintAll(items []fmt.Stringer) {
    for _, v := range items {
        fmt.Println(v.String())
    }
}

The rule of thumb: if the function's behaviour depends only on methods, use an interface. Use a type parameter when you need the actual type back out, which is what interfaces cannot do.

package main

import (
    "fmt"
    "sync"
    "time"
)

type cached[V any] struct {
    value   V
    expires time.Time
}

// Cache is generic over both key and value. K must be comparable because
// it is a map key; V can be anything at all.
type Cache[K comparable, V any] struct {
    mu    sync.RWMutex
    items map[K]cached[V]
    ttl   time.Duration
}

func NewCache[K comparable, V any](ttl time.Duration) *Cache[K, V] {
    return &Cache[K, V]{items: map[K]cached[V]{}, ttl: ttl}
}

func (c *Cache[K, V]) Set(k K, v V) {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.items[k] = cached[V]{value: v, expires: time.Now().Add(c.ttl)}
}

func (c *Cache[K, V]) Get(k K) (V, bool) {
    c.mu.RLock()
    e, ok := c.items[k]
    c.mu.RUnlock()

    var zero V
    if !ok || time.Now().After(e.expires) {
        return zero, false
    }
    return e.value, true
}

// GetOrLoad is where the design earns itself: the loader returns a V and
// the caller receives a V, with no any and no type assertion anywhere.
func (c *Cache[K, V]) GetOrLoad(k K,
    load func(K) (V, error)) (V, error) {
    if v, ok := c.Get(k); ok {
        return v, nil
    }
    v, err := load(k)
    if err != nil {
        var zero V
        return zero, err
    }
    c.Set(k, v)
    return v, nil
}

type User struct {
    ID   int
    Name string
}

func main() {
    users := NewCache[int, User](time.Minute)
    counts := NewCache[string, int](time.Minute)

    calls := 0
    loadUser := func(id int) (User, error) {
        calls++
        return User{ID: id, Name: fmt.Sprintf("user-%d", id)}, nil
    }

    u, _ := users.GetOrLoad(1, loadUser)
    fmt.Println(u.Name, "loader calls:", calls)   // user-1  1

    u, _ = users.GetOrLoad(1, loadUser)
    fmt.Println(u.Name, "loader calls:", calls)   // user-1  1 (cached)

    // u is a User, not an any. This compiles, and would not if the cache
    // stored any.
    fmt.Println("id plus one:", u.ID+1)

    counts.Set("hits", 42)
    n, _ := counts.Get("hits")
    fmt.Println("count doubled:", n*2)            // 84, n is an int
}

Assignment

Commit your work with the message Generics - Assignment One, exactly as written, so the leaderboard can score it.