From 136c04f71adf3611d94c33552aebb63290647580 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 8 Dec 2011 16:39:05 -0800 Subject: [PATCH] doc/go1: most of the simple language changes R=rsc, adg, r CC=golang-dev https://golang.org/cl/5477044 --- doc/go1.html | 226 ++++++++++++++++++++++++++++++++++++++++++++++- doc/go1.tmpl | 182 +++++++++++++++++++++++++++++++++++++- doc/progs/go1.go | 74 ++++++++++++++++ 3 files changed, 479 insertions(+), 3 deletions(-) diff --git a/doc/go1.html b/doc/go1.html index 642f610b4b..4ac6924912 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -31,17 +31,92 @@ r60 to compile and run under Go 1. Finally, it outlines the new go command for building Go programs and the new binary release process being introduced. Most of these topics have more thorough presentations elsewhere; such documents are linked below. +

Changes to the language

Append

+

+The append built-in function is variadic, so one can +append to a byte slice using the ... syntax in the +call. +

+ +
    greeting := []byte{}
+    greeting = append(greeting, []byte("hello ")...)
+
+ +

+By analogy with the similar property of copy, Go 1 +permits a string to be appended (byte-wise) directly to a byte +slice; the conversion is no longer necessary: +

+ +
    greeting = append(greeting, "world"...)
+
+ +

+Updating: +This is a new feature, so existing code needs no changes. +

+

Close

+

+The close built-in function lets a sender tell a receiver +that no more data will be transmitted on the channel. In Go 1 the +type system enforces the directionality when possible: it is illegal +to call close on a receive-only channel: +

+ +
+    var c chan int
+    var csend chan<- int = c
+    var crecv <-chan int = c
+    close(c)     // legal
+    close(csend) // legal
+    close(crecv) // illegal
+
+ +

+Updating: +Existing code that attempts to close a receive-only channel was +erroneous even before Go 1 and should be fixed. The compiler will +now reject such code. +

+

Composite literals

Goroutines during init

+

+Go 1 allows goroutines to be created and run during initialization. +(They used to be created but were not run until after initialization +completed.) Code that uses goroutines can now be called from +init routines and global initialization expressions +without introducing a deadlock. +

+ +
var PackageGlobal int
+
+func init() {
+    c := make(chan int)
+    go initializationFunction(c)
+    PackageGlobal = <-c
+}
+
+ +

+Updating: +This is a new feature, so existing code needs no changes, +although it's possible that code that depends on goroutines not starting before main will break. +There was no such code in the standard repository. +

+

The rune type

Deleting from maps

@@ -77,14 +152,161 @@ the ignored value can be safely discarded from the program and will flag other uses of the syntax for inspection by the programmer.

-

Iterating in maps

+

Iterating in maps

+ +

+In Go 1, the order in which elements are visited when iterating +over a map using a for range statement +is defined to be unpredictable, even if the same loop is run multiple +times with the same map. +Code should not assume that the elements are visited in any particular order. +

+ +
    m := map[string]int{"Sunday": 0, "Monday": 1}
+    for name, value := range m {
+        // This loop should not assume Sunday will be visited first.
+        f(name, value)
+    }
+
+ +

+Updating: +This is one change where tools cannot help. Most existing code +will be unaffected, but some programs may break or misbehave; we +recommend manual checking of all range statements over maps to +verify they do not depend on iteration order. There were a few such +examples in the standard repository; they have been fixed. +Note that it was already incorrect to depend on the iteration order, which +was unspecified. This change codifies the unpredictability. +

Multiple assignment

+

+Go 1 fully specifies the evaluation order in multiple assignment +statements. In particular, if the left-hand side of the assignment +statement contains expressions that require evaluation, such as +function calls or array indexing operations, these will all be done +using the usual left-to-right rule before any variables are assigned +their value. Once everything is evaluated, the actual assignments +proceed in left-to-right order. +

+ +

+These examples illustrate the behavior. +

+ +
    sa := []int{1, 2, 3}
+    i := 0
+    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2
+
+    sb := []int{1, 2, 3}
+    j := 0
+    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1
+
+    sc := []int{1, 2, 3}
+    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)
+
+ +Updating: +This is one change where tools cannot help, but breakage is unlikely. +No code in the standard repository was broken by this change, and code +that depended on the previous unspecified behavior was already incorrect. +

+

Returns and shadowed variables

+

+A shadowed variable is one that has the same name as another variable in an inner scope. +In functions with named return values, +the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. +(It isn't part of the specification, because this is one area we are still exploring; +the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.) +

+ +

+This function implicitly returns a shadowed return value and will be rejected by the compiler: +

+ +
+    func Bug() (i, j, k int) {
+        for i = 0; i < 5; i++ {
+            for j := 0; j < 5; j++ { // Redeclares j.
+                k += i*j
+                if k > 100 {
+                    return // Rejected: j is shadowed here.
+                }
+            }
+        }
+        return // OK: j is not shadowed here.
+    }
+
+ +

+Updating: +Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. +The few cases that arose in the standard repository were mostly bugs. +

+ +

Copying structs with unexported fields

+

Equality of structs and arrays

+

+Go 1 defines equality and inequality (== and +!=) for struct and array values, respectively, provided +the elements of the data structures can themselves be compared. +That is, if equality is defined for all the fields of a struct (or +an array element), then it is defined for the struct (or array). +

+ +

+As a result, structs and arrays can now be used as map keys: +

+ +
    //    type Day struct {
+    //        long string
+    //        short string
+    //    }
+    //    Christmas := Day{"Christmas", "XMas"}
+    //    Thanksgiving := Day{"Thanksgiving", "Turkey"}
+    //    holiday := map[Day]bool {
+    //        Christmas: true,
+    //        Thanksgiving: true,
+    //    }
+    //    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])
+
+ +

+Note that equality is still undefined for slices, for which the +calculation is in general infeasible. Also note that the ordered +comparison operators (< <= +> >=) are still undefined for +structs and arrays. + +

+Updating: +This is a new feature, so existing code needs no changes. +

+ +

Function and map equality

+ +

+Go 1 disallows checking for equality of functions and maps, +respectively, except to compare them directly to nil. +

+ +

+Updating: +Existing code that depends on function or map equality will be +rejected by the compiler and will need to be fixed by hand. +Few programs will be affected, but the fix may require some +redesign. +

+

Changes to the library

The package hierarchy

@@ -106,7 +328,7 @@ while others have been deleted outright. Old path New path -asn1 encoding/asn1 +asn1 encoding/asn1 csv encoding/csv gob encoding/gob json encoding/json diff --git a/doc/go1.tmpl b/doc/go1.tmpl index 3da62f8a3b..d317f3b0f0 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -27,17 +27,79 @@ r60 to compile and run under Go 1. Finally, it outlines the new go command for building Go programs and the new binary release process being introduced. Most of these topics have more thorough presentations elsewhere; such documents are linked below. +

Changes to the language

Append

+

+The append built-in function is variadic, so one can +append to a byte slice using the ... syntax in the +call. +

+ +{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}} + +

+By analogy with the similar property of copy, Go 1 +permits a string to be appended (byte-wise) directly to a byte +slice; the conversion is no longer necessary: +

+ +{{code "progs/go1.go" `/append.*world/`}} + +

+Updating: +This is a new feature, so existing code needs no changes. +

+

Close

+

+The close built-in function lets a sender tell a receiver +that no more data will be transmitted on the channel. In Go 1 the +type system enforces the directionality when possible: it is illegal +to call close on a receive-only channel: +

+ +
+    var c chan int
+    var csend chan<- int = c
+    var crecv <-chan int = c
+    close(c)     // legal
+    close(csend) // legal
+    close(crecv) // illegal
+
+ +

+Updating: +Existing code that attempts to close a receive-only channel was +erroneous even before Go 1 and should be fixed. The compiler will +now reject such code. +

+

Composite literals

Goroutines during init

+

+Go 1 allows goroutines to be created and run during initialization. +(They used to be created but were not run until after initialization +completed.) Code that uses goroutines can now be called from +init routines and global initialization expressions +without introducing a deadlock. +

+ +{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}} + +

+Updating: +This is a new feature, so existing code needs no changes, +although it's possible that code that depends on goroutines not starting before main will break. +There was no such code in the standard repository. +

+

The rune type

Deleting from maps

@@ -71,14 +133,132 @@ the ignored value can be safely discarded from the program and will flag other uses of the syntax for inspection by the programmer.

-

Iterating in maps

+

Iterating in maps

+ +

+In Go 1, the order in which elements are visited when iterating +over a map using a for range statement +is defined to be unpredictable, even if the same loop is run multiple +times with the same map. +Code should not assume that the elements are visited in any particular order. +

+ +{{code "progs/go1.go" `/Sunday/` `/^ }/`}} + +

+Updating: +This is one change where tools cannot help. Most existing code +will be unaffected, but some programs may break or misbehave; we +recommend manual checking of all range statements over maps to +verify they do not depend on iteration order. There were a few such +examples in the standard repository; they have been fixed. +Note that it was already incorrect to depend on the iteration order, which +was unspecified. This change codifies the unpredictability. +

Multiple assignment

+

+Go 1 fully specifies the evaluation order in multiple assignment +statements. In particular, if the left-hand side of the assignment +statement contains expressions that require evaluation, such as +function calls or array indexing operations, these will all be done +using the usual left-to-right rule before any variables are assigned +their value. Once everything is evaluated, the actual assignments +proceed in left-to-right order. +

+ +

+These examples illustrate the behavior. +

+ +{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}} + +Updating: +This is one change where tools cannot help, but breakage is unlikely. +No code in the standard repository was broken by this change, and code +that depended on the previous unspecified behavior was already incorrect. +

+

Returns and shadowed variables

+

+A shadowed variable is one that has the same name as another variable in an inner scope. +In functions with named return values, +the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. +(It isn't part of the specification, because this is one area we are still exploring; +the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.) +

+ +

+This function implicitly returns a shadowed return value and will be rejected by the compiler: +

+ +
+    func Bug() (i, j, k int) {
+        for i = 0; i < 5; i++ {
+            for j := 0; j < 5; j++ { // Redeclares j.
+                k += i*j
+                if k > 100 {
+                    return // Rejected: j is shadowed here.
+                }
+            }
+        }
+        return // OK: j is not shadowed here.
+    }
+
+ +

+Updating: +Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. +The few cases that arose in the standard repository were mostly bugs. +

+ +

Copying structs with unexported fields

+

Equality of structs and arrays

+

+Go 1 defines equality and inequality (== and +!=) for struct and array values, respectively, provided +the elements of the data structures can themselves be compared. +That is, if equality is defined for all the fields of a struct (or +an array element), then it is defined for the struct (or array). +

+ +

+As a result, structs and arrays can now be used as map keys: +

+ +{{code "progs/go1.go" `/type Day struct/` `/Printf/`}} + +

+Note that equality is still undefined for slices, for which the +calculation is in general infeasible. Also note that the ordered +comparison operators (< <= +> >=) are still undefined for +structs and arrays. + +

+Updating: +This is a new feature, so existing code needs no changes. +

+ +

Function and map equality

+ +

+Go 1 disallows checking for equality of functions and maps, +respectively, except to compare them directly to nil. +

+ +

+Updating: +Existing code that depends on function or map equality will be +rejected by the compiler and will need to be fixed by hand. +Few programs will be affected, but the fix may require some +redesign. +

+

Changes to the library

The package hierarchy

diff --git a/doc/progs/go1.go b/doc/progs/go1.go index 0a7416c484..f02ede7403 100644 --- a/doc/progs/go1.go +++ b/doc/progs/go1.go @@ -9,7 +9,11 @@ package main import "log" func main() { + stringAppend() mapDelete() + mapIteration() + multipleAssignment() + structEquality() } func mapDelete() { @@ -20,3 +24,73 @@ func mapDelete() { log.Fatal("mapDelete:", m) } } + +func stringAppend() { + greeting := []byte{} + greeting = append(greeting, []byte("hello ")...) + greeting = append(greeting, "world"...) + if string(greeting) != "hello world" { + log.Fatal("stringAppend: ", string(greeting)) + } +} + +func mapIteration() { + m := map[string]int{"Sunday": 0, "Monday": 1} + for name, value := range m { + // This loop should not assume Sunday will be visited first. + f(name, value) + } +} + +func assert(t bool) { + if !t { + log.Panic("assertion fail") + } +} + +func multipleAssignment() { + sa := []int{1, 2, 3} + i := 0 + i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2 + + sb := []int{1, 2, 3} + j := 0 + sb[j], j = 2, 1 // sets sb[0] = 2, j = 1 + + sc := []int{1, 2, 3} + sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end) + + assert(i == 1 && sa[0] == 2) + assert(j == 1 && sb[0] == 2) + assert(sc[0] == 2) +} + +func structEquality() { + // Feature not net in repo. + // type Day struct { + // long string + // short string + // } + // Christmas := Day{"Christmas", "XMas"} + // Thanksgiving := Day{"Thanksgiving", "Turkey"} + // holiday := map[Day]bool { + // Christmas: true, + // Thanksgiving: true, + // } + // fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas]) +} + +func f(string, int) { +} + +func initializationFunction(c chan int) { + c <- 1 +} + +var PackageGlobal int + +func init() { + c := make(chan int) + go initializationFunction(c) + PackageGlobal = <-c +} -- 2.52.0