Three new books, Go Optimizations 101, Go Details & Tips 101 and Go Generics 101 are published now. It is most cost-effective to buy all of them through this book bundle in the Leanpub book store.

Please follow Go 101 Twitter account @Go100and1 to get latest news of Go 101 books/articles/apps/libraries.

Constraints and Type Parameters

A constraint means a type constraint, it is used to constrain some type parameters. We could view constraints as types of types.

The relation between a constraint and a type parameter is like the relation between a type and a value. If we say types are value templates (and values are type instances), then constraints are type templates (and types are constraint instances).

A type parameter is a type which is declared in a type parameter list and could be used in a generic type specification or a generic function/method declaration. Each type parameter is a distinct named type.

Type parameter lists will be explained in detail in a later section.

As mentioned in the previous chapter, type constraints are actually interface types. In order to let interface types be competent to act as the constraint role, Go 1.18 enhances the expressiveness of interface types by supporting several new notations.

Enhanced interface syntax

Some new notations are introduced into Go to make it possible to use interface types as constraints.

Note that, a type literal always denotes an unnamed type, whereas a type name may denote a named type or unnamed type.

Some legal examples of the new notations:

// tilde forms
~int
~[]byte
~map[int]string
~chan struct{}
~struct{x int}

// unions of terms
uint8 | uint16 | uint32 | uint64
~[]byte | ~string
map[int]int | []int | [16]int | any
chan struct{} | ~struct{x int}

We know that, before Go 1.18, an interface type may embed

Go 1.18 relaxed the limitations of type elements, so that now an interface type may embed the following type elements:

The orders of interface elements embedded in an interface type are not important.

The following code snippet shows some interface type declarations, in which the interface type literals in the declarations of N and O are only legal since Go 1.18.

type L interface {
	Run() error
	Stop()
}

type M interface {
	L
	Step() error
}

type N interface {
	M
	interface{ Resume() }
	~map[int]bool
	~[]byte | string
}

type O interface {
	Pause()
	N
	string
	int64 | ~chan int | any
}

Embedding an interface type in another one is equivalent to (recursively) expanding the elements in the former into the latter. In the above example, the declarations of M, N and O are equivalent to the following ones:

type M interface {
	Run() error
	Stop()
	Step() error
}

type N interface {
	Run() error
	Stop()
	Step() error
	Resume()
	~map[int]bool
	~[]byte | string
}

type O interface {
	Run() error
	Stop()
	Step() error
	Pause()
	Resume()
	~map[int]bool
	~[]byte | string
	string
	int64 | ~chan int | any
}

We could view a single type literal, type name or tilde form as a term union with only one term. So simply speaking, since Go 1.18, an interface type may specify some methods and embed some term unions.

An interface type without any embedding elements is called an empty interface. For example, the predeclared any type alias denotes an empty interface type.

Type sets and method sets

Before Go 1.18, an interface type is defined as a method set. Since Go 1.18, an interface type is defined as a type set. A type set only consists of non-interface types.

As the type set of an empty interface type (for example, the predeclared any) contains all non-interface types.

By the current specification, two unnamed constraints are equivalent to each other if their type sets are equal.

Given the types declared in the following code snippet, for each interface type, its type set is shown in its preceding comment.

type Bytes []byte  // underlying type is []byte
type Letters Bytes // underlying type is []byte
type Blank struct{}
type MyString string // underlying type is string

func (MyString) M() {}
func (Bytes) M() {}
func (Blank) M() {}

// The type set of P only contains one type:
// []byte.
type P interface {[]byte}

// The type set of Q contains
// []byte, Bytes, and Letters.
type Q interface {~[]byte}

// The type set of R contains only two types:
// []byte and string.
type R interface {[]byte | string}

// The type set of S is empty.
type S interface {R; M()}

// The type set of T contains:
// []byte, Bytes, Letters, string, and MyString.
type T interface {~[]byte | ~string}

// The type set of U contains:
// MyString, Bytes, and Blank.
type U interface {M()}

// V <=> P
type V interface {[]byte; any}

// The type set of W contains:
// Bytes and MyString.
type W interface {T; U}

// Z <=> any. Z is a blank interface. Its
// type set contains all non-interface types.
type Z interface {~[]byte | ~string | any}

Please note that interface elements are separated with semicolon (;), either explicitly or implicitly (Go compilers will insert some missing semicolons as needed in compilations). The following interface type literals are equivalent to each other. The type set of the interface type denoted by them is empty. The interface type and the underlying type of the type S shown in the above code snippet are actually identical.

interface {~string; string; M();}
interface {~string; string; M()}
interface {
	~string
	string
	M()
}

If the type set of a type X is a subset of an interface type Y, we say X implements (or satisfies) Y. Here, X may be an interface type or a non-interface type.

Because the type set of an empty interface type is a super set of the type sets of any types, all types implement an empty interface type.

In the above example,

The list of methods specified by an interface type is called the method set of the interface type. If an interface type X implements another interface type Y, then the method set of X must be a super set of Y.

Interface types whose type sets can be defined entirely by a method set (may be empty) are called basic interface types. Before 1.18, Go only supports basic interface types. Basic interfaces may be used as either value types or type constraints, but non-basic interfaces may only be used as type constraints (as of Go 1.19).

In the above examples, L, M, U, Z and any are basic types.

In the following code, the declaration lines for x and y both compile okay, but the line declaring z fails to compile.

var x any
var y interface {M()}

// error: interface contains type constraints
var z interface {~[]byte}

Whether or not to support non-basic interface types as value types in future Go versions in unclear now.

Note, before Go toolchain 1.19, aliases to non-basic interface types were not supported. The following type alias declarations are only legal since Go toolchain 1.19.

type C[T any] interface{~int; M() T}
type C1 = C[bool]
type C2 = comparable
type C3 = interface {~[]byte | ~string}

More about the predeclared comparable constraint

As aforementioned, besides any, Go 1.18 also introduces another new predeclared identifier comparable, which denotes an interface type that is implemented by all comparable types.

The comparable interface type could be embedded in other interface types to filter out incomparable types from their type sets. For example, the type set of the following declared constraint C contains only one type: string, because the other three types in the union are all incomprarable types.

type C interface {
	comparable
	[]byte | string | func() | map[int]bool
}

Currently (Go 1.19), the comparable interface is treated as a non-basic interface type. So, now, it may only be used as type parameter constraints, not as value types. The following code is illegal:

var x comparable = 123

The type set of the comparable interface is the set of all comparable types. The set is a subset of the type set of the any interface, so comparable undoubtedly implements any, and not vice versa.

On the other hand, starting from Go 1.0, all basic interface types are treated as comparable types. The blank interface type any is not an exception. So it looks that any (as a value type) should satisfy (implement) the comparable constraint. This is quite odd.

After deliberation, Go core team believe that it is a design flaw to treat all interface types as comparable types and it is a pity that the comparable type has not been supported since Go 1.0 to avoid this flaw.

Go core team try to make up for this flaw in Go custom generics age. So they decided that all basic interface types don't satisfy (implement) the comparable constraint. A consequence of this decision is it causes diffculties to some code designs.

To avoid the consequence, a proposal has been made to permit using comparable as value types. Whether or not it should be accepted is still under discuss. It could be accepted in as earlier as Go 1.19.

Another benefit brought by the proposal is that it provides a way to ensure some interface comparisons will never panic. For example, calls to the following function might panic at run time:

func foo(x, y any) bool {
	return x == y
}

var _ = foo([]int{}, []int{}) // panics

If the comparable type could be used as a value type, then we could change the parameter types of the foo function to comparable to ensure the calls to the foo function will never panic.

func foo(x, y comparable) bool {
	return x == y
}

var _ = foo([]int{}, []int{}) // fails to compile

More requirements for union terms

The above has mentioned that a union term may not be a type parameter. There are two other requirements for union terms.

The first is an implementation specific requirement: a term union with more than one term cannot contain the predeclared identifier comparable or interfaces that have methods. For example, the following term unions are both illegal (as of Go toolchain 1.19):

[]byte | comparable
string | error

To make descriptions simple, this book will view the predeclared comparable interface type as an interface type having a method (but not view it as a basic interface type).

Another requirement (restriction) is that the type sets of all non-interface type terms in a term union must have no intersections. For example, in the following code snippet, the term unions in the first declaration fails to compile, but the last two compile okay.

type _ interface {
	int | ~int // error
}

type _ interface {
	interface{int} | interface{~int} // okay
}

type _ interface {
	int | interface{~int} // okay
}

The three term unions in the above code snippet are equivalent to each other in logic, which means this restriction is not very reasonable. So it might be removed in later Go versions, or become stricter to defeat the workaround.

Type parameter lists

From the examples shown in the last chapter, we know type parameter lists are used in generic type specifications, method declarations for generic base types and generic function declarations.

A type parameter list contains at least one type parameter declaration and is enclosed in square brackets. Each parameter declaration is composed of a name part and a constraint part (we can think the constraints are implicit in method declarations for generic base types). The name represents a type parameter constrained by the constraint. Parameter declarations are comma-separated in a type parameter list.

In a type parameter list, all type parameter names must be present. They may be the blank identifier _ (called blank name). All non-blank names in a type parameter list must be unique.

Similar to value parameter lists, if the constraints of some successive type parameter declarations in a type parameter list are identical, then these type parameter declarations could share a common constraint part in the type parameter list. For example, the following two type parameter lists are equivalent.

[A any, B any, X comparable, _ comparable]
[A, B any, X, _ comparable]

Similar to value parameter lists, if the right ] token in a type parameter list and the last constraint in the list are at the same line, an optional comma is allowed to be inserted between them. The comma is required if the two are not at the same line.

For example, in the following code, the beginning lines are legal, the ending lines are not.

// Legal ones:
[T interface{~map[int]string}]
[T interface{~map[int]string},]
[T interface{~map[int]string},
]
[A, B any, _, _ comparable]
[A, B any, _, _ comparable,]
[A, B any, _, _ comparable,
]
[A, B any,
_, _ comparable]

// Illegal ones:
[A, B any, _, _ comparable
]
[T interface{~map[int]string}
]

Variadic type parameters are not supported.

To make descriptions simple, the type set of the constraint of a type parameter is also called the type set of the type parameter and type set of a value of the type parameter in this book.

Simplified constraint form

In a type parameter list, if a constraint only contains one element and that element is a type element, then the enclosing interface{} may be omitted for convenience. For example, the following two type parameter lists are equivalent.

[X interface{string|[]byte}, Y interface{~int}]
[X string|[]byte, Y ~int]

The simplified constraint forms make code look much cleaner. For most cases, they don't cause any problems. However, it might cause parsing ambiguities for some special cases. In particular, parsing ambiguities might arise when the type parameter list of a generic type specification declares a single type parameter which constraint presents in simplified form and starts with * or (.

For example, does the following code declare a generic type?

type G[T *int] struct{}

It depends on what the int identifier denotes. If it denotes a type (very possible, not absolutely), then compilers should think the code declares a generic type. If it denotes a constant (it is possible), then compilers will treat T *int as a multiplication expression and think the code declares an ordinary array type.

It is possible for compilers to distinguish what the int identifier denotes, but there are some costs to achieve this. To avoid the costs, compilers always treat the int identifier as a value expression and think the above declaration is an ordinary array type declaration. So the above declaration line will fail to compile if T or int don't denote integer constants.

Then how to declare a generic type with a single type parameter with *int as the constraint? There are two ways to accomplish this:

  1. use the full constraint form, or
  2. let a comma follow the simplified constraint form.

The two ways are shown in the following code snippet:

// Assume int is a predeclared type.
type G[T interface{*int}] struct{}
type G[T *int,] struct{}

The two ways shown above are also helpful for some other special cases which might also cause parsing ambiguities. For example,

// PA might be array pointer variable, or a type name.
// Compilers don't treat it as a type name.
type K[cap (*PA)] struct{}

// S might be a string constant, or a type name.
// Compilers don't treat it as a type name.
type L[len (S)] struct{}

The following is another case which might cause parsing ambiguity.

// T, int and bool might be three constant integers,
// or int and bool are both predeclared types.
type C5[T *int|bool] struct{}

We should insert a comma after the presumed constraint *int|bool to remove the ambiguity.

type C5[T *int|bool, ] struct{} // compiles okay

(Note: this way doesn't work with Go toolchain 1.18. It was a bug and has been fixed since Go toolchain 1.19.)

We could also use full constraint form or exchange the places of *int and bool to make it compile okay.

// Assume int and bool are predeclared types.
type C5[T interface{*int|bool}] struct{}
type C5[T bool|*int] struct{}

On the other hand, the following two weird generic type declarations are both legal.

// "make" is a declared type parameter.
// Its constraint is interface{chan int}.
type PtrToChan[make (chan int)] *make

// "new" is a declared type parameter.
// Its constraint is interface{[3]float64}.
type Matrix33[new ([3]float64)] [3]new

The two declarations are really bad practices. Don't use them in serious code.

Each type parameter is a distinct named type

Since Go 1.18, named types include

Two different type parameters are never identical.

The type of a type parameter is a constraint, a.k.a an interface type. This means the underlying type of a type parameter type should be an interface type. However, this doesn't mean a type parameter behaves like an interface type. Its values may not box non-interface values and be type asserted (as of Go 1.19). In fact, it is almost totally meaningless to talk about underlying types of type parameters. We just need to know that the underlying type of a type parameter is not itself. And we ought to think that two type parameters never share an identical underlying type, even if the constraints of the two type parameters are identical.

In fact, a type parameter is just a placeholder for the types in its type set. Generally speaking, it represents a type which owns the common traits of the types in its type set.

As the underlying type of a type parameter type is not the type parameter type itself, the tilde form ~T is illegal if T is type parameter. So the following (equivalent) type parameter lists are illegal.

[A int, B ~A]                       // error
[A interface{int}, B interface{~A}] // error

As mentioned above, type parameters are also disallowed to be embedded as type names and type terms in an interface type. The following declarations are also illegal.

type Cx[T int] interface {
	T
}

type Cy[T int] interface {
	T | []string
}

In fact, currently (Go 1.19), type parameters may not be embedded in struct types, too.

Composite type literals (unnamed types) containing type parameters are ordinary types

For example, *T is always an ordinary (pointer) type. It is a type literal, so its underlying type is itself, whether or not T is a type parameter. The following type parameter list is legal.

[A int, B *A] // okay

For the same reason, the following type parameter lists are also legal.

[T ~string|~int, A ~[2]T, B ~chan T]            // okay
[T comparable, M ~map[T]int32, F ~func(T) bool] // okay

The scopes of a type parameters

Go specification says:

So the following type declaration is valid, even if the use of type parameter E is ahead of its declaration. The type parameter E is used in the constraint of the type parameter S,

type G[S ~[]E, E int] struct{}

Please note,

By Go specification, the function and method declarations in the following code all fail to compile.

type C any
func foo1[C C]() {}    // error: C redeclared
func foo2[T C](T T) {} // error: T redeclared

type G[G any] struct{x G} // okay
func (E G[E]) Bar1() {}   // error: E redeclared

The following Bar2 method declaration should compile okay, but it doesn't now (Go toolchain 1.19). This is a bug which will be fixed in Go toolchain 1.21.

type G[G any] struct{x G} // okay
func (v G[G]) Bar2() {}   // error: G is not a generic type

More about generic type and function declarations

We have seen a generic type declaration and some generic function declarations in the last chapter. Different from ordinary type and function declarations, each of the generic ones has a type parameter list part.

This book doesn't plan to further talk about generic type and function declaration syntax.

The source type part of a generic type declaration must be an ordinary type. So it might be

The following code shows some generic type declarations with all sorts of source types. All of these declarations are valid.

// The source types are ordinary type names.
type (
	Fake1[T any] int
	Fake2[_ any] []bool
)

// The source type is an unnamed type (composite type).
type MyData [A any, B ~bool, C comparable] struct {
	x A
	y B
	z C
}

// The source type is an instantiated type.
type YourData[C comparable] MyData[string, bool, C]

Type parameters may not be used as the source types in generic type declarations. For example, the following code doesn't compile.

type G[T any] T // error

Index↡

The Go 101 project is hosted on Github. Welcome to improve Go 101 articles by submitting corrections for all kinds of mistakes, such as typos, grammar errors, wording inaccuracies, description flaws, code bugs and broken links.

If you would like to learn some Go details and facts every serveral days, please follow Go 101's official Twitter account @go100and1 or join Go 101 slack channels.

The digital versions of this book are available at the following places:
Tapir, the author of Go 101, has been on writing the Go 101 series books and maintaining the go101.org website since 2016 July. New contents will be continually added to the book and the website from time to time. Tapir is also an indie game developer. You can also support Go 101 by playing Tapir's games (made for both Android and iPhone/iPad):
Individual donations via PayPal are also welcome.

Index: