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