Source file src/builtin/builtin.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 /* 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 string 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 // TypeOrExpr is here for the purposes of documentation only. It is a stand-in 126 // for either a Go type or an expression. 127 type TypeOrExpr int 128 129 // IntegerType is here for the purposes of documentation only. It is a stand-in 130 // for any integer type: int, uint, int8 etc. 131 type IntegerType int 132 133 // FloatType is here for the purposes of documentation only. It is a stand-in 134 // for either float type: float32 or float64. 135 type FloatType float32 136 137 // ComplexType is here for the purposes of documentation only. It is a 138 // stand-in for either complex type: complex64 or complex128. 139 type ComplexType complex64 140 141 // The append built-in function appends elements to the end of a slice. If 142 // it has sufficient capacity, the destination is resliced to accommodate the 143 // new elements. If it does not, a new underlying array will be allocated. 144 // Append returns the updated slice. It is therefore necessary to store the 145 // result of append, often in the variable holding the slice itself: 146 // 147 // slice = append(slice, elem1, elem2) 148 // slice = append(slice, anotherSlice...) 149 // 150 // As a special case, it is legal to append a string to a byte slice, like this: 151 // 152 // slice = append([]byte("hello "), "world"...) 153 func append(slice []Type, elems ...Type) []Type 154 155 // The copy built-in function copies elements from a source slice into a 156 // destination slice. (As a special case, it also will copy bytes from a 157 // string to a slice of bytes.) The source and destination may overlap. Copy 158 // returns the number of elements copied, which will be the minimum of 159 // len(src) and len(dst). 160 func copy(dst, src []Type) int 161 162 // The delete built-in function deletes the element with the specified key 163 // (m[key]) from the map. If m is nil or there is no such element, delete 164 // is a no-op. 165 func delete(m map[Type]Type1, key Type) 166 167 // The len built-in function returns the length of v, according to its type: 168 // 169 // - Array: the number of elements in v. 170 // - Pointer to array: the number of elements in *v (even if v is nil). 171 // - Slice, or map: the number of elements in v; if v is nil, len(v) is zero. 172 // - String: the number of bytes in v. 173 // - Channel: the number of elements queued (unread) in the channel buffer; 174 // if v is nil, len(v) is zero. 175 // 176 // For some arguments, such as a string literal or a simple array expression, the 177 // result can be a constant. See the Go language specification's "Length and 178 // capacity" section for details. 179 func len(v Type) int 180 181 // The cap built-in function returns the capacity of v, according to its type: 182 // 183 // - Array: the number of elements in v (same as len(v)). 184 // - Pointer to array: the number of elements in *v (same as len(v)). 185 // - Slice: the maximum length the slice can reach when resliced; 186 // if v is nil, cap(v) is zero. 187 // - Channel: the channel buffer capacity, in units of elements; 188 // if v is nil, cap(v) is zero. 189 // 190 // For some arguments, such as a simple array expression, the result can be a 191 // constant. See the Go language specification's "Length and capacity" section for 192 // details. 193 func cap(v Type) int 194 195 // The make built-in function allocates and initializes an object of type 196 // slice, map, or chan (only). Like new, the first argument is a type, not a 197 // value. Unlike new, make's return type is the same as the type of its 198 // argument, not a pointer to it. The specification of the result depends on 199 // the type: 200 // 201 // - Slice: The size specifies the length. The capacity of the slice is 202 // equal to its length. A second integer argument may be provided to 203 // specify a different capacity; it must be no smaller than the 204 // length. For example, make([]int, 0, 10) allocates an underlying array 205 // of size 10 and returns a slice of length 0 and capacity 10 that is 206 // backed by this underlying array. 207 // - Map: An empty map is allocated with enough space to hold the 208 // specified number of elements. The size may be omitted, in which case 209 // a small starting size is allocated. 210 // - Channel: The channel's buffer is initialized with the specified 211 // buffer capacity. If zero, or the size is omitted, the channel is 212 // unbuffered. 213 func make(t Type, size ...IntegerType) Type 214 215 // The max built-in function returns the largest value of a fixed number of 216 // arguments of [cmp.Ordered] types. There must be at least one argument. 217 // If T is a floating-point type and any of the arguments are NaNs, 218 // max will return NaN. 219 func max[T cmp.Ordered](x T, y ...T) T 220 221 // The min built-in function returns the smallest value of a fixed number of 222 // arguments of [cmp.Ordered] types. There must be at least one argument. 223 // If T is a floating-point type and any of the arguments are NaNs, 224 // min will return NaN. 225 func min[T cmp.Ordered](x T, y ...T) T 226 227 // The built-in function new allocates a new, initialized variable and returns 228 // a pointer to it. It accepts a single argument, which may be either a type 229 // or an expression. 230 // If the argument is a type T, then new(T) allocates a variable of type T 231 // initialized to its zero value. 232 // Otherwise, the argument is an expression x and new(x) allocates a variable 233 // of the type of x initialized to the value of x. If that value is an untyped 234 // constant, it is first implicitly converted to its default type. 235 func new(TypeOrExpr) *Type 236 237 // The complex built-in function constructs a complex value from two 238 // floating-point values. The real and imaginary parts must be of the same 239 // size, either float32 or float64 (or assignable to them), and the return 240 // value will be the corresponding complex type (complex64 for float32, 241 // complex128 for float64). 242 func complex(r, i FloatType) ComplexType 243 244 // The real built-in function returns the real part of the complex number c. 245 // The return value will be floating point type corresponding to the type of c. 246 func real(c ComplexType) FloatType 247 248 // The imag built-in function returns the imaginary part of the complex 249 // number c. The return value will be floating point type corresponding to 250 // the type of c. 251 func imag(c ComplexType) FloatType 252 253 // The clear built-in function clears maps and slices. 254 // For maps, clear deletes all entries, resulting in an empty map. 255 // For slices, clear sets all elements up to the length of the slice 256 // to the zero value of the respective element type. If the argument 257 // type is a type parameter, the type parameter's type set must 258 // contain only map or slice types, and clear performs the operation 259 // implied by the type argument. If t is nil, clear is a no-op. 260 func clear[T ~[]Type | ~map[Type]Type1](t T) 261 262 // The close built-in function closes a channel, which must be either 263 // bidirectional or send-only. It should be executed only by the sender, 264 // never the receiver, and has the effect of shutting down the channel after 265 // the last sent value is received. After the last value has been received 266 // from a closed channel c, any receive from c will succeed without 267 // blocking, returning the zero value for the channel element. The form 268 // 269 // x, ok := <-c 270 // 271 // will also set ok to false for a closed and empty channel. 272 func close(c chan<- Type) 273 274 // The panic built-in function stops normal execution of the current 275 // goroutine. When a function F calls panic, normal execution of F stops 276 // immediately. Any functions whose execution was deferred by F are run in 277 // the usual way, and then F returns to its caller. To the caller G, the 278 // invocation of F then behaves like a call to panic, terminating G's 279 // execution and running any deferred functions. This continues until all 280 // functions in the executing goroutine have stopped, in reverse order. At 281 // that point, the program is terminated with a non-zero exit code. This 282 // termination sequence is called panicking and can be controlled by the 283 // built-in function recover. 284 // 285 // Starting in Go 1.21, calling panic with a nil interface value or an 286 // untyped nil causes a run-time error (a different panic). 287 // The GODEBUG setting panicnil=1 disables the run-time error. 288 func panic(v any) 289 290 // The recover built-in function allows a program to manage behavior of a 291 // panicking goroutine. Executing a call to recover inside a deferred 292 // function (but not any function called by it) stops the panicking sequence 293 // by restoring normal execution and retrieves the error value passed to the 294 // call of panic. If recover is called outside the deferred function it will 295 // not stop a panicking sequence. In this case, or when the goroutine is not 296 // panicking, recover returns nil. 297 // 298 // Prior to Go 1.21, recover would also return nil if panic is called with 299 // a nil argument. See [panic] for details. 300 func recover() any 301 302 // The print built-in function formats its arguments in an 303 // implementation-specific way and writes the result to standard error. 304 // Print is useful for bootstrapping and debugging; it is not guaranteed 305 // to stay in the language. 306 func print(args ...Type) 307 308 // The println built-in function formats its arguments in an 309 // implementation-specific way and writes the result to standard error. 310 // Spaces are always added between arguments and a newline is appended. 311 // Println is useful for bootstrapping and debugging; it is not guaranteed 312 // to stay in the language. 313 func println(args ...Type) 314 315 // The error built-in interface type is the conventional interface for 316 // representing an error condition, with the nil value representing no error. 317 type error interface { 318 Error() string 319 } 320