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