Generics

What it is and why it exists

A generic is a function or type with one or more type parameters. A concrete type replaces each parameter when you call a generic function or instantiate a generic type. The compiler still checks operations, arguments, and results at compile time, so callers don’t have to assert a value from any back to the desired type.

Generics address code that repeats across types while keeping the same structure. Slice transformations, set lookups, and stacks care about relationships between element types, but shouldn’t need separate implementations for int, string, and every domain type. Type parameters put that relationship in the signature: Map[T, U any]([]T, func(T) U) []U says that the converter accepts an element from the input and determines the result element type.

Interfaces and generics solve different problems. An interface value hides a dynamic concrete type and is useful when callers operate on different implementations through a method set; a generic preserves the concrete static type within each instantiation and suits algorithms and containers. If an implementation only calls a method such as Read or String, an ordinary interface parameter is often more direct. If the same type appears in several parameter or result positions, a type parameter usually expresses the contract better.

Go added generics in 1.18. You’ll meet them in the standard library’s slices, maps, and cmp packages, in reusable data structures, and in helpers that would otherwise require reflection. They aren’t a way to remove all duplication: separate implementations are clearer when types require different semantics.

How it works

Type parameters preserve relationships

A type parameter appears in square brackets after a declaration’s name. T, K, and V are type names used within that declaration, and every name has a constraint. Adjacent parameters with the same constraint can share it, as in [T, U any].

Ordinary parameters and results of a generic function can use these names. Fields of a generic type can use them too, while methods redeclare the corresponding receiver type parameters in the receiver, as in func (s *Stack[T]) Push(value T). This T corresponds to the parameter of Stack; it isn’t a new type parameter introduced by the method.

Instantiation performs two checks. The compiler first confirms that every type argument satisfies its constraint, then creates the function or type instance for those arguments. The resulting Stack[string] and Stack[int] are different named types and aren’t assignable to one another.

Constraints determine available operations

A generic constraint is an interface. It describes the type set allowed to replace a type parameter and determines what the function body may do with that parameter. With an any constraint, code can rely only on behavior common to every type, such as assignment, passing, and returning values.

The predeclared comparable constraint accepts types that can be map keys and permits == and !=. It promises no ordering, so a < b doesn’t compile. For ordered operations, use the standard library’s cmp.Ordered or declare a constraint limited to the types your domain needs.

A constraint interface can embed methods, type terms, or both. fmt.Stringer requires a String() string method; ~int | ~int64 is a union accepting types whose underlying type is int or int64. Separate elements in a constraint intersect, so a type must meet both sides when you write a method and a type term.

Type sets describe candidates

A type set is the set of all non-interface types represented by an interface. A method element keeps types implementing that method, a union combines candidate type terms, and separate embedded elements intersect. Generic code may use only operations supported with the same meaning by every type in the set.

The type term int means only the predeclared type int. ~int also includes a named type such as type Score int, because its underlying type is int. The tilde isn’t approximate runtime matching; it is constraint syntax checked statically by the compiler.

An interface containing type terms can be used only as a constraint, not as an ordinary variable type. You can write func Max[T Ordered](...), but you can’t declare var value Ordered to store any ordered value. If you need an interface value, use a basic interface containing only methods, or use any and validate the dynamic type at a boundary.

Type inference removes call-site noise

Type inference lets the compiler derive omitted type arguments from function arguments and constraint relationships. In Map(ids, strconv.Itoa), ids provides T, and the signature of strconv.Itoa provides U. Once inference succeeds, the caller doesn’t need to write Map[int, string].

Inference works for function calls and other specified contexts; it doesn’t infer a generic type’s arguments from composite-literal fields. You must write the string in Stack[string]{}. A function call can also lack enough information, such as when a type parameter occurs only in the result. In that case, supply a type argument explicitly or redesign the signature so an input carries the relationship.

Untyped constants participate in inference and representability checks. Mixing constant kinds can produce a wider default type than expected, or leave no type that satisfies both the constraint and arguments. API examples and tests should include variables, named types, and untyped constants instead of testing integer literals alone.

Generic types still follow zero-value rules

Generic structs, defined slice types, and other named types follow ordinary Go rules after instantiation. A field’s zero value comes from the actual type argument: var item T is 0 for int and nil for a pointer. When that zero value has domain meaning, returning only T can’t report whether an operation succeeded.

Whether a generic container’s own zero value is usable depends on its fields and methods. A stack backed by a slice can append immediately, so its zero value works well; a set backed by a map must initialize before its first write. A constructor, lazy initialization, or a documented zero-value contract can all work, but the API should choose one clear behavior.

Examples

Preserve input-output relationships with Map

The first example converts invoice numbers to labels. T and U can differ, and the call relies entirely on inference. The return type is still []string, with no assertion required.

Map only allocates a result, reads T, calls the converter, and writes U, so any is sufficient. Adding a numeric union wouldn’t enable another operation; it would only reject strings and structs. This signature is useful because it preserves a relationship, not because it loosens runtime types.

Accept named types with a type set

This maximum function needs >, so it declares a type set that actually supports ordering. Score is a distinct named type whose underlying type is int; ~int lets it satisfy the constraint. An extra Boolean distinguishes empty input from a valid zero value.

package main

import "fmt"

type Ordered interface {
	~int | ~int64 | ~float64 | ~string
}

type Score int

func Max[T Ordered](values []T) (T, bool) {
	if len(values) == 0 {
		var zero T
		return zero, false
	}

	best := values[0]
	for _, value := range values[1:] {
		if value > best {
			best = value
		}
	}
	return best, true
}

func main() {
	best, ok := Max([]Score{72, 91, 84})
	fmt.Println(best, ok)

	empty, ok := Max([]Score(nil))
	fmt.Println(empty, ok)
}

91 true
0 false

If ~int becomes int, Score no longer satisfies the constraint. The function doesn’t need to know whether the argument is specifically Score; the constraint has already proved that > is valid for every candidate. The returned best retains the Score type.

Make a generic container’s zero value useful

The underlying representation of Stack[T] is a slice. A nil slice can be appended to, so callers don’t need a constructor. Pop returns (T, bool) to distinguish an empty stack from a stored zero value.

package main

import "fmt"

type Stack[T any] []T

func (s *Stack[T]) Push(value T) {
	*s = append(*s, value)
}

func (s *Stack[T]) Pop() (T, bool) {
	if len(*s) == 0 {
		var zero T
		return zero, false
	}

	last := len(*s) - 1
	value := (*s)[last]
	*s = (*s)[:last]
	return value, true
}

func main() {
	var stages Stack[string]
	stages.Push("review")
	stages.Push("publish")

	for range 3 {
		stage, ok := stages.Pop()
		fmt.Printf("%q %t\n", stage, ok)
	}
}

"publish" true
"review" true
"" false

The receiver is *Stack[T] because both Push and Pop replace the slice descriptor. The element type still comes from the string instantiation. If storage changes to a map, writes through the zero value stop being safe, so the API contract must change too.

Pitfalls

Treating comparable as ordered

Slices, maps, and functions don’t satisfy comparable; most scalars, pointers, channels, interfaces, and arrays or structs with comparable fields do. Comparability still doesn’t imply order. Booleans and structs are immediate counterexamples.

Fix: use the standard library’s cmp.Ordered, or declare a constraint containing only the predeclared and named types you need. When ordering is a domain rule, accept a comparison function instead of assuming < expresses that rule.

Performing extra operations under any

Changing the code to a type switch usually works around the static relationship and misses named types. It also turns every added type branch into runtime maintenance.

Fix: derive the constraint from operations in the body. Embed a method interface when you need a method, declare suitable type terms when you need an operator, and keep any when the implementation only moves values around.

Forgetting ~ and rejecting domain types

Forcing callers to convert a UserID to int discards useful static information and can mix identifiers from different domains. Constraints describe type identity and underlying types, not general conversion rules.

Fix: use ~int if the algorithm is valid for every named type with that underlying type. If the API should accept only the exact predeclared type, retain int and document and test that boundary.

Adding type parameters to a method

Adding every future parameter to the receiver in advance makes each instantiation carry unrelated types. It also promotes a relationship used by one operation into the identity of the whole type.

Fix: write a standalone function such as MapStack[T, U any](Stack[T], func(T) U) Stack[U] when the operation introduces U. Put a parameter on the generic type only when it determines fields or the long-term contract of its methods.

Using a zero value to mean failure

Generated code often introduces var zero T to make a return compile but never decides how the caller should interpret it. The problem isn’t unique to generics, but a type parameter means the zero value’s shape isn’t known while writing the function.

Fix: return (T, bool) or (T, error) and make the caller handle absence explicitly. Return a lone T only when the domain contract makes its zero value the one correct result.

Further reading

• Go language specification: type parameter declarations
• Go tutorial: getting started with generics
• Go blog: an introduction to generics
• Standard library documentation for cmp.Ordered