Source file src/go/types/type.go

     1	// Copyright 2011 The Go Authors. All rights reserved.
     2	// Use of this source code is governed by a BSD-style
     3	// license that can be found in the LICENSE file.
     4	
     5	package types
     6	
     7	import "sort"
     8	
     9	// A Type represents a type of Go.
    10	// All types implement the Type interface.
    11	type Type interface {
    12		// Underlying returns the underlying type of a type.
    13		Underlying() Type
    14	
    15		// String returns a string representation of a type.
    16		String() string
    17	}
    18	
    19	// BasicKind describes the kind of basic type.
    20	type BasicKind int
    21	
    22	const (
    23		Invalid BasicKind = iota // type is invalid
    24	
    25		// predeclared types
    26		Bool
    27		Int
    28		Int8
    29		Int16
    30		Int32
    31		Int64
    32		Uint
    33		Uint8
    34		Uint16
    35		Uint32
    36		Uint64
    37		Uintptr
    38		Float32
    39		Float64
    40		Complex64
    41		Complex128
    42		String
    43		UnsafePointer
    44	
    45		// types for untyped values
    46		UntypedBool
    47		UntypedInt
    48		UntypedRune
    49		UntypedFloat
    50		UntypedComplex
    51		UntypedString
    52		UntypedNil
    53	
    54		// aliases
    55		Byte = Uint8
    56		Rune = Int32
    57	)
    58	
    59	// BasicInfo is a set of flags describing properties of a basic type.
    60	type BasicInfo int
    61	
    62	// Properties of basic types.
    63	const (
    64		IsBoolean BasicInfo = 1 << iota
    65		IsInteger
    66		IsUnsigned
    67		IsFloat
    68		IsComplex
    69		IsString
    70		IsUntyped
    71	
    72		IsOrdered   = IsInteger | IsFloat | IsString
    73		IsNumeric   = IsInteger | IsFloat | IsComplex
    74		IsConstType = IsBoolean | IsNumeric | IsString
    75	)
    76	
    77	// A Basic represents a basic type.
    78	type Basic struct {
    79		kind BasicKind
    80		info BasicInfo
    81		name string
    82	}
    83	
    84	// Kind returns the kind of basic type b.
    85	func (b *Basic) Kind() BasicKind { return b.kind }
    86	
    87	// Info returns information about properties of basic type b.
    88	func (b *Basic) Info() BasicInfo { return b.info }
    89	
    90	// Name returns the name of basic type b.
    91	func (b *Basic) Name() string { return b.name }
    92	
    93	// An Array represents an array type.
    94	type Array struct {
    95		len  int64
    96		elem Type
    97	}
    98	
    99	// NewArray returns a new array type for the given element type and length.
   100	// A negative length indicates an unknown length.
   101	func NewArray(elem Type, len int64) *Array { return &Array{len, elem} }
   102	
   103	// Len returns the length of array a.
   104	// A negative result indicates an unknown length.
   105	func (a *Array) Len() int64 { return a.len }
   106	
   107	// Elem returns element type of array a.
   108	func (a *Array) Elem() Type { return a.elem }
   109	
   110	// A Slice represents a slice type.
   111	type Slice struct {
   112		elem Type
   113	}
   114	
   115	// NewSlice returns a new slice type for the given element type.
   116	func NewSlice(elem Type) *Slice { return &Slice{elem} }
   117	
   118	// Elem returns the element type of slice s.
   119	func (s *Slice) Elem() Type { return s.elem }
   120	
   121	// A Struct represents a struct type.
   122	type Struct struct {
   123		fields []*Var
   124		tags   []string // field tags; nil if there are no tags
   125	}
   126	
   127	// NewStruct returns a new struct with the given fields and corresponding field tags.
   128	// If a field with index i has a tag, tags[i] must be that tag, but len(tags) may be
   129	// only as long as required to hold the tag with the largest index i. Consequently,
   130	// if no field has a tag, tags may be nil.
   131	func NewStruct(fields []*Var, tags []string) *Struct {
   132		var fset objset
   133		for _, f := range fields {
   134			if f.name != "_" && fset.insert(f) != nil {
   135				panic("multiple fields with the same name")
   136			}
   137		}
   138		if len(tags) > len(fields) {
   139			panic("more tags than fields")
   140		}
   141		return &Struct{fields: fields, tags: tags}
   142	}
   143	
   144	// NumFields returns the number of fields in the struct (including blank and embedded fields).
   145	func (s *Struct) NumFields() int { return len(s.fields) }
   146	
   147	// Field returns the i'th field for 0 <= i < NumFields().
   148	func (s *Struct) Field(i int) *Var { return s.fields[i] }
   149	
   150	// Tag returns the i'th field tag for 0 <= i < NumFields().
   151	func (s *Struct) Tag(i int) string {
   152		if i < len(s.tags) {
   153			return s.tags[i]
   154		}
   155		return ""
   156	}
   157	
   158	// A Pointer represents a pointer type.
   159	type Pointer struct {
   160		base Type // element type
   161	}
   162	
   163	// NewPointer returns a new pointer type for the given element (base) type.
   164	func NewPointer(elem Type) *Pointer { return &Pointer{base: elem} }
   165	
   166	// Elem returns the element type for the given pointer p.
   167	func (p *Pointer) Elem() Type { return p.base }
   168	
   169	// A Tuple represents an ordered list of variables; a nil *Tuple is a valid (empty) tuple.
   170	// Tuples are used as components of signatures and to represent the type of multiple
   171	// assignments; they are not first class types of Go.
   172	type Tuple struct {
   173		vars []*Var
   174	}
   175	
   176	// NewTuple returns a new tuple for the given variables.
   177	func NewTuple(x ...*Var) *Tuple {
   178		if len(x) > 0 {
   179			return &Tuple{x}
   180		}
   181		return nil
   182	}
   183	
   184	// Len returns the number variables of tuple t.
   185	func (t *Tuple) Len() int {
   186		if t != nil {
   187			return len(t.vars)
   188		}
   189		return 0
   190	}
   191	
   192	// At returns the i'th variable of tuple t.
   193	func (t *Tuple) At(i int) *Var { return t.vars[i] }
   194	
   195	// A Signature represents a (non-builtin) function or method type.
   196	// The receiver is ignored when comparing signatures for identity.
   197	type Signature struct {
   198		// We need to keep the scope in Signature (rather than passing it around
   199		// and store it in the Func Object) because when type-checking a function
   200		// literal we call the general type checker which returns a general Type.
   201		// We then unpack the *Signature and use the scope for the literal body.
   202		scope    *Scope // function scope, present for package-local signatures
   203		recv     *Var   // nil if not a method
   204		params   *Tuple // (incoming) parameters from left to right; or nil
   205		results  *Tuple // (outgoing) results from left to right; or nil
   206		variadic bool   // true if the last parameter's type is of the form ...T (or string, for append built-in only)
   207	}
   208	
   209	// NewSignature returns a new function type for the given receiver, parameters,
   210	// and results, either of which may be nil. If variadic is set, the function
   211	// is variadic, it must have at least one parameter, and the last parameter
   212	// must be of unnamed slice type.
   213	func NewSignature(recv *Var, params, results *Tuple, variadic bool) *Signature {
   214		if variadic {
   215			n := params.Len()
   216			if n == 0 {
   217				panic("types.NewSignature: variadic function must have at least one parameter")
   218			}
   219			if _, ok := params.At(n - 1).typ.(*Slice); !ok {
   220				panic("types.NewSignature: variadic parameter must be of unnamed slice type")
   221			}
   222		}
   223		return &Signature{nil, recv, params, results, variadic}
   224	}
   225	
   226	// Recv returns the receiver of signature s (if a method), or nil if a
   227	// function. It is ignored when comparing signatures for identity.
   228	//
   229	// For an abstract method, Recv returns the enclosing interface either
   230	// as a *Named or an *Interface. Due to embedding, an interface may
   231	// contain methods whose receiver type is a different interface.
   232	func (s *Signature) Recv() *Var { return s.recv }
   233	
   234	// Params returns the parameters of signature s, or nil.
   235	func (s *Signature) Params() *Tuple { return s.params }
   236	
   237	// Results returns the results of signature s, or nil.
   238	func (s *Signature) Results() *Tuple { return s.results }
   239	
   240	// Variadic reports whether the signature s is variadic.
   241	func (s *Signature) Variadic() bool { return s.variadic }
   242	
   243	// An Interface represents an interface type.
   244	type Interface struct {
   245		methods   []*Func // ordered list of explicitly declared methods
   246		embeddeds []Type  // ordered list of explicitly embedded types
   247	
   248		allMethods []*Func // ordered list of methods declared with or embedded in this interface (TODO(gri): replace with mset)
   249	}
   250	
   251	// emptyInterface represents the empty (completed) interface
   252	var emptyInterface = Interface{allMethods: markComplete}
   253	
   254	// markComplete is used to mark an empty interface as completely
   255	// set up by setting the allMethods field to a non-nil empty slice.
   256	var markComplete = make([]*Func, 0)
   257	
   258	// NewInterface returns a new (incomplete) interface for the given methods and embedded types.
   259	// Each embedded type must have an underlying type of interface type.
   260	// NewInterface takes ownership of the provided methods and may modify their types by setting
   261	// missing receivers. To compute the method set of the interface, Complete must be called.
   262	//
   263	// Deprecated: Use NewInterfaceType instead which allows any (even non-defined) interface types
   264	// to be embedded. This is necessary for interfaces that embed alias type names referring to
   265	// non-defined (literal) interface types.
   266	func NewInterface(methods []*Func, embeddeds []*Named) *Interface {
   267		tnames := make([]Type, len(embeddeds))
   268		for i, t := range embeddeds {
   269			tnames[i] = t
   270		}
   271		return NewInterfaceType(methods, tnames)
   272	}
   273	
   274	// NewInterfaceType returns a new (incomplete) interface for the given methods and embedded types.
   275	// Each embedded type must have an underlying type of interface type (this property is not
   276	// verified for defined types, which may be in the process of being set up and which don't
   277	// have a valid underlying type yet).
   278	// NewInterfaceType takes ownership of the provided methods and may modify their types by setting
   279	// missing receivers. To compute the method set of the interface, Complete must be called.
   280	func NewInterfaceType(methods []*Func, embeddeds []Type) *Interface {
   281		typ := new(Interface)
   282	
   283		if len(methods) == 0 && len(embeddeds) == 0 {
   284			return typ
   285		}
   286	
   287		var mset objset
   288		for _, m := range methods {
   289			if mset.insert(m) != nil {
   290				panic("multiple methods with the same name")
   291			}
   292			// set receiver if we don't have one
   293			if sig := m.typ.(*Signature); sig.recv == nil {
   294				sig.recv = NewVar(m.pos, m.pkg, "", typ)
   295			}
   296		}
   297		sort.Sort(byUniqueMethodName(methods))
   298	
   299		if len(embeddeds) > 0 {
   300			// All embedded types should be interfaces; however, defined types
   301			// may not yet be fully resolved. Only verify that non-defined types
   302			// are interfaces. This matches the behavior of the code before the
   303			// fix for #25301 (issue #25596).
   304			for _, t := range embeddeds {
   305				if _, ok := t.(*Named); !ok && !IsInterface(t) {
   306					panic("embedded type is not an interface")
   307				}
   308			}
   309			sort.Stable(byUniqueTypeName(embeddeds))
   310		}
   311	
   312		typ.methods = methods
   313		typ.embeddeds = embeddeds
   314		return typ
   315	}
   316	
   317	// NumExplicitMethods returns the number of explicitly declared methods of interface t.
   318	func (t *Interface) NumExplicitMethods() int { return len(t.methods) }
   319	
   320	// ExplicitMethod returns the i'th explicitly declared method of interface t for 0 <= i < t.NumExplicitMethods().
   321	// The methods are ordered by their unique Id.
   322	func (t *Interface) ExplicitMethod(i int) *Func { return t.methods[i] }
   323	
   324	// NumEmbeddeds returns the number of embedded types in interface t.
   325	func (t *Interface) NumEmbeddeds() int { return len(t.embeddeds) }
   326	
   327	// Embedded returns the i'th embedded defined (*Named) type of interface t for 0 <= i < t.NumEmbeddeds().
   328	// The result is nil if the i'th embedded type is not a defined type.
   329	//
   330	// Deprecated: Use EmbeddedType which is not restricted to defined (*Named) types.
   331	func (t *Interface) Embedded(i int) *Named { tname, _ := t.embeddeds[i].(*Named); return tname }
   332	
   333	// EmbeddedType returns the i'th embedded type of interface t for 0 <= i < t.NumEmbeddeds().
   334	func (t *Interface) EmbeddedType(i int) Type { return t.embeddeds[i] }
   335	
   336	// NumMethods returns the total number of methods of interface t.
   337	func (t *Interface) NumMethods() int { return len(t.allMethods) }
   338	
   339	// Method returns the i'th method of interface t for 0 <= i < t.NumMethods().
   340	// The methods are ordered by their unique Id.
   341	func (t *Interface) Method(i int) *Func { return t.allMethods[i] }
   342	
   343	// Empty reports whether t is the empty interface.
   344	func (t *Interface) Empty() bool { return len(t.allMethods) == 0 }
   345	
   346	// Complete computes the interface's method set. It must be called by users of
   347	// NewInterfaceType and NewInterface after the interface's embedded types are
   348	// fully defined and before using the interface type in any way other than to
   349	// form other types. Complete returns the receiver.
   350	func (t *Interface) Complete() *Interface {
   351		if t.allMethods != nil {
   352			return t
   353		}
   354	
   355		// collect all methods
   356		var allMethods []*Func
   357		allMethods = append(allMethods, t.methods...)
   358		for _, et := range t.embeddeds {
   359			it := et.Underlying().(*Interface)
   360			it.Complete()
   361			// copy embedded methods unchanged (see issue #28282)
   362			allMethods = append(allMethods, it.allMethods...)
   363		}
   364		sort.Sort(byUniqueMethodName(allMethods))
   365	
   366		// t.methods and/or t.embeddeds may have been empty
   367		if allMethods == nil {
   368			allMethods = markComplete
   369		}
   370		t.allMethods = allMethods
   371	
   372		return t
   373	}
   374	
   375	// A Map represents a map type.
   376	type Map struct {
   377		key, elem Type
   378	}
   379	
   380	// NewMap returns a new map for the given key and element types.
   381	func NewMap(key, elem Type) *Map {
   382		return &Map{key, elem}
   383	}
   384	
   385	// Key returns the key type of map m.
   386	func (m *Map) Key() Type { return m.key }
   387	
   388	// Elem returns the element type of map m.
   389	func (m *Map) Elem() Type { return m.elem }
   390	
   391	// A Chan represents a channel type.
   392	type Chan struct {
   393		dir  ChanDir
   394		elem Type
   395	}
   396	
   397	// A ChanDir value indicates a channel direction.
   398	type ChanDir int
   399	
   400	// The direction of a channel is indicated by one of these constants.
   401	const (
   402		SendRecv ChanDir = iota
   403		SendOnly
   404		RecvOnly
   405	)
   406	
   407	// NewChan returns a new channel type for the given direction and element type.
   408	func NewChan(dir ChanDir, elem Type) *Chan {
   409		return &Chan{dir, elem}
   410	}
   411	
   412	// Dir returns the direction of channel c.
   413	func (c *Chan) Dir() ChanDir { return c.dir }
   414	
   415	// Elem returns the element type of channel c.
   416	func (c *Chan) Elem() Type { return c.elem }
   417	
   418	// A Named represents a named type.
   419	type Named struct {
   420		obj        *TypeName // corresponding declared object
   421		underlying Type      // possibly a *Named during setup; never a *Named once set up completely
   422		methods    []*Func   // methods declared for this type (not the method set of this type); signatures are type-checked lazily
   423	}
   424	
   425	// NewNamed returns a new named type for the given type name, underlying type, and associated methods.
   426	// If the given type name obj doesn't have a type yet, its type is set to the returned named type.
   427	// The underlying type must not be a *Named.
   428	func NewNamed(obj *TypeName, underlying Type, methods []*Func) *Named {
   429		if _, ok := underlying.(*Named); ok {
   430			panic("types.NewNamed: underlying type must not be *Named")
   431		}
   432		typ := &Named{obj: obj, underlying: underlying, methods: methods}
   433		if obj.typ == nil {
   434			obj.typ = typ
   435		}
   436		return typ
   437	}
   438	
   439	// Obj returns the type name for the named type t.
   440	func (t *Named) Obj() *TypeName { return t.obj }
   441	
   442	// NumMethods returns the number of explicit methods whose receiver is named type t.
   443	func (t *Named) NumMethods() int { return len(t.methods) }
   444	
   445	// Method returns the i'th method of named type t for 0 <= i < t.NumMethods().
   446	func (t *Named) Method(i int) *Func { return t.methods[i] }
   447	
   448	// SetUnderlying sets the underlying type and marks t as complete.
   449	func (t *Named) SetUnderlying(underlying Type) {
   450		if underlying == nil {
   451			panic("types.Named.SetUnderlying: underlying type must not be nil")
   452		}
   453		if _, ok := underlying.(*Named); ok {
   454			panic("types.Named.SetUnderlying: underlying type must not be *Named")
   455		}
   456		t.underlying = underlying
   457	}
   458	
   459	// AddMethod adds method m unless it is already in the method list.
   460	func (t *Named) AddMethod(m *Func) {
   461		if i, _ := lookupMethod(t.methods, m.pkg, m.name); i < 0 {
   462			t.methods = append(t.methods, m)
   463		}
   464	}
   465	
   466	// Implementations for Type methods.
   467	
   468	func (b *Basic) Underlying() Type     { return b }
   469	func (a *Array) Underlying() Type     { return a }
   470	func (s *Slice) Underlying() Type     { return s }
   471	func (s *Struct) Underlying() Type    { return s }
   472	func (p *Pointer) Underlying() Type   { return p }
   473	func (t *Tuple) Underlying() Type     { return t }
   474	func (s *Signature) Underlying() Type { return s }
   475	func (t *Interface) Underlying() Type { return t }
   476	func (m *Map) Underlying() Type       { return m }
   477	func (c *Chan) Underlying() Type      { return c }
   478	func (t *Named) Underlying() Type     { return t.underlying }
   479	
   480	func (b *Basic) String() string     { return TypeString(b, nil) }
   481	func (a *Array) String() string     { return TypeString(a, nil) }
   482	func (s *Slice) String() string     { return TypeString(s, nil) }
   483	func (s *Struct) String() string    { return TypeString(s, nil) }
   484	func (p *Pointer) String() string   { return TypeString(p, nil) }
   485	func (t *Tuple) String() string     { return TypeString(t, nil) }
   486	func (s *Signature) String() string { return TypeString(s, nil) }
   487	func (t *Interface) String() string { return TypeString(t, nil) }
   488	func (m *Map) String() string       { return TypeString(m, nil) }
   489	func (c *Chan) String() string      { return TypeString(c, nil) }
   490	func (t *Named) String() string     { return TypeString(t, nil) }
   491	

View as plain text