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