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*/ 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// 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. 97const 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. 101var 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. 106type 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. 111type 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. 115type 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. 119type 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. 123type 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"...) 134func 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). 141func 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. 146func 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// For some arguments, such as a string literal or a simple array expression, the 156// result can be a constant. See the Go language specification's "Length and 157// capacity" section for details. 158func len(v Type) int 159 160// The cap built-in function returns the capacity of v, according to its type: 161// Array: the number of elements in v (same as len(v)). 162// Pointer to array: the number of elements in *v (same as len(v)). 163// Slice: the maximum length the slice can reach when resliced; 164// if v is nil, cap(v) is zero. 165// Channel: the channel buffer capacity, in units of elements; 166// if v is nil, cap(v) is zero. 167// For some arguments, such as a simple array expression, the result can be a 168// constant. See the Go language specification's "Length and capacity" section for 169// details. 170func cap(v Type) int 171 172// The make built-in function allocates and initializes an object of type 173// slice, map, or chan (only). Like new, the first argument is a type, not a 174// value. Unlike new, make's return type is the same as the type of its 175// argument, not a pointer to it. The specification of the result depends on 176// the type: 177// Slice: The size specifies the length. The capacity of the slice is 178// equal to its length. A second integer argument may be provided to 179// specify a different capacity; it must be no smaller than the 180// length. For example, make([]int, 0, 10) allocates an underlying array 181// of size 10 and returns a slice of length 0 and capacity 10 that is 182// backed by this underlying array. 183// Map: An empty map is allocated with enough space to hold the 184// specified number of elements. The size may be omitted, in which case 185// a small starting size is allocated. 186// Channel: The channel's buffer is initialized with the specified 187// buffer capacity. If zero, or the size is omitted, the channel is 188// unbuffered. 189func make(t Type, size ...IntegerType) Type 190 191// The new built-in function allocates memory. The first argument is a type, 192// not a value, and the value returned is a pointer to a newly 193// allocated zero value of that type. 194func new(Type) *Type 195 196// The complex built-in function constructs a complex value from two 197// floating-point values. The real and imaginary parts must be of the same 198// size, either float32 or float64 (or assignable to them), and the return 199// value will be the corresponding complex type (complex64 for float32, 200// complex128 for float64). 201func complex(r, i FloatType) ComplexType 202 203// The real built-in function returns the real part of the complex number c. 204// The return value will be floating point type corresponding to the type of c. 205func real(c ComplexType) FloatType 206 207// The imag built-in function returns the imaginary part of the complex 208// number c. The return value will be floating point type corresponding to 209// the type of c. 210func imag(c ComplexType) FloatType 211 212// The close built-in function closes a channel, which must be either 213// bidirectional or send-only. It should be executed only by the sender, 214// never the receiver, and has the effect of shutting down the channel after 215// the last sent value is received. After the last value has been received 216// from a closed channel c, any receive from c will succeed without 217// blocking, returning the zero value for the channel element. The form 218// x, ok := <-c 219// will also set ok to false for a closed channel. 220func close(c chan<- Type) 221 222// The panic built-in function stops normal execution of the current 223// goroutine. When a function F calls panic, normal execution of F stops 224// immediately. Any functions whose execution was deferred by F are run in 225// the usual way, and then F returns to its caller. To the caller G, the 226// invocation of F then behaves like a call to panic, terminating G's 227// execution and running any deferred functions. This continues until all 228// functions in the executing goroutine have stopped, in reverse order. At 229// that point, the program is terminated with a non-zero exit code. This 230// termination sequence is called panicking and can be controlled by the 231// built-in function recover. 232func panic(v interface{}) 233 234// The recover built-in function allows a program to manage behavior of a 235// panicking goroutine. Executing a call to recover inside a deferred 236// function (but not any function called by it) stops the panicking sequence 237// by restoring normal execution and retrieves the error value passed to the 238// call of panic. If recover is called outside the deferred function it will 239// not stop a panicking sequence. In this case, or when the goroutine is not 240// panicking, or if the argument supplied to panic was nil, recover returns 241// nil. Thus the return value from recover reports whether the goroutine is 242// panicking. 243func recover() interface{} 244 245// The print built-in function formats its arguments in an 246// implementation-specific way and writes the result to standard error. 247// Print is useful for bootstrapping and debugging; it is not guaranteed 248// to stay in the language. 249func print(args ...Type) 250 251// The println built-in function formats its arguments in an 252// implementation-specific way and writes the result to standard error. 253// Spaces are always added between arguments and a newline is appended. 254// Println is useful for bootstrapping and debugging; it is not guaranteed 255// to stay in the language. 256func println(args ...Type) 257 258// The error built-in interface type is the conventional interface for 259// representing an error condition, with the nil value representing no error. 260type error interface { 261 Error() string 262} 263