diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/asm.html | 17 | ||||
-rw-r--r-- | doc/go1.17_spec.html | 12 | ||||
-rw-r--r-- | doc/go_mem.html | 16 | ||||
-rw-r--r-- | doc/go_spec.html | 374 | ||||
-rw-r--r-- | doc/godebug.md | 64 |
5 files changed, 414 insertions, 69 deletions
diff --git a/doc/asm.html b/doc/asm.html index f7787a407..dd395ec83 100644 --- a/doc/asm.html +++ b/doc/asm.html @@ -464,6 +464,23 @@ Function is the outermost frame of the call stack. Traceback should stop at this </li> </ul> +<h3 id="special-instructions">Special instructions</h3> + +<p> +The <code>PCALIGN</code> pseudo-instruction is used to indicate that the next instruction should be aligned +to a specified boundary by padding with no-op instructions. +</p> + +<p> +It is currently supported on arm64, amd64, ppc64, loong64 and riscv64. + +For example, the start of the <code>MOVD</code> instruction below is aligned to 32 bytes: +<pre> +PCALIGN $32 +MOVD $2, R0 +</pre> +</p> + <h3 id="data-offsets">Interacting with Go types and constants</h3> <p> diff --git a/doc/go1.17_spec.html b/doc/go1.17_spec.html index 0b374e7bf..c87d9aff3 100644 --- a/doc/go1.17_spec.html +++ b/doc/go1.17_spec.html @@ -7,8 +7,11 @@ <h2 id="Introduction">Introduction</h2> <p> -This is a reference manual for the Go programming language. For -more information and other documents, see <a href="/">golang.org</a>. +This is the reference manual for the Go programming language as it was for +language version 1.17, in October 2021, before the introduction of generics. +It is provided for historical interest. +The current reference manual can be found <a href="/doc/go_spec.html">here</a>. +For more information and other documents, see <a href="/">go.dev</a>. </p> <p> @@ -914,7 +917,7 @@ are required when different numeric types are mixed in an expression or assignment. For instance, <code>int32</code> and <code>int</code> are not the same type even though they may have the same size on a particular architecture. - +</p> <h3 id="String_types">String types</h3> @@ -1451,6 +1454,7 @@ maps grow to accommodate the number of items stored in them, with the exception of <code>nil</code> maps. A <code>nil</code> map is equivalent to an empty map except that no elements may be added. +</p> <h3 id="Channel_types">Channel types</h3> @@ -3641,6 +3645,8 @@ As the <code>++</code> and <code>--</code> operators form statements, not expressions, they fall outside the operator hierarchy. As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. +</p> + <p> There are five precedence levels for binary operators. Multiplication operators bind strongest, followed by addition diff --git a/doc/go_mem.html b/doc/go_mem.html index 661e1e781..026c1172e 100644 --- a/doc/go_mem.html +++ b/doc/go_mem.html @@ -159,6 +159,7 @@ union of the sequenced before and synchronized before relations. For an ordinary (non-synchronizing) data read <i>r</i> on a memory location <i>x</i>, <i>W</i>(<i>r</i>) must be a write <i>w</i> that is <i>visible</i> to <i>r</i>, where visible means that both of the following hold: +</p> <ol> <li><i>w</i> happens before <i>r</i>. @@ -221,7 +222,7 @@ for programs that do contain races. </p> <p> -First, any implementation can, upon detecting a data race, +Any implementation can, upon detecting a data race, report the race and halt execution of the program. Implementations using ThreadSanitizer (accessed with “<code>go</code> <code>build</code> <code>-race</code>”) @@ -229,7 +230,18 @@ do exactly this. </p> <p> -Otherwise, a read <i>r</i> of a memory location <i>x</i> +A read of an array, struct, or complex number +may by implemented as a read of each individual sub-value +(array element, struct field, or real/imaginary component), +in any order. +Similarly, a write of an array, struct, or complex number +may be implemented as a write of each individual sub-value, +in any order. +</p> + +<p> +A read <i>r</i> of a memory location <i>x</i> +holding a value that is not larger than a machine word must observe some write <i>w</i> such that <i>r</i> does not happen before <i>w</i> and there is no write <i>w'</i> such that <i>w</i> happens before <i>w'</i> diff --git a/doc/go_spec.html b/doc/go_spec.html index c39a44236..7b9dd3862 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ <!--{ "Title": "The Go Programming Language Specification", - "Subtitle": "Version of Aug 2, 2023", + "Subtitle": "Language version go1.22 (Feb 6, 2024)", "Path": "/ref/spec" }--> @@ -10,7 +10,7 @@ This is the reference manual for the Go programming language. The pre-Go1.18 version, without generics, can be found <a href="/doc/go1.17_spec.html">here</a>. -For more information and other documents, see <a href="/">golang.org</a>. +For more information and other documents, see <a href="/">go.dev</a>. </p> <p> @@ -70,6 +70,14 @@ enumerations or code snippets that are not further specified. The character <cod language. </p> +<p> +A link of the form [<a href="#Language_versions">Go 1.xx</a>] indicates that a described +language feature (or some aspect of it) was changed or added with language version 1.xx and +thus requires at minimum that language version to build. +For details, see the <a href="#Language_versions">linked section</a> +in the <a href="#Appendix">appendix</a>. +</p> + <h2 id="Source_code_representation">Source code representation</h2> <p> @@ -263,7 +271,8 @@ continue for import return var <p> The following character sequences represent <a href="#Operators">operators</a> -(including <a href="#Assignment_statements">assignment operators</a>) and punctuation: +(including <a href="#Assignment_statements">assignment operators</a>) and punctuation +[<a href="#Go_1.18">Go 1.18</a>]: </p> <pre class="grammar"> + & += &= && == != ( ) @@ -281,7 +290,8 @@ An integer literal is a sequence of digits representing an <a href="#Constants">integer constant</a>. An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code> for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal, -and <code>0x</code> or <code>0X</code> for hexadecimal. +and <code>0x</code> or <code>0X</code> for hexadecimal +[<a href="#Go_1.13">Go 1.13</a>]. A single <code>0</code> is considered a decimal zero. In hexadecimal literals, letters <code>a</code> through <code>f</code> and <code>A</code> through <code>F</code> represent values 10 through 15. @@ -347,7 +357,8 @@ prefix, an integer part (hexadecimal digits), a radix point, a fractional part ( and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits). One of the integer part or the fractional part may be elided; the radix point may be elided as well, but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.) -An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>. +An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup> +[<a href="#Go_1.13">Go 1.13</a>]. </p> <p> @@ -411,7 +422,8 @@ It consists of an <a href="#Integer_literals">integer</a> or <a href="#Floating-point_literals">floating-point</a> literal followed by the lowercase letter <code>i</code>. The value of an imaginary literal is the value of the respective -integer or floating-point literal multiplied by the imaginary unit <i>i</i>. +integer or floating-point literal multiplied by the imaginary unit <i>i</i> +[<a href="#Go_1.13">Go 1.13</a>] </p> <pre class="ebnf"> @@ -884,7 +896,7 @@ are required when different numeric types are mixed in an expression or assignment. For instance, <code>int32</code> and <code>int</code> are not the same type even though they may have the same size on a particular architecture. - +</p> <h3 id="String_types">String types</h3> @@ -1340,6 +1352,7 @@ interface{} <p> For convenience, the predeclared type <code>any</code> is an alias for the empty interface. +[<a href="#Go_1.18">Go 1.18</a>] </p> <p> @@ -1375,13 +1388,15 @@ as the <code>File</code> interface. In a slightly more general form an interface <code>T</code> may use a (possibly qualified) interface type name <code>E</code> as an interface element. This is called -<i>embedding</i> interface <code>E</code> in <code>T</code>. +<i>embedding</i> interface <code>E</code> in <code>T</code> +[<a href="#Go_1.14">Go 1.14</a>]. The type set of <code>T</code> is the <i>intersection</i> of the type sets defined by <code>T</code>'s explicitly declared methods and the type sets of <code>T</code>’s embedded interfaces. In other words, the type set of <code>T</code> is the set of all types that implement all the explicitly declared methods of <code>T</code> and also all the methods of -<code>E</code>. +<code>E</code> +[<a href="#Go_1.18">Go 1.18</a>]. </p> <pre> @@ -1420,7 +1435,8 @@ type ReadCloser interface { <p> In their most general form, an interface element may also be an arbitrary type term <code>T</code>, or a term of the form <code>~T</code> specifying the underlying type <code>T</code>, -or a union of terms <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>. +or a union of terms <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code> +[<a href="#Go_1.18">Go 1.18</a>]. Together with method specifications, these elements enable the precise definition of an interface's type set as follows: </p> @@ -2303,7 +2319,9 @@ as an <a href="#Operands">operand</a>, and in <a href="#Assignment_statements">a <p> The following identifiers are implicitly declared in the -<a href="#Blocks">universe block</a>: +<a href="#Blocks">universe block</a> +[<a href="#Go_1.18">Go 1.18</a>] +[<a href="#Go_1.21">Go 1.21</a>]: </p> <pre class="grammar"> Types: @@ -2487,7 +2505,8 @@ TypeSpec = AliasDecl | TypeDef . <h4 id="Alias_declarations">Alias declarations</h4> <p> -An alias declaration binds an identifier to the given type. +An alias declaration binds an identifier to the given type +[<a href="#Go_1.9">Go 1.9</a>]. </p> <pre class="ebnf"> @@ -2636,7 +2655,8 @@ func (l *List[T]) Len() int { … } A type parameter list declares the <i>type parameters</i> of a generic function or type declaration. The type parameter list looks like an ordinary <a href="#Function_types">function parameter list</a> except that the type parameter names must all be present and the list is enclosed -in square brackets rather than parentheses. +in square brackets rather than parentheses +[<a href="#Go_1.18">Go 1.18</a>]. </p> <pre class="ebnf"> @@ -2719,7 +2739,8 @@ type T6[P int] struct{ f *T6[P] } // ok: reference to T6 is not in type para <p> A <i>type constraint</i> is an <a href="#Interface_types">interface</a> that defines the set of permissible type arguments for the respective type parameter and controls the -operations supported by values of that type parameter. +operations supported by values of that type parameter +[<a href="#Go_1.18">Go 1.18</a>]. </p> <pre class="ebnf"> @@ -2749,7 +2770,8 @@ other interfaces based on their type sets. But this should get us going for now. The <a href="#Predeclared_identifiers">predeclared</a> <a href="#Interface_types">interface type</a> <code>comparable</code> denotes the set of all non-interface types that are -<a href="#Comparison_operators">strictly comparable</a>. +<a href="#Comparison_operators">strictly comparable</a> +[<a href="#Go_1.18">Go 1.18</a>]. </p> <p> @@ -2782,7 +2804,8 @@ if <code>T</code> is an element of the type set defined by <code>C</code>; i.e., if <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>. As an exception, a <a href="#Comparison_operators">strictly comparable</a> type constraint may also be satisfied by a <a href="#Comparison_operators">comparable</a> -(not necessarily strictly comparable) type argument. +(not necessarily strictly comparable) type argument +[<a href="#Go_1.20">Go 1.20</a>]. More precisely: </p> @@ -3910,7 +3933,7 @@ For <code>a</code> of <a href="#Type_parameter_declarations">type parameter type that <code>P</code> is instantiated with, and the type of <code>a[x]</code> is the type of the (identical) element types.</li> <li><code>a[x]</code> may not be assigned to if <code>P</code>'s type set - includes string types. + includes string types.</li> </ul> <p> @@ -4306,7 +4329,7 @@ with the same underlying array. <p> A generic function or type is <i>instantiated</i> by substituting <i>type arguments</i> -for the type parameters. +for the type parameters [<a href="#Go_1.18">Go 1.18</a>]. Instantiation proceeds in two steps: </p> @@ -4491,7 +4514,7 @@ the type parameters of the functions that need to be instantiated and for which no explicit type arguments is provided. These type parameters are called <i>bound</i> type parameters. For instance, in the <code>dedup</code> example above, the type parameters -<code>P</code> and <code>E</code> are bound to <code>dedup</code>. +<code>S</code> and <code>E</code> are bound to <code>dedup</code>. An argument to a generic function call may be a generic function itself. The type parameters of that function are included in the set of bound type parameters. @@ -4639,7 +4662,7 @@ Type inference succeeds if no unification step fails and the map has an entry for each type parameter. </p> -</pre> +<p> For example, given the type equation with the bound type parameter <code>P</code> </p> @@ -4759,6 +4782,7 @@ to the type of the other operand. <p> The right operand in a shift expression must have <a href="#Numeric_types">integer type</a> +[<a href="#Go_1.13">Go 1.13</a>] or be an untyped constant <a href="#Representability">representable</a> by a value of type <code>uint</code>. If the left operand of a non-constant shift expression is an untyped constant, @@ -4803,6 +4827,7 @@ As the <code>++</code> and <code>--</code> operators form statements, not expressions, they fall outside the operator hierarchy. As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. +</p> <p> There are five precedence levels for binary operators. Multiplication operators bind strongest, followed by addition @@ -4825,12 +4850,13 @@ For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. </p> <pre> -+x -23 + 3*x[i] -x <= f() -^a >> b -f() || g() -x == y+1 && <-chanInt > 0 ++x // x +42 + a - b // (42 + a) - b +23 + 3*x[i] // 23 + (3 * x[i]) +x <= f() // x <= f() +^a >> b // (^a) >> b +f() || g() // f() || g() +x == y+1 && <-chanInt > 0 // (x == (y+1)) && ((<-chanInt) > 0) </pre> @@ -5207,7 +5233,7 @@ Specifically: <p> Logical operators apply to <a href="#Boolean_types">boolean</a> values and yield a result of the same type as the operands. -The right operand is evaluated conditionally. +The left operand is evaluated, and then the right if the condition requires it. </p> <pre class="grammar"> @@ -5424,7 +5450,8 @@ in any of these cases: <code>x</code> is a string and <code>T</code> is a slice of bytes or runes. </li> <li> - <code>x</code> is a slice, <code>T</code> is an array or a pointer to an array, + <code>x</code> is a slice, <code>T</code> is an array [<a href="#Go_1.20">Go 1.20</a>] + or a pointer to an array [<a href="#Go_1.17">Go 1.17</a>], and the slice and array types have <a href="#Type_identity">identical</a> element types. </li> </ul> @@ -5569,7 +5596,7 @@ myString([]myRune{0x1f30e}) // "\U0001f30e" == "🌎" <li> Converting a value of a string type to a slice of bytes type -yields a slice whose successive elements are the bytes of the string. +yields a non-nil slice whose successive elements are the bytes of the string. <pre> []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} @@ -5785,24 +5812,28 @@ determine the evaluation order of individual initialization expressions in Otherwise, when evaluating the <a href="#Operands">operands</a> of an expression, assignment, or <a href="#Return_statements">return statement</a>, -all function calls, method calls, and -communication operations are evaluated in lexical left-to-right -order. +all function calls, method calls, +<a href="#Receive operator">receive operations</a>, +and <a href="#Logical_operators">binary logical operations</a> +are evaluated in lexical left-to-right order. </p> <p> For example, in the (function-local) assignment </p> <pre> -y[f()], ok = g(h(), i()+x[j()], <-c), k() +y[f()], ok = g(z || h(), i()+x[j()], <-c), k() </pre> <p> the function calls and communication happen in the order -<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, +<code>f()</code>, <code>h()</code> (if <code>z</code> +evaluates to false), <code>i()</code>, <code>j()</code>, <code><-c</code>, <code>g()</code>, and <code>k()</code>. However, the order of those events compared to the evaluation and indexing of <code>x</code> and the evaluation -of <code>y</code> is not specified. +of <code>y</code> and <code>z</code> is not specified, +except as required lexically. For instance, <code>g</code> +cannot be called before its arguments are evaluated. </p> <pre> @@ -6510,7 +6541,6 @@ additionally it may specify an <i>init</i> and a <i>post</i> statement, such as an assignment, an increment or decrement statement. The init statement may be a <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. -Variables declared by the init statement are re-used in each iteration. </p> <pre class="ebnf"> @@ -6542,12 +6572,55 @@ for cond { S() } is the same as for ; cond ; { S() } for { S() } is the same as for true { S() } </pre> +<p> +Each iteration has its own separate declared variable (or variables) +[<a href="#Go_1.22">Go 1.22</a>]. +The variable used by the first iteration is declared by the init statement. +The variable used by each subsequent iteration is declared implicitly before +executing the post statement and initialized to the value of the previous +iteration's variable at that moment. +</p> + +<pre> +var prints []func() +for i := 0; i < 5; i++ { + prints = append(prints, func() { println(i) }) + i++ +} +for _, p := range prints { + p() +} +</pre> + +<p> +prints +</p> + +<pre> +1 +3 +5 +</pre> + +<p> +Prior to [<a href="#Go_1.22">Go 1.22</a>], iterations share one set of variables +instead of having their own separate variables. +In that case, the example above prints +</p> + +<pre> +6 +6 +6 +</pre> + <h4 id="For_range">For statements with <code>range</code> clause</h4> <p> A "for" statement with a "range" clause -iterates through all entries of an array, slice, string or map, -or values received on a channel. For each entry it assigns <i>iteration values</i> +iterates through all entries of an array, slice, string or map, values received on +a channel, or integer values from zero to an upper limit [<a href="#Go_1.22">Go 1.22</a>]. +For each entry it assigns <i>iteration values</i> to corresponding <i>iteration variables</i> if present and then executes the block. </p> @@ -6558,12 +6631,12 @@ RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . <p> The expression on the right in the "range" clause is called the <i>range expression</i>, its <a href="#Core_types">core type</a> must be -an array, pointer to an array, slice, string, map, or channel permitting -<a href="#Receive_operator">receive operations</a>. +an array, pointer to an array, slice, string, map, channel permitting +<a href="#Receive_operator">receive operations</a>, or an integer. As with an assignment, if present the operands on the left must be <a href="#Address_operators">addressable</a> or map index expressions; they -denote the iteration variables. If the range expression is a channel, at most -one iteration variable is permitted, otherwise there may be up to two. +denote the iteration variables. If the range expression is a channel or integer, +at most one iteration variable is permitted, otherwise there may be up to two. If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, the range clause is equivalent to the same clause without that identifier. </p> @@ -6588,6 +6661,7 @@ array or slice a [n]E, *[n]E, or []E index i int a[i] E string s string type index i int see below rune map m map[K]V key k K m[k] V channel c chan E, <-chan E element e E +integer n integer type value i see below </pre> <ol> @@ -6626,22 +6700,36 @@ For channels, the iteration values produced are the successive values sent on the channel until the channel is <a href="#Close">closed</a>. If the channel is <code>nil</code>, the range expression blocks forever. </li> -</ol> -<p> -The iteration values are assigned to the respective -iteration variables as in an <a href="#Assignment_statements">assignment statement</a>. -</p> +<li> +For an integer value <code>n</code>, the iteration values 0 through <code>n-1</code> +are produced in increasing order. +If <code>n</code> <= 0, the loop does not run any iterations. +</li> +</ol> <p> The iteration variables may be declared by the "range" clause using a form of <a href="#Short_variable_declarations">short variable declaration</a> (<code>:=</code>). -In this case their types are set to the types of the respective iteration values -and their <a href="#Declarations_and_scope">scope</a> is the block of the "for" -statement; they are re-used in each iteration. -If the iteration variables are declared outside the "for" statement, -after execution their values will be those of the last iteration. +In this case their <a href="#Declarations_and_scope">scope</a> is the block of the "for" statement +and each iteration has its own new variables [<a href="#Go_1.22">Go 1.22</a>] +(see also <a href="#For_clause">"for" statements with a ForClause</a>). +If the range expression is a (possibly untyped) integer expression <code>n</code>, +the variable has the same type as if it was +<a href="#Variable_declarations">declared</a> with initialization +expression <code>n</code>. +Otherwise, the variables have the types of their respective iteration values. +</p> + +<p> +If the iteration variables are not explicitly declared by the "range" clause, +they must be preexisting. +In this case, the iteration values are assigned to the respective variables +as in an <a href="#Assignment_statements">assignment statement</a>. +If the range expression is a (possibly untyped) integer expression <code>n</code>, +<code>n</code> too must be <a href="#Assignability">assignable</a> to the iteration variable; +if there is no iteration variable, <code>n</code> must be assignable to <code>int</code>. </p> <pre> @@ -6678,6 +6766,17 @@ for w := range ch { // empty a channel for range ch {} + +// call f(0), f(1), ... f(9) +for i := range 10 { + // type of i is int (default type for untyped constant 10) + f(i) +} + +// invalid: 256 cannot be assigned to uint8 +var u uint8 +for u = range 256 { +} </pre> @@ -7229,7 +7328,8 @@ n3 := copy(b, "Hello, World!") // n3 == 5, b is []byte("Hello") <p> The built-in function <code>clear</code> takes an argument of <a href="#Map_types">map</a>, <a href="#Slice_types">slice</a>, or <a href="#Type_parameter_declarations">type parameter</a> type, -and deletes or zeroes out all elements. +and deletes or zeroes out all elements +[<a href="#Go_1.21">Go 1.21</a>]. </p> <pre class="grammar"> @@ -7496,7 +7596,8 @@ The precise behavior is implementation-dependent. The built-in functions <code>min</code> and <code>max</code> compute the smallest—or largest, respectively—value of a fixed number of arguments of <a href="#Comparison_operators">ordered types</a>. -There must be at least one argument. +There must be at least one argument +[<a href="#Go_1.21">Go 1.21</a>]. </p> <p> @@ -8212,8 +8313,8 @@ of if the general conversion rules take care of this. <p> A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> value may not be <a href="#Address_operators">dereferenced</a>. -Any pointer or value of <a href="#Underlying_types">underlying type</a> <code>uintptr</code> can be -<a href="#Conversions">converted</a> to a type of underlying type <code>Pointer</code> and vice versa. +Any pointer or value of <a href="#Core_types">core type</a> <code>uintptr</code> can be +<a href="#Conversions">converted</a> to a type of core type <code>Pointer</code> and vice versa. The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. </p> @@ -8224,6 +8325,10 @@ bits = *(*uint64)(unsafe.Pointer(&f)) type ptr unsafe.Pointer bits = *(*uint64)(ptr(&f)) +func f[P ~*B, B any](p P) uintptr { + return uintptr(unsafe.Pointer(p)) +} + var p ptr = nil </pre> @@ -8272,7 +8377,8 @@ of constant size. <p> The function <code>Add</code> adds <code>len</code> to <code>ptr</code> -and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code>. +and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code> +[<a href="#Go_1.17">Go 1.17</a>]. The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>. A constant <code>len</code> argument must be <a href="#Representability">representable</a> by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>. @@ -8292,7 +8398,8 @@ and whose length and capacity are <code>len</code>. <p> except that, as a special case, if <code>ptr</code> is <code>nil</code> and <code>len</code> is zero, -<code>Slice</code> returns <code>nil</code>. +<code>Slice</code> returns <code>nil</code> +[<a href="#Go_1.17">Go 1.17</a>]. </p> <p> @@ -8301,14 +8408,16 @@ A constant <code>len</code> argument must be non-negative and <a href="#Represen if it is an untyped constant it is given type <code>int</code>. At run time, if <code>len</code> is negative, or if <code>ptr</code> is <code>nil</code> and <code>len</code> is not zero, -a <a href="#Run_time_panics">run-time panic</a> occurs. +a <a href="#Run_time_panics">run-time panic</a> occurs +[<a href="#Go_1.17">Go 1.17</a>]. </p> <p> The function <code>SliceData</code> returns a pointer to the underlying array of the <code>slice</code> argument. If the slice's capacity <code>cap(slice)</code> is not zero, that pointer is <code>&slice[:1][0]</code>. If <code>slice</code> is <code>nil</code>, the result is <code>nil</code>. -Otherwise it is a non-<code>nil</code> pointer to an unspecified memory address. +Otherwise it is a non-<code>nil</code> pointer to an unspecified memory address +[<a href="#Go_1.20">Go 1.20</a>]. </p> <p> @@ -8317,12 +8426,14 @@ The function <code>String</code> returns a <code>string</code> value whose under The same requirements apply to the <code>ptr</code> and <code>len</code> argument as in the function <code>Slice</code>. If <code>len</code> is zero, the result is the empty string <code>""</code>. Since Go strings are immutable, the bytes passed to <code>String</code> must not be modified afterwards. +[<a href="#Go_1.20">Go 1.20</a>] </p> <p> The function <code>StringData</code> returns a pointer to the underlying bytes of the <code>str</code> argument. For an empty string the return value is unspecified, and may be <code>nil</code>. -Since Go strings are immutable, the bytes returned by <code>StringData</code> must not be modified. +Since Go strings are immutable, the bytes returned by <code>StringData</code> must not be modified +[<a href="#Go_1.20">Go 1.20</a>]. </p> <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> @@ -8363,6 +8474,145 @@ A struct or array type has size zero if it contains no fields (or elements, resp <h2 id="Appendix">Appendix</h2> +<h3 id="Language_versions">Language versions</h3> + +<p> +The <a href="/doc/go1compat">Go 1 compatibility guarantee</a> ensures that +programs written to the Go 1 specification will continue to compile and run +correctly, unchanged, over the lifetime of that specification. +More generally, as adjustments are made and features added to the language, +the compatibility guarantee ensures that a Go program that works with a +specific Go language version will continue to work with any subsequent version. +</p> + +<p> +For instance, the ability to use the prefix <code>0b</code> for binary +integer literals was introduced with Go 1.13, indicated +by [<a href="#Go_1.13">Go 1.13</a>] in the section on +<a href="#Integer_literals">integer literals</a>. +Source code containing an integer literal such as <code>0b1011</code> +will be rejected if the implied or required language version used by +the compiler is older than Go 1.13. +</p> + +<p> +The following table describes the minimum language version required for +features introduced after Go 1. +</p> + +<h4 id="Go_1.9">Go 1.9</h4> +<ul> +<li> +An <a href="#Alias_declarations">alias declaration</a> may be used to declare an alias name for a type. +</li> +</ul> + +<h4 id="Go_1.13">Go 1.13</h4> +<ul> +<li> +<a href="#Integer_literals">Integer literals</a> may use the prefixes <code>0b</code>, <code>0B</code>, <code>0o</code>, +and <code>0O</code> for binary, and octal literals, respectively. +</li> +<li> +Hexadecimal <a href="#Floating-point_literals">floating-point literals</a> may be written using the prefixes +<code>0x</code> and <code>0X</code>. +</li> +<li> +The <a href="#Imaginary_literals">imaginary suffix</a> <code>i</code> may be used with any (binary, decimal, hexadecimal) +integer or floating-point literal, not just decimal literals. +</li> +<li> +The digits of any number literal may be <a href="#Integer_literals">separated</a> (grouped) +using underscores <code>_</code>. +</li> +<li> +The shift count in a <a href="#Operators">shift operation</a> may be a signed integer type. +</li> +</ul> + +<h4 id="Go_1.14">Go 1.14</h4> +<ul> +<li> +Emdedding a method more than once through different <a href="#Embedded_interfaces">embedded interfaces</a> +is not an error. +</li> +</ul> + +<h4 id="Go_1.17">Go 1.17</h4> +<ul> +<li> +A slice may be <a href="#Conversions">converted</a> to an array pointer if the slice and array element +types match, and the array is not longer than the slice. +</li> +<li> +The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions +<code>Add</code> and <code>Slice</code>. +</li> +</ul> + +<h4 id="Go_1.18">Go 1.18</h4> +<p> +The 1.18 release adds polymorphic functions and types ("generics") to the language. +Specifically: +</p> +<ul> +<li> +The set of <a href="#Operators_and_punctuation">operators and punctuation</a> includes the new token <code>~</code>. +</li> +<li> +Function and type declarations may declare <a href="#Type_parameter_declarations">type parameters</a>. +</li> +<li> +Interface types may <a href="#General_interfaces">embed arbitrary types</a> (not just type names of interfaces) +as well as union and <code>~T</code> type elements. +</li> +<li> +The set of <a href="#Predeclared_identifiers">predeclared</a> types includes the new types +<code>any</code> and <code>comparable</code>. +</li> +</ul> + +<h4 id="Go_1.20">Go 1.20</h4> +<ul> +<li> +A slice may be <a href="#Conversions">converted</a> to an array if the slice and array element +types match and the array is not longer than the slice. +</li> +<li> +The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions +<code>SliceData</code>, <code>String</code>, and <code>StringData</code>. +</li> +<li> +<a href="#Comparison_operators">Comparable types</a> (such as ordinary interfaces) may satisfy +<code>comparable</code> constraints, even if the type arguments are not strictly comparable. +</li> +</ul> + +<h4 id="Go_1.21">Go 1.21</h4> +<ul> +<li> +The set of <a href="#Predeclared_identifiers">predeclared</a> functions includes the new functions +<code>min</code>, <code>max</code>, and <code>clear</code>. +</li> +<li> +<a href="#Type_inference">Type inference</a> uses the types of interface methods for inference. +It also infers type arguments for generic functions assigned to variables or +passed as arguments to other (possibly generic) functions. +</li> +</ul> + +<h4 id="Go_1.22">Go 1.22</h4> +<ul> +<li> +In a <a href="#For_statements">"for" statement</a>, each iteration has its own set of iteration +variables rather than sharing the same variables in each iteration. +</li> +<li> +A "for" statement with <a href="#For_range">"range" clause</a> may iterate over +integer values from zero to an upper limit. +</li> +</ul> + <h3 id="Type_unification_rules">Type unification rules</h3> <p> @@ -8487,7 +8737,7 @@ Finally, two types that are not bound type parameters unify loosely identical <a href="#Interface_types">type terms</a>, both or neither embed the predeclared type <a href="#Predeclared_identifiers">comparable</a>, - corresponding method types unify per the element matching mode, + corresponding method types unify exactly, and the method set of one of the interfaces is a subset of the method set of the other interface. </li> diff --git a/doc/godebug.md b/doc/godebug.md index d26555503..a7619c9a3 100644 --- a/doc/godebug.md +++ b/doc/godebug.md @@ -129,11 +129,71 @@ and the [go command documentation](/cmd/go#hdr-Build_and_test_caching). ### Go 1.22 Go 1.22 adds a configurable limit to control the maximum acceptable RSA key size -that can be used in TLS handshakes, controlled by the [`tlsmaxrsasize`setting](/pkg/crypto/tls#Conn.Handshake). +that can be used in TLS handshakes, controlled by the [`tlsmaxrsasize` setting](/pkg/crypto/tls#Conn.Handshake). The default is tlsmaxrsasize=8192, limiting RSA to 8192-bit keys. To avoid denial of service attacks, this setting and default was backported to Go 1.19.13, Go 1.20.8, and Go 1.21.1. +Go 1.22 made it an error for a request or response read by a net/http +client or server to have an empty Content-Length header. +This behavior is controlled by the `httplaxcontentlength` setting. + +Go 1.22 changed the behavior of ServeMux to accept extended +patterns and unescape both patterns and request paths by segment. +This behavior can be controlled by the +[`httpmuxgo121` setting](/pkg/net/http/#ServeMux). + +Go 1.22 added the [Alias type](/pkg/go/types#Alias) to [go/types](/pkg/go/types) +for the explicit representation of [type aliases](/ref/spec#Type_declarations). +Whether the type checker produces `Alias` types or not is controlled by the +[`gotypesalias` setting](/pkg/go/types#Alias). +For Go 1.22 it defaults to `gotypesalias=0`. +For Go 1.23, `gotypealias=1` will become the default. +This setting will be removed in a future release, Go 1.24 at the earliest. + +Go 1.22 changed the default minimum TLS version supported by both servers +and clients to TLS 1.2. The default can be reverted to TLS 1.0 using the +[`tls10server` setting](/pkg/crypto/tls/#Config). + +Go 1.22 changed the default TLS cipher suites used by clients and servers when +not explicitly configured, removing the cipher suites which used RSA based key +exchange. The default can be revert using the [`tlsrsakex` setting](/pkg/crypto/tls/#Config). + +Go 1.22 disabled +[`ConnectionState.ExportKeyingMaterial`](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial) +when the connection supports neither TLS 1.3 nor Extended Master Secret +(implemented in Go 1.21). It can be reenabled with the [`tlsunsafeekm` +setting](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial). + +Go 1.22 changed how the runtime interacts with transparent huge pages on Linux. +In particular, a common default Linux kernel configuration can result in +significant memory overheads, and Go 1.22 no longer works around this default. +To work around this issue without adjusting kernel settings, transparent huge +pages can be disabled for Go memory with the +[`disablethp` setting](/pkg/runtime#hdr-Environment_Variable). +This behavior was backported to Go 1.21.1, but the setting is only available +starting with Go 1.21.6. +This setting may be removed in a future release, and users impacted by this issue +should adjust their Linux configuration according to the recommendations in the +[GC guide](/doc/gc-guide#Linux_transparent_huge_pages), or switch to a Linux +distribution that disables transparent huge pages altogether. + +Go 1.22 added contention on runtime-internal locks to the [`mutex` +profile](/pkg/runtime/pprof#Profile). Contention on these locks is always +reported at `runtime._LostContendedRuntimeLock`. Complete stack traces of +runtime locks can be enabled with the [`runtimecontentionstacks` +setting](/pkg/runtime#hdr-Environment_Variable). These stack traces have +non-standard semantics, see setting documentation for details. + +Go 1.22 added a new [`crypto/x509.Certificate`](/pkg/crypto/x509/#Certificate) +field, [`Policies`](/pkg/crypto/x509/#Certificate.Policies), which supports +certificate policy OIDs with components larger than 31 bits. By default this +field is only used during parsing, when it is populated with policy OIDs, but +not used during marshaling. It can be used to marshal these larger OIDs, instead +of the existing PolicyIdentifiers field, by using the +[`x509usepolicies` setting.](/pkg/crypto/x509/#CreateCertificate). + + ### Go 1.21 Go 1.21 made it a run-time error to call `panic` with a nil interface value, @@ -191,7 +251,7 @@ There is no plan to remove this setting. ### Go 1.18 Go 1.18 removed support for SHA1 in most X.509 certificates, -controlled by the [`x509sha1` setting](/crypto/x509#InsecureAlgorithmError). +controlled by the [`x509sha1` setting](/pkg/crypto/x509#InsecureAlgorithmError). This setting will be removed in a future release, Go 1.22 at the earliest. ### Go 1.10 |