Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(3158)

Delta Between Two Patch Sets: src/pkg/builtin/builtin.go

Issue 4907041: code review 4907041: builtin: add documentation for builtins (Closed)
Left Patch Set: diff -r af3bbd9ae031 https://go.googlecode.com/hg/ Created 12 years, 7 months ago
Right Patch Set: diff -r 27f839c9fae4 https://go.googlecode.com/hg/ Created 12 years, 7 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | no next file » | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
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{}
LEFTRIGHT
« no previous file | no next file » | Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Toggle Comments ('s')

Powered by Google App Engine
RSS Feeds Recent Issues | This issue
This is Rietveld f62528b