Left: | ||
Right: |
OLD | NEW |
---|---|
(Empty) | |
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 built-in functions. | |
7 The functions documented here are not actually in package builtin | |
8 but their descriptions here allow godoc to present documentation | |
9 for the language's special functions. | |
10 */ | |
11 package builtin | |
12 | |
13 // AnyType is here for the purposes of documentation only. It is a stand-in | |
dsymonds
2011/08/15 03:19:35
rouge double-space after period
| |
14 // for any Go type, but represents the same type for any given function | |
15 // invocation. | |
16 type AnyType int | |
dsymonds
2011/08/15 03:19:35
did you consider using "T" as the name for this?
r
2011/08/15 03:31:43
The unsafe package uses "ArbitraryType", which is
niemeyer
2011/08/15 03:38:24
This is definitely subjective, but I find it diffi
epaz1733
2021/10/20 08:03:05
Done.
mithunshope
2023/01/18 12:57:24
Done.
| |
17 | |
18 // IntegerType is here for the purposes of documentation only. It is a stand-in | |
19 // for any integer type: int, uint int8 etc. | |
20 type IntegerType int | |
21 | |
22 // FloatType is here for the purposes of documentation only. It is a stand-in | |
23 // for either float type: float32 or float64. | |
24 type FloatType int | |
25 | |
26 // ComplexType is here for the purposes of documentation only. It is a | |
27 // stand-in for either complex type: complex64 or complex128. | |
28 type ComplexType int | |
29 | |
30 // The append built-in function appends elements to the end of a slice. If | |
31 // it has sufficient capacity, the destination is resliced to accommodate the | |
32 // new elements. If it does not, a new slice (and underlying array) will be | |
niemeyer
2011/08/15 03:38:24
I believe a new slice will be allocated either way
| |
33 // allocated. Append returns the updated slice. It is therefore necessary | |
34 // to store the result of append, often in the variable holding the slice | |
35 // itself: | |
36 // slice = append(slice, elem1, elem2) | |
37 // slice = appedn(slice, anotherSlice...) | |
38 func append(slice []AnyType, elems ...AnyType) []AnyType | |
39 | |
40 // The copy built-in function copies elements from a source slice into a | |
41 // destination slice. (As a special case, it also will copy bytes from a | |
niemeyer
2011/08/15 03:38:24
I didn't know that.. good to have docs.
| |
42 // string to a slice of bytes.) The source and destination may overlap. Copy | |
43 // returns the number of elements copied, which will be the minimum of | |
44 // len(src) and len(dst). | |
45 func copy(dst, src []AnyType) int | |
46 | |
47 // The len built-in function returns the length of v, according to its type: | |
48 // Array, slice, or map: the number of elements in v. | |
49 // Pointer to array: the number of elements in *v. | |
50 // String: the number of byes in v. | |
niemeyer
2011/08/15 03:38:24
Typo
mithunshope
2023/01/18 12:57:24
Done.
| |
51 // Channel: the number of elements queued (unread) in the channel buffer. | |
52 func len(v AnyType) int | |
dsymonds
2011/08/15 03:19:35
want to call out the cases for nil values?
| |
53 | |
54 // The cap built-in function returns the capacity of v, according to its type: | |
55 // Array: the number of elements in v (same as len(v)). | |
56 // Pointer to array: the number of elements in *v (same as len(v)). | |
57 // Slice: the maximum length the slice can reach when resliced. | |
58 // Channel: the maximum channel buffer capacity, in units of elements. | |
59 func cap(v AnyType) int | |
60 | |
61 // The make built-in function allocates and initializes an object of type | |
62 // slice, map, or chan (only). Like new, the first argument is a type, not a | |
63 // value. Unlike new, make's return type is the same as the type of its | |
64 // argument, not a pointer to it. The specification of the result depends on | |
65 // the type: | |
66 // Slice: The size specifies the length. The capacity of the slice is | |
67 // equal to its length. A second integer argument may be provided to | |
68 // specify a different capacity; it must be no smaller than the | |
69 // length, so make([]int, 0, 10) allocates a slice of length 0 and | |
70 // capacity 10. | |
71 // Map: An initial allocation is made according to the size but the | |
72 // resulting map has length 0. The size may be omitted, in which case | |
dsymonds
2011/08/15 03:19:35
double space
| |
73 // a small starting size is allocated. | |
74 // Chan: The channel's buffer is initialized with the specified buffer | |
dsymonds
2011/08/15 03:19:35
s/Chan/Channel/, like len and cap.
| |
75 // capacity. If zero, or the size is omitted, the channel is | |
dsymonds
2011/08/15 03:19:35
double space
| |
76 // unbuffered. | |
77 func make(AnyType, size IntegerType) AnyType | |
78 | |
79 // The new built-in function allocates memory. The first argument is a type, | |
dsymonds
2011/08/15 03:19:35
double space
| |
80 // not a value, and the value returned is a pointer to a newly | |
81 // allocated zero value of that type. | |
82 func new(AnyType) *AnyType | |
83 | |
84 // The complex built-in function constructs a complex value from two | |
85 // floating-point values. The real and imaginary parts must be of the same | |
86 // size, either float32 or float64 (or assignable to them), and the return | |
87 // value will be the corresponding complex type (complex64 for float32, | |
88 // complex128 for float64). | |
89 func complex(r, i FloatType) ComplexType | |
90 | |
91 // The real built-in function returns the real part of the complex number c. | |
92 // The return value will be floating point type corresponding to the type of c. | |
93 func real(c ComplexType) FloatType | |
94 | |
95 // The imaginary built-in function returns the imaginary part of the complex | |
96 // number c. The return value will be floating point type corresponding to | |
97 // the type of c. | |
98 func imag(c ComplexType) FloatType | |
99 | |
100 // The close built-in function closes a channel, which must be either | |
101 // bidirectional or send-only. It should be executed only by the sender, | |
102 // never the receiver, and has the effect of shutting down the channel after | |
103 // the last sent value is received. After the last value has been received | |
104 // from a closed channel c, | |
105 // x, ok := <-c | |
106 // will set x to the channel element's zero value and ok to false, and select | |
107 // clauses involving c will never execute. | |
108 func close(c chan AnyType) | |
dsymonds
2011/08/15 03:19:35
You could add a send-only annotation here; that wo
| |
109 | |
110 // The panic built-in function stops normal execution of the current | |
111 // goroutine. When a function F calls panic, normal execution of F stops | |
112 // immediately. Any functions whose execution was deferred by F are run in | |
113 // the usual way, and then F returns to its caller. To the caller G, the | |
114 // invocation of F then behaves like a call to panic, terminating G's | |
115 // execution and running any deferred functions. This continues until all | |
116 // functions in the executing goroutine have stopped, in reverse order. At | |
117 // that point, the program is terminated and the error condition is reported, | |
118 // including the value of the argument to panic. This termination sequence | |
119 // is called panicking and can be controlled by the built-in function | |
120 // recover. | |
121 func panic(v interface{}) | |
122 | |
123 // The recover built-in function allows a program to manage behavior of a | |
124 // panicking goroutine. Executing a call to recover inside a deferred | |
125 // function (but not any function called by it) stops the panicking sequence | |
126 // by restoring normal execution and retrieves the error value passed to the | |
127 // call of panic. If recover is called outside the deferred function it will | |
128 // not stop a panicking sequence. In this case, or when the goroutine is not | |
129 // panicking, or if the argument supplied to panic was nil, recover returns | |
130 // nil. Thus the return value from recover reports whether the goroutine is | |
131 // panicking. | |
132 func recover() interface{} | |
OLD | NEW |