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