Documentation
¶
Overview ¶
Package typeparams contains common utilities for writing tools that interact with generic Go code, as introduced with Go 1.18.
Many of the types and functions in this package are proxies for the new APIs introduced in the standard library with Go 1.18. For example, the typeparams.Union type is an alias for go/types.Union, and the ForTypeSpec function returns the value of the go/ast.TypeSpec.TypeParams field. At Go versions older than 1.18 these helpers are implemented as stubs, allowing users of this package to write code that handles generic constructs inline, even if the Go version being used to compile does not support generics.
Additionally, this package contains common utilities for working with the new generic constructs, to supplement the standard library APIs. Notably, the NormalTerms API computes a minimal representation of the structural restrictions on a type parameter. In the future, these supplemental APIs may be available in the standard library..
Index ¶
- Variables
- func Enabled() bool
- func ForFuncType(n *ast.FuncType) *ast.FieldList
- func ForTypeSpec(n *ast.TypeSpec) *ast.FieldList
- func GenericAssignableTo(ctxt *Context, V, T types.Type) bool
- func GetInstances(info *types.Info) map[*ast.Ident]Instance
- func InitInstances(info *types.Info)
- func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error)
- func IsComparable(iface *types.Interface) bool
- func IsImplicit(iface *types.Interface) bool
- func IsMethodSet(iface *types.Interface) bool
- func IsTypeParam(t types.Type) bool
- func MarkImplicit(iface *types.Interface)
- func NamedTypeOrigin(named *types.Named) types.Type
- func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, ...) *types.Signature
- func OriginMethod(fn *types.Func) *types.Func
- func PackIndexExpr(x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) ast.Expr
- func SetForNamed(n *types.Named, tparams []*TypeParam)
- func UnpackIndexExpr(n ast.Node) (x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos)
- type Context
- type IndexListExpr
- type Instance
- type Term
- type TypeList
- type TypeParam
- type TypeParamList
- type Union
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyTypeSet = errors.New("empty type set")
ErrEmptyTypeSet is returned if a type set computation results in a type set with no types.
Functions ¶
func Enabled ¶
func Enabled() bool
Enabled reports whether type parameters are enabled in the current build environment.
func ForFuncType ¶
ForFuncType returns n.TypeParams.
func ForTypeSpec ¶
ForTypeSpec returns n.TypeParams.
func GenericAssignableTo ¶
GenericAssignableTo is a generalization of types.AssignableTo that implements the following rule for uninstantiated generic types:
If V and T are generic named types, then V is considered assignable to T if, for every possible instantation of V[A_1, ..., A_N], the instantiation T[A_1, ..., A_N] is valid and V[A_1, ..., A_N] implements T[A_1, ..., A_N].
If T has structural constraints, they must be satisfied by V.
For example, consider the following type declarations:
type Interface[T any] interface {
Accept(T)
}
type Container[T any] struct {
Element T
}
func (c Container[T]) Accept(t T) { c.Element = t }
In this case, GenericAssignableTo reports that instantiations of Container are assignable to the corresponding instantiation of Interface.
func GetInstances ¶
GetInstances returns info.Instances.
func InitInstances ¶
InitInstances initializes info to record information about type and function instances.
func Instantiate ¶
func Instantiate(ctxt *Context, typ types.Type, targs []types.Type, validate bool) (types.Type, error)
Instantiate calls types.Instantiate.
func IsComparable ¶
IsComparable calls iface.IsComparable().
func IsMethodSet ¶
IsMethodSet calls iface.IsMethodSet().
func IsTypeParam ¶
IsTypeParam reports whether t is a type parameter.
func MarkImplicit ¶
MarkImplicit calls iface.MarkImplicit().
func NamedTypeOrigin ¶
NamedTypeOrigin returns named.Orig().
func NewSignatureType ¶
func NewSignatureType(recv *types.Var, recvTypeParams, typeParams []*TypeParam, params, results *types.Tuple, variadic bool) *types.Signature
NewSignatureType calls types.NewSignatureType.
func OriginMethod ¶
OriginMethod returns the origin method associated with the method fn. For methods on a non-generic receiver base type, this is just fn. However, for methods with a generic receiver, OriginMethod returns the corresponding method in the method set of the origin type.
As a special case, if fn is not a method (has no receiver), OriginMethod returns fn.
func PackIndexExpr ¶
PackIndexExpr returns an *ast.IndexExpr or *ast.IndexListExpr, depending on the cardinality of indices. Calling PackIndexExpr with len(indices) == 0 will panic.
func SetForNamed ¶
SetForNamed sets the type params tparams on n. Each tparam must be of dynamic type *types.TypeParam.
func UnpackIndexExpr ¶
func UnpackIndexExpr(n ast.Node) (x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos)
UnpackIndexExpr extracts data from AST nodes that represent index expressions.
For an ast.IndexExpr, the resulting indices slice will contain exactly one index expression. For an ast.IndexListExpr (go1.18+), it may have a variable number of index expressions.
For nodes that don't represent index expressions, the first return value of UnpackIndexExpr will be nil.
Types ¶
type IndexListExpr ¶
type IndexListExpr = ast.IndexListExpr
IndexListExpr is an alias for ast.IndexListExpr.
type Term ¶
Term is an alias for types.Term.
func NormalTerms ¶
NormalTerms returns a slice of terms representing the normalized structural type restrictions of a type, if any.
For all types whose underlying type is not *types.TypeParam, *types.Interface, or *types.Union, this is just a single term with Tilde() == false and Type() == typ. For types whose underlying type is *types.TypeParam, *types.Interface, and *types.Union, see below.
Structural type restrictions of a type parameter are created via non-interface types embedded in its constraint interface (directly, or via a chain of interface embeddings). For example, in the declaration type T[P interface{~int; m()}] int is the structural restriction of the type parameter P is ~int.
With interface embedding and unions, the specification of structural type restrictions may be arbitrarily complex. For example, consider the following:
type A interface{ ~string|~[]byte }
type B interface{ int|string }
type C interface { ~string|~int }
type T[P interface{ A|B; C }] int
In this example, the structural type restriction of P is ~string|int: A|B expands to ~string|~[]byte|int|string, which reduces to ~string|~[]byte|int, which when intersected with C (~string|~int) yields ~string|int.
NormalTerms computes these expansions and reductions, producing a "normalized" form of the embeddings. A structural restriction is normalized if it is a single union containing no interface terms, and is minimal in the sense that removing any term changes the set of types satisfying the constraint. It is left as a proof for the reader that, modulo sorting, there is exactly one such normalized form.
Because the minimal representation always takes this form, NormalTerms returns a slice of tilde terms corresponding to the terms of the union in the normalized structural restriction. An error is returned if the type is invalid, exceeds complexity bounds, or has an empty type set. In the latter case, NormalTerms returns ErrEmptyTypeSet.
NormalTerms makes no guarantees about the order of terms, except that it is deterministic.
type TypeList ¶
TypeList is an alias for types.TypeList
func NamedTypeArgs ¶
NamedTypeArgs returns named.TypeArgs().
type TypeParamList ¶
type TypeParamList = types.TypeParamList
TypeParamList is an alias for types.TypeParamList
func ForNamed ¶
func ForNamed(named *types.Named) *TypeParamList
ForNamed extracts the (possibly empty) type parameter object list from named.
func ForSignature ¶
func ForSignature(sig *types.Signature) *TypeParamList
ForSignature returns sig.TypeParams()
func RecvTypeParams ¶
func RecvTypeParams(sig *types.Signature) *TypeParamList
RecvTypeParams returns sig.RecvTypeParams().
Source Files
Directories