From 781462dc46db97fa2146844ab2e51e400aa3928d Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Fri, 10 Sep 2010 13:53:18 +1000 Subject: [PATCH] doc/tutorial: update for slice changes. Awaiting the lower-bound change before checkin. Fixes #1067. R=rsc, iant, gri CC=golang-dev https://golang.org/cl/2105043 --- doc/go_tutorial.html | 67 +++++++++++++++++++++++------------------- doc/go_tutorial.txt | 55 ++++++++++++++++++---------------- doc/progs/cat.go | 6 ++-- doc/progs/cat_rot13.go | 12 ++++---- doc/progs/sum.go | 4 +-- 5 files changed, 78 insertions(+), 66 deletions(-) diff --git a/doc/go_tutorial.html b/doc/go_tutorial.html index a653fb032f..13ccb829d4 100644 --- a/doc/go_tutorial.html +++ b/doc/go_tutorial.html @@ -286,14 +286,15 @@ In Go, since arrays are values, it's meaningful (and useful) to talk about pointers to arrays.

The size of the array is part of its type; however, one can declare -a slice variable, to which one can assign a pointer to -any array -with the same element type or—much more commonly—a slice -expression of the form a[low : high], representing -the subarray indexed by low through high-1. -Slices look a lot like arrays but have +a slice variable to hold a reference to any array, of any size, +with the same element type. +A slice +expression has the form a[low : high], representing +the internal array indexed from low through high-1; the resulting +slice is indexed from 0 through high-low-1. +In short, slices look a lot like arrays but with no explicit size ([] vs. [10]) and they reference a segment of -an underlying, often anonymous, regular array. Multiple slices +an underlying, usually anonymous, regular array. Multiple slices can share data if they represent pieces of the same array; multiple arrays can never share data.

@@ -302,17 +303,28 @@ regular arrays; they're more flexible, have reference semantics, and are efficient. What they lack is the precise control of storage layout of a regular array; if you want to have a hundred elements of an array stored within your structure, you should use a regular -array. +array. To create one, use a compound value constructor—an +expression formed +from a type followed by a brace-bounded expression like this: +

+

+    [3]int{1,2,3}
+
+

+In this case the constructor builds an array of 3 ints.

When passing an array to a function, you almost always want to declare the formal parameter to be a slice. When you call -the function, take the address of the array and Go will -create (efficiently) a slice reference and pass that. +the function, slice the array to create +(efficiently) a slice reference and pass that. +By default, the lower and upper bounds of a slice match the +ends of the existing object, so the concise notation [:] +will slice the whole array.

Using slices one can write this function (from sum.go): 

 
-09    func sum(a []int) int {   // returns an int
+09    func sum(a []int) int { // returns an int
 10        s := 0
 11        for i := 0; i < len(a); i++ {
 12            s += a[i]
@@ -321,32 +333,27 @@ Using slices one can write this function (from sum.go):
 15    }

-and invoke it like this: -

-

 
-19        s := sum(&[3]int{1,2,3})  // a slice of the array is passed to sum
-
-

Note how the return type (int) is defined for sum() by stating it after the parameter list. -The expression [3]int{1,2,3}—a type followed by a -brace-bounded -expression—is a constructor for a value, in this case an array -of 3 ints. -Putting an & -in front gives us the address of a unique instance of the value. We pass the -pointer to sum() by (implicitly) promoting it to a slice. +

+To call the function, we slice the array. This intricate call (we'll show +a simpler way in a moment) constructs +an array and slices it: +

+

+    s := sum([3]int{1,2,3}[:])
+

If you are creating a regular array but want the compiler to count the elements for you, use ... as the array size: 

-    s := sum(&[...]int{1,2,3})
+    s := sum([...]int{1,2,3}[:])

-In practice, though, unless you're meticulous about storage layout within a -data structure, a slice itself—using empty brackets and no -&—is all you need: +That's fussier than necessary, though. +In practice, unless you're meticulous about storage layout within a +data structure, a slice itself—using empty brackets with no size—is all you need: 

     s := sum([]int{1,2,3})
@@ -687,7 +694,7 @@ Building on the file package, here's a simple version of the Unix u
 15        const NBUF = 512
 16        var buf [NBUF]byte
 17        for {
-18            switch nr, er := f.Read(&buf); true {
+18            switch nr, er := f.Read(buf[:]); true {
 19            case nr < 0:
 20                fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
 21                os.Exit(1)
@@ -803,7 +810,7 @@ and use it from within a mostly unchanged cat() function:
 57            r = newRotate13(r)
 58        }
 59        for {
-60            switch nr, er := r.Read(&buf); {
+60            switch nr, er := r.Read(buf[:]); {
 61            case nr < 0:
 62                fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
 63                os.Exit(1)
diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt
index bcea0db2b5..477199ac3c 100644
--- a/doc/go_tutorial.txt
+++ b/doc/go_tutorial.txt
@@ -227,14 +227,15 @@ In Go, since arrays are values, it's meaningful (and useful) to talk
 about pointers to arrays.
 
 The size of the array is part of its type; however, one can declare
-a slice variable, to which one can assign a pointer to
-any array
-with the same element type or—much more commonly—a slice
-expression of the form "a[low : high]", representing
-the subarray indexed by "low" through "high-1".
-Slices look a lot like arrays but have
+a slice variable to hold a reference to any array, of any size,
+with the same element type.
+A slice
+expression has the form "a[low : high]", representing
+the internal array indexed from "low" through "high-1"; the resulting
+slice is indexed from "0" through "high-low-1".
+In short, slices look a lot like arrays but with
 no explicit size ("[]" vs. "[10]") and they reference a segment of
-an underlying, often anonymous, regular array.  Multiple slices
+an underlying, usually anonymous, regular array.  Multiple slices
 can share data if they represent pieces of the same array;
 multiple arrays can never share data.
 
@@ -243,39 +244,43 @@ regular arrays; they're more flexible, have reference semantics,
 and are efficient.  What they lack is the precise control of storage
 layout of a regular array; if you want to have a hundred elements
 of an array stored within your structure, you should use a regular
-array.
+array. To create one, use a compound value constructor—an
+expression formed
+from a type followed by a brace-bounded expression like this:
+
+	[3]int{1,2,3}
+
+In this case the constructor builds an array of 3 "ints".
 
 When passing an array to a function, you almost always want
 to declare the formal parameter to be a slice.  When you call
-the function, take the address of the array and  Go will
-create (efficiently) a slice reference and pass that.
+the function, slice the array to create
+(efficiently) a slice reference and pass that.
+By default, the lower and upper bounds of a slice match the
+ends of the existing object, so the concise notation "[:]"
+will slice the whole array.
 
 Using slices one can write this function (from "sum.go"):
 
 --PROG progs/sum.go /sum/ /^}/
 
-and invoke it like this:
-
---PROG progs/sum.go /1,2,3/
-
 Note how the return type ("int") is defined for "sum()" by stating it
 after the parameter list.
-The expression "[3]int{1,2,3}"—a type followed by a
-brace-bounded
-expression—is a constructor for a value, in this case an array
-of 3 "ints".
-Putting an "&"
-in front gives us the address of a unique instance of the value.  We pass the
-pointer to "sum()" by (implicitly) promoting it to a slice.
+
+To call the function, we slice the array.  This intricate call (we'll show
+a simpler way in a moment) constructs
+an array and slices it:
+
+	s := sum([3]int{1,2,3}[:])
 
 If you are creating a regular array but want the compiler to count the
 elements for you, use "..." as the array size:
 
-	s := sum(&[...]int{1,2,3})
+	s := sum([...]int{1,2,3}[:])
 
-In practice, though, unless you're meticulous about storage layout within a
-data structure, a slice itself—using empty brackets and no
-"&"—is all you need:
+That's fussier than necessary, though.
+In practice, unless you're meticulous about storage layout within a
+data structure, a slice itself—using empty brackets with no size—is all you need:
 
 	s := sum([]int{1,2,3})
 
diff --git a/doc/progs/cat.go b/doc/progs/cat.go
index f8d1a54fb8..697e5f7865 100644
--- a/doc/progs/cat.go
+++ b/doc/progs/cat.go
@@ -15,11 +15,11 @@ func cat(f *file.File) {
 	const NBUF = 512
 	var buf [NBUF]byte
 	for {
-		switch nr, er := f.Read(&buf); true {
+		switch nr, er := f.Read(buf[:]); true {
 		case nr < 0:
 			fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", f.String(), er.String())
 			os.Exit(1)
-		case nr == 0:  // EOF
+		case nr == 0: // EOF
 			return
 		case nr > 0:
 			if nw, ew := file.Stdout.Write(buf[0:nr]); nw != nr {
@@ -30,7 +30,7 @@ func cat(f *file.File) {
 }
 
 func main() {
-	flag.Parse()   // Scans the arg list and sets up flags
+	flag.Parse() // Scans the arg list and sets up flags
 	if flag.NArg() == 0 {
 		cat(file.Stdin)
 	}
diff --git a/doc/progs/cat_rot13.go b/doc/progs/cat_rot13.go
index 42c6195fb9..03fc02259a 100644
--- a/doc/progs/cat_rot13.go
+++ b/doc/progs/cat_rot13.go
@@ -15,10 +15,10 @@ var rot13Flag = flag.Bool("rot13", false, "rot13 the input")
 
 func rot13(b byte) byte {
 	if 'a' <= b && b <= 'z' {
-	   b = 'a' + ((b - 'a') + 13) % 26
+		b = 'a' + ((b-'a')+13)%26
 	}
 	if 'A' <= b && b <= 'Z' {
-	   b = 'A' + ((b - 'A') + 13) % 26
+		b = 'A' + ((b-'A')+13)%26
 	}
 	return b
 }
@@ -29,7 +29,7 @@ type reader interface {
 }
 
 type rotate13 struct {
-	source	reader
+	source reader
 }
 
 func newRotate13(source reader) *rotate13 {
@@ -57,11 +57,11 @@ func cat(r reader) {
 		r = newRotate13(r)
 	}
 	for {
-		switch nr, er := r.Read(&buf); {
+		switch nr, er := r.Read(buf[:]); {
 		case nr < 0:
 			fmt.Fprintf(os.Stderr, "cat: error reading from %s: %s\n", r.String(), er.String())
 			os.Exit(1)
-		case nr == 0:  // EOF
+		case nr == 0: // EOF
 			return
 		case nr > 0:
 			nw, ew := file.Stdout.Write(buf[0:nr])
@@ -73,7 +73,7 @@ func cat(r reader) {
 }
 
 func main() {
-	flag.Parse()   // Scans the arg list and sets up flags
+	flag.Parse() // Scans the arg list and sets up flags
 	if flag.NArg() == 0 {
 		cat(file.Stdin)
 	}
diff --git a/doc/progs/sum.go b/doc/progs/sum.go
index 74fd5bca3a..9caa799fdd 100644
--- a/doc/progs/sum.go
+++ b/doc/progs/sum.go
@@ -6,7 +6,7 @@ package main
 
 import "fmt"
 
-func sum(a []int) int {   // returns an int
+func sum(a []int) int { // returns an int
 	s := 0
 	for i := 0; i < len(a); i++ {
 		s += a[i]
@@ -16,6 +16,6 @@ func sum(a []int) int {   // returns an int
 
 
 func main() {
-	s := sum(&[3]int{1,2,3})  // a slice of the array is passed to sum
+	s := sum([3]int{1, 2, 3}[:]) // a slice of the array is passed to sum
 	fmt.Print(s, "\n")
 }
-- 
2.50.0