From c489746ec7de41572ea267e1e3cce40efd2d80b4 Mon Sep 17 00:00:00 2001
From: Mark McGranaghan <mmcgrana@gmail.com>
Date: Wed, 10 Oct 2012 21:53:00 -0700
Subject: [PATCH] publish slices, tweak surrounding

---
 examples.txt                        |  2 +-
 examples/arrays/arrays.go           | 22 ++++----
 examples/arrays/arrays.sh           |  2 +-
 examples/sha1-hashes/sha1-hashes.go |  2 +-
 examples/slices/slices.go           | 79 ++++++++++++++++++++++++++---
 examples/slices/slices.sh           | 21 ++++++++
 examples/tickers/tickers.go         |  8 +--
 examples/timers/timers.go           |  2 +-
 8 files changed, 111 insertions(+), 27 deletions(-)
 create mode 100644 examples/slices/slices.sh

diff --git a/examples.txt b/examples.txt
index e298737..737f1ce 100644
--- a/examples.txt
+++ b/examples.txt
@@ -7,7 +7,7 @@ Hello World
 # If/Else
 # Switch
 Arrays
-# Slices
+Slices
 Maps
 # Range
 # Functions
diff --git a/examples/arrays/arrays.go b/examples/arrays/arrays.go
index 274ce75..5150ff4 100644
--- a/examples/arrays/arrays.go
+++ b/examples/arrays/arrays.go
@@ -1,4 +1,4 @@
-// In Go, an array is a numbered sequence of elements of a
+// In Go, an _array_ is a numbered sequence of elements of a
 // specific length.
 
 package main
@@ -10,26 +10,26 @@ func main() {
     // The type of elements and length are both part of
     // the array's type. Here we create an array `x` that
     // will hold exactly 5 ints.
-    var x [5]int
+    var a [5]int
 
     // By default an array is zero-valued, which for ints
     // means an array of `0`s.
-    fmt.Println("emp:", x)
+    fmt.Println("emp:", a)
 
     // We can set a value at a given index using the
     // `array[index] = value` syntax, and get a value
     // with `array[index]`.
-    x[4] = 100
-    fmt.Println("set:", x)
-    fmt.Println("get:", x[4])
+    a[4] = 100
+    fmt.Println("set:", a)
+    fmt.Println("get:", a[4])
+
+    // The builtin `len` returns the length of an array.
+    fmt.Println("len:", len(a))
 
     // Use this syntax to decalare and initalize an array
     // in one line.
-    y := [5]int{1, 2, 3, 4, 4}
-    fmt.Println("dcl:", y)
-
-    // The builtin `len` returns the length of an array.
-    fmt.Println("len:", len(y))
+    b := [5]int{1, 2, 3, 4, 5}
+    fmt.Println("dcl:", b)
 
     // Array types are one-dimensional, but you can
     // compose types to build multi-dimensional data
diff --git a/examples/arrays/arrays.sh b/examples/arrays/arrays.sh
index 639468f..b6401f5 100644
--- a/examples/arrays/arrays.sh
+++ b/examples/arrays/arrays.sh
@@ -4,8 +4,8 @@ $ go run arrays.go
 emp: [0 0 0 0 0]
 set: [0 0 0 0 100]
 get: 100
-dcl: [1 2 3 4 4]
 len: 5
+dcl: [1 2 3 4 5]
 2d:  [[0 1 2] [1 2 3]]
 
 # You'll see _slices_ much more often than arrays in
diff --git a/examples/sha1-hashes/sha1-hashes.go b/examples/sha1-hashes/sha1-hashes.go
index 9da8d68..12c6d5c 100644
--- a/examples/sha1-hashes/sha1-hashes.go
+++ b/examples/sha1-hashes/sha1-hashes.go
@@ -1,4 +1,4 @@
-// [SHA1 hashes](http://en.wikipedia.org/wiki/SHA-1) are
+// [_SHA1 hashes_](http://en.wikipedia.org/wiki/SHA-1) are
 // frequently used to compute short identities for binary
 // or text blobs. For example, the [git revision control
 // system](http://git-scm.com/) uses SHA1s extensively to
diff --git a/examples/slices/slices.go b/examples/slices/slices.go
index fc0fb85..41107de 100644
--- a/examples/slices/slices.go
+++ b/examples/slices/slices.go
@@ -1,14 +1,77 @@
+// _Slices_ are a key data type in Go, giving a more
+// powerful interface to sequences that arrays.
+
 package main
 
 import "fmt"
 
 func main() {
-    slice1 := []int{1, 2, 3}
-    slice2 := append(slice1, 4, 5)
-    fmt.Println(slice1)
-    fmt.Println(slice2)
-    slice3 := make([]int, 2)
-    copy(slice3, slice1)
-    fmt.Println(slice1)
-    fmt.Println(slice3)
+
+    // In contrast to arrays, slices are typed only
+    // by the elements it contains (not the number of
+    // elements). To create an empty slice with non-zero
+    // length, use the builtin `make`. Here we make a
+    // slice of `int`s of length 5.
+    s := make([]int, 5)
+
+    // New slices are initially empty-valued.
+    fmt.Println("emp:", s)
+
+    // We can set and get just like with arrays.
+    s[4] = 100
+    fmt.Println("set:", s)
+    fmt.Println("get:", s[4])
+
+    // `len` returns the length of the slice as expected.
+    fmt.Println("len:", len(s))
+
+    // In addition to these basic operations, slices
+    // support several more that make them richer than
+    // arrays. One is the builtin `append`, which 
+    // returns a slice containing one or more new values.
+    // Note that we need to accapt a return value from
+    // append as we may get a new slice reference.
+    s = append(s, 6)
+    s = append(s, 7, 8)
+    fmt.Println("apd:", s)
+
+    // Slices can also be `copy`'d. Here we create an
+    // empty slice `c` of the same length as `s` and copy
+    // into `c` from `s`.
+    c := make([]int, len(s))
+    copy(c, s)
+    fmt.Println("cpy:", c)
+
+    // Slices support a "slice" operator, which is denoted
+    // with brackets containing a `:`. For example, this
+    // get a slice of the elements 4, 5, and 6.
+    l := s[4:7]
+    fmt.Println("sl1:", l)
+
+    // To slice up the 7th index.
+    l = s[:7]
+    fmt.Println("sl2:", l)
+
+    // Or from the 4th index upwards.
+    l = s[4:]
+    fmt.Println("sl3:", l)
+
+    // We can declare and initalize a slice in a single
+    // line as well.
+    t := []int{1, 2, 3, 4, 5}
+    fmt.Println("dcl:", t)
+
+    // Slices can be composed into multi-dimensional data
+    // structures. The length of the inner slices can
+    // vary, unlike in the case of multi-dimensional
+    // arrays.
+    twoD := make([][]int, 3)
+    for i := 0; i < 3; i++ {
+        innerLen := i + 1
+        twoD[i] = make([]int, innerLen)
+        for j := 0; j < innerLen; j++ {
+            twoD[i][j] = i + j
+        }
+    }
+    fmt.Println("2d: ", twoD)
 }
diff --git a/examples/slices/slices.sh b/examples/slices/slices.sh
new file mode 100644
index 0000000..dde66d7
--- /dev/null
+++ b/examples/slices/slices.sh
@@ -0,0 +1,21 @@
+# Note that while slices are different types than arrays,
+# they are rendered similarly by `fmt.Println`.
+$ go run slices.go
+emp: [0 0 0 0 0]
+set: [0 0 0 0 100]
+get: 100
+len: 5
+apd: [0 0 0 0 100 6 7 8]
+cpy: [0 0 0 0 100 6 7 8]
+sl1: [100 6 7]
+sl2: [0 0 0 0 100 6 7]
+sl3: [100 6 7 8]
+dcl: [1 2 3 4 5]
+2d:  [[0] [1 2] [2 3 4]]
+
+# Check out this [great blog post](http://blog.golang.org/2011/01/go-slices-usage-and-internals.html)
+# by the Go team for more details on the design and
+# implementation of slices in Go.
+
+# Now that we've seen arrays and slices we'll look at
+# Go's other key builtin data structure: maps.
diff --git a/examples/tickers/tickers.go b/examples/tickers/tickers.go
index fa10a6b..bb716ab 100644
--- a/examples/tickers/tickers.go
+++ b/examples/tickers/tickers.go
@@ -1,8 +1,8 @@
 // [Timers](timers) are for when you want to do
-// something once in the future - tickers are for when you
-// want to do something repeatedly at regular intervals.
-// Here's an example of a ticker that ticks periodically
-// until we stop it.
+// something once in the future - _tickers_ are for when
+// you want to do something repeatedly at regular
+// intervals. Here's an example of a ticker that ticks
+// periodically until we stop it.
 
 package main
 
diff --git a/examples/timers/timers.go b/examples/timers/timers.go
index a0a8937..08fe02b 100644
--- a/examples/timers/timers.go
+++ b/examples/timers/timers.go
@@ -1,6 +1,6 @@
 // We often want to execute Go code at some point in the
 // future, or repeatedly at some interval. Go's built-in
-// timer and ticker features make both of these tasks
+// _timer_ and _ticker_ features make both of these tasks
 // easy. We'll look first at timers and then
 // at [tickers](tickers).