From: Robert Griesemer Date: Wed, 24 May 2023 18:42:57 +0000 (-0700) Subject: spec: re-order built-ins sections alphabetically (more or less) X-Git-Tag: go1.21rc1~264 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=15a4e0d9703033e0b2be4dc6830f03570df7943e;p=gostls13.git 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 --- 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,6 +7183,89 @@ so they can only appear in call expressions; they cannot be used as function values.

+ +

Appending to and copying slices

+ +

+The built-in functions append and copy assist in +common slice operations. +For both functions, the result is independent of whether the memory referenced +by the arguments overlaps. +

+ +

+The variadic function append +appends zero or more values x to a slice s +and returns the resulting slice of the same type as s. +The core type of s must be a slice +of type []E. +The values x are passed to a parameter of type ...E +and the respective parameter +passing rules apply. +As a special case, if the core type of s is []byte, +append also accepts a second argument with core type +bytestring followed by .... +This form appends the bytes of the byte slice or string. +

+ +
+append(s S, x ...E) S  // core type of S is []E
+
+ +

+If the capacity of s is not large enough to fit the additional +values, append allocates a new, sufficiently large underlying +array that fits both the existing slice elements and the additional values. +Otherwise, append re-uses the underlying array. +

+ +
+s0 := []int{0, 0}
+s1 := append(s0, 2)                // append a single element     s1 is []int{0, 0, 2}
+s2 := append(s1, 3, 5, 7)          // append multiple elements    s2 is []int{0, 0, 2, 3, 5, 7}
+s3 := append(s2, s0...)            // append a slice              s3 is []int{0, 0, 2, 3, 5, 7, 0, 0}
+s4 := append(s3[3:6], s3[2:]...)   // append overlapping slice    s4 is []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
+
+var t []interface{}
+t = append(t, 42, 3.1415, "foo")   //                             t is []interface{}{42, 3.1415, "foo"}
+
+var b []byte
+b = append(b, "bar"...)            // append string contents      b is []byte{'b', 'a', 'r' }
+
+ +

+The function copy copies slice elements from +a source src to a destination dst and returns the +number of elements copied. +The core types of both arguments must be slices +with identical element type. +The number of elements copied is the minimum of +len(src) and len(dst). +As a special case, if the destination's core type is []byte, +copy also accepts a source argument with core type + bytestring. +This form copies the bytes from the byte slice or string into the byte slice. +

+ +
+copy(dst, src []T) int
+copy(dst []byte, src string) int
+
+ +

+Examples: +

+ +
+var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
+var s = make([]int, 6)
+var b = make([]byte, 5)
+n1 := copy(s, a[0:])            // n1 == 6, s is []int{0, 1, 2, 3, 4, 5}
+n2 := copy(s, s[2:])            // n2 == 4, s is []int{2, 3, 4, 5, 4, 5}
+n3 := copy(b, "Hello, World!")  // n3 == 5, b is []byte("Hello")
+
+ +

Clear

@@ -7213,6 +7296,7 @@ performs the operation corresponding to the actual type argument. If the map or slice is nil, clear is a no-op.

+

Close

@@ -7229,6 +7313,100 @@ The multi-valued receive operation returns a received value along with an indication of whether the channel is closed.

+ +

Manipulating complex numbers

+ +

+Three functions assemble and disassemble complex numbers. +The built-in function complex constructs a complex +value from a floating-point real and imaginary part, while +real and imag +extract the real and imaginary parts of a complex value. +

+ +
+complex(realPart, imaginaryPart floatT) complexT
+real(complexT) floatT
+imag(complexT) floatT
+
+ +

+The type of the arguments and return value correspond. +For complex, the two arguments must be of the same +floating-point type and the return type is the +complex type +with the corresponding floating-point constituents: +complex64 for float32 arguments, and +complex128 for float64 arguments. +If one of the arguments evaluates to an untyped constant, it is first implicitly +converted to the type of the other argument. +If both arguments evaluate to untyped constants, they must be non-complex +numbers or their imaginary parts must be zero, and the return value of +the function is an untyped complex constant. +

+ +

+For real and imag, the argument must be +of complex type, and the return type is the corresponding floating-point +type: float32 for a complex64 argument, and +float64 for a complex128 argument. +If the argument evaluates to an untyped constant, it must be a number, +and the return value of the function is an untyped floating-point constant. +

+ +

+The real and imag functions together form the inverse of +complex, so for a value z of a complex type Z, +z == Z(complex(real(z), imag(z))). +

+ +

+If the operands of these functions are all constants, the return +value is a constant. +

+ +
+var a = complex(2, -2)             // complex128
+const b = complex(1.0, -1.4)       // untyped complex constant 1 - 1.4i
+x := float32(math.Cos(math.Pi/2))  // float32
+var c64 = complex(5, -x)           // complex64
+var s int = complex(1, 0)          // untyped complex constant 1 + 0i can be converted to int
+_ = complex(1, 2<<s)               // illegal: 2 assumes floating-point type, cannot shift
+var rl = real(c64)                 // float32
+var im = imag(a)                   // float64
+const c = imag(b)                  // untyped constant -1.4
+_ = imag(3 << s)                   // illegal: 3 assumes complex type, cannot shift
+
+ +

+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

@@ -7299,36 +7477,6 @@ const ( 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

@@ -7355,7 +7503,6 @@ 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, @@ -7384,179 +7531,37 @@ The precise behavior is implementation-dependent.

-

Appending to and copying slices

- -

-The built-in functions append and copy assist in -common slice operations. -For both functions, the result is independent of whether the memory referenced -by the arguments overlaps. -

- -

-The variadic function append -appends zero or more values x to a slice s -and returns the resulting slice of the same type as s. -The core type of s must be a slice -of type []E. -The values x are passed to a parameter of type ...E -and the respective parameter -passing rules apply. -As a special case, if the core type of s is []byte, -append also accepts a second argument with core type -bytestring followed by .... -This form appends the bytes of the byte slice or string. -

- -
-append(s S, x ...E) S  // core type of S is []E
-
- -

-If the capacity of s is not large enough to fit the additional -values, append allocates a new, sufficiently large underlying -array that fits both the existing slice elements and the additional values. -Otherwise, append re-uses the underlying array. -

- -
-s0 := []int{0, 0}
-s1 := append(s0, 2)                // append a single element     s1 is []int{0, 0, 2}
-s2 := append(s1, 3, 5, 7)          // append multiple elements    s2 is []int{0, 0, 2, 3, 5, 7}
-s3 := append(s2, s0...)            // append a slice              s3 is []int{0, 0, 2, 3, 5, 7, 0, 0}
-s4 := append(s3[3:6], s3[2:]...)   // append overlapping slice    s4 is []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
-
-var t []interface{}
-t = append(t, 42, 3.1415, "foo")   //                             t is []interface{}{42, 3.1415, "foo"}
-
-var b []byte
-b = append(b, "bar"...)            // append string contents      b is []byte{'b', 'a', 'r' }
-
+

Allocation

-The function copy copies slice elements from -a source src to a destination dst and returns the -number of elements copied. -The core types of both arguments must be slices -with identical element type. -The number of elements copied is the minimum of -len(src) and len(dst). -As a special case, if the destination's core type is []byte, -copy also accepts a source argument with core type - bytestring. -This form copies the bytes from the byte slice or string into the byte slice. +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. 

-copy(dst, src []T) int
-copy(dst []byte, src string) int
+new(T)

-Examples: +For instance 

-var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
-var s = make([]int, 6)
-var b = make([]byte, 5)
-n1 := copy(s, a[0:])            // n1 == 6, s is []int{0, 1, 2, 3, 4, 5}
-n2 := copy(s, s[2:])            // n2 == 4, s is []int{2, 3, 4, 5, 4, 5}
-n3 := copy(b, "Hello, World!")  // n3 == 5, b is []byte("Hello")
-
- - -

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. -

- - -

Manipulating complex numbers

- -

-Three functions assemble and disassemble complex numbers. -The built-in function complex constructs a complex -value from a floating-point real and imaginary part, while -real and imag -extract the real and imaginary parts of a complex value. -

- -
-complex(realPart, imaginaryPart floatT) complexT
-real(complexT) floatT
-imag(complexT) floatT
+type S struct { a int; b float64 }
+new(S)

-The type of the arguments and return value correspond. -For complex, the two arguments must be of the same -floating-point type and the return type is the -complex type -with the corresponding floating-point constituents: -complex64 for float32 arguments, and -complex128 for float64 arguments. -If one of the arguments evaluates to an untyped constant, it is first implicitly -converted to the type of the other argument. -If both arguments evaluate to untyped constants, they must be non-complex -numbers or their imaginary parts must be zero, and the return value of -the function is an untyped complex constant. -

- -

-For real and imag, the argument must be -of complex type, and the return type is the corresponding floating-point -type: float32 for a complex64 argument, and -float64 for a complex128 argument. -If the argument evaluates to an untyped constant, it must be a number, -and the return value of the function is an untyped floating-point constant. -

- -

-The real and imag functions together form the inverse of -complex, so for a value z of a complex type Z, -z == Z(complex(real(z), imag(z))). -

- -

-If the operands of these functions are all constants, the return -value is a constant. +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.

-
-var a = complex(2, -2)             // complex128
-const b = complex(1.0, -1.4)       // untyped complex constant 1 - 1.4i
-x := float32(math.Cos(math.Pi/2))  // float32
-var c64 = complex(5, -x)           // complex64
-var s int = complex(1, 0)          // untyped complex constant 1 + 0i can be converted to int
-_ = complex(1, 2<<s)               // illegal: 2 assumes floating-point type, cannot shift
-var rl = real(c64)                 // float32
-var im = imag(a)                   // float64
-const c = imag(b)                  // untyped constant -1.4
-_ = imag(3 << s)                   // illegal: 3 assumes complex type, cannot shift
-
- -

-Arguments of type parameter type are not permitted. -

Handling panics

@@ -7655,6 +7660,7 @@ accept arbitrary argument types, but printing of boolean, numeric, and string types must be supported.

+

Packages