package typeparams

Import Path
	golang.org/x/tools/internal/typeparams (on go.dev)

Dependency Relation
	imports 8 packages, and imported by one package

Involved Source Files

	  d common.go
		Package typeparams contains common utilities for writing tools that
		interact with generic Go code, as introduced with Go 1.18. It
		supplements the standard library APIs. Notably, the StructuralTerms
		API computes a minimal representation of the structural
		restrictions on a type parameter.
		
		An external version of these APIs is available in the
		golang.org/x/exp/typeparams module.

	    coretype.go
	    free.go
	    normalize.go
	    termlist.go
	    typeterm.go
Package-Level Type Names (total 4, in which 1 is exported)

	/* sort exporteds by: alphabet | popularity */
	 type Free (struct)
		Free is a memoization of the set of free type parameters within a
		type. It makes a sequence of calls to [Free.Has] for overlapping
		types more efficient. The zero value is ready for use.
		
		NOTE: Adapted from go/types/infer.go. If it is later exported, factor.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			seen map[types.Type]bool
		Methods (only one, which is exported)
			(*Free) Has(typ types.Type) (res bool)
				Has reports whether the specified type has a free type parameter.


	/* 3 unexporteds ... *//* 3 unexporteds: */
	 type term (struct)
		A term describes elementary type sets:
		
			 ∅:  (*term)(nil)     == ∅                      // set of no types (empty set)
			 𝓤:  &term{}          == 𝓤                      // set of all types (𝓤niverse)
			 T:  &term{false, T}  == {T}                    // set of type T
			~t:  &term{true, t}   == {t' | under(t') == t}  // set of types with underlying type t

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			tilde bool
				// valid if typ != nil

			typ types.Type
		Methods (total 7, in which 1 is exported)
			(*term) String() string
			/* 6 unexporteds ... *//* 6 unexporteds: */
			(*term) disjoint(y *term) bool
				disjoint reports whether x ∩ y == ∅.
				x.typ and y.typ must not be nil.

			(*term) equal(y *term) bool
				equal reports whether x and y represent the same type set.

			(*term) includes(t types.Type) bool
				includes reports whether t ∈ x.

			(*term) intersect(y *term) *term
				intersect returns the intersection x ∩ y.

			(*term) subsetOf(y *term) bool
				subsetOf reports whether x ⊆ y.

			(*term) union(y *term) (_, _ *term)
				union returns the union x ∪ y: zero, one, or two non-nil terms.

		Implements (at least 4, in which 2 are exported)
			*term : expvar.Var
			*term : fmt.Stringer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			*term : context.stringer
			*term : runtime.stringer

	 type termlist ([])
		A termlist represents the type set represented by the union
		t1 ∪ y2 ∪ ... tn of the type sets of the terms t1 to tn.
		A termlist is in normal form if all terms are disjoint.
		termlist operations don't require the operands to be in
		normal form.

		Methods (total 10, in which 1 is exported)
			( termlist) String() string
				String prints the termlist exactly (without normalization).

			/* 9 unexporteds ... *//* 9 unexporteds: */
			( termlist) equal(yl termlist) bool
				equal reports whether xl and yl represent the same type set.

			( termlist) includes(t types.Type) bool
				includes reports whether t ∈ xl.

			( termlist) intersect(yl termlist) termlist
				intersect returns the intersection xl ∩ yl.

			( termlist) isAll() bool
				isAll reports whether the termlist xl represents the set of all types.

			( termlist) isEmpty() bool
				isEmpty reports whether the termlist xl represents the empty set of types.

			( termlist) norm() termlist
				norm returns the normal form of xl.

			( termlist) subsetOf(yl termlist) bool
				subsetOf reports whether xl ⊆ yl.

			( termlist) supersetOf(y *term) bool
				supersetOf reports whether y ⊆ xl.

			( termlist) union(yl termlist) termlist
				union returns the union xl ∪ yl.

		Implements (at least 4, in which 2 are exported)
			 termlist : expvar.Var
			 termlist : fmt.Stringer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 termlist : context.stringer
			 termlist : runtime.stringer
		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var allTermlist

	 type termSet (struct)
		A termSet holds the normalized set of terms for a given type.
		
		The name termSet is intentionally distinct from 'type set': a type set is
		all types that implement a type (and includes method restrictions), whereas
		a term set just represents the structural restrictions on a type.

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			complete bool
			terms termlist
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func computeTermSetInternal(t types.Type, seen map[types.Type]*termSet, depth int) (res *termSet, err error)
		As Inputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func computeTermSetInternal(t types.Type, seen map[types.Type]*termSet, depth int) (res *termSet, err error)


Package-Level Functions (total 14, in which 10 are exported)

	 func CoreType(T types.Type) types.Type
		CoreType returns the core type of T or nil if T does not have a core type.
		
		See https://go.dev/ref/spec#Core_types for the definition of a core type.

	 func Deref(t types.Type) types.Type
		Deref returns the type of the variable pointed to by t,
		if t's core type is a pointer; otherwise it returns t.
		
		Do not assume that Deref(T)==T implies T is not a pointer:
		consider "type T *T", for example.
		
		TODO(adonovan): ideally this would live in typesinternal, but that
		creates an import cycle. Move there when we melt this package down.

	 func InterfaceTermSet(iface *types.Interface) ([]*types.Term, error)
		InterfaceTermSet computes the normalized terms for a constraint interface,
		returning an error if the term set cannot be computed or is empty. In the
		latter case, the error will be ErrEmptyTypeSet.
		
		See the documentation of StructuralTerms for more information on
		normalization.

	 func IsTypeParam(t types.Type) bool
		IsTypeParam reports whether t is a type parameter (or an alias of one).

	 func MustDeref(t types.Type) types.Type
		MustDeref returns the type of the variable pointed to by t.
		It panics if t's core type is not a pointer.
		
		TODO(adonovan): ideally this would live in typesinternal, but that
		creates an import cycle. Move there when we melt this package down.

	 func NormalTerms(T types.Type) ([]*types.Term, error)
		NormalTerms returns a slice of terms representing the normalized structural
		type restrictions of a type, if any.
		
		For all types other than *types.TypeParam, *types.Interface, and
		*types.Union, this is just a single term with Tilde() == false and
		Type() == typ. For *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 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.

	 func PackIndexExpr(x ast.Expr, lbrack token.Pos, indices []ast.Expr, rbrack token.Pos) ast.Expr
		PackIndexExpr returns an *ast.IndexExpr or *ast.IndexListExpr, depending on
		the cardinality of indices. Calling PackIndexExpr with len(indices) == 0
		will panic.

	 func StructuralTerms(tparam *types.TypeParam) ([]*types.Term, error)
		StructuralTerms returns a slice of terms representing the normalized
		structural type restrictions of a type parameter, if any.
		
		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
		
		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.
		
		StructuralTerms 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, StructuralTerms
		returns a slice of tilde terms corresponding to the terms of the union in
		the normalized structural restriction. An error is returned if the
		constraint interface is invalid, exceeds complexity bounds, or has an empty
		type set. In the latter case, StructuralTerms returns ErrEmptyTypeSet.
		
		StructuralTerms makes no guarantees about the order of terms, except that it
		is deterministic.

	 func UnionTermSet(union *types.Union) ([]*types.Term, error)
		UnionTermSet computes the normalized terms for a union, returning an error
		if the term set cannot be computed or is empty. In the latter case, the
		error will be ErrEmptyTypeSet.
		
		See the documentation of StructuralTerms for more information on
		normalization.

	 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.

	/* 4 unexporteds ... *//* 4 unexporteds: */
	 func computeTermSet(typ types.Type) ([]*types.Term, error)
	 func computeTermSetInternal(t types.Type, seen map[types.Type]*termSet, depth int) (res *termSet, err error)
	 func indentf(depth int, format string, args ...any)
	 func under(t types.Type) types.Type
		under is a facade for the go/types internal function of the same name. It is
		used by typeterm.go.


Package-Level Variables (total 2, in which 1 is exported)

	  var ErrEmptyTypeSet error
	/* one unexported ... *//* one unexported: */
	  var allTermlist termlist
		allTermlist represents the set of all types.
		It is in normal form.


Package-Level Constants (total 2, neither is exported)

	/* 2 unexporteds ... *//* 2 unexporteds: */
	const debug = false
	const termSep = " | "
		termSep is the separator used between individual terms.

The pages are generated with Golds v0.7.6. (GOOS=linux GOARCH=amd64)