Golang Generics: Type Parameters, Constraints and Examples

A generic function

Type parameters go in square brackets before the regular parameters. Each one has a constraint that says which types are allowed.

package main

import (
	"fmt"
	"strconv"
)

func Map[T, U any](items []T, f func(T) U) []U {
	out := make([]U, 0, len(items))
	for _, it := range items {
		out = append(out, f(it))
	}
	return out
}

func main() {
	nums := []int{1, 2, 3}

	squares := Map(nums, func(n int) int { return n * n })
	fmt.Println(squares)

	labels := Map(nums, strconv.Itoa)
	fmt.Printf("%q\n", labels)

	lengths := Map([]string{"go", "rust", "c"}, func(s string) int { return len(s) })
	fmt.Println(lengths)
}

T and U are inferred from the arguments, so you rarely write Map[int, string](...). Inference works from function arguments; it cannot infer a type that appears only in the result. For func Zero[T any]() T, you must write Zero[int]().

Before Go 1.18 this function had to be written once per type, or take []interface{} and lose type safety.

Constraints

A constraint is an interface. It limits which types can be used and, in return, tells the compiler which operations are allowed on values of that type.

package main

import (
	"cmp"
	"fmt"
)

func Index[T comparable](s []T, target T) int {
	for i, v := range s {
		if v == target { // needs comparable
			return i
		}
	}
	return -1
}

func Largest[T cmp.Ordered](s []T) T {
	m := s[0]
	for _, v := range s[1:] {
		if v > m { // needs cmp.Ordered
			m = v
		}
	}
	return m
}

func main() {
	fmt.Println(Index([]string{"a", "b", "c"}, "c"))
	fmt.Println(Largest([]float64{2.5, 9.1, 4.0}))
	fmt.Println(Largest([]string{"pear", "apple", "zucchini"}))
}

With any instead of comparable, v == target fails to compile: invalid operation: v == target (incomparable types in type set). The constraint is what makes the operator legal.

These two helpers already exist: slices.Index and slices.Max. The standard slices, maps and cmp packages cover most everyday generic needs, so check them before writing your own.

Custom constraints with type unions and ~

A constraint can list types with |. The operators allowed are the ones every listed type supports.

package main

import "fmt"

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

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

type Cents int64

func main() {
	fmt.Println(Sum([]int{1, 2, 3}))
	fmt.Println(Sum([]float64{0.5, 0.25}))
	fmt.Println(Sum([]Cents{199, 250})) // works because of ~int64
}

The tilde matters. ~int64 means "any type whose underlying type is int64", so the named type Cents is accepted. Written as plain int64, Sum([]Cents{...}) fails with Cents does not satisfy Number (possibly missing ~ for int64 in Number).

Interfaces containing type unions can only be used as constraints, never as ordinary variable types. var n Number does not compile.

The golang.org/x/exp/constraints package has ready-made Integer, Float and Signed constraints. It is outside the standard library, so the runner here cannot import it; cmp.Ordered is the standard one.

Generic types

Structs, slices, maps and other types can have type parameters too. Methods on a generic type use the receiver's parameters.

package main

import (
	"errors"
	"fmt"
)

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, error) {
	var zero T
	if len(s.items) == 0 {
		return zero, errors.New("empty stack")
	}
	v := s.items[len(s.items)-1]
	s.items = s.items[:len(s.items)-1]
	return v, nil
}

func (s *Stack[T]) Len() int { return len(s.items) }

type Pair[K comparable, V any] struct {
	Key K
	Val V
}

func main() {
	var s Stack[string]
	s.Push("a")
	s.Push("b")
	v, _ := s.Pop()
	fmt.Println(v, s.Len())

	_, err := (&Stack[int]{}).Pop()
	fmt.Println(err)

	p := Pair[string, int]{Key: "age", Val: 31}
	fmt.Printf("%+v\n", p)
}

Two details in this example come up constantly:

• The zero value of T. var zero T is how you return "nothing" from generic code. There is no T{} or nil that works for every type.
• Instantiation. A generic type must be instantiated before use: Stack[string], not Stack. Inside its own methods, the receiver is written Stack[T].

Go 1.24 added generic type aliases: type Set[T comparable] = map[T]struct{} now compiles.

Limits you will run into

• No type parameters on methods. func (s *Stack[T]) Map[U any](...) is not allowed. Use a top-level function.
• No specialization. You cannot write a separate implementation for T = string. A type switch on any(v) inside the function is the workaround, and usually a hint that generics are the wrong tool.
• No operator constraints by name. You cannot say "any type with a + method"; you list the types in a union.
• Field access through a constraint does not work. Even if every type in a union has a field ID, v.ID is not allowed. Use a method in the constraint instead.

When not to use generics

Generics fit container types (stacks, sets, caches, trees) and algorithms over slices and maps that do the same thing for every element type. They do not fit everywhere.

• One concrete type. If the function is only ever called with []User, a generic version adds reading cost and nothing else.
• Behavior that differs by type. That is what interfaces are for. A function taking an io.Writer is simpler than one taking [T io.Writer], and works the same.
• Replacing interface parameters. func Print[T fmt.Stringer](v T) is no better than func Print(v fmt.Stringer).

The Go team's own guideline: write the code for a specific type first, and reach for type parameters when you notice yourself writing the same code a second time with only the types changed.

Common mistakes

• Using any where comparable or cmp.Ordered is needed. The compiler rejects == or < on an any type parameter.
• Forgetting ~. User-defined types like type ID int fail a plain int constraint.
• Returning nil for a type parameter. Not allowed unless the constraint limits T to pointer-like types. Return a zero value.
• Writing a generic helper that already exists. Check slices, maps and cmp first.