From 15a4e0d9703033e0b2be4dc6830f03570df7943e Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Wed, 24 May 2023 11:42:57 -0700 Subject: [PATCH] spec: re-order built-ins sections alphabetically (more or less) Put the sections for the various built-ins into alphabetical order based on the built-in name, while keeping built-ins that belong together together. The order is now (captialized letter determines order): - Append - Clear - Close - Complex, real, imag - Delete - Len, cap - Make - Min, max (to be inserted here) - New - Panic, recover - Print, println There are some white space adjustments but no changes to the prose of the moved sections. Change-Id: Iaec509918c6bc965df3f28656374de03279bdc9e Reviewed-on: https://go-review.googlesource.com/c/go/+/498135 Reviewed-by: Robert Griesemer TryBot-Bypass: Robert Griesemer Reviewed-by: Ian Lance Taylor --- doc/go_spec.html | 428 ++++++++++++++++++++++++----------------------- 1 file changed, 217 insertions(+), 211 deletions(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index 51af33c175..3f24b53f7f 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ @@ -7183,206 +7183,6 @@ so they can only appear in call expressions; they cannot be used as function values.

-

Clear

- -

-The built-in function clear takes an argument of map, -slice, or type parameter type, -and deletes or zeroes out all elements. -

- -
-Call        Argument type     Result
-
-clear(m)    map[K]T           deletes all entries, resulting in an
-                              empty map (len(m) == 0)
-
-clear(s)    []T               sets all elements up to the length of
-                              s to the zero value of T
-
-clear(t)    type parameter    see below
-
- -

-If the argument type is a type parameter, -all types in its type set must be maps or slices, and clear -performs the operation corresponding to the actual type argument. -

- -

-If the map or slice is nil, clear is a no-op. -

- -

Close

- -

-For an argument ch with a core type -that is a channel, the built-in function close -records that no more values will be sent on the channel. -It is an error if ch is a receive-only channel. -Sending to or closing a closed channel causes a run-time panic. -Closing the nil channel also causes a run-time panic. -After calling close, and after any previously -sent values have been received, receive operations will return -the zero value for the channel's type without blocking. -The multi-valued receive operation -returns a received value along with an indication of whether the channel is closed. -

- -

Length and capacity

- -

-The built-in functions len and cap take arguments -of various types and return a result of type int. -The implementation guarantees that the result always fits into an int. -

- -
-Call      Argument type    Result
-
-len(s)    string type      string length in bytes
-          [n]T, *[n]T      array length (== n)
-          []T              slice length
-          map[K]T          map length (number of defined keys)
-          chan T           number of elements queued in channel buffer
-          type parameter   see below
-
-cap(s)    [n]T, *[n]T      array length (== n)
-          []T              slice capacity
-          chan T           channel buffer capacity
-          type parameter   see below
-
- -

-If the argument type is a type parameter P, -the call len(e) (or cap(e) respectively) must be valid for -each type in P's type set. -The result is the length (or capacity, respectively) of the argument whose type -corresponds to the type argument with which P was -instantiated. -

- -

-The capacity of a slice is the number of elements for which there is -space allocated in the underlying array. -At any time the following relationship holds: -

- -
-0 <= len(s) <= cap(s)
-
- -

-The length of a nil slice, map or channel is 0. -The capacity of a nil slice or channel is 0. -

- -

-The expression len(s) is constant if -s is a string constant. The expressions len(s) and -cap(s) are constants if the type of s is an array -or pointer to an array and the expression s does not contain -channel receives or (non-constant) -function calls; in this case s is not evaluated. -Otherwise, invocations of len and cap are not -constant and s is evaluated. -

- -
-const (
-	c1 = imag(2i)                    // imag(2i) = 2.0 is a constant
-	c2 = len([10]float64{2})         // [10]float64{2} contains no function calls
-	c3 = len([10]float64{c1})        // [10]float64{c1} contains no function calls
-	c4 = len([10]float64{imag(2i)})  // imag(2i) is a constant and no function call is issued
-	c5 = len([10]float64{imag(z)})   // invalid: imag(z) is a (non-constant) function call
-)
-var z complex128
-
- -

Allocation

- -

-The built-in function new takes a type T, -allocates storage for a variable of that type -at run time, and returns a value of type *T -pointing to it. -The variable is initialized as described in the section on -initial values. -

- -
-new(T)
-
- -

-For instance -

- -
-type S struct { a int; b float64 }
-new(S)
-
- -

-allocates storage for a variable of type S, -initializes it (a=0, b=0.0), -and returns a value of type *S containing the address -of the location. -

- -

Making slices, maps and channels

- -

-The built-in function make takes a type T, -optionally followed by a type-specific list of expressions. -The core type of T must -be a slice, map or channel. -It returns a value of type T (not *T). -The memory is initialized as described in the section on -initial values. -

- -
-Call             Core type    Result
-
-make(T, n)       slice        slice of type T with length n and capacity n
-make(T, n, m)    slice        slice of type T with length n and capacity m
-
-make(T)          map          map of type T
-make(T, n)       map          map of type T with initial space for approximately n elements
-
-make(T)          channel      unbuffered channel of type T
-make(T, n)       channel      buffered channel of type T, buffer size n
-
- - -

-Each of the size arguments n and m must be of integer type, -have a type set containing only integer types, -or be an untyped constant. -A constant size argument must be non-negative and representable -by a value of type int; if it is an untyped constant it is given type int. -If both n and m are provided and are constant, then -n must be no larger than m. -For slices and channels, if n is negative or larger than m at run time, -a run-time panic occurs. -

- -
-s := make([]int, 10, 100)       // slice with len(s) == 10, cap(s) == 100
-s := make([]int, 1e3)           // slice with len(s) == cap(s) == 1000
-s := make([]int, 1<<63)         // illegal: len(s) is not representable by a value of type int
-s := make([]int, 10, 0)         // illegal: len(s) > cap(s)
-c := make(chan int, 10)         // channel with a buffer size of 10
-m := make(map[string]int, 100)  // map with initial space for approximately 100 elements
-
- -

-Calling make with a map type and size hint n will -create a map with initial space to hold n map elements. -The precise behavior is implementation-dependent. -

-

Appending to and copying slices

@@ -7466,27 +7266,51 @@ n3 := copy(b, "Hello, World!") // n3 == 5, b is []byte("Hello") -

Deletion of map elements

+

Clear

-The built-in function delete removes the element with key -k from a map m. The -value k must be assignable -to the key type of m. +The built-in function clear takes an argument of map, +slice, or type parameter type, +and deletes or zeroes out all elements. 

-delete(m, k)  // remove element m[k] from map m
+Call        Argument type     Result
+
+clear(m)    map[K]T           deletes all entries, resulting in an
+                              empty map (len(m) == 0)
+
+clear(s)    []T               sets all elements up to the length of
+                              s to the zero value of T
+
+clear(t)    type parameter    see below

-If the type of m is a type parameter, -all types in that type set must be maps, and they must all have identical key types. +If the argument type is a type parameter, +all types in its type set must be maps or slices, and clear +performs the operation corresponding to the actual type argument.

-If the map m is nil or the element m[k] -does not exist, delete is a no-op. +If the map or slice is nil, clear is a no-op. +

+ + +

Close

+ +

+For an argument ch with a core type +that is a channel, the built-in function close +records that no more values will be sent on the channel. +It is an error if ch is a receive-only channel. +Sending to or closing a closed channel causes a run-time panic. +Closing the nil channel also causes a run-time panic. +After calling close, and after any previously +sent values have been received, receive operations will return +the zero value for the channel's type without blocking. +The multi-valued receive operation +returns a received value along with an indication of whether the channel is closed.

@@ -7558,6 +7382,187 @@ _ = imag(3 << s) // illegal: 3 assumes complex type, can Arguments of type parameter type are not permitted.

+ +

Deletion of map elements

+ +

+The built-in function delete removes the element with key +k from a map m. The +value k must be assignable +to the key type of m. +

+ +
+delete(m, k)  // remove element m[k] from map m
+
+ +

+If the type of m is a type parameter, +all types in that type set must be maps, and they must all have identical key types. +

+ +

+If the map m is nil or the element m[k] +does not exist, delete is a no-op. +

+ + +

Length and capacity

+ +

+The built-in functions len and cap take arguments +of various types and return a result of type int. +The implementation guarantees that the result always fits into an int. +

+ +
+Call      Argument type    Result
+
+len(s)    string type      string length in bytes
+          [n]T, *[n]T      array length (== n)
+          []T              slice length
+          map[K]T          map length (number of defined keys)
+          chan T           number of elements queued in channel buffer
+          type parameter   see below
+
+cap(s)    [n]T, *[n]T      array length (== n)
+          []T              slice capacity
+          chan T           channel buffer capacity
+          type parameter   see below
+
+ +

+If the argument type is a type parameter P, +the call len(e) (or cap(e) respectively) must be valid for +each type in P's type set. +The result is the length (or capacity, respectively) of the argument whose type +corresponds to the type argument with which P was +instantiated. +

+ +

+The capacity of a slice is the number of elements for which there is +space allocated in the underlying array. +At any time the following relationship holds: +

+ +
+0 <= len(s) <= cap(s)
+
+ +

+The length of a nil slice, map or channel is 0. +The capacity of a nil slice or channel is 0. +

+ +

+The expression len(s) is constant if +s is a string constant. The expressions len(s) and +cap(s) are constants if the type of s is an array +or pointer to an array and the expression s does not contain +channel receives or (non-constant) +function calls; in this case s is not evaluated. +Otherwise, invocations of len and cap are not +constant and s is evaluated. +

+ +
+const (
+	c1 = imag(2i)                    // imag(2i) = 2.0 is a constant
+	c2 = len([10]float64{2})         // [10]float64{2} contains no function calls
+	c3 = len([10]float64{c1})        // [10]float64{c1} contains no function calls
+	c4 = len([10]float64{imag(2i)})  // imag(2i) is a constant and no function call is issued
+	c5 = len([10]float64{imag(z)})   // invalid: imag(z) is a (non-constant) function call
+)
+var z complex128
+
+ + +

Making slices, maps and channels

+ +

+The built-in function make takes a type T, +optionally followed by a type-specific list of expressions. +The core type of T must +be a slice, map or channel. +It returns a value of type T (not *T). +The memory is initialized as described in the section on +initial values. +

+ +
+Call             Core type    Result
+
+make(T, n)       slice        slice of type T with length n and capacity n
+make(T, n, m)    slice        slice of type T with length n and capacity m
+
+make(T)          map          map of type T
+make(T, n)       map          map of type T with initial space for approximately n elements
+
+make(T)          channel      unbuffered channel of type T
+make(T, n)       channel      buffered channel of type T, buffer size n
+
+ +

+Each of the size arguments n and m must be of integer type, +have a type set containing only integer types, +or be an untyped constant. +A constant size argument must be non-negative and representable +by a value of type int; if it is an untyped constant it is given type int. +If both n and m are provided and are constant, then +n must be no larger than m. +For slices and channels, if n is negative or larger than m at run time, +a run-time panic occurs. +

+ +
+s := make([]int, 10, 100)       // slice with len(s) == 10, cap(s) == 100
+s := make([]int, 1e3)           // slice with len(s) == cap(s) == 1000
+s := make([]int, 1<<63)         // illegal: len(s) is not representable by a value of type int
+s := make([]int, 10, 0)         // illegal: len(s) > cap(s)
+c := make(chan int, 10)         // channel with a buffer size of 10
+m := make(map[string]int, 100)  // map with initial space for approximately 100 elements
+
+ +

+Calling make with a map type and size hint n will +create a map with initial space to hold n map elements. +The precise behavior is implementation-dependent. +

+ + +

Allocation

+ +

+The built-in function new takes a type T, +allocates storage for a variable of that type +at run time, and returns a value of type *T +pointing to it. +The variable is initialized as described in the section on +initial values. +

+ +
+new(T)
+
+ +

+For instance +

+ +
+type S struct { a int; b float64 }
+new(S)
+
+ +

+allocates storage for a variable of type S, +initializes it (a=0, b=0.0), +and returns a value of type *S containing the address +of the location. +

+ +

Handling panics

Two built-in functions, panic and recover, @@ -7655,6 +7660,7 @@ accept arbitrary argument types, but printing of boolean, numeric, and string types must be supported.

+

Packages