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/*
6Package builtin provides documentation for Go's predeclared identifiers.
7The items documented here are not actually in package builtin
8but their descriptions here allow godoc to present documentation
9for the language's special identifiers.
10*/
11package builtin
12
13// bool is the set of boolean values, true and false.
14type bool bool
15
16// true and false are the two untyped boolean values.
17const (
18 true = 0 == 0 // Untyped bool.
19 false = 0 != 0 // Untyped bool.
20)
21
22// uint8 is the set of all unsigned 8-bit integers.
23// Range: 0 through 255.
24type uint8 uint8
25
26// uint16 is the set of all unsigned 16-bit integers.
27// Range: 0 through 65535.
28type uint16 uint16
29
30// uint32 is the set of all unsigned 32-bit integers.
31// Range: 0 through 4294967295.
32type uint32 uint32
33
34// uint64 is the set of all unsigned 64-bit integers.
35// Range: 0 through 18446744073709551615.
36type uint64 uint64
37
38// int8 is the set of all signed 8-bit integers.
39// Range: -128 through 127.
40type int8 int8
41
42// int16 is the set of all signed 16-bit integers.
43// Range: -32768 through 32767.
44type int16 int16
45
46// int32 is the set of all signed 32-bit integers.
47// Range: -2147483648 through 2147483647.
48type int32 int32
49
50// int64 is the set of all signed 64-bit integers.
51// Range: -9223372036854775808 through 9223372036854775807.
52type int64 int64
53
54// float32 is the set of all IEEE-754 32-bit floating-point numbers.
55type float32 float32
56
57// float64 is the set of all IEEE-754 64-bit floating-point numbers.
58type float64 float64
59
60// complex64 is the set of all complex numbers with float32 real and
61// imaginary parts.
62type complex64 complex64
63
64// complex128 is the set of all complex numbers with float64 real and
65// imaginary parts.
66type complex128 complex128
67
68// string is the set of all strings of 8-bit bytes, conventionally but not
69// necessarily representing UTF-8-encoded text. A string may be empty, but
70// not nil. Values of string type are immutable.
71type string string
72
73// int is a signed integer type that is at least 32 bits in size. It is a
74// distinct type, however, and not an alias for, say, int32.
75type int int
76
77// uint is an unsigned integer type that is at least 32 bits in size. It is a
78// distinct type, however, and not an alias for, say, uint32.
79type uint uint
80
81// uintptr is an integer type that is large enough to hold the bit pattern of
82// any pointer.
83type uintptr uintptr
84
85// byte is an alias for uint8 and is equivalent to uint8 in all ways. It is
86// used, by convention, to distinguish byte values from 8-bit unsigned
87// integer values.
88type byte = uint8
89
90// rune is an alias for int32 and is equivalent to int32 in all ways. It is
91// used, by convention, to distinguish character values from integer values.
92type rune = int32
93
94// any is an alias for interface{} and is equivalent to interface{} in all ways.
95type any = interface{}
96
97// comparable is an interface that is implemented by all comparable types
98// (booleans, numbers, strings, pointers, channels, arrays of comparable types,
99// structs whose fields are all comparable types).
100// The comparable interface may only be used as a type parameter constraint,
101// not as the type of a variable.
102type comparable interface{ comparable }
103
104// iota is a predeclared identifier representing the untyped integer ordinal
105// number of the current const specification in a (usually parenthesized)
106// const declaration. It is zero-indexed.
107const iota = 0 // Untyped int.
108
109// nil is a predeclared identifier representing the zero value for a
110// pointer, channel, func, interface, map, or slice type.
111var nil Type // Type must be a pointer, channel, func, interface, map, or slice type
112
113// Type is here for the purposes of documentation only. It is a stand-in
114// for any Go type, but represents the same type for any given function
115// invocation.
116type Type int
117
118// Type1 is here for the purposes of documentation only. It is a stand-in
119// for any Go type, but represents the same type for any given function
120// invocation.
121type Type1 int
122
123// IntegerType is here for the purposes of documentation only. It is a stand-in
124// for any integer type: int, uint, int8 etc.
125type IntegerType int
126
127// FloatType is here for the purposes of documentation only. It is a stand-in
128// for either float type: float32 or float64.
129type FloatType float32
130
131// ComplexType is here for the purposes of documentation only. It is a
132// stand-in for either complex type: complex64 or complex128.
133type ComplexType complex64
134
135// The append built-in function appends elements to the end of a slice. If
136// it has sufficient capacity, the destination is resliced to accommodate the
137// new elements. If it does not, a new underlying array will be allocated.
138// Append returns the updated slice. It is therefore necessary to store the
139// result of append, often in the variable holding the slice itself:
140//
141// slice = append(slice, elem1, elem2)
142// slice = append(slice, anotherSlice...)
143//
144// As a special case, it is legal to append a string to a byte slice, like this:
145//
146// slice = append([]byte("hello "), "world"...)
147func append(slice []Type, elems ...Type) []Type
148
149// The copy built-in function copies elements from a source slice into a
150// destination slice. (As a special case, it also will copy bytes from a
151// string to a slice of bytes.) The source and destination may overlap. Copy
152// returns the number of elements copied, which will be the minimum of
153// len(src) and len(dst).
154func copy(dst, src []Type) int
155
156// The delete built-in function deletes the element with the specified key
157// (m[key]) from the map. If m is nil or there is no such element, delete
158// is a no-op.
159func delete(m map[Type]Type1, key Type)
160
161// The len built-in function returns the length of v, according to its type:
162//
163// Array: the number of elements in v.
164// Pointer to array: the number of elements in *v (even if v is nil).
165// Slice, or map: the number of elements in v; if v is nil, len(v) is zero.
166// String: the number of bytes in v.
167// Channel: the number of elements queued (unread) in the channel buffer;
168// if v is nil, len(v) is zero.
169//
170// For some arguments, such as a string literal or a simple array expression, the
171// result can be a constant. See the Go language specification's "Length and
172// capacity" section for details.
173func len(v Type) int
174
175// The cap built-in function returns the capacity of v, according to its type:
176//
177// Array: the number of elements in v (same as len(v)).
178// Pointer to array: the number of elements in *v (same as len(v)).
179// Slice: the maximum length the slice can reach when resliced;
180// if v is nil, cap(v) is zero.
181// Channel: the channel buffer capacity, in units of elements;
182// if v is nil, cap(v) is zero.
183//
184// For some arguments, such as a simple array expression, the result can be a
185// constant. See the Go language specification's "Length and capacity" section for
186// details.
187func cap(v Type) int
188
189// The make built-in function allocates and initializes an object of type
190// slice, map, or chan (only). Like new, the first argument is a type, not a
191// value. Unlike new, make's return type is the same as the type of its
192// argument, not a pointer to it. The specification of the result depends on
193// the type:
194//
195// Slice: The size specifies the length. The capacity of the slice is
196// equal to its length. A second integer argument may be provided to
197// specify a different capacity; it must be no smaller than the
198// length. For example, make([]int, 0, 10) allocates an underlying array
199// of size 10 and returns a slice of length 0 and capacity 10 that is
200// backed by this underlying array.
201// Map: An empty map is allocated with enough space to hold the
202// specified number of elements. The size may be omitted, in which case
203// a small starting size is allocated.
204// Channel: The channel's buffer is initialized with the specified
205// buffer capacity. If zero, or the size is omitted, the channel is
206// unbuffered.
207func make(t Type, size ...IntegerType) Type
208
209// The new built-in function allocates memory. The first argument is a type,
210// not a value, and the value returned is a pointer to a newly
211// allocated zero value of that type.
212func new(Type) *Type
213
214// The complex built-in function constructs a complex value from two
215// floating-point values. The real and imaginary parts must be of the same
216// size, either float32 or float64 (or assignable to them), and the return
217// value will be the corresponding complex type (complex64 for float32,
218// complex128 for float64).
219func complex(r, i FloatType) ComplexType
220
221// The real built-in function returns the real part of the complex number c.
222// The return value will be floating point type corresponding to the type of c.
223func real(c ComplexType) FloatType
224
225// The imag built-in function returns the imaginary part of the complex
226// number c. The return value will be floating point type corresponding to
227// the type of c.
228func imag(c ComplexType) FloatType
229
230// The close built-in function closes a channel, which must be either
231// bidirectional or send-only. It should be executed only by the sender,
232// never the receiver, and has the effect of shutting down the channel after
233// the last sent value is received. After the last value has been received
234// from a closed channel c, any receive from c will succeed without
235// blocking, returning the zero value for the channel element. The form
236//
237// x, ok := <-c
238//
239// will also set ok to false for a closed and empty channel.
240func close(c chan<- Type)
241
242// The panic built-in function stops normal execution of the current
243// goroutine. When a function F calls panic, normal execution of F stops
244// immediately. Any functions whose execution was deferred by F are run in
245// the usual way, and then F returns to its caller. To the caller G, the
246// invocation of F then behaves like a call to panic, terminating G's
247// execution and running any deferred functions. This continues until all
248// functions in the executing goroutine have stopped, in reverse order. At
249// that point, the program is terminated with a non-zero exit code. This
250// termination sequence is called panicking and can be controlled by the
251// built-in function recover.
252func panic(v any)
253
254// The recover built-in function allows a program to manage behavior of a
255// panicking goroutine. Executing a call to recover inside a deferred
256// function (but not any function called by it) stops the panicking sequence
257// by restoring normal execution and retrieves the error value passed to the
258// call of panic. If recover is called outside the deferred function it will
259// not stop a panicking sequence. In this case, or when the goroutine is not
260// panicking, or if the argument supplied to panic was nil, recover returns
261// nil. Thus the return value from recover reports whether the goroutine is
262// panicking.
263func recover() any
264
265// The print built-in function formats its arguments in an
266// implementation-specific way and writes the result to standard error.
267// Print is useful for bootstrapping and debugging; it is not guaranteed
268// to stay in the language.
269func print(args ...Type)
270
271// The println built-in function formats its arguments in an
272// implementation-specific way and writes the result to standard error.
273// Spaces are always added between arguments and a newline is appended.
274// Println is useful for bootstrapping and debugging; it is not guaranteed
275// to stay in the language.
276func println(args ...Type)
277
278// The error built-in interface type is the conventional interface for
279// representing an error condition, with the nil value representing no error.
280type error interface {
281 Error() string
282}
