From 68c7e8a2f431577e77273f1860f3f88dc06627ea Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 27 Feb 2012 07:31:34 +1100 Subject: [PATCH] doc/go1: add justification discussions to major changes Fixes #3086. R=golang-dev, gri, r, kevlar CC=golang-dev https://golang.org/cl/5700067 --- doc/go1.html | 204 +++++++++++++++++++++++++++++++++++++++------------ doc/go1.tmpl | 204 +++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 314 insertions(+), 94 deletions(-) diff --git a/doc/go1.html b/doc/go1.html index 54916d56431..3309a407306 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -57,9 +57,11 @@ r60.3). It also explains how to update code from r60 to run under Go 1.

Append

-The append built-in function is variadic, so one can -append to a byte slice using the ... syntax in the -call. +The append predeclared variadic function makes it easy to grow a slice +by adding elements to the end. +A common use is to add bytes to the end of a byte slice when generating output. +However, append did not provide a way to append a string to a []byte, +which is another common case. 

    m := map[string]int{"Sunday": 0, "Monday": 1}
     for name, value := range m {
@@ -298,8 +348,14 @@ 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
+The language specification guarantees that in assignments
+the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned.
+To guarantee predictable behavior,
+Go 1 refines the specification further.
+

+
+

+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
@@ -333,7 +389,11 @@ 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.
+A common mistake is to use return (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable.
+This situation is called shadowing: the result variable has been shadowed by another variable with the same name declared 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;
@@ -367,9 +427,17 @@ The few cases that arose in the standard repository were mostly bugs.
 
Copying structs with unexported fields

 
 

-Go 1 relaxes the rules about accessing structs with unexported (lower-case) fields,
-permitting a client package to assign (and therefore copy) such a struct.
-Of course, the client package still cannot access such fields individually.
+The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package.
+There was, however, a required exception for a method receiver;
+also, the implementations of copy and append have never honored the restriction.
+

+
+

+Go 1 will allow packages to copy struct values containing unexported fields from other packages.
+Besides resolving the inconsistency,
+this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface.
+The new implementations of time.Time and
+reflect.Value are examples of types taking advantage of this new property.
 

 
 

@@ -414,18 +482,26 @@ will show that the secret field of the struct has been copied to the new value.
 This is a new feature, so existing code needs no changes.
 

 
-
Equality of structs and arrays

+
Equality

 
 

-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).
+Before Go 1, the language did not define equality on struct and array values.
+This meant,
+among other things, that structs and arrays could not be used as map keys.
+On the other hand, Go did define equality on function and map values.
+Function equality was problematic in the presence of closures
+(when are two closures equal?)
+while map equality compared pointers, not the maps' content, which was usually
+not what the user would want.
 

 
 

-As a result, structs and arrays can now be used as map keys:
+Go 1 addressed these issues.
+First, structs and arrays can be compared for equality and inequality
+(== and !=),
+and therefore be used as map keys,
+provided they are composed from elements for which equality is also defined,
+using element-wise comparison.