From 1dddd83c494849dd71b72a4415c5238b0716dd30 Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Wed, 13 Dec 2023 12:29:32 -0800 Subject: [PATCH] doc: document version at which new language features were introduced in spec Add a new section to the Appendix describing what features were changed or added in which language version. Add short links with references to the required language version where relevant. Fixes #63857. Change-Id: I5250f856d8688a71602076fcc662aa678d96a5d2 Reviewed-on: https://go-review.googlesource.com/c/go/+/549518 Reviewed-by: Robert Griesemer Reviewed-by: Rob Pike Auto-Submit: Robert Griesemer Reviewed-by: Russ Cox TryBot-Bypass: Robert Griesemer Reviewed-by: Alan Donovan --- doc/go_spec.html | 216 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 192 insertions(+), 24 deletions(-) diff --git a/doc/go_spec.html b/doc/go_spec.html index 89ab2d35d1..3c065f57cb 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,6 +1,6 @@ @@ -70,6 +70,14 @@ enumerations or code snippets that are not further specified. The character +

+A link of the form [Go 1.xx] 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 linked section +in the appendix. +

+

Source code representation

@@ -263,7 +271,8 @@ continue for import return var

The following character sequences represent operators -(including assignment operators) and punctuation: +(including assignment operators) and punctuation +[Go 1.18]: 

 +    &     +=    &=     &&    ==    !=    (    )
@@ -281,7 +290,8 @@ An integer literal is a sequence of digits representing an
 integer constant.
 An optional prefix sets a non-decimal base: 0b or 0B
 for binary, 0, 0o, or 0O for octal,
-and 0x or 0X for hexadecimal.
+and 0x or 0X for hexadecimal
+[Go 1.13].
 A single 0 is considered a decimal zero.
 In hexadecimal literals, letters a through f
 and A through F 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 (p or P 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 2exp.
+An exponent value exp scales the mantissa (integer and fractional part) by 2exp
+[Go 1.13].
 

 
 

@@ -411,7 +422,8 @@ It consists of an integer or
 floating-point literal
 followed by the lowercase letter i.
 The value of an imaginary literal is the value of the respective
-integer or floating-point literal multiplied by the imaginary unit i.
+integer or floating-point literal multiplied by the imaginary unit i
+[Go 1.13]
 

 
 
@@ -1340,6 +1352,7 @@ interface{}
 
 

 For convenience, the predeclared type any is an alias for the empty interface.
+[Go 1.18]
 

 
 

@@ -1375,13 +1388,15 @@ as the File interface.
 In a slightly more general form
 an interface T may use a (possibly qualified) interface type
 name E as an interface element. This is called
-embedding interface E in T.
+embedding interface E in T
+[Go 1.14].
 The type set of T is the intersection of the type sets
 defined by T's explicitly declared methods and the type sets
 of T’s embedded interfaces.
 In other words, the type set of T is the set of all types that implement all the
 explicitly declared methods of T and also all the methods of
-E.
+E
+[Go 1.18].
 

 
 
@@ -1420,7 +1435,8 @@ type ReadCloser interface {
 

 In their most general form, an interface element may also be an arbitrary type term
 T, or a term of the form ~T specifying the underlying type T,
-or a union of terms t1|t2|…|tn.
+or a union of terms t1|t2|…|tn
+[Go 1.18].
 Together with method specifications, these elements enable the precise
 definition of an interface's type set as follows:
 

@@ -2303,7 +2319,9 @@ as an operand, and in a
 
 

 The following identifiers are implicitly declared in the
-universe block:
+universe block
+[Go 1.18]
+[Go 1.21]:
 

 
 Types:
@@ -2487,7 +2505,8 @@ TypeSpec = AliasDecl | TypeDef .
 
Alias declarations

 
 

-An alias declaration binds an identifier to the given type.
+An alias declaration binds an identifier to the given type
+[Go 1.9].
 

 
 
@@ -2636,7 +2655,8 @@ func (l *List[T]) Len() int  { … }
 A type parameter list declares the type parameters of a generic function or type declaration.
 The type parameter list looks like an ordinary function parameter list
 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
+[Go 1.18].
 

 
 
@@ -2719,7 +2739,8 @@ type T6[P int] struct{ f *T6[P] }     // ok: reference to T6 is not in type para
 

 A type constraint is an interface 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
+[Go 1.18].
 

 
 
@@ -2749,7 +2770,8 @@ other interfaces based on their type sets. But this should get us going for now.
 The predeclared
 interface type comparable
 denotes the set of all non-interface types that are
-strictly comparable.
+strictly comparable
+[Go 1.18].
 

 
 

@@ -2782,7 +2804,8 @@ if T is an element of the type set defined by C; i.e.,
 if T implements C.
 As an exception, a strictly comparable
 type constraint may also be satisfied by a comparable
-(not necessarily strictly comparable) type argument.
+(not necessarily strictly comparable) type argument
+[Go 1.20].
 More precisely:
 

 
@@ -4306,7 +4329,7 @@ with the same underlying array.
 
 

 A generic function or type is instantiated by substituting type arguments
-for the type parameters.
+for the type parameters [Go 1.18].
 Instantiation proceeds in two steps:
 

 
@@ -4759,6 +4782,7 @@ to the type of the other operand.
 
 

 The right operand in a shift expression must have integer type
+[Go 1.13]
 or be an untyped constant representable by a
 value of type uint.
 If the left operand of a non-constant shift expression is an untyped constant,
@@ -5426,7 +5450,8 @@ in any of these cases:
 	x is a string and T is a slice of bytes or runes.
 	
 	
  • 
-	x is a slice, T is an array or a pointer to an array,
+	x is a slice, T is an array [Go 1.20]
+	or a pointer to an array [Go 1.17],
 	and the slice and array types have identical element types.
 	
    • 
 
@@ -6553,7 +6578,7 @@ for      { S() }    is the same as    for true     { S() }
 
    
 A "for" statement with a "range" clause
 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 channel, or integer values from zero to an upper limit [Go 1.22].
 For each entry it assigns iteration values
 to corresponding iteration variables if present and then executes the block.
 
    
@@ -7249,7 +7274,8 @@ n3 := copy(b, "Hello, World!")  // n3 == 5, b is []byte("Hello")
 
    
 The built-in function clear takes an argument of map,
 slice, or type parameter type,
-and deletes or zeroes out all elements.
+and deletes or zeroes out all elements
+[Go 1.21].
 
    
 
 
    @@ -7516,7 +7542,8 @@ The precise behavior is implementation-dependent.
 The built-in functions min and max compute the
 smallest—or largest, respectively—value of a fixed number of
 arguments of ordered types.
-There must be at least one argument.
+There must be at least one argument
+[Go 1.21].
 
    
 
 
    
@@ -8296,7 +8323,8 @@ of constant size.
 
 
    
 The function Add adds len to ptr
-and returns the updated pointer unsafe.Pointer(uintptr(ptr) + uintptr(len)).
+and returns the updated pointer unsafe.Pointer(uintptr(ptr) + uintptr(len))
+[Go 1.17].
 The len argument must be of integer type or an untyped constant.
 A constant len argument must be representable by a value of type int;
 if it is an untyped constant it is given type int.
@@ -8316,7 +8344,8 @@ and whose length and capacity are len.
 
    
 except that, as a special case, if ptr
 is nil and len is zero,
-Slice returns nil.
+Slice returns nil
+[Go 1.17].
 
    
 
 
    
@@ -8325,14 +8354,16 @@ A constant len argument must be non-negative and run-time panic occurs.
+a run-time panic occurs
+[Go 1.17].
 
    
 
 
    
 The function SliceData returns a pointer to the underlying array of the slice argument.
 If the slice's capacity cap(slice) is not zero, that pointer is &slice[:1][0].
 If slice is nil, the result is nil.
-Otherwise it  is a non-nil pointer to an unspecified memory address.
+Otherwise it  is a non-nil pointer to an unspecified memory address
+[Go 1.20].
 
    
 
 
    
@@ -8341,12 +8372,14 @@ The function String returns a string value whose under
 The same requirements apply to the ptr and len argument as in the function
 Slice. If len is zero, the result is the empty string "".
 Since Go strings are immutable, the bytes passed to String must not be modified afterwards.
+[Go 1.20]
 
    
 
 
    
 The function StringData returns a pointer to the underlying bytes of the str argument.
 For an empty string the return value is unspecified, and may be nil.
-Since Go strings are immutable, the bytes returned by StringData must not be modified.
+Since Go strings are immutable, the bytes returned by StringData must not be modified
+[Go 1.20].
 
    
 
 
    Size and alignment guarantees
    
@@ -8387,6 +8420,141 @@ A struct or array type has size zero if it contains no fields (or elements, resp
 
 
    Appendix
    
 
+
    Language versions
    
+
+
    
+The Go 1 compatibility guarantee 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 adjustements 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.
+
    
+
+
    
+For instance, the ability to use the prefix 0b for binary
+integer literals was introduced with Go 1.13, indicated
+by [Go 1.13] in the section on
+integer literals.
+Source code containing an integer literal such as 0b1011
+will be rejected if the implied or required language version used by
+the compiler is older than Go 1.13.
+
    
+
+
    
+The following table describes the minimum language version required for
+features introduced after Go 1.
+
    
+
+
    Go 1.9
    
+
+
+
    Go 1.13
    
+
      
+
    • 
+Integer literals may use the prefixes 0b, 0B, 0o,
+and 0O for binary, and octal literals, respectively.
+
      • 
+
    • 
+Hexadecimal floating-point literals may be written using the prefixes
+0x and 0X.
+
      • 
+
    • 
+The imaginary suffix i may be used with any (binary, decimal, hexadecimal)
+integer or floating-point literal, not just decimal literals.
+
      • 
+
    • 
+The digits of any number literal may be separated (grouped)
+using underscores _.
+
      • 
+
    • 
+The shift count in a shift operation may be a signed integer type.
+
      • 
+
    
+
+
    Go 1.14
    
+
      
+
    • 
+Emdedding a method more than once through different embedded interfaces
+is not an error.
+
      • 
+
    
+
+
    Go 1.17
    
+
      
+
    • 
+A slice may be converted to an array pointer if the slice and array element
+types match, and the array is not longer than the slice.
+
      • 
+
    • 
+The built-in package unsafe includes the new functions
+Add and Slice.
+
      • 
+
    
+
+
    Go 1.18
    
+
    
+The 1.18 release adds polymorphic functions and types ("generics") to the language.
+Specifically:
+
    
+
+
+
    Go 1.20
    
+
      
+
    • 
+A slice may be converted to an array if the slice and array element
+types match and the array is not longer than the slice.
+
      • 
+
    • 
+The built-in package unsafe includes the new functions
+SliceData, String, and StringData.
+
      • 
+
    • 
+Comparable types (such as ordinary interfaces) may satisfy
+comparable constraints, even if the type arguments are not strictly comparable.
+
      • 
+
    
+
+
    Go 1.21
    
+
      
+
    • 
+The set of predeclared functions includes the new functions
+min, max, and clear.
+
      • 
+
    • 
+Type inference 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.
+
      • 
+
    
+
+
    Go 1.22
    
+
+
 
    Type unification rules
    
 
 
    
-- 
2.52.0