summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/articles/godoc_documenting_go_code.html14
-rw-r--r--doc/articles/image_package.html4
-rw-r--r--doc/articles/race_detector.html54
-rw-r--r--doc/code.html474
-rw-r--r--doc/codewalk/markov.xml2
-rw-r--r--doc/codewalk/urlpoll.go2
-rw-r--r--doc/contribute.html7
-rw-r--r--doc/devel/weekly.html4
-rw-r--r--doc/docs.html6
-rw-r--r--doc/effective_go.html758
-rw-r--r--doc/gccgo_contribute.html2
-rw-r--r--doc/go1.1.html1004
-rw-r--r--doc/go1.html10
-rw-r--r--doc/go_faq.html162
-rw-r--r--doc/go_spec.html455
-rw-r--r--doc/godocs.js8
-rw-r--r--doc/install.html56
-rw-r--r--doc/progs/eff_unused1.go18
-rw-r--r--doc/progs/eff_unused2.go22
-rwxr-xr-xdoc/progs/run1
-rw-r--r--doc/progs/unused1.go12
-rw-r--r--doc/progs/unused2.go16
-rw-r--r--doc/reference.html6
-rw-r--r--doc/root.html41
-rw-r--r--doc/style.css5
25 files changed, 2415 insertions, 728 deletions
diff --git a/doc/articles/godoc_documenting_go_code.html b/doc/articles/godoc_documenting_go_code.html
index 18a3ee953..3f4e3228c 100644
--- a/doc/articles/godoc_documenting_go_code.html
+++ b/doc/articles/godoc_documenting_go_code.html
@@ -83,18 +83,20 @@ godoc's output, with one notable exception. Top-level comments that begin with
the word <code>"BUG(who)"</code> are recognized as known bugs, and included in
the "Bugs" section of the package documentation. The "who" part should be the
user name of someone who could provide more information. For example, this is a
-known issue from the <a href="/pkg/bytes/#pkg-bugs"><code>bytes</code></a> package:
+known issue from the <a href="/pkg/sync/atomic/#pkg-note-BUG"><code>sync/atomic</code></a> package:
</p>
<pre>
-// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
+// BUG(rsc): On x86-32, the 64-bit functions use instructions
+// unavailable before the Pentium MMX. On both ARM and x86-32, it is the
+// caller's responsibility to arrange for 64-bit alignment of 64-bit
+// words accessed atomically.
</pre>
<p>
-Godoc treats executable commands somewhat differently. Instead of inspecting the
-command source code, it looks for a Go source file belonging to the special
-package "documentation". The comment on the "package documentation" clause is
-used as the command's documentation. For example, see the
+Godoc treats executable commands in the same way. It looks for a comment on
+package main, which is sometimes put in a separate file called <code>doc.go</code>.
+For example, see the
<a href="/cmd/godoc/">godoc documentation</a> and its corresponding
<a href="/src/cmd/godoc/doc.go">doc.go</a> file.
</p>
diff --git a/doc/articles/image_package.html b/doc/articles/image_package.html
index ebe92a1ca..39a93ccda 100644
--- a/doc/articles/image_package.html
+++ b/doc/articles/image_package.html
@@ -130,7 +130,7 @@ much easier to type.
A <code>Rectangle</code> is inclusive at the top-left and exclusive at the
bottom-right. For a <code>Point p</code> and a <code>Rectangle r</code>,
<code>p.In(r)</code> if and only if
-<code>r.Min.X &lt;= p.X &amp;&amp; p.X &lt; r.Max.X</code>, and similarly for <code>Y</code>. This is analagous to how
+<code>r.Min.X &lt;= p.X &amp;&amp; p.X &lt; r.Max.X</code>, and similarly for <code>Y</code>. This is analogous to how
a slice <code>s[i0:i1]</code> is inclusive at the low end and exclusive at the
high end. (Unlike arrays and slices, a <code>Rectangle</code> often has a
non-zero origin.)
@@ -236,7 +236,7 @@ more complicated, to access these struct type's <code>Pix</code> field directly.
The slice-based <code>Image</code> implementations also provide a
<code>SubImage</code> method, which returns an <code>Image</code> backed by the
same array. Modifying the pixels of a sub-image will affect the pixels of the
-original image, analagous to how modifying the contents of a sub-slice
+original image, analogous to how modifying the contents of a sub-slice
<code>s[i0:i1]</code> will affect the contents of the original slice
<code>s</code>.
</p>
diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html
index 400d96b19..2d36f616e 100644
--- a/doc/articles/race_detector.html
+++ b/doc/articles/race_detector.html
@@ -6,7 +6,9 @@
<h2 id="Introduction">Introduction</h2>
<p>
-Data races are one of the most common and hardest to debug types of bugs in concurrent systems. A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write. See the <a href="/ref/mem/">The Go Memory Model</a> for details.
+Data races are among the most common and hardest to debug types of bugs in concurrent systems.
+A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write.
+See the <a href="/ref/mem/">The Go Memory Model</a> for details.
</p>
<p>
@@ -32,7 +34,8 @@ func main() {
<h2 id="Usage">Usage</h2>
<p>
-Fortunately, Go includes a built-in data race detector. To use it, add the <code>-race</code> flag to the go command:
+To help diagnose such bugs, Go includes a built-in data race detector.
+To use it, add the <code>-race</code> flag to the go command:
</p>
<pre>
@@ -45,7 +48,9 @@ $ go install -race mypkg // to install the package
<h2 id="Report_Format">Report Format</h2>
<p>
-When the race detector finds a data race in the program, it prints a report. The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created. For example:
+When the race detector finds a data race in the program, it prints a report.
+The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created.
+Here is an example:
</p>
<pre>
@@ -86,7 +91,8 @@ Goroutine 184 (running) created at:
<h2 id="Options">Options</h2>
<p>
-The <code>GORACE</code> environment variable sets race detector options. The format is:
+The <code>GORACE</code> environment variable sets race detector options.
+The format is:
</p>
<pre>
@@ -100,7 +106,8 @@ The options are:
<ul>
<li>
<code>log_path</code> (default <code>stderr</code>): The race detector writes
-its report to a file named log_path.pid. The special names <code>stdout</code>
+its report to a file named <code>log_path.<em>pid</em></code>.
+The special names <code>stdout</code>
and <code>stderr</code> cause reports to be written to standard output and
standard error, respectively.
</li>
@@ -117,8 +124,8 @@ from all reported file paths, to make reports more concise.
<li>
<code>history_size</code> (default <code>1</code>): The per-goroutine memory
-access history is <code>32K * 2**history_size elements</code>. Increasing this
-value can avoid a "failed to restore the stack" error in reports, but at the
+access history is <code>32K * 2**history_size elements</code>.
+Increasing this value can avoid a "failed to restore the stack" error in reports, at the
cost of increased memory usage.
</li>
</ul>
@@ -134,9 +141,10 @@ $ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test -
<h2 id="Excluding_Tests">Excluding Tests</h2>
<p>
-When you build with <code>-race</code> flag, go command defines additional
-<a href="/pkg/go/build/#Build_Constraints">build tag</a> <code>race</code>.
-You can use it to exclude some code/tests under the race detector. For example:
+When you build with <code>-race</code> flag, the <code>go</code> command defines additional
+<a href="/pkg/go/build/#hdr-Build_Constraints">build tag</a> <code>race</code>.
+You can use the tag to exclude some code and tests when running the race detector.
+Some examples:
</p>
<pre>
@@ -165,7 +173,8 @@ func TestBaz(t *testing.T) {
<p>
To start, run your tests using the race detector (<code>go test -race</code>).
The race detector only finds races that happen at runtime, so it can't find
-races in code paths that are not executed. If your tests have incomplete coverage,
+races in code paths that are not executed.
+If your tests have incomplete coverage,
you may find more races by running a binary built with <code>-race</code> under a realistic
workload.
</p>
@@ -194,9 +203,9 @@ func main() {
<p>
The variable <code>i</code> in the function literal is the same variable used by the loop, so
-the read in the goroutine races with the loop increment. (This program typically
-prints 55555, not 01234.) The program can be fixed by making a copy of the
-variable:
+the read in the goroutine races with the loop increment.
+(This program typically prints 55555, not 01234.)
+The program can be fixed by making a copy of the variable:
</p>
<pre>
@@ -246,7 +255,7 @@ func ParallelWrite(data []byte) chan error {
</pre>
<p>
-The fix is to introduce new variables in the goroutines (note <code>:=</code>):
+The fix is to introduce new variables in the goroutines (note the use of <code>:=</code>):
</p>
<pre>
@@ -260,8 +269,8 @@ The fix is to introduce new variables in the goroutines (note <code>:=</code>):
<h3 id="Unprotected_global_variable">Unprotected global variable</h3>
<p>
-If the following code is called from several goroutines, it leads to bad races on the <code>service</code> map.
-Concurrent reads and writes of a map are not safe:
+If the following code is called from several goroutines, it leads to races on the <code>service</code> map.
+Concurrent reads and writes of the same map are not safe:
</p>
<pre>
@@ -302,7 +311,8 @@ func LookupService(name string) net.Addr {
<h3 id="Primitive_unprotected_variable">Primitive unprotected variable</h3>
<p>
-Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.), like in the following example:
+Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.),
+as in this example:
</p>
<pre>
@@ -327,12 +337,16 @@ func (w *Watchdog) Start() {
</pre>
<p>
-Even such &ldquo;innocent&rdquo; data races can lead to hard to debug problems caused by (1) non-atomicity of the memory accesses, (2) interference with compiler optimizations and (3) processor memory access reordering issues.
+Even such "innocent" data races can lead to hard-to-debug problems caused by
+non-atomicity of the memory accesses,
+interference with compiler optimizations,
+or reordering issues accessing processor memory .
</p>
<p>
A typical fix for this race is to use a channel or a mutex.
-To preserve the lock-free behavior, one can also use the <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package.
+To preserve the lock-free behavior, one can also use the
+<a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package.
</p>
<pre>
diff --git a/doc/code.html b/doc/code.html
index 82b211870..f64dd6a2a 100644
--- a/doc/code.html
+++ b/doc/code.html
@@ -6,344 +6,381 @@
<p>
This document demonstrates the development of a simple Go package and
-introduces the <a href="/cmd/go/">go command</a>, the standard way to fetch,
+introduces the <a href="/cmd/go/">go tool</a>, the standard way to fetch,
build, and install Go packages and commands.
</p>
<p>
-This content is also available as a <a href="http://www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>.
+The <code>go</code> tool requires you to organize your code in a specific
+way. Please read this document carefully.
+It explains the simplest way to get up and running with your Go installation.
+</p>
+
+<p>
+A similar explanation is available as a
+<a href="http://www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>.
</p>
-<h2 id="GOPATH">Code organization</h2>
+<h2 id="Organization">Code organization</h2>
-<h3><code>GOPATH</code> and workspaces</h3>
+<h3 id="Workspaces">Workspaces</h3>
<p>
-One of Go's design goals is to make writing software easier. To that end, the
-<code>go</code> command doesn't use Makefiles or other configuration files to
-guide program construction. Instead, it uses the source code to find
-dependencies and determine build conditions. This means your source code and
-build scripts are always in sync; they are one and the same.
+The <code>go</code> tool is designed to work with open source code maintained
+in public repositories. Although you don't need to publish your code, the model
+for how the environment is set up works the same whether you do or not.
</p>
<p>
-The one thing you must do is set a <code>GOPATH</code> environment variable.
-<code>GOPATH</code> tells the <code>go</code> command (and other related tools)
-where to find and install the Go packages on your system.
+Go code must be kept inside a <i>workspace</i>.
+A workspace is a directory hierarchy with three directories at its root:
</p>
+<ul>
+<li><code>src</code> contains Go source files organized into packages (one package per directory),
+<li><code>pkg</code> contains package objects, and
+<li><code>bin</code> contains executable commands.
+</ul>
+
<p>
-<code>GOPATH</code> is a list of paths. It shares the syntax of your system's
-<code>PATH</code> environment variable. A typical <code>GOPATH</code> on
-a Unix system might look like this:
+The <code>go</code> tool builds source packages and installs the resulting
+binaries to the <code>pkg</code> and <code>bin</code> directories.
</p>
-<pre>
-GOPATH=/home/user/ext:/home/user/mygo
-</pre>
-
<p>
-(On a Windows system use semicolons as the path separator instead of colons.)
+The <code>src</code> subdirectory typically contains multiple version control
+repositories (such as for Git or Mercurial) that track the development of one
+or more source packages.
</p>
<p>
-Each path in the list (in this case <code>/home/user/ext</code> or
-<code>/home/user/mygo</code>) specifies the location of a <i>workspace</i>.
-A workspace contains Go source files and their associated package objects, and
-command executables. It has a prescribed structure of three subdirectories:
+To give you an idea of how a workspace looks in practice, here's an example:
</p>
-<ul>
-<li><code>src</code> contains Go source files,
-<li><code>pkg</code> contains compiled package objects, and
-<li><code>bin</code> contains executable commands.
-</ul>
+<pre>
+bin/
+ streak # command executable
+ todo # command executable
+pkg/
+ linux_amd64/
+ code.google.com/p/goauth2/
+ oauth.a # package object
+ github.com/nf/todo/
+ task.a # package object
+src/
+ code.google.com/p/goauth2/
+ .hg/ # mercurial repository metadata
+ oauth/
+ oauth.go # package source
+ oauth_test.go # test source
+ github.com/nf/
+ streak/
+ .git/ # git repository metadata
+ oauth.go # command source
+ streak.go # command source
+ todo/
+ .git/ # git repository metadata
+ task/
+ task.go # package source
+ todo.go # command source
+</pre>
<p>
-Subdirectories of the <code>src</code> directory hold independent packages, and
-all source files (<code>.go</code>, <code>.c</code>, <code>.h</code>, and
-<code>.s</code>) in each subdirectory are elements of that subdirectory's
-package.
+This workspace contains three repositories (<code>goauth2</code>,
+<code>streak</code>, and <code>todo</code>) comprising two commands
+(<code>streak</code> and <code>todo</code>) and two libraries
+(<code>oauth</code> and <code>task</code>).
</p>
<p>
-When building a program that imports the package "<code>widget</code>" the
-<code>go</code> command looks for <code>src/pkg/widget</code> inside the Go root,
-and then&mdash;if the package source isn't found there&mdash;it searches
-for <code>src/widget</code> inside each workspace in order.
+Commands and libraries are built from different kinds of source packages.
+We will discuss the distinction <a href="#PackageNames">later</a>.
</p>
+
+<h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>
+
<p>
-Multiple workspaces can offer some flexibility and convenience, but for now
-we'll concern ourselves with only a single workspace.
+The <code>GOPATH</code> environment variable specifies the location of your
+workspace. It is likely the only environment variable you'll need to set
+when developing Go code.
</p>
<p>
-Let's work through a simple example. First, create a <code>$HOME/mygo</code>
-directory and its <code>src</code> subdirectory:
+To get started, create a workspace directory and set <code>GOPATH</code>
+accordingly. Your workspace can be located wherever you like, but we'll use
+<code>$HOME/go</code> in this document. Note that this must <b>not</b> be the
+same path as your Go installation.
</p>
<pre>
-$ mkdir -p $HOME/mygo/src # create a place to put source code
+$ <b>mkdir $HOME/go</b>
+$ <b>export GOPATH=$HOME/go</b>
</pre>
<p>
-Next, set it as the <code>GOPATH</code>. You should also add the
-<code>bin</code> subdirectory to your <code>PATH</code> environment variable so
-that you can run the commands therein without specifying their full path.
-To do this, add the following lines to <code>$HOME/.profile</code> (or
-equivalent):
+For convenience, add the workspace's <code>bin</code> subdirectory
+to your <code>PATH</code>:
</p>
<pre>
-export GOPATH=$HOME/mygo
-export PATH=$PATH:$HOME/mygo/bin
+$ <b>export PATH=$PATH:$GOPATH/bin</b>
</pre>
-<h3>Import paths</h3>
+<h3 id="PackagePaths">Package paths</h3>
<p>
-The standard packages are given short import paths such as <code>"fmt"</code>
-and <code>"net/http"</code> for convenience.
-For your own projects, it is important to choose a base import path that is
-unlikely to collide with future additions to the standard library or other
-external libraries.
+The packages from the standard library are given short paths such as
+<code>"fmt"</code> and <code>"net/http"</code>.
+For your own packages, you must choose a base path that is unlikely to
+collide with future additions to the standard library or other external
+libraries.
</p>
<p>
-The best way to choose an import path is to use the location of your version
-control repository.
-For instance, if your source repository is at <code>example.com</code>
-or <code>code.google.com/p/example</code>, you should begin your package
-paths with that URL, as in "<code>example.com/foo/bar</code>" or
-"<code>code.google.com/p/example/foo/bar</code>".
-Using this convention, the <code>go</code> command can automatically check out and
-build the source code by its import path alone.
+If you keep your code in a source repository somewhere, then you should use the
+root of that source repository as your base path.
+For instance, if you have a <a href="https://github.com/">GitHub</a> account at
+<code>github.com/user</code>, that should be your base path.
</p>
<p>
-If you don't intend to install your code in this way, you should at
-least use a unique prefix like "<code>widgets/</code>", as in
-"<code>widgets/foo/bar</code>". A good rule is to use a prefix such as your
-company or project name, since it is unlikely to be used by another group.
+Note that you don't need to publish your code to a remote repository before you
+can build it. It's just a good habit to organize your code as if you will
+publish it someday. In practice you can choose any arbitrary path name,
+as long as it is unique to the standard library and greater Go ecosystem.
</p>
<p>
-We'll use <code>example/</code> as our base import path:
+We'll use <code>github.com/user</code> as our base path. Create a directory
+inside your workspace in which to keep source code:
</p>
<pre>
-$ mkdir -p $GOPATH/src/example
+$ <b>mkdir -p $GOPATH/src/github.com/user</b>
</pre>
-<h3>Package names</h3>
+<h3 id="Command">Your first program</h3>
<p>
-The first statement in a Go source file should be
+To compile and run a simple program, first choose a package path (we'll use
+<code>github.com/user/hello</code>) and create a corresponding package directory
+inside your workspace:
</p>
<pre>
-package <i>name</i>
+$ <b>mkdir $GOPATH/src/github.com/user/hello</b>
</pre>
<p>
-where <code><i>name</i></code> is the package's default name for imports.
-(All files in a package must use the same <code><i>name</i></code>.)
+Next, create a file named <code>hello.go</code> inside that directory,
+containing the following Go code.
</p>
-<p>
-Go's convention is that the package name is the last element of the
-import path: the package imported as "<code>crypto/rot13</code>"
-should be named <code>rot13</code>.
-There is no requirement that package names be unique
-across all packages linked into a single binary,
-only that the import paths (their full file names) be unique.
-</p>
+<pre>
+package main
-<p>
-Create a new package under <code>example</code> called <code>newmath</code>:
-</p>
+import "fmt"
-<pre>
-$ cd $GOPATH/src/example
-$ mkdir newmath
+func main() {
+ fmt.Printf("Hello, world.\n")
+}
</pre>
<p>
-Then create a file named <code>$GOPATH/src/example/newmath/sqrt.go</code>
-containing the following Go code:
+Now you can build and install that program with the <code>go</code> tool:
</p>
<pre>
-// Package newmath is a trivial example package.
-package newmath
-
-// Sqrt returns an approximation to the square root of x.
-func Sqrt(x float64) float64 {
- // This is a terrible implementation.
- // Real code should import "math" and use math.Sqrt.
- z := 0.0
- for i := 0; i &lt; 1000; i++ {
- z -= (z*z - x) / (2 * x)
- }
- return z
-}
+$ <b>go install github.com/user/hello</b>
</pre>
<p>
-This package is imported by the path name of the directory it's in, starting
-after the <code>src</code> component:
+Note that you can run this command from anywhere on your system. The
+<code>go</code> tool finds the source code by looking for the
+<code>github.com/user/hello</code> package inside the workspace specified by
+<code>GOPATH</code>.
+</p>
+
+<p>
+You can also omit the package path if you run <code>go install</code> from the
+package directory:
</p>
<pre>
-import "example/newmath"
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>go install</b>
</pre>
<p>
-See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
-Go's naming conventions.
+This command builds the <code>hello</code> command, producing an executable
+binary. It then installs that binary to the workspace's <code>bin</code>
+directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>).
+In our example, that will be <code>$GOPATH/bin/hello</code>, which is
+<code>$HOME/go/bin/hello</code>.
</p>
-
-<h2>Building and installing</h2>
+<p>
+The <code>go</code> tool will only print output when an error occurs, so if
+these commands produce no output they have executed successfully.
+</p>
<p>
-The <code>go</code> command comprises several subcommands, the most central being
-<code>install</code>. Running <code>go install <i>importpath</i></code> builds
-and installs a package and its dependencies.
+You can now run the program by typing its full path at the command line:
</p>
+<pre>
+$ <b>$GOPATH/bin/hello</b>
+Hello, world.
+</pre>
+
<p>
-To "install a package" means to write the package object or executable command
-to the <code>pkg</code> or <code>bin</code> subdirectory of the workspace in
-which the source resides.
+Or, as you have added <code>$GOPATH/bin</code> to your <code>PATH</code>,
+just type the binary name:
</p>
-<h3>Building a package</h3>
+<pre>
+$ <b>hello</b>
+Hello, world.
+</pre>
<p>
-To build and install the <code>newmath</code> package, type
+If you're using a source control system, now would be a good time to initialize
+a repository, add the files, and commit your first change. Again, this step is
+optional: you do not need to use source control to write Go code.
</p>
<pre>
-$ go install example/newmath
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>git init</b>
+Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
+$ <b>git add hello.go</b>
+$ <b>git commit -m "initial commit"</b>
+[master (root-commit) 0b4507d] initial commit
+ 1 file changed, 1 insertion(+)
+ create mode 100644 hello.go
</pre>
<p>
-This command will produce no output if the package and its dependencies
-are built and installed correctly.
+Pushing the code to a remote repository is left as an exercise for the reader.
+</p>
+
+
+<h3 id="Library">Your first library</h3>
+
+<p>
+Let's write a library and use it from the <code>hello</code> program.
</p>
<p>
-As a convenience, the <code>go</code> command will assume the current directory
-if no import path is specified on the command line. This sequence of commands
-has the same effect as the one above:
+Again, the first step is to choose a package path (we'll use
+<code>github.com/user/newmath</code>) and create the package directory:
</p>
<pre>
-$ cd $GOPATH/src/example/newmath
-$ go install
+$ <b>mkdir $GOPATH/src/github.com/user/newmath</b>
</pre>
<p>
-The resulting workspace directory tree (assuming we're running Linux on a 64-bit
-system) looks like this:
+Next, create a file named <code>sqrt.go</code> in that directory with the
+following contents.
</p>
<pre>
-pkg/
- linux_amd64/
- example/
- newmath.a # package object
-src/
- example/
- newmath/
- sqrt.go # package source
-</pre>
-
+// Package newmath is a trivial example package.
+package newmath
-<h3>Building a command</h3>
+// Sqrt returns an approximation to the square root of x.
+func Sqrt(x float64) float64 {
+ z := 0.0
+ for i := 0; i < 1000; i++ {
+ z -= (z*z - x) / (2 * x)
+ }
+ return z
+}
+</pre>
<p>
-The <code>go</code> command treats code belonging to <code>package main</code> as
-an executable command and installs the package binary to the
-<code>GOPATH</code>'s <code>bin</code> subdirectory.
+Now, test that the package compiles with <code>go build</code>:
</p>
+<pre>
+$ <b>go build github.com/user/newmath</b>
+</pre>
+
<p>
-Add a command named <code>hello</code> to the source tree.
-First create the <code>example/hello</code> directory:
+Or, if you are working in the package's source directory, just:
</p>
<pre>
-$ cd $GOPATH/src/example
-$ mkdir hello
+$ <b>go build</b>
</pre>
<p>
-Then create the file <code>$GOPATH/src/example/hello/hello.go</code>
-containing the following Go code.
+This won't produce an output file. To do that, you must use <code>go
+install</code>, which places the package object inside the <code>pkg</code>
+directory of the workspace.
+</p>
+
+<p>
+After confirming that the <code>newmath</code> package builds,
+modify your original <code>hello.go</code> (which is in
+<code>$GOPATH/src/github.com/user/hello</code>) to use it:
</p>
<pre>
-// Hello is a trivial example of a main package.
package main
import (
- "example/newmath"
- "fmt"
+ "fmt"
+
+ <b>"github.com/user/newmath"</b>
)
func main() {
- fmt.Printf("Hello, world. Sqrt(2) = %v\n", newmath.Sqrt(2))
+ fmt.Printf("Hello, world. <b>Sqrt(2) = %v\n", newmath.Sqrt(2)</b>)
}
</pre>
<p>
-Next, run <code>go install</code>, which builds and installs the binary to
-<code>$GOPATH/bin</code> (or <code>$GOBIN</code>, if set; to simplify
-presentation, this document assumes <code>GOBIN</code> is unset):
+Whenever the <code>go</code> tool installs a package or binary, it also
+installs whatever dependencies it has. So when you install the <code>hello</code>
+program
</p>
<pre>
-$ go install example/hello
+$ <b>go install github.com/user/hello</b>
</pre>
<p>
-To run the program, invoke it by name as you would any other command:
+the <code>newmath</code> package will be installed as well, automatically.
</p>
-<pre>
-$ $GOPATH/bin/hello
-Hello, world. Sqrt(2) = 1.414213562373095
-</pre>
-
<p>
-If you added <code>$HOME/mygo/bin</code> to your <code>PATH</code>, you may omit
-the path to the executable:
+Running the new version of the program, you should see some numerical output:
</p>
<pre>
-$ hello
+$ <b>hello</b>
Hello, world. Sqrt(2) = 1.414213562373095
</pre>
<p>
-The workspace directory tree now looks like this:
+After the steps above, your workspace should look like this:
</p>
<pre>
bin/
hello # command executable
pkg/
- linux_amd64/
- example/
+ linux_amd64/ # this will reflect your OS and architecture
+ github.com/user/
newmath.a # package object
src/
- example/
+ github.com/user/
hello/
hello.go # command source
newmath/
@@ -351,13 +388,55 @@ src/
</pre>
<p>
-The <code>go</code> command also provides a <code>build</code> command, which is
-like <code>install</code> except it builds all objects in a temporary directory
-and does not install them under <code>pkg</code> or <code>bin</code>.
-When building a command an executable named after the last element of the
-import path is written to the current directory. When building a package,
-<code>go build</code> serves merely to test that the package and its
-dependencies can be built. (The resulting package object is thrown away.)
+Note that <code>go install</code> placed the <code>newmath.a</code> object in a
+directory inside <code>pkg/linux_amd64</code> that mirrors its source
+directory.
+This is so that future invocations of the <code>go</code> tool can find the
+package object and avoid recompiling the package unnecessarily.
+The <code>linux_amd64</code> part is there to aid in cross-compilation,
+and will reflect the operating system and architecture of your system.
+</p>
+
+<p>
+Go command executables are statically linked; the package objects need not
+be present to run Go programs.
+</p>
+
+
+<h3 id="PackageNames">Package names</h3>
+
+<p>
+The first statement in a Go source file must be
+</p>
+
+<pre>
+package <i>name</i>
+</pre>
+
+<p>
+where <code><i>name</i></code> is the package's default name for imports.
+(All files in a package must use the same <code><i>name</i></code>.)
+</p>
+
+<p>
+Go's convention is that the package name is the last element of the
+import path: the package imported as "<code>crypto/rot13</code>"
+should be named <code>rot13</code>.
+</p>
+
+<p>
+Executable commands must always use <code>package main</code>.
+</p>
+
+<p>
+There is no requirement that package names be unique
+across all packages linked into a single binary,
+only that the import paths (their full file names) be unique.
+</p>
+
+<p>
+See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
+Go's naming conventions.
</p>
@@ -379,8 +458,8 @@ if the function calls a failure function such as <code>t.Error</code> or
<p>
Add a test to the <code>newmath</code> package by creating the file
-<code>$GOPATH/src/example/newmath/sqrt_test.go</code> containing the following
-Go code.
+<code>$GOPATH/src/github.com/user/newmath/sqrt_test.go</code> containing the
+following Go code.
</p>
<pre>
@@ -392,17 +471,27 @@ func TestSqrt(t *testing.T) {
const in, out = 4, 2
if x := Sqrt(in); x != out {
t.Errorf("Sqrt(%v) = %v, want %v", in, x, out)
- }
+ }
}
</pre>
<p>
-Now run the test with <code>go test</code>:
+Then run the test with <code>go test</code>:
+</p>
+
+<pre>
+$ <b>go test github.com/user/newmath</b>
+ok github.com/user/newmath 0.165s
+</pre>
+
+<p>
+As always, if you are running the <code>go</code> tool from the package
+directory, you can omit the package path:
</p>
<pre>
-$ go test example/newmath
-ok example/newmath 0.165s
+$ <b>go test</b>
+ok github.com/user/newmath 0.165s
</pre>
<p>
@@ -415,7 +504,7 @@ Run <code><a href="/cmd/go/#hdr-Test_packages">go help test</a></code> and see t
<p>
An import path can describe how to obtain the package source code using a
-revision control system such as Git or Mercurial. The <code>go</code> command uses
+revision control system such as Git or Mercurial. The <code>go</code> tool uses
this property to automatically fetch packages from remote repositories.
For instance, the examples described in this document are also kept in a
Mercurial repository hosted at Google Code,
@@ -425,8 +514,8 @@ If you include the repository URL in the package's import path,
</p>
<pre>
-$ go get code.google.com/p/go.example/hello
-$ $GOPATH/bin/hello
+$ <b>go get code.google.com/p/go.example/hello</b>
+$ <b>$GOPATH/bin/hello</b>
Hello, world. Sqrt(2) = 1.414213562373095
</pre>
@@ -439,17 +528,17 @@ fetch and behaves the same as <code>go install</code>.)
<p>
After issuing the above <code>go get</code> command, the workspace directory
-tree should now now look like this:
+tree should now look like this:
</p>
<pre>
bin/
hello # command executable
pkg/
- linux_amd64/
+ linux_amd64/
code.google.com/p/go.example/
newmath.a # package object
- example/
+ github.com/user/
newmath.a # package object
src/
code.google.com/p/go.example/
@@ -458,7 +547,7 @@ src/
newmath/
sqrt.go # package source
sqrt_test.go # test source
- example/
+ github.com/user/
hello/
hello.go # command source
newmath/
@@ -480,12 +569,13 @@ import "code.google.com/p/go.example/newmath"
<p>
This convention is the easiest way to make your Go packages available for
others to use.
-The <a href="http://code.google.com/p/go-wiki/wiki/Projects">Go Community Wiki</a>
-has a list of external Go projects including programs and libraries.
+The <a href="http://code.google.com/p/go-wiki/wiki/Projects">Go Wiki</a>
+and <a href="http://godoc.org/">godoc.org</a>
+provide lists of external Go projects.
</p>
<p>
-For more information on using remote repositories with the <code>go</code> command, see
+For more information on using remote repositories with the <code>go</code> tool, see
<code><a href="/cmd/go/#hdr-Remote_import_path_syntax">go help remote</a></code>.
</p>
diff --git a/doc/codewalk/markov.xml b/doc/codewalk/markov.xml
index 7f1281817..76c448ac3 100644
--- a/doc/codewalk/markov.xml
+++ b/doc/codewalk/markov.xml
@@ -181,7 +181,7 @@ p == Prefix{"am", "not"}</pre>
one index to the left (if you consider zero as the leftmost index).
<pre>
p := Prefix{"I", "am"}
-copy(p, p[:1])
+copy(p, p[1:])
// p == Prefix{"am", "am"}</pre>
We then assign the provided <code>word</code> to the last index
of the slice:
diff --git a/doc/codewalk/urlpoll.go b/doc/codewalk/urlpoll.go
index e716c7e6c..1fb99581f 100644
--- a/doc/codewalk/urlpoll.go
+++ b/doc/codewalk/urlpoll.go
@@ -76,7 +76,7 @@ func (r *Resource) Poll() string {
return resp.Status
}
-// Sleep sleeps for an appropriate interval (dependant on error state)
+// Sleep sleeps for an appropriate interval (dependent on error state)
// before sending the Resource to done.
func (r *Resource) Sleep(done chan<- *Resource) {
time.Sleep(pollInterval + errTimeout*time.Duration(r.errCount))
diff --git a/doc/contribute.html b/doc/contribute.html
index 72c936472..c659de617 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -117,6 +117,13 @@ enabled for your checkout in <code>$GOROOT</code>, the remainder of this
document assumes you are inside <code>$GOROOT</code> when issuing commands.
</p>
+<p>
+Windows users may need to perform extra steps to get the code review
+extension working. See the
+<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a>
+on the <a href="http://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details.
+</p>
+
<h3>Log in to the code review site.</h3>
<p>
diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html
index f8d3ec6dd..c22064258 100644
--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -2035,7 +2035,7 @@ Other changes:
* spec: define order of multiple assignment.
* syscall/windows: dll function load and calling changes (thanks Alex Brainman).
* syscall: add #ifdefs to fix the manual corrections in ztypes_linux_arm.go (thanks Dave Cheney),
- adjust Mount to accomodate stricter FS implementations.
+ adjust Mount to accommodate stricter FS implementations.
* testing: fix time reported for failing tests.
* utf8: add Valid and ValidString.
* websocket: tweak hybi ReadHandshake to support Firefox (thanks Luca Greco).
@@ -4362,7 +4362,7 @@ The print/println bootstrapping functions now write to standard error.
To write to standard output, use fmt.Print[ln].
A new tool, govet, has been added to the Go distribution. Govet is a static
-checker for Go programs. At the moment, and for the forseeable future,
+checker for Go programs. At the moment, and for the foreseeable future,
it only checks arguments to print calls.
The cgo tool for writing Go bindings for C code has changed so that it no
diff --git a/doc/docs.html b/doc/docs.html
index 3112381c2..2dcab5d51 100644
--- a/doc/docs.html
+++ b/doc/docs.html
@@ -82,6 +82,12 @@ Answers to common questions about Go.
A guide for updating your code to work with Go 1.
</p>
+<h3 id="go1.1notes"><a href="/doc/go1.1.html">Go 1.1 Release Notes</a></h3>
+<p>
+A list of significant changes in Go 1.1, with instructions for updating your
+code where necessary.
+</p>
+
<h3 id="go1compat"><a href="/doc/go1compat.html">Go 1 and the Future of Go Programs</a></h3>
<p>
What Go 1 defines and the backwards-compatibility guarantees one can expect as
diff --git a/doc/effective_go.html b/doc/effective_go.html
index e02694add..1b3168683 100644
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -403,8 +403,10 @@ if owner != user {
<p>
By convention, one-method interfaces are named by
-the method name plus the -er suffix: <code>Reader</code>,
-<code>Writer</code>, <code>Formatter</code> etc.
+the method name plus an -er suffix or similar modification
+to construct an agent noun: <code>Reader</code>,
+<code>Writer</code>, <code>Formatter</code>,
+<code>CloseNotifier</code> etc.
</p>
<p>
@@ -696,10 +698,18 @@ for _, value := range array {
</pre>
<p>
+The blank identifier has many uses, as described in <a href="#blank">a later section</a>.
+
+<p>
For strings, the <code>range</code> does more work for you, breaking out individual
Unicode code points by parsing the UTF-8.
Erroneous encodings consume one byte and produce the
-replacement rune U+FFFD. The loop
+replacement rune U+FFFD.
+(The name (with associated builtin type) <code>rune</code> is Go terminology for a
+single Unicode code point.
+See <a href="http://golang.org/ref/spec#Rune_literals">the language specification</a>
+for details.)
+The loop
</p>
<pre>
for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding
@@ -797,6 +807,8 @@ func Compare(a, b []byte) int {
}
</pre>
+<h2 id="type_switch">Type switch</h2>
+
<p>
A switch can also be used to discover the dynamic type of an interface
variable. Such a <em>type switch</em> uses the syntax of a type
@@ -831,8 +843,8 @@ case *int:
One of Go's unusual features is that functions and methods
can return multiple values. This form can be used to
improve on a couple of clumsy idioms in C programs: in-band
-error returns (such as <code>-1</code> for <code>EOF</code>)
-and modifying an argument.
+error returns such as <code>-1</code> for <code>EOF</code>
+and modifying an argument passed by address.
</p>
<p>
@@ -841,7 +853,8 @@ error code secreted away in a volatile location.
In Go, <code>Write</code>
can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
bytes but not all of them because you filled the device&rdquo;.
-The signature of <code>File.Write</code> in package <code>os</code> is:
+The signature of the <code>Write</code> method on files from
+package <code>os</code> is:
</p>
<pre>
@@ -1208,7 +1221,7 @@ It creates slices, maps, and channels only, and it returns an <em>initialized</e
(not <em>zeroed</em>)
value of type <code>T</code> (not <code>*T</code>).
The reason for the distinction
-is that these three types are, under the covers, references to data structures that
+is that these three types represent, under the covers, references to data structures that
must be initialized before use.
A slice, for example, is a three-item descriptor
containing a pointer to the data (inside an array), the length, and the
@@ -1253,7 +1266,8 @@ v := make([]int, 100)
<p>
Remember that <code>make</code> applies only to maps, slices and channels
and does not return a pointer.
-To obtain an explicit pointer allocate with <code>new</code>.
+To obtain an explicit pointer allocate with <code>new</code> or take the address
+of a variable explicitly.
</p>
<h3 id="arrays">Arrays</h3>
@@ -1300,7 +1314,8 @@ x := Sum(&amp;array) // Note the explicit address-of operator
</pre>
<p>
-But even this style isn't idiomatic Go. Slices are.
+But even this style isn't idiomatic Go.
+Use slices instead.
</p>
<h3 id="slices">Slices</h3>
@@ -1312,9 +1327,9 @@ dimension such as transformation matrices, most array programming in
Go is done with slices rather than simple arrays.
</p>
<p>
-Slices are <i>reference types</i>, which means that if you assign one
-slice to another, both refer to the same underlying array. For
-instance, if a function takes a slice argument, changes it makes to
+Slices hold references to an underlying array, and if you assign one
+slice to another, both refer to the same array.
+If a function takes a slice argument, changes it makes to
the elements of the slice will be visible to the caller, analogous to
passing a pointer to the underlying array. A <code>Read</code>
function can therefore accept a slice argument rather than a pointer
@@ -1391,19 +1406,87 @@ design, though, we need a little more information, so we'll return
to it later.
</p>
+<h3 id="two_dimensional_slices">Two-dimensional slices</h3>
+
+<p>
+Go's arrays and slices are one-dimensional.
+To create the equivalent of a 2D array or slice, it is necessary to define an array-of-arrays
+or slice-of-slices, like this:
+</p>
+
+<pre>
+type Transform [3][3]float64 // A 3x3 array, really an array of arrays.
+type LinesOfText [][]byte // A slice of byte slices.
+</pre>
+
+<p>
+Because slices are variable-length, it is possible to have each inner
+slice be a different length.
+That can be a common situation, as in our <code>LinesOfText</code>
+example: each line has an independent length.
+</p>
+
+<pre>
+text := LinesOfText{
+ []byte("Now is the time"),
+ []byte("for all good gophers"),
+ []byte("to bring some fun to the party."),
+}
+</pre>
+
+<p>
+Sometimes it's necessary to allocate a 2D slice, a situation that can arise when
+processing scan lines of pixels, for instance.
+There are two ways to achieve this.
+One is to allocate each slice independently; the other
+is to allocate a single array and point the individual slices into it.
+Which to use depends on your application.
+If the slices might grow or shrink, they should be allocated independently
+to avoid overwriting the next line; if not, it can be more efficient to construct
+the object with a single allocation.
+For reference, here are sketches of the two methods.
+First, a line a time:
+</p>
+
+<pre>
+// Allocate the top-level slice.
+picture := make([][]uint8, YSize) // One row per unit of y.
+// Loop over the rows, allocating the slice for each row.
+for i := range picture {
+ picture[i] = make([]uint8, XSize)
+}
+</pre>
+
+<p>
+And now as one allocation, sliced into lines:
+</p>
+
+<pre>
+// Allocate the top-level slice, the same as before.
+picture := make([][]uint8, YSize) // One row per unit of y.
+// Allocate one large slice to hold all the pixels.
+pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8.
+// Loop over the rows, slicing each row from the front of the remaining pixels slice.
+for i := range picture {
+ picture[i], pixels = pixels[:XSize], pixels[XSize:]
+}
+</pre>
<h3 id="maps">Maps</h3>
<p>
-Maps are a convenient and powerful built-in data structure to associate
-values of different types.
+Maps are a convenient and powerful built-in data structure that associate
+values of one type (the <em>key</em>) with values of another type
+(the <em>element</em> or <em>value</em>)
The key can be of any type for which the equality operator is defined,
such as integers,
floating point and complex numbers,
strings, pointers, interfaces (as long as the dynamic type
-supports equality), structs and arrays. Slices cannot be used as map keys,
+supports equality), structs and arrays.
+Slices cannot be used as map keys,
because equality is not defined on them.
-Like slices, maps are a reference type. If you pass a map to a function
+Like slices, maps hold references to an underlying data structure.
+If you pass a map to a function
that changes the contents of the map, the changes will be visible
in the caller.
</p>
@@ -1453,7 +1536,7 @@ if attended[person] { // will be false if person is not in the map
<p>
Sometimes you need to distinguish a missing entry from
a zero value. Is there an entry for <code>"UTC"</code>
-or is that zero value because it's not in the map at all?
+or is that the empty string because it's not in the map at all?
You can discriminate with a form of multiple assignment.
</p>
<pre>
@@ -1480,10 +1563,8 @@ func offset(tz string) int {
</pre>
<p>
To test for presence in the map without worrying about the actual value,
-you can use the blank identifier (<code>_</code>).
-The blank identifier can be assigned or declared with any value of any type, with the
-value discarded harmlessly. For testing just presence in a map, use the blank
-identifier in place of the usual variable for the value.
+you can use the <a href="#blank">blank identifier</a> (<code>_</code>)
+in place of the usual variable for the value.
</p>
<pre>
_, present := timeZone[tz]
@@ -1491,7 +1572,7 @@ _, present := timeZone[tz]
<p>
To delete a map entry, use the <code>delete</code>
built-in function, whose arguments are the map and the key to be deleted.
-It's safe to do this this even if the key is already absent
+It's safe to do this even if the key is already absent
from the map.
</p>
<pre>
@@ -1524,8 +1605,7 @@ fmt.Println("Hello", 23)
fmt.Println(fmt.Sprint("Hello ", 23))
</pre>
<p>
-As mentioned in
-the <a href="http://tour.golang.org">Tour</a>, <code>fmt.Fprint</code>
+The formatted print functions <code>fmt.Fprint</code>
and friends take as a first argument any object
that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
and <code>os.Stderr</code> are familiar instances.
@@ -1591,8 +1671,10 @@ map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
<p>
(Note the ampersands.)
That quoted string format is also available through <code>%q</code> when
-applied to a value of type <code>string</code> or <code>[]byte</code>;
-the alternate format <code>%#q</code> will use backquotes instead if possible.
+applied to a value of type <code>string</code> or <code>[]byte</code>.
+The alternate format <code>%#q</code> will use backquotes instead if possible.
+(The <code>%q</code> format also applies to integers and runes, producing a
+single-quoted rune constant.)
Also, <code>%x</code> works on strings, byte arrays and byte slices as well as
on integers, generating a long hexadecimal string, and with
a space in the format (<code>%&nbsp;x</code>) it puts spaces between the bytes.
@@ -1632,10 +1714,45 @@ the receiver for <code>String</code> must be of value type; this example used a
that's more efficient and idiomatic for struct types.
See the section below on <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
</p>
+
<p>
Our <code>String</code> method is able to call <code>Sprintf</code> because the
-print routines are fully reentrant and can be used recursively.
-We can even go one step further and pass a print routine's arguments directly to another such routine.
+print routines are fully reentrant and can be wrapped this way.
+There is one important detail to understand about this approach,
+however: don't construct a <code>String</code> method by calling
+<code>Sprintf</code> in a way that will recur into your <code>String</code>
+method indefinitely. This can happen if the <code>Sprintf</code>
+call attempts to print the receiver directly as a string, which in
+turn will invoke the method again. It's a common and easy mistake
+to make, as this example shows.
+</p>
+
+<pre>
+type MyString string
+
+func (m MyString) String() string {
+ return fmt.Sprintf("MyString=%s", m) // Error: will recur forever.
+}
+</pre>
+
+<p>
+It's also easy to fix: convert the argument to the basic string type, which does not have the
+method.
+</p>
+
+<pre>
+type MyString string
+func (m MyString) String() string {
+ return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion.
+}
+</pre>
+
+<p>
+In the <a href="#initialization">initialization section</a> we'll see another technique that avoids this recursion.
+</p>
+
+<p>
+Another printing technique is to pass a print routine's arguments directly to another such routine.
The signature of <code>Printf</code> uses the type <code>...interface{}</code>
for its final argument to specify that an arbitrary number of parameters (of arbitrary type)
can appear after the format.
@@ -1690,7 +1807,7 @@ is different from our custom <code>Append</code> function above.
Schematically, it's like this:
</p>
<pre>
-func append(slice []<i>T</i>, elements...T) []<i>T</i>
+func append(slice []<i>T</i>, elements ...<i>T</i>) []<i>T</i>
</pre>
<p>
where <i>T</i> is a placeholder for any given type. You can't
@@ -1738,7 +1855,7 @@ would be wrong; <code>y</code> is not of type <code>int</code>.
Although it doesn't look superficially very different from
initialization in C or C++, initialization in Go is more powerful.
Complex structures can be built during initialization and the ordering
-issues between initialized objects in different packages are handled
+issues among initialized objects, even among different packages, are handled
correctly.
</p>
@@ -1748,7 +1865,7 @@ correctly.
Constants in Go are just that&mdash;constant.
They are created at compile time, even when defined as
locals in functions,
-and can only be numbers, strings or booleans.
+and can only be numbers, characters (runes), strings or booleans.
Because of the compile-time restriction, the expressions
that define them must be constant expressions,
evaluatable by the compiler. For instance,
@@ -1766,9 +1883,11 @@ sets of values.
</p>
{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
<p>
-The ability to attach a method such as <code>String</code> to a
-type makes it possible for such values to format themselves
-automatically for printing, even as part of a general type.
+The ability to attach a method such as <code>String</code> to any
+user-defined type makes it possible for arbitrary values to format themselves
+automatically for printing.
+Although you'll see it most often applied to structs, this technique is also useful for
+scalar types such as floating-point types like <code>ByteSize</code>.
</p>
{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
<p>
@@ -1777,13 +1896,13 @@ while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
</p>
<p>
-Note that it's fine to call <code>Sprintf</code> and friends in the
-implementation of <code>String</code> methods, but beware of
-recurring into the <code>String</code> method through the nested
-<code>Sprintf</code> call using a string format
-(<code>%s</code>, <code>%q</code>, <code>%v</code>, <code>%x</code> or <code>%X</code>).
-The <code>ByteSize</code> implementation of <code>String</code> is safe
-because it calls <code>Sprintf</code> with <code>%f</code>.
+The use here of <code>Sprintf</code>
+to implement <code>ByteSize</code>'s <code>String</code> method is safe
+(avoids recurring indefinitely) not because of a conversion but
+because it calls <code>Sprintf</code> with <code>%f</code>,
+which is not a string format: <code>Sprintf</code> will only call
+the <code>String</code> method when it wants a string, and <code>%f</code>
+wants a floating-point value.
</p>
<h3 id="variables">Variables</h3>
@@ -1837,7 +1956,8 @@ func init() {
<h3 id="pointers_vs_values">Pointers vs. Values</h3>
<p>
-Methods can be defined for any named type that is not a pointer or an interface;
+As we saw with <code>ByteSize</code>,
+methods can be defined for any named type (except a pointer or an interface);
the receiver does not have to be a struct.
</p>
<p>
@@ -1898,7 +2018,7 @@ modifications to be discarded.
</p>
<p>
By the way, the idea of using <code>Write</code> on a slice of bytes
-is implemented by <code>bytes.Buffer</code>.
+is central to the implementation of <code>bytes.Buffer</code>.
</p>
<h2 id="interfaces_and_types">Interfaces and other types</h2>
@@ -1941,10 +2061,8 @@ func (s Sequence) String() string {
}
</pre>
<p>
-The conversion causes <code>s</code> to be treated as an ordinary slice
-and therefore receive the default formatting.
-Without the conversion, <code>Sprint</code> would find the
-<code>String</code> method of <code>Sequence</code> and recur indefinitely.
+This method is another example of the conversion technique for calling
+<code>Sprintf</code> safely from a <code>String</code> method.
Because the two types (<code>Sequence</code> and <code>[]int</code>)
are the same if we ignore the type name, it's legal to convert between them.
The conversion doesn't create a new value, it just temporarily acts
@@ -1976,6 +2094,91 @@ and <code>[]int</code>), each of which does some part of the job.
That's more unusual in practice but can be effective.
</p>
+<h3 id="interface_conversions">Interface conversions and type assertions</h3>
+
+<p>
+<a href="#type_switch">Type switches</a> are a form of conversion: they take an interface and, for
+each case in the switch, in a sense convert it to the type of that case.
+Here's a simplified version of how the code under <code>fmt.Printf</code> turns a value into
+a string using a type switch.
+If it's already a string, we want the actual string value held by the interface, while if it has a
+<code>String</code> method we want the result of calling the method.
+</p>
+
+<pre>
+type Stringer interface {
+ String() string
+}
+
+var value interface{} // Value provided by caller.
+switch str := value.(type) {
+case string:
+ return str
+case Stringer:
+ return str.String()
+}
+</pre>
+
+<p>
+The first case finds a concrete value; the second converts the interface into another interface.
+It's perfectly fine to mix types this way.
+</p>
+
+<p>
+What if there's only one type we care about? If we know the value holds a <code>string</code>
+and we just want to extract it?
+A one-case type switch would do, but so would a <em>type assertion</em>.
+A type assertion takes an interface value and extracts from it a value of the specified explicit type.
+The syntax borrows from the clause opening a type switch, but with an explicit
+type rather than the <code>type</code> keyword:
+
+<pre>
+value.(typeName)
+</pre>
+
+<p>
+and the result is a new value with the static type <code>typeName</code>.
+That type must either be the concrete type held by the interface, or a second interface
+type that the value can be converted to.
+To extract the string we know is in the value, we could write:
+</p>
+
+<pre>
+str := value.(string)
+</pre>
+
+<p>
+But if it turns out that the value does not contain a string, the program will crash with a run-time error.
+To guard against that, use the "comma, ok" idiom to test, safely, whether the value is a string:
+</p>
+
+<pre>
+str, ok := value.(string)
+if ok {
+ fmt.Printf("string value is: %q\n", str)
+} else {
+ fmt.Printf("value is not a string\n")
+}
+</pre>
+
+<p>
+If the type assertion fails, <code>str</code> will still exist and be of type string, but it will have
+the zero value, an empty string.
+</p>
+
+<p>
+As an illustration of the capability, here's an <code>if</code>-<code>else</code>
+statement that's equivalent to the type switch that opened this section.
+</p>
+
+<pre>
+if str, ok := value.(string); ok {
+ return str
+} else if str, ok := value.(Stringer); ok {
+ return str.String()
+}
+</pre>
+
<h3 id="generality">Generality</h3>
<p>
If a type exists only to implement an interface
@@ -2133,9 +2336,7 @@ It's easy to write a function to print the arguments.
</p>
<pre>
func ArgServer() {
- for _, s := range os.Args {
- fmt.Println(s)
- }
+ fmt.Println(os.Args)
}
</pre>
<p>
@@ -2171,9 +2372,7 @@ to have the right signature.
<pre>
// Argument server.
func ArgServer(w http.ResponseWriter, req *http.Request) {
- for _, s := range os.Args {
- fmt.Fprintln(w, s)
- }
+ fmt.Fprintln(w, os.Args)
}
</pre>
<p>
@@ -2202,6 +2401,196 @@ a channel, and a function, all because interfaces are just sets of
methods, which can be defined for (almost) any type.
</p>
+<h2 id="blank">The blank identifier</h2>
+
+<p>
+We've mentioned the blank identifier a couple of times now, in the context of
+<a href="#for"><code>for</code> <code>range</code> loops</a>
+and <a href="#maps">maps</a>.
+The blank identifier can be assigned or declared with any value of any type, with the
+value discarded harmlessly.
+It's a bit like writing to the Unix <code>/dev/null</code> file:
+it represents a write-only value
+to be used as a place-holder
+where a variable is needed but the actual value is irrelevant.
+It has uses beyond those we've seen already.
+</p>
+
+<h3 id="blank_assign">The blank identifier in multiple assignment</h3>
+
+<p>
+The use of a blank identifier in a <code>for</code> <code>range</code> loop is a
+special case of a general situation: multiple assignment.
+<p>
+If an assignment requires multiple values on the left side,
+but one of the values will not be used by the program,
+a blank identifier on the left-hand-side of
+the assignment avoids the need
+to create a dummy variable and makes it clear that the
+value is to be discarded.
+For instance, when calling a function that returns
+a value and an error, but only the error is important,
+use the blank identifier to discard the irrelevant value.
+</p>
+
+<pre>
+if _, err := os.Stat(path); os.IsNotExist(err) {
+ fmt.Printf("%s does not exist\n", path)
+}
+</pre>
+
+<p>
+Occasionally you'll see code that discards the error value in order
+to ignore the error; this is terrible practice. Always check error returns;
+they're provided for a reason.
+</p>
+
+<pre>
+// Bad! This code will crash if path does not exist.
+fi, _ := os.Stat(path)
+if fi.IsDir() {
+ fmt.Printf("%s is a directory\n", path)
+}
+</pre>
+
+<h3 id="blank_unused">Unused imports and variables</h3>
+
+<p>
+It is an error to import a package or to declare a variable without using it.
+Unused imports bloat the program and slow compilation,
+while a variable that is initialized but not used is at least
+a wasted computation and perhaps indicative of a
+larger bug.
+When a program is under active development, however,
+unused imports and variables often arise and it can
+be annoying to delete them just to have the compilation proceed,
+only to have them be needed again later.
+The blank identifier provides a workaround.
+</p>
+<p>
+This half-written program has two unused imports
+(<code>fmt</code> and <code>io</code>)
+and an unused variable (<code>fd</code>),
+so it will not compile, but it would be nice to see if the
+code so far is correct.
+</p>
+{{code "/doc/progs/eff_unused1.go" `/package/` `$`}}
+<p>
+To silence complaints about the unused imports, use a
+blank identifier to refer to a symbol from the imported package.
+Similarly, assigning the unused variable <code>fd</code>
+to the blank identifier will silence the unused variable error.
+This version of the program does compile.
+</p>
+{{code "/doc/progs/eff_unused2.go" `/package/` `$`}}
+
+<p>
+By convention, the global declarations to silence import errors
+should come right after the imports and be commented,
+both to make them easy to find and as a reminder to clean things up later.
+</p>
+
+<h3 id="blank_import">Import for side effect</h3>
+
+<p>
+An unused import like <code>fmt</code> or <code>io</code> in the
+previous example should eventually be used or removed:
+blank assignments identify code as a work in progress.
+But sometimes it is useful to import a package only for its
+side effects, without any explicit use.
+For example, during its <code>init</code> function,
+the <code><a href="/pkg/net/http/pprof/">net/http/pprof</a></code>
+package registers HTTP handlers that provide
+debugging information. It has an exported API, but
+most clients need only the handler registration and
+access the data through a web page.
+To import the package only for its side effects, rename the package
+to the blank identifier:
+</p>
+<pre>
+import _ "net/http/pprof"
+</pre>
+<p>
+This form of import makes clear that the package is being
+imported for its side effects, because there is no other possible
+use of the package: in this file, it doesn't have a name.
+(If it did, and we didn't use that name, the compiler would reject the program.)
+</p>
+
+<h3 id="blank_implements">Interface checks</h3>
+
+<p>
+As we saw in the discussion of <a href="#interfaces_and_types">interfaces</a> above,
+a type need not declare explicitly that it implements an interface.
+Instead, a type implements the interface just by implementing the interface's methods.
+In practice, most interface conversions are static and therefore checked at compile time.
+For example, passing an <code>*os.File</code> to a function
+expecting an <code>io.Reader</code> will not compile unless
+<code>*os.File</code> implements the <code>io.Reader</code> interface.
+</p>
+
+<p>
+Some interface checks do happen at run-time, though.
+One instance is in the <code><a href="/pkg/encoding/json/">encoding/json</a></code>
+package, which defines a <code><a href="/pkg/encoding/json/#Marshaler">Marshaler</a></code>
+interface. When the JSON encoder receives a value that implements that interface,
+the encoder invokes the value's marshaling method to convert it to JSON
+instead of doing the standard conversion.
+The encoder checks this property at run time with a <a href="interface_conversions">type assertion</a> like:
+</p>
+
+<pre>
+m, ok := val.(json.Marshaler)
+</pre>
+
+<p>
+If it's necessary only to ask whether a type implements an interface, without
+actually using the interface itself, perhaps as part of an error check, use the blank
+identifier to ignore the type-asserted value:
+</p>
+
+<pre>
+if _, ok := val.(json.Marshaler); ok {
+ fmt.Printf("value %v of type %T implements json.Marshaler\n", val, val)
+}
+</pre>
+
+<p>
+One place this situation arises is when it is necessary to guarantee within the package implementing the type that
+it actually satisfies the interface.
+If a type—for example,
+<code><a href="/pkg/encoding/json/#RawMessage">json.RawMessage</a></code>—needs
+a custom its JSON representation, it should implement
+<code>json.Marshaler</code>, but there are no static conversions that would
+cause the compiler to verify this automatically.
+If the type inadvertently fails to satisfy the interface, the JSON encoder will still work,
+but will not use the custom implementation.
+To guarantee that the implementation is correct,
+a global declaration using the blank identifier can be used in the package:
+</p>
+<pre>
+var _ json.Marshaler = (*RawMessage)(nil)
+</pre>
+<p>
+In this declaration, the assignment involving a conversion of a
+<code>*RawMessage</code> to a <code>Marshaler</code>
+requires that <code>*RawMessage</code> implements <code>Marshaler</code>,
+and that property will be checked at compile time.
+Should the <code>json.Marshaler</code> interface change, this package
+will no longer compile and we will be on notice that it needs to be updated.
+</p>
+
+<p>
+The appearance of the blank identifier in this construct indicates that
+the declaration exists only for the type checking,
+not to create a variable.
+Don't do this for every type that satisfies an interface, though.
+By convention, such declarations are only used
+when there are no static conversions already present in the code,
+which is a rare event.
+</p>
+
+
<h2 id="embedding">Embedding</h2>
<p>
@@ -2328,8 +2717,8 @@ log to the <code>Job</code>:
job.Log("starting now...")
</pre>
<p>
-The <code>Logger</code> is a regular field of the struct and we can initialize
-it in the usual way with a constructor,
+The <code>Logger</code> is a regular field of the <code>Job</code> struct,
+so we can initialize it in the usual way inside the constructor for <code>Job</code>, like this,
</p>
<pre>
func NewJob(command string, logger *log.Logger) *Job {
@@ -2344,10 +2733,12 @@ job := &amp;Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
</pre>
<p>
If we need to refer to an embedded field directly, the type name of the field,
-ignoring the package qualifier, serves as a field name. If we needed to access the
+ignoring the package qualifier, serves as a field name, as it did
+in the <code>Read</code> method of our <code>ReaderWriter</code> struct.
+Here, if we needed to access the
<code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>,
-we would write <code>job.Logger</code>.
-This would be useful if we wanted to refine the methods of <code>Logger</code>.
+we would write <code>job.Logger</code>,
+which would be useful if we wanted to refine the methods of <code>Logger</code>.
</p>
<pre>
func (job *Job) Logf(format string, args ...interface{}) {
@@ -2463,7 +2854,8 @@ completion. For that, we need channels.
<h3 id="channels">Channels</h3>
<p>
-Like maps, channels are a reference type and are allocated with <code>make</code>.
+Like maps, channels are allocated with <code>make</code>, and
+the resulting value acts as a reference to an underlying data structure.
If an optional integer parameter is provided, it sets the buffer size for the channel.
The default is zero, for an unbuffered or synchronous channel.
</p>
@@ -2473,7 +2865,7 @@ cj := make(chan int, 0) // unbuffered channel of integers
cs := make(chan *os.File, 100) // buffered channel of pointers to Files
</pre>
<p>
-Channels combine communication&mdash;the exchange of a value&mdash;with
+Unbuffered channels combine communication&mdash;the exchange of a value&mdash;with
synchronization&mdash;guaranteeing that two calculations (goroutines) are in
a known state.
</p>
@@ -2503,18 +2895,26 @@ means waiting until some receiver has retrieved a value.
<p>
A buffered channel can be used like a semaphore, for instance to
limit throughput. In this example, incoming requests are passed
-to <code>handle</code>, which sends a value into the channel, processes
-the request, and then receives a value from the channel.
+to <code>handle</code>, which receives a value from the channel, processes
+the request, and then sends a value back to the channel
+to ready the "semaphore" for the next consumer.
The capacity of the channel buffer limits the number of
-simultaneous calls to <code>process</code>.
+simultaneous calls to <code>process</code>,
+so during initialization we prime the channel by filling it to capacity.
</p>
<pre>
var sem = make(chan int, MaxOutstanding)
func handle(r *Request) {
- sem &lt;- 1 // Wait for active queue to drain.
- process(r) // May take a long time.
- &lt;-sem // Done; enable next request to run.
+ &lt;-sem // Wait for active queue to drain.
+ process(r) // May take a long time.
+ sem &lt;- 1 // Done; enable next request to run.
+}
+
+func init() {
+ for i := 0; i < MaxOutstanding; i++ {
+ sem &lt;- 1
+ }
}
func Serve(queue chan *Request) {
@@ -2524,8 +2924,37 @@ func Serve(queue chan *Request) {
}
}
</pre>
+
+<p>
+Because data synchronization occurs on a receive from a channel
+(that is, the send "happens before" the receive; see
+<a href="/ref/mem">The Go Memory Model</a>),
+acquisition of the semaphore must be on a channel receive, not a send.
+</p>
+
+<p>
+This design has a problem, though: <code>Serve</code>
+creates a new goroutine for
+every incoming request, even though only <code>MaxOutstanding</code>
+of them can run at any moment.
+As a result, the program can consume unlimited resources if the requests come in too fast.
+We can address that deficiency by changing <code>Serve</code> to
+gate the creation of the goroutines.
+</p>
+
+<pre>
+func Serve(queue chan *Request) {
+ for req := range queue {
+ &lt;-sem
+ go func() {
+ process(req)
+ sem &lt;- 1
+ }()
+ }
+}</pre>
+
<p>
-Here's the same idea implemented by starting a fixed
+Another solution that manages resources well is to start a fixed
number of <code>handle</code> goroutines all reading from the request
channel.
The number of goroutines limits the number of simultaneous
@@ -2534,6 +2963,7 @@ This <code>Serve</code> function also accepts a channel on which
it will be told to exit; after launching the goroutines it blocks
receiving from that channel.
</p>
+
<pre>
func handle(queue chan *Request) {
for r := range queue {
@@ -2669,6 +3099,17 @@ of logical CPUs on the local machine.
Again, this requirement is expected to be retired as the scheduling and run-time improve.
</p>
+<p>
+Be sure not to confuse the ideas of concurrency—structuring a program
+as independently executing components—and parallelism—executing
+calculations in parallel for efficiency on multiple CPUs.
+Although the concurrency features of Go can make some problems easy
+to structure as parallel computations, Go is a concurrent language,
+not a parallel one, and not all parallelization problems fit Go's model.
+For a discussion of the distinction, see the talk cited in
+<a href="http://blog.golang.org/2013/01/concurrency-is-not-parallelism.html">this
+blog post</a>.
+
<h3 id="leaky_buffer">A leaky buffer</h3>
<p>
@@ -2785,7 +3226,7 @@ it is much more informative than the plain
<p>
When feasible, error strings should identify their origin, such as by having
-a prefix naming the package that generated the error. For example, in package
+a prefix naming the operation or package that generated the error. For example, in package
<code>image</code>, the string representation for a decoding error due to an
unknown format is "image: unknown format".
</p>
@@ -2813,11 +3254,8 @@ for try := 0; try &lt; 2; try++ {
</pre>
<p>
-The second <code>if</code> statement here is idiomatic Go.
-The type assertion <code>err.(*os.PathError)</code> is
-checked with the "comma ok" idiom (mentioned <a href="#maps">earlier</a>
-in the context of examining maps).
-If the type assertion fails, <code>ok</code> will be false, and <code>e</code>
+The second <code>if</code> statement here is another <a href="#interface_conversion">type assertion</a>.
+If it fails, <code>ok</code> will be false, and <code>e</code>
will be <code>nil</code>.
If it succeeds, <code>ok</code> will be true, which means the
error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
@@ -2840,9 +3278,7 @@ that in effect creates a run-time error that will stop the program
(but see the next section). The function takes a single argument
of arbitrary type&mdash;often a string&mdash;to be printed as the
program dies. It's also a way to indicate that something impossible has
-happened, such as exiting an infinite loop. In fact, the compiler
-recognizes a <code>panic</code> at the end of a function and
-suppresses the usual check for a <code>return</code> statement.
+happened, such as exiting an infinite loop.
</p>
@@ -2944,7 +3380,7 @@ With our recovery pattern in place, the <code>do</code>
function (and anything it calls) can get out of any bad situation
cleanly by calling <code>panic</code>. We can use that idea to
simplify error handling in complex software. Let's look at an
-idealized excerpt from the <code>regexp</code> package, which reports
+idealized version of a <code>regexp</code> package, which reports
parsing errors by calling <code>panic</code> with a local
error type. Here's the definition of <code>Error</code>,
an <code>error</code> method, and the <code>Compile</code> function.
@@ -2980,23 +3416,32 @@ func Compile(str string) (regexp *Regexp, err error) {
<p>
If <code>doParse</code> panics, the recovery block will set the
return value to <code>nil</code>&mdash;deferred functions can modify
-named return values. It then will then check, in the assignment
+named return values. It will then check, in the assignment
to <code>err</code>, that the problem was a parse error by asserting
that it has the local type <code>Error</code>.
If it does not, the type assertion will fail, causing a run-time error
that continues the stack unwinding as though nothing had interrupted
-it. This check means that if something unexpected happens, such
+it.
+This check means that if something unexpected happens, such
as an index out of bounds, the code will fail even though we
are using <code>panic</code> and <code>recover</code> to handle
-user-triggered errors.
+parse errors.
</p>
<p>
-With error handling in place, the <code>error</code> method
+With error handling in place, the <code>error</code> method (because it's a
+method bound to a type, it's fine, even natural, for it to have the same name
+as the builtin <code>error</code> type)
makes it easy to report parse errors without worrying about unwinding
-the parse stack by hand.
+the parse stack by hand:
</p>
+<pre>
+if pos==0 {
+ re.error("'*' illegal at start of expression")
+}
+</pre>
+
<p>
Useful though this pattern is, it should be used only within a package.
<code>Parse</code> turns its internal <code>panic</code> calls into
@@ -3015,155 +3460,6 @@ filter unexpected problems and re-panic with the original error.
That's left as an exercise for the reader.
</p>
-<h2 id="blank">Blank identifier</h2>
-
-<p>
-Go defines a special identifier <code>_</code>, called the <i>blank identifier</i>.
-The blank identifier can be used in a declaration to avoid
-declaring a name, and it can be used in an assignment to discard a value.
-This definition makes it useful in a variety of contexts.
-</p>
-
-<h3 id="blank_assign">Multiple assignment</h3>
-
-<p>
-If an assignment requires multiple values on the left side,
-but one of the values will not be used by the program,
-using the blank identifier in the assignment avoids the need
-to create a dummy variable.
-We saw one example of this in the discussion of
-<a href="#for">for loops</a> above.
-</p>
-<pre>
-sum := 0
-for _, value := range array {
- sum += value
-}
-</pre>
-
-<p>
-Another common use is when calling a function that returns
-a value and an error, but only the error is important.
-</p>
-<pre>
-if _, err := os.Stat(path); os.IsNotExist(err) {
- fmt.Printf("%s does not exist\n", path)
-}
-</pre>
-
-<p>
-A final use that is more common than it should be is to
-discard the error from a function that is not expected to fail.
-This is usually a mistake: when the function does fail, the code
-will continue on and probably panic dereferencing a nil pointer.
-</p>
-<pre>
-// Always check errors: this program crashes if path does not exist.
-fi, _ := os.Stat(path)
-fmt.Printf("%s is %d bytes\n", path, fi.Size())
-</pre>
-
-<h3 id="blank_unused">Unused imports and variables</h3>
-
-<p>
-Go defines that it is an error to import a package without using it,
-or to declare a variable without using its value.
-Unused imports bloat a program and lengthen compiles unnecessarily;
-a variable that is initialized but not used is at least
-a wasted computation and perhaps indicative of a
-larger bug.
-Of course, both of these situations also arise in programs
-that are under active development, as you test and refine
-your code.
-</p>
-<p>
-For example, in this program, there are two unused imports
-(<code>fmt</code> and <code>io</code>)
-and an unused variable (<code>greeting</code>).
-</p>
-{{code "/doc/progs/unused1.go" `/package/` `$`}}
-<p>
-Top-level blank declarations referring to the packages
-will silence the unused import errors.
-By convention, these declarations should come immediately after
-the imports, as a reminder to clean things up later.
-Similarly, assigning <code>greeting</code> to a blank identifier
-will silence the unused variable error.
-</p>
-{{code "/doc/progs/unused2.go" `/package/` `$`}}
-
-<h3 id="blank_import">Import for side effect</h3>
-
-<p>
-An unused import like <code>fmt</code> or <code>io</code> in the last section
-should eventually be used or removed:
-blank assignments identify code as a work in progress.
-But sometimes it is useful to import a package only for its
-side effects, without any explicit use.
-For example, during its <code>init</code> function,
-the <code><a href="/pkg/net/http/pprof/">net/http/pprof</a></code>
-package registers HTTP handlers that provide useful
-debugging information. It has an exported API too, but
-most clients need only the handler registration.
-In this situation, it is conventional to rename the package
-to the blank identifier:
-</p>
-<pre>
-import _ "net/http/pprof"
-</pre>
-<p>
-This form of import makes clear that the package is being
-imported for its side effects, because there is no other possible
-use of the package: in this file, it doesn't have a name.
-</p>
-
-<h3 id="blank_implements">Interface checks</h3>
-
-<p>
-As we saw in the discussion of <a href="#interfaces_and_types">interfaces</a> above,
-Go does not require a type to declare explicitly that it implements an interface.
-It implements the interface by simply implementing the required methods.
-This makes Go programs more lightweight and flexible, and it can avoid
-unnecessary dependencies between packages.
-Most interface conversions are static, visible to the compiler,
-and therefore checked at compile time.
-For example, passing an <code>*os.File</code> to a function
-expecting an <code>io.Reader</code> will not compile unless
-<code>*os.File</code> implements the <code>io.Reader</code> interface.
-</p>
-<p>
-However, some types that are used only to satisfy dynamic interface checks.
-For example, the <code><a href="/pkg/encoding/json/">encoding/json</a></code>
-package defines a <code><a href="/pkg/encoding/json/#Marshaler">Marshaler</a></code>
-interface. If the JSON encoder encounters a type implementing that interface,
-the encoder will let the type convert itself to JSON instead of using the standard
-conversion.
-This check is done only at runtime, with code like:
-</p>
-<pre>
-m, ok := val.(json.Marshaler)
-</pre>
-<p>
-If a type—for example,
-<code><a href="/pkg/encoding/json/#RawMessage">json.RawMessage</a></code>—intends
-to customize its JSON representation, it should implement
-<code>json.Marshaler</code>, but there are no static conversions that would
-cause the compiler to verify this automatically.
-A declaration can be used to add such a check:
-</p>
-<pre>
-var _ json.Marshaler = (*RawMessage)(nil)
-</pre>
-<p>
-As part of type-checking this static assignment of a
-<code>*RawMessage</code> to a <code>Marshaler</code>,
-the Go compiler will require that <code>*RawMessage</code> implements <code>Marshaler</code>.
-Using the blank identifier here indicates that
-the declaration exists only for the type checking,
-not to create a variable.
-Conventionally, such declarations are used only when there are
-no static conversions already present in the code.
-</p>
<h2 id="web_server">A web server</h2>
diff --git a/doc/gccgo_contribute.html b/doc/gccgo_contribute.html
index 4d268e02c..b2a0b651c 100644
--- a/doc/gccgo_contribute.html
+++ b/doc/gccgo_contribute.html
@@ -84,7 +84,7 @@ To run the gccgo test suite, run <code>make check-go</code> in your
build directory. This will run various tests
under <code>gcc/testsuite/go.*</code> and will also run
the <code>libgo</code> testsuite. This copy of the tests from the
-main Go repository is run using the DejaGNU script found in
+main Go repository is run using the DejaGNU script found
in <code>gcc/testsuite/go.test/go-test.exp</code>.
</p>
diff --git a/doc/go1.1.html b/doc/go1.1.html
index ae0a09939..6256ae201 100644
--- a/doc/go1.1.html
+++ b/doc/go1.1.html
@@ -6,18 +6,57 @@
<h2 id="introduction">Introduction to Go 1.1</h2>
-TODO
- - overview
- - link back to Go 1 and also Go 1 Compatibility docs.
+<p>
+The release of <a href="/doc/go1.html">Go version 1</a> (Go 1 or Go 1.0 for short)
+in March of 2012 introduced a new period
+of stability in the Go language and libraries.
+That stability has helped nourish a growing community of Go users
+and systems around the world.
+Several "point" releases since
+then—1.0.1, 1.0.2, and 1.0.3—have been issued.
+These point releases fixed known bugs but made
+no non-critical changes to the implementation.
+</p>
+
+<p>
+This new release, Go 1.1, keeps the <a href="/doc/go1compat.html">promise
+of compatibility</a> but adds a couple of significant
+(backwards-compatible, of course) language changes, has a long list
+of (again, compatible) library changes, and
+includes major work on the implementation of the compilers,
+libraries, and run-time.
+The focus is on performance.
+Benchmarking is an inexact science at best, but we see significant,
+sometimes dramatic speedups for many of our test programs.
+We trust that many of our users' programs will also see improvements
+just by updating their Go installation and recompiling.
+</p>
+
+<p>
+This document summarizes the changes between Go 1 and Go 1.1.
+Very little if any code will need modification to run with Go 1.1,
+although a couple of rare error cases surface with this release
+and need to be addressed if they arise.
+Details appear below; see the discussion of
+<a href="#int">64-bit ints</a> and <a href="#unicode_literals">Unicode literals</a>
+in particular.
+</p>
<h2 id="language">Changes to the language</h2>
-TODO
+<p>
+<a href="/doc/go1compat.html">The Go compatibility document</a> promises
+that programs written to the Go 1 language specification will continue to operate,
+and those promises are maintained.
+In the interest of firming up the specification, though, there are
+details about some error cases that have been clarified.
+There are also some new language features.
+</p>
<h3 id="divzero">Integer division by zero</h3>
<p>
-In Go 1, integer division by a constant zero produced a runtime panic:
+In Go 1, integer division by a constant zero produced a run-time panic:
</p>
<pre>
@@ -30,15 +69,104 @@ func f(x int) int {
In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
</p>
+<h3 id="unicode_literals">Surrogates in Unicode literals</h3>
+
+<p>
+The definition of string and rune literals has been refined to exclude surrogate halves from the
+set of valid Unicode code points.
+See the <a href="#unicode">Unicode</a> section for more information.
+</p>
+
+<h3 id="method_values">Method values</h3>
+
+<p>
+Go 1.1 now implements
+<a href="/ref/spec#Method_values">method values</a>,
+which are functions that have been bound to a specific receiver value.
+For instance, given a
+<a href="/pkg/bufio/#Writer"><code>Writer</code></a>
+value <code>w</code>,
+the expression
+<code>w.Write</code>,
+a method value, is a function that will always write to <code>w</code>; it is equivalent to
+a function literal closing over <code>w</code>:
+</p>
+
+<pre>
+func (p []byte) (n int, err error) {
+ return w.Write(p)
+}
+</pre>
+
+<p>
+Method values are distinct from method expressions, which generate functions
+from methods of a given type; the method expression <code>(*bufio.Writer).Write</code>
+is equivalent to a function with an extra first argument, a receiver of type
+<code>(*bufio.Writer)</code>:
+</p>
+
+<pre>
+func (w *bufio.Writer, p []byte) (n int, err error) {
+ return w.Write(p)
+}
+</pre>
+
+<p>
+<em>Updating</em>: No existing code is affected; the change is strictly backward-compatible.
+</p>
+
+<h3 id="return">Return requirements</h3>
+
+<p>
+Before Go 1.1, a function that returned a value needed an explicit "return"
+or call to <code>panic</code> at
+the end of the function; this was a simple way to make the programmer
+be explicit about the meaning of the function. But there are many cases
+where a final "return" is clearly unnecessary, such as a function with
+only an infinite "for" loop.
+</p>
+
+<p>
+In Go 1.1, the rule about final "return" statements is more permissive.
+It introduces the concept of a
+<a href="/ref/spec/#Terminating_statements"><em>terminating statement</em></a>,
+a statement that is guaranteed to be the last one a function executes.
+Examples include
+"for" loops with no condition and "if-else"
+statements in which each half ends in a "return".
+If the final statement of a function can be shown <em>syntactically</em> to
+be a terminating statement, no final "return" statement is needed.
+</p>
+
+<p>
+Note that the rule is purely syntactic: it pays no attention to the values in the
+code and therefore requires no complex analysis.
+</p>
+
+<p>
+<em>Updating</em>: The change is backward-compatible, but existing code
+with superfluous "return" statements and calls to <code>panic</code> may
+be simplified manually.
+Such code can be identified by <code>go vet</code>.
+</p>
<h2 id="impl">Changes to the implementations and tools</h2>
-TODO: more
+<h3 id="gccgo">Status of gccgo</h3>
-<h3 id="gc-flag">Command-line flag parsing</h3>
+<p>
+The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in
+<code>gccgo</code>'s releases.
+The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of <code>gccgo</code>.
+Its library is a little behind the release, but the biggest difference is that method values are not implemented.
+Sometime around May 2013, we expect 4.8.1 of GCC to ship with a <code>gccgo</code>
+providing a complete Go 1.1 implementaiton.
+</p>
+
+<h3 id="gc_flag">Command-line flag parsing</h3>
<p>
-In the gc toolchain, the compilers and linkers now use the
+In the gc tool chain, the compilers and linkers now use the
same command-line flag parsing rules as the Go flag package, a departure
from the traditional Unix flag parsing. This may affect scripts that invoke
the tool directly.
@@ -50,7 +178,11 @@ For example,
<h3 id="int">Size of int on 64-bit platforms</h3>
<p>
-The language allows the implementation to choose whether the <code>int</code> type and <code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code> and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations (TODO: check that gccgo does) <a href="http://golang.org/issue/2188">now make <code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64</a>.
+The language allows the implementation to choose whether the <code>int</code> type and
+<code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code>
+and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations
+now make
+<code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64.
Among other things, this enables the allocation of slices with
more than 2 billion elements on 64-bit platforms.
</p>
@@ -59,7 +191,7 @@ more than 2 billion elements on 64-bit platforms.
<em>Updating</em>:
Most programs will be unaffected by this change.
Because Go does not allow implicit conversions between distinct
-<a href="/ref/spec#Numeric_types">numeric types</a>,
+<a href="/ref/spec/#Numeric_types">numeric types</a>,
no programs will stop compiling due to this change.
However, programs that contain implicit assumptions
that <code>int</code> is only 32 bits may change behavior.
@@ -72,7 +204,7 @@ i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit
fmt.Println(i)
</pre>
-<p>Portable code intending 32-bit sign extension (yielding -1 on all systems)
+<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems)
would instead say:
</p>
@@ -80,31 +212,133 @@ would instead say:
i := int(int32(x))
</pre>
-<h3 id="asm">Assembler</h3>
+<h3 id="heap">Heap size on 64-bit architectures</h3>
+
+<p>
+On 64-bit architectures, the maximum heap size has been enlarged substantially,
+from a few gigabytes to several tens of gigabytes.
+(The exact details depend on the system and may change.)
+</p>
+
+<p>
+On 32-bit architectures, the heap size has not changed.
+</p>
+
+<p>
+<em>Updating</em>:
+This change should have no effect on existing programs beyond allowing them
+to run with larger heaps.
+</p>
+
+<h3 id="unicode">Unicode</h3>
+
+<p>
+To make it possible to represent code points greater than 65535 in UTF-16,
+Unicode defines <em>surrogate halves</em>,
+a range of code points to be used only in the assembly of large values, and only in UTF-16.
+The code points in that surrogate range are illegal for any other purpose.
+In Go 1.1, this constraint is honored by the compiler, libraries, and run-time:
+a surrogate half is illegal as a rune value, when encoded as UTF-8, or when
+encoded in isolation as UTF-16.
+When encountered, for example in converting from a rune to UTF-8, it is
+treated as an encoding error and will yield the replacement rune,
+<a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>,
+U+FFFD.
+</p>
+
+<p>
+This program,
+</p>
+
+<pre>
+import "fmt"
+
+func main() {
+ fmt.Printf("%+q\n", string(0xD800))
+}
+</pre>
+
+<p>
+printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1.
+</p>
+
+<p>
+Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as
+<code>'\ud800'</code> and <code>"\ud800"</code> are now rejected by the compilers.
+When written explicitly as UTF-8 encoded bytes,
+such strings can still be created, as in <code>"\xed\xa0\x80"</code>.
+However, when such a string is decoded as a sequence of runes, as in a range loop, it will yield only <code>utf8.RuneError</code>
+values.
+</p>
+
+<p>
+The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first
+character of a Go source file.
+Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary,
+some editors add the mark as a kind of "magic number" identifying a UTF-8 encoded file.
+</p>
<p>
-Due to the <a href="#int">int</a> and TODO: OTHER changes,
-the placement of function arguments on the stack has changed.
+<em>Updating</em>:
+Most programs will be unaffected by the surrogate change.
+Programs that depend on the old behavior should be modified to avoid the issue.
+The byte-order-mark change is strictly backward-compatible.
+</p>
+
+<h3 id="race">Race detector</h3>
+
+<p>
+A major addition to the tools is a <em>race detector</em>, a way to
+find bugs in programs caused by concurrent access of the same
+variable, where at least one of the accesses is a write.
+This new facility is built into the <code>go</code> tool.
+For now, it is only available on Linux, Mac OS X, and Windows systems with
+64-bit x86 processors.
+To enable it, set the <code>-race</code> flag when building or testing your program
+(for instance, <code>go test -race</code>).
+The race detector is documented in <a href="/doc/articles/race_detector.html">a separate article</a>.
+</p>
+
+<h3 id="gc_asm">The gc assemblers</h3>
+
+<p>
+Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and
+a new internal <a href="http://golang.org/s/go11func">representation of functions</a>,
+the arrangement of function arguments on the stack has changed in the gc tool chain.
Functions written in assembly will need to be revised at least
to adjust frame pointer offsets.
</p>
-<h3 id="gotool">Changes to the go tool</h3>
+<p>
+<em>Updating</em>:
+The <code>go vet</code> command now checks that functions implemented in assembly
+match the Go function prototypes they implement.
+</p>
+
+<h3 id="gocmd">Changes to the go command</h3>
-<p>The <code>go</code> tool has acquired several improvements which are intended to improve the experience for new Go users.</p>
+<p>
+The <a href="/cmd/go/"><code>go</code></a> command has acquired several
+changes intended to improve the experience for new Go users.
+</p>
-<p>Firstly, when compiling, testing, or running Go code, the <code>go</code> tool will now give more detailed errors messages, including a list of paths searched, when a package cannot be located.
+<p>
+First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages,
+including a list of paths searched, when a package cannot be located.
</p>
<pre>
$ go build foo/quxx
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
- /home/User/go/src/pkg/foo/quxx (from $GOROOT)
- /home/User/src/foo/quxx (from $GOPATH)
+ /home/you/go/src/pkg/foo/quxx (from $GOROOT)
+ /home/you/src/foo/quxx (from $GOPATH)
</pre>
<p>
-Secondly, the <code>go get</code> command no longer allows <code>$GOROOT</code> as the default destination when downloading package source. To use <code>go get</code> command, a valid <code>$GOPATH</code> is now required.
+Second, the <code>go get</code> command no longer allows <code>$GOROOT</code>
+as the default destination when downloading package source.
+To use the <code>go get</code>
+command, a <a href="/doc/code.html#GOPATH">valid <code>$GOPATH</code></a> is now required.
</p>
<pre>
@@ -112,77 +346,327 @@ $ GOPATH= go get code.google.com/p/foo/quxx
package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath
</pre>
-<p>Finally, as a result of the previous change, the <code>go get</code> command will also fail when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
+<p>
+Finally, as a result of the previous change, the <code>go get</code> command will also fail
+when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
</p>
<pre>
$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx
-warning: GOPATH set to GOROOT (/home/User/go) has no effect
+warning: GOPATH set to GOROOT (/home/you/go) has no effect
package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath
</pre>
-<h3 id="gofix">Changes to go fix</h3>
+<h3 id="gotest">Changes to the go test command</h3>
+
+<p>
+The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
+command no longer deletes the binary when run with profiling enabled,
+to make it easier to analyze the profile.
+The implementation sets the <code>-c</code> flag automatically, so after running,
+</p>
+
+<pre>
+$ go test -cpuprofile cpuprof.out mypackage
+</pre>
+
+<p>
+the file <code>mypackage.test</code> will be left in the directory where <code>go test</code> was run.
+</p>
<p>
-The <code>go fix</code> command no longer applies fixes to update code from
-before Go 1 to use Go 1 APIs. To update pre-Go 1 code to Go 1.1, use a Go 1.0 toolchain
+The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
+command can now generate profiling information
+that reports where goroutines are blocked, that is,
+where they tend to stall waiting for an event such as a channel communication.
+The information is presented as a
+<em>blocking profile</em>
+enabled with the
+<code>-blockprofile</code>
+option of
+<code>go test</code>.
+Run <code>go help test</code> for more information.
+</p>
+
+<h3 id="gofix">Changes to the go fix command</h3>
+
+<p>
+The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as
+<code>go fix</code>, no longer applies fixes to update code from
+before Go 1 to use Go 1 APIs.
+To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain
to convert the code to Go 1.0 first.
</p>
+<h3 id="tags">Build constraints</h3>
+
+<p>
+The "<code>go1.1</code>" tag has been added to the list of default
+<a href="/pkg/go/build/#hdr-Build_Constraints">build constraints</a>.
+This permits packages to take advantage of the new features in Go 1.1 while
+remaining compatible with earlier versions of Go.
+</p>
+
+<p>
+To build a file only with Go 1.1 and above, add this build constraint:
+</p>
+
+<pre>
+// +build go1.1
+</pre>
+
+<p>
+To build a file only with Go 1.0.x, use the converse constraint:
+</p>
+
+<pre>
+// +build !go1.1
+</pre>
+
+<h3 id="platforms">Additional platforms</h3>
+
+<p>
+The Go 1.1 tool chain adds experimental support for <code>freebsd/arm</code>,
+<code>netbsd/386</code>, <code>netbsd/amd64</code>, <code>netbsd/arm</code>,
+<code>openbsd/386</code> and <code>openbsd/amd64</code> platforms.
+</p>
+
+<p>
+An ARMv6 or later processor is required for <code>freebsd/arm</code> or
+<code>netbsd/arm</code>.
+</p>
+
+<p>
+Go 1.1 adds experimental support for <code>cgo</code> on <code>linux/arm</code>.
+</p>
+
+<h3 id="crosscompile">Cross compilation</h3>
+
+<p>
+When cross-compiling, the <code>go</code> tool will disable <code>cgo</code>
+support by default.
+</p>
+
+<p>
+To explicitly enable <code>cgo</code>, set <code>CGO_ENABLED=1</code>.
+</p>
+
+<h2 id="performance">Performance</h2>
+
+<p>
+The performance of code compiled with the Go 1.1 gc tool suite should be noticeably
+better for most Go programs.
+Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes
+much more, but occasionally less or even non-existent.
+There are too many small performance-driven tweaks through the tools and libraries
+to list them all here, but the following major changes are worth noting:
+</p>
+
+<ul>
+<li>The gc compilers generate better code in many cases, most noticeably for
+floating point on the 32-bit Intel architecture.</li>
+<li>The gc compilers do more in-lining, including for some operations
+in the run-time such as <a href="/pkg/builtin/#append"><code>append</code></a>
+and interface conversions.</li>
+<li>There is a new implementation of Go maps with significant reduction in
+memory footprint and CPU time.</li>
+<li>The garbage collector has been made more parallel, which can reduce
+latencies for programs running on multiple CPUs.</li>
+<li>The garbage collector is also more precise, which costs a small amount of
+CPU time but can reduce the size of the heap significantly, especially
+on 32-bit architectures.</li>
+<li>Due to tighter coupling of the run-time and network libraries, fewer
+context switches are required on network operations.</li>
+</ul>
+
<h2 id="library">Changes to the standard library</h2>
-<h3 id="debug_elf">debug/elf</h3>
+<h3 id="bufio_scanner">bufio.Scanner</h3>
+
<p>
-Previous versions of the debug/elf package intentionally skipped over the first
-symbol in the ELF symbol table, since it is always an empty symbol. This symbol
-is no longer skipped since indexes into the symbol table returned by debug/elf,
-will be different to indexes into the original ELF symbol table. Any code that
-calls the debug/elf functions Symbols or ImportedSymbols may need to be
-adjusted to account for the additional symbol and the change in symbol offsets.
+The various routines to scan textual input in the
+<a href="/pkg/bufio/"><code>bufio</code></a>
+package,
+<a href="/pkg/bufio/#Reader.ReadBytes"><code>ReadBytes</code></a>,
+<a href="/pkg/bufio/#Reader.ReadString"><code>ReadString</code></a>
+and particularly
+<a href="/pkg/bufio/#Reader.ReadLine"><code>ReadLine</code></a>,
+are needlessly complex to use for simple purposes.
+In Go 1.1, a new type,
+<a href="/pkg/bufio/#Scanner"><code>Scanner</code></a>,
+has been added to make it easier to do simple tasks such as
+read the input as a sequence of lines or space-delimited words.
+It simplifies the problem by terminating the scan on problematic
+input such as pathologically long lines, and having a simple
+default: line-oriented input, with each line stripped of its terminator.
+Here is code to reproduce the input a line at a time:
</p>
-<h3 id="html_template">html/template</h3>
+<pre>
+scanner := bufio.NewScanner(os.Stdin)
+for scanner.Scan() {
+ fmt.Println(scanner.Text()) // Println will add back the final '\n'
+}
+if err := scanner.Err(); err != nil {
+ fmt.Fprintln(os.Stderr, "reading standard input:", err)
+}
+</pre>
<p>
-Templates using the undocumented and only partially implemented
-"noescape" feature will break: that feature was removed.
+Scanning behavior can be adjusted through a function to control subdividing the input
+(see the documentation for <a href="/pkg/bufio/#SplitFunc"><code>SplitFunc</code></a>),
+but for tough problems or the need to continue past errors, the older interface
+may still be required.
</p>
<h3 id="net">net</h3>
<p>
-The protocol-specific resolvers were formerly
-lax about the network name passed in. For example, although the documentation was clear
-that the only valid networks for <code>ResolveTCPAddr</code> are <code>"tcp"</code>,
-<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted
-any string. The Go 1.1 implementation returns an error if the network is not one of those strings.
-The same is true of the other protocol-specific resolvers <code>ResolveIPAddr</code>, <code>ResolveUDPAddr</code>, and
-<code>ResolveUnixAddr</code>.
+The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly
+lax about the network name passed in.
+Although the documentation was clear
+that the only valid networks for
+<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>
+are <code>"tcp"</code>,
+<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string.
+The Go 1.1 implementation returns an error if the network is not one of those strings.
+The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
+<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
+<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>.
+</p>
+
+<p>
+The previous implementation of
+<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
+returned a
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
+a representation of the connection endpoint.
+The Go 1.1 implementation instead returns a
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
+to allow reading and writing
+with its
+<a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a>
+and
+<a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a>
+methods.
</p>
<p>
-The previous <code>ListenUnixgram</code> returned <code>UDPConn</code> as
-arepresentation of the connection endpoint. The Go 1.1 implementation
-returns <code>UnixConn</code> to allow reading and writing
-with <code>ReadFrom</code> and <code>WriteTo</code> methods on
-the <code>UnixConn</code>.
+The data structures
+<a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
+<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>, and
+<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>
+add a new string field called <code>Zone</code>.
+Code using untagged composite literals (e.g. <code>net.TCPAddr{ip, port}</code>)
+instead of tagged literals (<code>net.TCPAddr{IP: ip, Port: port}</code>)
+will break due to the new field.
+The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages.
</p>
+<p>
+<em>Updating</em>:
+To correct breakage caused by the new struct field,
+<code>go fix</code> will rewrite code to add tags for these types.
+More generally, <code>go vet</code> will identify composite literals that
+should be revised to use field tags.
+</p>
+
+<h3 id="reflect">reflect</h3>
+
+<p>
+The <a href="/pkg/reflect/"><code>reflect</code></a> package has several significant additions.
+</p>
+
+<p>
+It is now possible to run a "select" statement using
+the <code>reflect</code> package; see the description of
+<a href="/pkg/reflect/#Select"><code>Select</code></a>
+and
+<a href="/pkg/reflect/#SelectCase"><code>SelectCase</code></a>
+for details.
+</p>
+
+<p>
+The new method
+<a href="/pkg/reflect/#Value.Convert"><code>Value.Convert</code></a>
+(or
+<a href="/pkg/reflect/#Type"><code>Type.ConvertibleTo</code></a>)
+provides functionality to execute a Go conversion or type assertion operation
+on a
+<a href="/pkg/reflect/#Value"><code>Value</code></a>
+(or test for its possibility).
+</p>
+
+<p>
+The new function
+<a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a>
+creates a wrapper function to make it easier to call a function with existing
+<a href="/pkg/reflect/#Value"><code>Values</code></a>,
+doing the standard Go conversions among the arguments, for instance
+to pass an actual <code>int</code> to a formal <code>interface{}</code>.
+</p>
+
+<p>
+Finally, the new functions
+<a href="/pkg/reflect/#ChanOf"><code>ChanOf</code></a>,
+<a href="/pkg/reflect/#MapOf"><code>MapOf</code></a>
+and
+<a href="/pkg/reflect/#SliceOf"><code>SliceOf</code></a>
+construct new
+<a href="/pkg/reflect/#Type"><code>Types</code></a>
+from existing types, for example to construct the type <code>[]T</code> given
+only <code>T</code>.
+</p>
+
+
<h3 id="time">time</h3>
<p>
-On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the time package
-returned times with microsecond precision. The Go 1.1 implementation of time on these
-systems now returns times with nanosecond precision. Code may exist that expects to be
-able to store such a time in an external format with only microsecond precision,
-read it back, and recover exactly the same time instant.
-In Go 1.1 the same time will not be recovered, since the external storage
-will have discarded nanoseconds.
-To address this case, there are two new methods of time.Time, Round and Truncate,
+On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the
+<a href="/pkg/time/"><code>time</code></a> package
+returned times with microsecond precision.
+The Go 1.1 implementation on these
+systems now returns times with nanosecond precision.
+Programs that write to an external format with microsecond precision
+and read it back, expecting to recover the original value, will be affected
+by the loss of precision.
+There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>,
+<a href="/pkg/time/#Time.Round"><code>Round</code></a>
+and
+<a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>,
that can be used to remove precision from a time before passing it to
external storage.
</p>
-<h3 id="exp_old">Exp and old subtrees moved to go.exp subrepo</h3>
+<p>
+The new method
+<a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a>
+returns the one-indexed integral day number of the year specified by the time value.
+</p>
+
+<p>
+The
+<a href="/pkg/time/#Timer"><code>Timer</code></a>
+type has a new method
+<a href="/pkg/time/#Timer.Reset"><code>Reset</code></a>
+that modifies the timer to expire after a specified duration.
+</p>
+
+<p>
+Finally, the new function
+<a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a>
+is like the existing
+<a href="/pkg/time/#Parse"><code>Parse</code></a>
+but parses the time in the context of a location (time zone), ignoring
+time zone information in the parsed string.
+This function addresses a common source of confusion in the time API.
+</p>
+
+<p>
+<em>Updating</em>:
+Code that needs to read and write times using an external format with
+lower precision should be modified to use the new methods.
+
+<h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3>
<p>
To make it easier for binary distributions to access them if desired, the <code>exp</code>
@@ -204,4 +688,410 @@ and then in Go source,
import "code.google.com/p/go.exp/ssa"
</pre>
-<h3 id="TODO">TODO</h3>
+<p>
+The old package <code>exp/norm</code> has also been moved, but to a new repository
+<code>go.text</code>, where the Unicode APIs and other text-related packages will
+be developed.
+</p>
+
+<h3 id="new_packages">New packages</h3>
+
+<p>
+There are three new packages.
+</p>
+
+<ul>
+<li>
+The <a href="/pkg/go/format/"><code>go/format</code></a> package provides
+a convenient way for a program to access the formatting capabilities of the
+<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
+It has two functions,
+<a href="/pkg/go/format/#Node"><code>Node</code></a> to format a Go parser
+<a href="/pkg/go/ast/#Node"><code>Node</code></a>,
+and
+<a href="/pkg/go/format/#Source"><code>Source</code></a>
+to reformat arbitrary Go source code into the standard format as provided by the
+<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
+</li>
+
+<li>
+The <a href="/pkg/net/http/cookiejar/"><code>net/http/cookiejar</code></a> package provides the basics for managing HTTP cookies.
+</li>
+
+<li>
+The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package provides low-level facilities for data race detection.
+It is internal to the race detector and does not otherwise export any user-visible functionality.
+</li>
+</ul>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+The following list summarizes a number of minor changes to the library, mostly additions.
+See the relevant package documentation for more information about each change.
+</p>
+
+<ul>
+<li>
+The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions,
+<a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a>
+and
+<a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>,
+with self-evident properties.
+Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
+has a new method
+<a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that
+provides some control over memory allocation inside the buffer.
+Finally, the
+<a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a
+<a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method
+so it implements the
+<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
+</li>
+
+<li>
+The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package has
+a new <a href="/pkg/compress/gzip/#Writer.Flush"><code>Flush</code></a>
+method for its
+<a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a>
+type that flushes its underlying <code>flate.Writer</code>.
+</li>
+
+<li>
+The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function,
+<a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs.
+</li>
+
+<li>
+The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package
+now supports PEM blocks (see
+<a href="/pkg/crypto/x509/#DecryptPEMBlock"><code>DecryptPEMBlock</code></a> for instance),
+and a new function
+<a href="/pkg/crypto/x509/#ParseECPrivateKey"><code>ParseECPrivateKey</code></a> to parse elliptic curve private keys.
+</li>
+
+<li>
+The <a href="/pkg/database/sql/"><code>database/sql</code></a> package
+has a new
+<a href="/pkg/database/sql/#DB.Ping"><code>Ping</code></a>
+method for its
+<a href="/pkg/database/sql/#DB"><code>DB</code></a>
+type that tests the health of the connection.
+</li>
+
+<li>
+The <a href="/pkg/database/sql/driver/"><code>database/sql/driver</code></a> package
+has a new
+<a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>
+interface that a
+<a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a>
+may implement to improve performance.
+</li>
+
+<li>
+The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package's
+<a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
+has a new method
+<a href="/pkg/encoding/json/#Decoder.Buffered"><code>Buffered</code></a>
+to provide access to the remaining data in its buffer,
+as well as a new method
+<a href="/pkg/encoding/json/#Decoder.UseNumber"><code>UseNumber</code></a>
+to unmarshal a value into the new type
+<a href="/pkg/encoding/json/#Number"><code>Number</code></a>,
+a string, rather than a float64.
+</li>
+
+<li>
+The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package
+has a new function,
+<a href="/pkg/encoding/xml/#EscapeText"><code>EscapeText</code></a>,
+which writes escaped XML output,
+and a method on
+<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>,
+<a href="/pkg/encoding/xml/#Encoder.Indent"><code>Indent</code></a>,
+to specify indented output.
+</li>
+
+<li>
+In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a
+new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a>
+and associated methods makes it easier to extract and process comments in Go programs.
+</li>
+
+<li>
+In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package,
+the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code>
+throughout the code,
+information that the <a href="/cmd/godoc/"><code>godoc</code></a>
+command can filter or present according to the value of the <code>-notes</code> flag.
+</li>
+
+<li>
+The undocumented and only partially implemented "noescape" feature of the
+<a href="/pkg/html/template/"><code>html/template</code></a>
+package has been removed; programs that depend on it will break.
+</li>
+
+<li>
+The <a href="/pkg/image/jpeg/"><code>image/jpeg</code></a> package now
+reads progressive JPEG files and handles a few more subsampling configurations.
+</li>
+
+<li>
+The <a href="/pkg/io/"><code>io</code></a> package now exports the
+<a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common
+functionality of writing a byte at a time.
+It also exports a new error, <a href="/pkg/io/#ErrNoProgress"><code>ErrNoProgress</code></a>,
+used to indicate a <code>Read</code> implementation is looping without delivering data.
+</li>
+
+<li>
+The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support
+for OS-specific logging features.
+</li>
+
+<li>
+The <a href="/pkg/math/big/"><code>math/big</code></a> package's
+<a href="/pkg/math/big/#Int"><code>Int</code></a> type
+now has methods
+<a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a>
+and
+<a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a>
+to convert to and from a JSON representation.
+Also,
+<a href="/pkg/math/big/#Int"><code>Int</code></a>
+can now convert directly to and from a <code>uint64</code> using
+<a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a>
+and
+<a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>,
+while
+<a href="/pkg/math/big/#Rat"><code>Rat</code></a>
+can do the same with <code>float64</code> using
+<a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a>
+and
+<a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/mime/multipart/"><code>mime/multipart</code></a> package
+has a new method for its
+<a href="/pkg/mime/multipart/#Writer"><code>Writer</code></a>,
+<a href="/pkg/mime/multipart/#Writer.SetBoundary"><code>SetBoundary</code></a>,
+to define the boundary separator used to package the output.
+The <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> also now
+transparently decodes any <code>quoted-printable</code> parts and removes
+the <code>Content-Transfer-Encoding</code> header when doing so.
+</li>
+
+<li>
+The
+<a href="/pkg/net/"><code>net</code></a> package's
+<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
+function has changed return types: it now returns a
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
+rather than a
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>, which was
+clearly a mistake in Go 1.0.
+Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package includes a new type,
+<a href="/pkg/net/#Dialer"><code>Dialer</code></a>, to supply options to
+<a href="/pkg/net/#Dialer.Dial"><code>Dial</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds support for
+link-local IPv6 addresses with zone qualifiers, such as <code>fe80::1%lo0</code>.
+The address structures <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
+<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>, and
+<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>
+record the zone in a new field, and functions that expect string forms of these addresses, such as
+<a href="/pkg/net/#Dial"><code>Dial</code></a>,
+<a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
+<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
+<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>,
+now accept the zone-qualified form.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds
+<a href="/pkg/net/#LookupNS"><code>LookupNS</code></a> to its suite of resolving functions.
+<code>LookupNS</code> returns the <a href="/pkg/net/#NS">NS records</a> for a host name.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds protocol-specific
+packet reading and writing methods to
+<a href="/pkg/net/#IPConn"><code>IPConn</code></a>
+(<a href="/pkg/net/#IPConn.ReadMsgIP"><code>ReadMsgIP</code></a>
+and <a href="/pkg/net/#IPConn.WriteMsgIP"><code>WriteMsgIP</code></a>) and
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>
+(<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>ReadMsgUDP</code></a> and
+<a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>WriteMsgUDP</code></a>).
+These are specialized versions of <a href="/pkg/net/#PacketConn"><code>PacketConn</code></a>'s
+<code>ReadFrom</code> and <code>WriteTo</code> methods that provide access to out-of-band data associated
+with the packets.
+ </li>
+
+ <li>
+The <a href="/pkg/net/"><code>net</code></a> package adds methods to
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> to allow closing half of the connection
+(<a href="/pkg/net/#UnixConn.CloseRead"><code>CloseRead</code></a> and
+<a href="/pkg/net/#UnixConn.CloseWrite"><code>CloseWrite</code></a>),
+matching the existing methods of <a href="/pkg/net/#TCPConn"><code>TCPConn</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package includes several new additions.
+<a href="/pkg/net/http/#ParseTime"><code>ParseTime</code></a> parses a time string, trying
+several common HTTP time formats.
+The <a href="/pkg/net/http/#Request.PostFormValue"><code>PostFormValue</code></a> method of
+<a href="/pkg/net/http/#Request"><code>Request</code></a> is like
+<a href="/pkg/net/http/#Request.FormValue"><code>FormValue</code></a> but ignores URL parameters.
+The <a href="/pkg/net/http/#CloseNotifier"><code>CloseNotifier</code></a> interface provides a mechanism
+for a server handler to discover when a client has disconnected.
+The <code>ServeMux</code> type now has a
+<a href="/pkg/net/http/#ServeMux.Handler"><code>Handler</code></a> method to access a path's
+<code>Handler</code> without executing it.
+The <code>Transport</code> can now cancel an in-flight request with
+<a href="/pkg/net/http/#Transport.CancelRequest"><code>CancelRequest</code></a>.
+Finally, the Transport is now more aggressive at closing TCP connections when
+a <a href="/pkg/net/http/#Response"><code>Response.Body</code></a> is closed before
+being fully consumed.
+</li>
+
+<li>
+The <a href="/pkg/net/mail/"><code>net/mail</code></a> package has two new functions,
+<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
+<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>,
+to parse RFC 5322-formatted mail addresses into
+<a href="/pkg/net/mail/#Address"><code>Address</code></a> structures.
+</li>
+
+<li>
+The <a href="/pkg/net/smtp/"><code>net/smtp</code></a> package's
+<a href="/pkg/net/smtp/#Client"><code>Client</code></a> type has a new method,
+<a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>,
+which transmits a <code>HELO</code> or <code>EHLO</code> message to the server.
+</li>
+
+<li>
+The <a href="/pkg/net/textproto/"><code>net/textproto</code></a> package
+has two new functions,
+<a href="/pkg/net/textproto/#TrimBytes"><code>TrimBytes</code></a> and
+<a href="/pkg/net/textproto/#TrimString"><code>TrimString</code></a>,
+which do ASCII-only trimming of leading and trailing spaces.
+</li>
+
+<li>
+The new method <a href="/pkg/os/#FileMode.IsRegular"><code>os.FileMode.IsRegular</code></a> makes it easy to ask if a file is a plain file.
+</li>
+
+<li>
+The <a href="/pkg/os/signal/"><code>os/signal</code></a> package has a new function,
+<a href="/pkg/os/signal/#Stop"><code>Stop</code></a>, which stops the package delivering
+any further signals to the channel.
+</li>
+
+<li>
+The <a href="/pkg/regexp/"><code>regexp</code></a> package
+now supports Unix-original leftmost-longest matches through the
+<a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a>
+method, while
+<a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices
+strings into pieces based on separators defined by the regular expression.
+</li>
+
+<li>
+The <a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package
+has three new functions regarding memory usage.
+The <a href="/pkg/runtime/debug/#FreeOSMemory"><code>FreeOSMemory</code></a>
+function triggers a run of the garbage collector and then attempts to return unused
+memory to the operating system;
+the <a href="/pkg/runtime/debug/#ReadGCStats"><code>ReadGCStats</code></a>
+function retrieves statistics about the collector; and
+<a href="/pkg/runtime/debug/#SetGCPercent"><code>SetGCPercent</code></a>
+provides a programmatic way to control how often the collector runs,
+including disabling it altogether.
+</li>
+
+<li>
+The <a href="/pkg/sort/"><code>sort</code></a> package has a new function,
+<a href="/pkg/sort/#Reverse"><code>Reverse</code></a>.
+Wrapping the argument of a call to
+<a href="/pkg/sort/#Sort"><code>sort.Sort</code></a>
+with a call to <code>Reverse</code> causes the sort order to be reversed.
+</li>
+
+<li>
+The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions,
+<a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a>
+and
+<a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a>
+with self-evident properties, and the new method
+<a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the
+<a href="/pkg/strings/#Reader"><code>Reader</code></a>
+type now implements the
+<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
+</li>
+
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package's
+<a href="/pkg/syscall/#Fchflags"><code>Fchflags</code></a> function on various BSDs
+(including Darwin) has changed signature.
+It now takes an int as the first parameter instead of a string.
+Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
+</li>
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package also has received many updates
+to make it more inclusive of constants and system calls for each supported operating system.
+</li>
+
+<li>
+The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation
+statistics in tests and benchmarks using the new
+<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function. And the
+<a href="/pkg/testing/#B.ReportAllocs"><code>ReportAllocs</code></a>
+method on <a href="/pkg/testing/#B"><code>testing.B</code></a> will enable printing of
+memory allocation statistics for the calling benchmark. It also introduces the
+<a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of
+<a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>.
+There is also a new
+<a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code>
+command-line flag,
+and a new
+<a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of
+<a href="/pkg/testing/#B"><code>testing.B</code></a> and
+<a href="/pkg/testing/#T"><code>testing.T</code></a>
+to simplify skipping an inappropriate test.
+</li>
+
+<li>
+In the <a href="/pkg/text/template/"><code>text/template</code></a>
+and
+<a href="/pkg/html/template/"><code>html/template</code></a> packages,
+templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines.
+Also, as part of the new parser, the
+<a href="/pkg/text/template/parse/#Node"><code>Node</code></a> interface got two new methods to provide
+better error reporting.
+Although this violates the Go 1 compatibility rules,
+no existing code should be affected because this interface is explicitly intended only to be used
+by the
+<a href="/pkg/text/template/"><code>text/template</code></a>
+and
+<a href="/pkg/html/template/"><code>html/template</code></a>
+packages and there are safeguards to guarantee that.
+</li>
+
+<li>
+The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0.
+</li>
+
+<li>
+In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package,
+the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point.
+To be valid, a rune must be in range and not be a surrogate half.
+</li>
+</ul>
diff --git a/doc/go1.html b/doc/go1.html
index 491fd7bf7..2687827c0 100644
--- a/doc/go1.html
+++ b/doc/go1.html
@@ -998,9 +998,9 @@ Running <code>go</code> <code>fix</code> will perform the needed changes.
<p>
In Go 1, the
<a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
-and
-<a href="/pkg/crypto/x509/#CreateCRL"><code>CreateCRL</code></a>
-functions in <code>crypto/x509</code> have been altered to take an
+function and
+<a href="/pkg/crypto/x509/#Certificate.CreateCRL"><code>CreateCRL</code></a>
+method in <code>crypto/x509</code> have been altered to take an
<code>interface{}</code> where they previously took a <code>*rsa.PublicKey</code>
or <code>*rsa.PrivateKey</code>. This will allow other public key algorithms
to be implemented in the future.
@@ -1183,7 +1183,7 @@ if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declara
(not just exported ones) are considered.
The function <code>NewFileDoc</code> was removed, and the function
<code>CommentText</code> has become the method
-<a href="/pkg/go/ast/#Text"><code>Text</code></a> of
+<a href="/pkg/go/ast/#CommentGroup.Text"><code>Text</code></a> of
<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
</p>
@@ -1497,7 +1497,7 @@ to test common error properties, plus a few new error values
with more Go-like names, such as
<a href="/pkg/os/#ErrPermission"><code>ErrPermission</code></a>
and
-<a href="/pkg/os/#ErrNoEnv"><code>ErrNoEnv</code></a>.
+<a href="/pkg/os/#ErrNotExist"><code>ErrNotExist</code></a>.
</p>
<p>
diff --git a/doc/go_faq.html b/doc/go_faq.html
index 5c68aa7e5..62a564b6b 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -157,6 +157,12 @@ and so on. These cannot be addressed well by libraries or tools; a new
language was called for.
</p>
+<p>
+The article <a href="http://talks.golang.org/2012/splash.article">Go at Google</a>
+discusses the background and motivation behind the design of the Go language,
+as well as providing more detail about many of the answers presented in this FAQ.
+</p>
+
<h3 id="ancestors">
What are Go's ancestors?</h3>
<p>
@@ -216,6 +222,13 @@ document server running in a production configuration on
<a href="https://developers.google.com/appengine/">Google App Engine</a>.
</p>
+<p>
+Other examples include the <a href="https://code.google.com/p/vitess/">Vitess</a>
+system for large-scale SQL installations and Google's download server, <code>dl.google.com</code>,
+which delivers Chrome binaries and other large installables such as <code>apt-get</code>
+packages.
+</p>
+
<h3 id="Do_Go_programs_link_with_Cpp_programs">
Do Go programs link with C/C++ programs?</h3>
@@ -394,6 +407,8 @@ for concurrency comes from Hoare's Communicating Sequential Processes, or CSP.
Occam and Erlang are two well known languages that stem from CSP.
Go's concurrency primitives derive from a different part of the family tree
whose main contribution is the powerful notion of channels as first class objects.
+Experience with several earlier languages has shown that the CSP model
+fits well into a procedural language framework.
</p>
<h3 id="goroutines">
@@ -439,6 +454,34 @@ as when hosting an untrusted program, the implementation could interlock
map access.
</p>
+<h3 id="language_changes">
+Will you accept my language change?</h3>
+
+<p>
+People often suggest improvements to the language—the
+<a href="http://groups.google.com/group/golang-nuts">mailing list</a>
+contains a rich history of such discussions—but very few of these changes have
+been accepted.
+</p>
+
+<p>
+Although Go is an open source project, the language and libraries are protected
+by a <a href="/doc/go1compat.html">compatibility promise</a> that prevents
+changes that break existing programs.
+If your proposal violates the Go 1 specification we cannot even entertain the
+idea, regardless of its merit.
+A future major release of Go may be incompatible with Go 1, but we're not ready
+to start talking about what that might be.
+</p>
+
+<p>
+Even if your proposal is compatible with the Go 1 spec, it may be
+not be in the spirit of Go's design goals.
+The article <i><a href="http://talks.golang.org/2012/splash.article">Go
+at Google: Language Design in the Service of Software Engineering</a></i>
+explains Go's origins and the motivation behind its design.
+</p>
+
<h2 id="types">Types</h2>
<h3 id="Is_Go_an_object-oriented_language">
@@ -874,11 +917,11 @@ There's a lot of history on that topic. Early on, maps and channels
were syntactically pointers and it was impossible to declare or use a
non-pointer instance. Also, we struggled with how arrays should work.
Eventually we decided that the strict separation of pointers and
-values made the language harder to use. Introducing reference types,
-including slices to handle the reference form of arrays, resolved
-these issues. Reference types add some regrettable complexity to the
-language but they have a large effect on usability: Go became a more
-productive, comfortable language when they were introduced.
+values made the language harder to use. Changing these
+types to act as references to the associated, shared data structures resolved
+these issues. This change added some regrettable complexity to the
+language but had a large effect on usability: Go became a more
+productive, comfortable language when it was introduced.
</p>
<h2 id="Writing_Code">Writing Code</h2>
@@ -949,6 +992,38 @@ combined with the Go project's mostly linear, non-branching use of
version control, a switch to git doesn't seem worthwhile.
</p>
+<h3 id="git_https">
+Why does "go get" use HTTPS when cloning a repository?</h3>
+
+<p>
+Companies often permit outgoing traffic only on the standard TCP ports 80 (HTTP)
+and 443 (HTTPS), blocking outgoing traffic on other ports, including TCP port 9418
+(git) and TCP port 22 (SSH).
+When using HTTPS instead of HTTP, <code>git</code> enforces certificate validation by
+default, providing protection against man-in-the-middle, eavesdropping and tampering attacks.
+The <code>go get</code> command therefore uses HTTPS for safety.
+</p>
+
+<p>
+If you use <code>git</code> and prefer to push changes through SSH using your existing key
+it's easy to work around this. For GitHub, try one of these solutions:
+</p>
+<ul>
+<li>Manually clone the repository in the expected package directory:
+<pre>
+$ cd $GOPATH/src/github.com/username
+$ git clone git@github.com:username/package.git
+</pre>
+</li>
+<li>Force <code>git push</code> to use the <code>SSH</code> protocol by appending
+these two lines to <code>~/.gitconfig</code>:
+<pre>
+[url "git@github.com:"]
+ pushInsteadOf = https://github.com/
+</pre>
+</li>
+</ul>
+
<h2 id="Pointers">Pointers and Allocation</h2>
<h3 id="pass_by_value">
@@ -974,6 +1049,57 @@ struct. If the interface value holds a pointer, copying the interface value
makes a copy of the pointer, but again not the data it points to.
</p>
+<h3 id="pointer_to_interface">
+When should I use a pointer to an interface?</h3>
+
+<p>
+Almost never. Pointers to interface values arise only in rare, tricky situations involving
+disguising an interface value's type for delayed evaluation.
+</p>
+
+<p>
+It is however a common mistake to pass a pointer to an interface value
+to a function expecting an interface. The compiler will complain about this
+error but the situation can still be confusing, because sometimes a
+<a href="#different_method_sets">pointer
+is necessary to satisfy an interface</a>.
+The insight is that although a pointer to a concrete type can satisfy
+an interface, with one exception <em>a pointer to an interface can never satisfy a interface</em>.
+</p>
+
+<p>
+Consider the variable declaration,
+</p>
+
+<pre>
+var w io.Writer
+</pre>
+
+<p>
+The printing function <code>fmt.Fprintf</code> takes as its first argument
+a value that satisfies <code>io.Writer</code>—something that implements
+the canonical <code>Write</code> method. Thus we can write
+</p>
+
+<pre>
+fmt.Fprintf(w, "hello, world\n")
+</pre>
+
+<p>
+If however we pass the address of <code>w</code>, the program will not compile.
+</p>
+
+<pre>
+fmt.Fprintf(&amp;w, "hello, world\n") // Compile-time error.
+</pre>
+
+<p>
+The one exception is that any value, even a pointer to an interface, can be assigned to
+a variable of empty interface type (<code>interface{}</code>).
+Even so, it's almost certainly a mistake if the value is a pointer to an interface;
+the result can be confusing.
+</p>
+
<h3 id="methods_on_values_or_pointers">
Should I define methods on values or pointers?</h3>
@@ -997,7 +1123,7 @@ There are several considerations.
First, and most important, does the method need to modify the
receiver?
If it does, the receiver <em>must</em> be a pointer.
-(Slices and maps are reference types, so their story is a little
+(Slices and maps act as references, so their story is a little
more subtle, but for instance to change the length of a slice
in a method the receiver must still be a pointer.)
In the examples above, if <code>pointerMethod</code> modifies
@@ -1048,7 +1174,7 @@ of Effective Go</a> for more details.
</p>
<h3 id="q_int_sizes">
-Why is <code>int</code> 32 bits on 64 bit machines?</h3>
+What is the size of an <code>int</code> on a 64 bit machine?</h3>
<p>
The sizes of <code>int</code> and <code>uint</code> are implementation-specific
@@ -1065,12 +1191,6 @@ floating-point numbers.
The default size of a floating-point constant is <code>float64</code>.
</p>
-<p>
-At the moment, all implementations use 32-bit ints, an essentially arbitrary decision.
-However, we expect that <code>int</code> will be increased to 64 bits on 64-bit
-architectures in a future release of Go.
-</p>
-
<h3 id="stack_or_heap">
How do I know whether a variable is allocated on the heap or the stack?</h3>
@@ -1154,6 +1274,9 @@ run-time support to utilize more than one OS thread.
<p>
Programs that perform parallel computation should benefit from an increase in
<code>GOMAXPROCS</code>.
+However, be aware that
+<a href="http://blog.golang.org/2013/01/concurrency-is-not-parallelism.html">concurrency
+is not parallelism</a>.
</p>
<h3 id="Why_GOMAXPROCS">
@@ -1187,6 +1310,11 @@ should recognize such cases and optimize its use of OS threads. For now,
<code>GOMAXPROCS</code> should be set on a per-application basis.
</p>
+<p>
+For more detail on this topic see the talk entitled,
+<a href="http://blog.golang.org/2013/01/concurrency-is-not-parallelism.html">Concurrency
+is not Parallelism</a>.
+
<h2 id="Functions_methods">Functions and Methods</h2>
<h3 id="different_method_sets">
@@ -1407,7 +1535,7 @@ test cases. The standard Go library is full of illustrative examples, such as in
What compiler technology is used to build the compilers?</h3>
<p>
-<code>Gccgo</code> has a C++ front-end with a recursive descent parser coupled to the
+<code>Gccgo</code> has a front end written in C++, with a recursive descent parser coupled to the
standard GCC back end. <code>Gc</code> is written in C using
<code>yacc</code>/<code>bison</code> for the parser.
Although it's a new program, it fits in the Plan 9 C compiler suite
@@ -1420,9 +1548,11 @@ We considered writing <code>gc</code>, the original Go compiler, in Go itself bu
elected not to do so because of the difficulties of bootstrapping and
especially of open source distribution&mdash;you'd need a Go compiler to
set up a Go environment. <code>Gccgo</code>, which came later, makes it possible to
-consider writing a compiler in Go, which might well happen. (Go would be a
+consider writing a compiler in Go, which might well happen.
+(Go would be a
fine language in which to implement a compiler; a native lexer and
-parser are already available in the <a href="/pkg/go/"><code>go</code></a> package.)
+parser are already available in the <a href="/pkg/go/"><code>go</code></a> package
+and a type checker is in the works.)
</p>
<p>
diff --git a/doc/go_spec.html b/doc/go_spec.html
index 0cb9f54b1..3938ba3e6 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -1,6 +1,6 @@
<!--{
"Title": "The Go Programming Language Specification",
- "Subtitle": "Version of March 1, 2013",
+ "Subtitle": "Version of May 8, 2013",
"Path": "/ref/spec"
}-->
@@ -103,6 +103,7 @@ compiler may disallow the NUL character (U+0000) in the source text.
Implementation restriction: For compatibility with other tools, a
compiler may ignore a UTF-8-encoded byte order mark
(U+FEFF) if it is the first Unicode code point in the source text.
+A byte order mark may be disallowed anywhere else in the source.
</p>
<h3 id="Characters">Characters</h3>
@@ -639,8 +640,8 @@ expressions</a>.
<p>
A type determines the set of values and operations specific to values of that
type. A type may be specified by a
-(possibly <a href="#Qualified_identifiers">qualified</a>) <i>type name</i>
-(§<a href="#Type_declarations">Type declarations</a>) or a <i>type literal</i>,
+(possibly <a href="#Qualified_identifiers">qualified</a>)
+<a href="#Type_declarations"><i>type name</i></a> or a <i>type literal</i>,
which composes a new type from previously declared types.
</p>
@@ -837,9 +838,9 @@ multi-dimensional types.
<h3 id="Slice_types">Slice types</h3>
<p>
-A slice is a reference to a contiguous segment of an array and
-contains a numbered sequence of elements from that array. A slice
-type denotes the set of all slices of arrays of its element type.
+A slice is a descriptor for a contiguous segment of an array and
+provides access to a numbered sequence of elements from that array.
+A slice type denotes the set of all slices of arrays of its element type.
The value of an uninitialized slice is <code>nil</code>.
</p>
@@ -866,8 +867,8 @@ distinct arrays always represent distinct storage.
The array underlying a slice may extend past the end of the slice.
The <i>capacity</i> is a measure of that extent: it is the sum of
the length of the slice and the length of the array beyond the slice;
-a slice of length up to that capacity can be created by `slicing' a new
-one from the original slice (§<a href="#Slices">Slices</a>).
+a slice of length up to that capacity can be created by
+<a href="#Slices"><i>slicing</i></a> a new one from the original slice.
The capacity of a slice <code>a</code> can be discovered using the
built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
</p>
@@ -1236,8 +1237,8 @@ KeyType = Type .
</pre>
<p>
-The comparison operators <code>==</code> and <code>!=</code>
-(§<a href="#Comparison_operators">Comparison operators</a>) must be fully defined
+The <a href="#Comparison_operators">comparison operators</a>
+<code>==</code> and <code>!=</code> must be fully defined
for operands of the key type; thus the key type must not be a function, map, or
slice.
If the key type is an interface type, these
@@ -1469,12 +1470,13 @@ Any value may be assigned to the <a href="#Blank_identifier">blank identifier</a
<h2 id="Blocks">Blocks</h2>
<p>
-A <i>block</i> is a sequence of declarations and statements within matching
-brace brackets.
+A <i>block</i> is a possibly empty sequence of declarations and statements
+within matching brace brackets.
</p>
<pre class="ebnf">
-Block = "{" { Statement ";" } "}" .
+Block = "{" StatementList "}" .
+StatementList = { Statement ";" } .
</pre>
<p>
@@ -1490,10 +1492,13 @@ In addition to explicit blocks in the source code, there are implicit blocks:
<li>Each file has a <i>file block</i> containing all Go source text
in that file.</li>
- <li>Each <code>if</code>, <code>for</code>, and <code>switch</code>
+ <li>Each <a href="#If_statements">"if"</a>,
+ <a href="#For_statements">"for"</a>, and
+ <a href="#Switch_statements">"switch"</a>
statement is considered to be in its own implicit block.</li>
- <li>Each clause in a <code>switch</code> or <code>select</code> statement
+ <li>Each clause in a <a href="#Switch_statements">"switch"</a>
+ or <a href="#Select_statements">"select"</a> statement
acts as an implicit block.</li>
</ol>
@@ -1567,8 +1572,9 @@ declarations.
<p>
Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
-used in the <code>break</code>, <code>continue</code>, and <code>goto</code>
-statements (§<a href="#Break_statements">Break statements</a>, §<a href="#Continue_statements">Continue statements</a>, §<a href="#Goto_statements">Goto statements</a>).
+used in the <a href="#Break_statements">"break"</a>,
+<a href="#Continue_statements">"continue"</a>, and
+<a href="#Goto_statements">"goto"</a> statements.
It is illegal to define a label that is never used.
In contrast to other identifiers, labels are not block scoped and do
not conflict with identifiers that are not labels. The scope of a label
@@ -1868,7 +1874,7 @@ var _, found = entries[name] // map lookup; only interested in "found"
<p>
If a list of expressions is given, the variables are initialized
-by assigning the expressions to the variables (§<a href="#Assignments">Assignments</a>)
+by <a href="#Assignments">assigning</a> the expressions to the variables
in order; all expressions must be consumed and all variables initialized from them.
Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
</p>
@@ -1935,9 +1941,11 @@ a, a := 1, 2 // illegal: double declaration of a or
<p>
Short variable declarations may appear only inside functions.
-In some contexts such as the initializers for <code>if</code>,
-<code>for</code>, or <code>switch</code> statements,
-they can be used to declare local temporary variables (§<a href="#Statements">Statements</a>).
+In some contexts such as the initializers for
+<a href="#If_statements">"if"</a>,
+<a href="#For_statements">"for"</a>, or
+<a href="#Switch_statements">"switch"</a> statements,
+they can be used to declare local temporary variables.
</p>
<h3 id="Function_declarations">Function declarations</h3>
@@ -1948,9 +1956,27 @@ to a function.
</p>
<pre class="ebnf">
-FunctionDecl = "func" FunctionName Signature [ Body ] .
+FunctionDecl = "func" FunctionName ( Function | Signature ) .
FunctionName = identifier .
-Body = Block .
+Function = Signature FunctionBody .
+FunctionBody = Block .
+</pre>
+
+<p>
+If the function's <a href="#Function_types">signature</a> declares
+result parameters, the function body's statement list must end in
+a <a href="#Terminating_statements">terminating statement</a>.
+</p>
+
+<pre>
+func findMarker(c <-chan int) int {
+ for i := range c {
+ if x := <-c; isMarker(x) {
+ return x
+ }
+ }
+ // invalid: missing return statement.
+}
</pre>
<p>
@@ -1972,13 +1998,13 @@ func flushICache(begin, end uintptr) // implemented externally
<h3 id="Method_declarations">Method declarations</h3>
<p>
-A method is a function with a <i>receiver</i>.
-A method declaration binds an identifier, the <i>method name</i>, to a method.
-It also associates the method with the receiver's <i>base type</i>.
+A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
+A method declaration binds an identifier, the <i>method name</i>, to a method,
+and associates the method with the receiver's <i>base type</i>.
</p>
<pre class="ebnf">
-MethodDecl = "func" Receiver MethodName Signature [ Body ] .
+MethodDecl = "func" Receiver MethodName ( Function | Signature ) .
Receiver = "(" [ identifier ] [ "*" ] BaseTypeName ")" .
BaseTypeName = identifier .
</pre>
@@ -2185,7 +2211,7 @@ For array and slice literals the following rules apply:
</ul>
<p>
-Taking the address of a composite literal (§<a href="#Address_operators">Address operators</a>)
+<a href="#Address_operators">Taking the address</a> of a composite literal
generates a pointer to a unique instance of the literal's value.
</p>
<pre>
@@ -2284,12 +2310,11 @@ noteFrequency := map[string]float32{
<h3 id="Function_literals">Function literals</h3>
<p>
-A function literal represents an anonymous function.
-It consists of a specification of the function type and a function body.
+A function literal represents an anonymous <a href="#Function_declarations">function</a>.
</p>
<pre class="ebnf">
-FunctionLit = FunctionType Body .
+FunctionLit = "func" Function .
</pre>
<pre>
@@ -2414,8 +2439,15 @@ expression is illegal.
In all other cases, <code>x.f</code> is illegal.
</li>
<li>
-If <code>x</code> is of pointer or interface type and has the value
-<code>nil</code>, assigning to, evaluating, or calling <code>x.f</code>
+If <code>x</code> is of pointer type and has the value
+<code>nil</code> and <code>x.f</code> denotes a struct field,
+assigning to or evaluating <code>x.f</code>
+causes a <a href="#Run_time_panics">run-time panic</a>.
+</li>
+<li>
+If <code>x</code> is of interface type and has the value
+<code>nil</code>, <a href="#Calls">calling</a> or
+<a href="#Method_values">evaluating</a> the method <code>x.f</code>
causes a <a href="#Run_time_panics">run-time panic</a>.
</li>
</ol>
@@ -2503,7 +2535,8 @@ rules apply:
If <code>a</code> is not a map:
</p>
<ul>
- <li>the index <code>x</code> must be an integer value; it is <i>in range</i> if <code>0 &lt;= x &lt; len(a)</code>,
+ <li>the index <code>x</code> must be of integer type or untyped;
+ it is <i>in range</i> if <code>0 &lt;= x &lt; len(a)</code>,
otherwise it is <i>out of range</i></li>
<li>a <a href="#Constants">constant</a> index must be non-negative
and representable by a value of type <code>int</code>
@@ -2894,9 +2927,7 @@ The right operand in a shift expression must have unsigned integer type
or be an untyped constant that can be converted to unsigned integer type.
If the left operand of a non-constant shift expression is an untyped constant,
the type of the constant is what it would be if the shift expression were
-replaced by its left operand alone; the type is <code>int</code> if it cannot
-be determined from the context (for instance, if the shift expression is an
-operand in a comparison against an untyped constant).
+replaced by its left operand alone.
</p>
<pre>
@@ -2905,10 +2936,12 @@ var i = 1&lt;&lt;s // 1 has type int
var j int32 = 1&lt;&lt;s // 1 has type int32; j == 0
var k = uint64(1&lt;&lt;s) // 1 has type uint64; k == 1&lt;&lt;33
var m int = 1.0&lt;&lt;s // 1.0 has type int
-var n = 1.0&lt;&lt;s != 0 // 1.0 has type int; n == false if ints are 32bits in size
+var n = 1.0&lt;&lt;s != i // 1.0 has type int; n == false if ints are 32bits in size
var o = 1&lt;&lt;s == 2&lt;&lt;s // 1 and 2 have type int; o == true if ints are 32bits in size
var p = 1&lt;&lt;s == 1&lt;&lt;33 // illegal if ints are 32bits in size: 1 has type int, but 1&lt;&lt;33 overflows int
var u = 1.0&lt;&lt;s // illegal: 1.0 has type float64, cannot shift
+var u1 = 1.0&lt;&lt;s != 0 // illegal: 1.0 has type float64, cannot shift
+var u2 = 1&lt;&lt;s != 1.0 // illegal: 1 has type float64, cannot shift
var v float32 = 1&lt;&lt;s // illegal: 1 has type float32, cannot shift
var w int64 = 1.0&lt;&lt;33 // 1.0&lt;&lt;33 is a constant shift expression
</pre>
@@ -3080,8 +3113,8 @@ occurs is implementation-specific.
For unsigned integer values, the operations <code>+</code>,
<code>-</code>, <code>*</code>, and <code>&lt;&lt;</code> are
computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
-the unsigned integer's type
-(§<a href="#Numeric_types">Numeric types</a>). Loosely speaking, these unsigned integer operations
+the <a href="#Numeric_types">unsigned integer</a>'s type.
+Loosely speaking, these unsigned integer operations
discard high bits upon overflow, and programs may rely on ``wrap around''.
</p>
<p>
@@ -3098,7 +3131,7 @@ not occur. For instance, it may not assume that <code>x &lt; x + 1</code> is alw
<h3 id="Comparison_operators">Comparison operators</h3>
<p>
-Comparison operators compare two operands and yield a boolean value.
+Comparison operators compare two operands and yield an untyped boolean value.
</p>
<pre class="grammar">
@@ -3158,8 +3191,8 @@ These terms and the result of the comparisons are defined as follows:
<li>
Channel values are comparable.
- Two channel values are equal if they were created by the same call to <code>make</code>
- (§<a href="#Making_slices_maps_and_channels">Making slices, maps, and channels</a>)
+ Two channel values are equal if they were created by the same call to
+ <a href="#Making_slices_maps_and_channels"><code>make</code></a>
or if both have value <code>nil</code>.
</li>
@@ -3206,20 +3239,17 @@ Comparison of pointer, channel, and interface values to <code>nil</code>
is also allowed and follows from the general rules above.
</p>
-<p>
-The result of a comparison can be assigned to any boolean type.
-If the context does not demand a specific boolean type,
-the result has type <code>bool</code>.
-</p>
-
<pre>
-type MyBool bool
+const c = 3 < 4 // c is the untyped bool constant true
+type MyBool bool
var x, y int
var (
- b1 MyBool = x == y // result of comparison has type MyBool
- b2 bool = x == y // result of comparison has type bool
- b3 = x == y // result of comparison has type bool
+ // The result of a comparison is an untyped bool.
+ // The usual assignment rules apply.
+ b3 = x == y // b3 has type bool
+ b4 bool = x == y // b4 has type bool
+ b5 MyBool = x == y // b5 has type MyBool
)
</pre>
@@ -3341,6 +3371,7 @@ type T struct {
}
func (tv T) Mv(a int) int { return 0 } // value receiver
func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
+
var t T
</pre>
@@ -3426,7 +3457,8 @@ the receiver is provided as the first argument to the call.
That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
as <code>f(t, 7)</code> not <code>t.f(7)</code>.
To construct a function that binds the receiver, use a
-<a href="#Function_literals">closure</a>.
+<a href="#Function_literals">function literal</a> or
+<a href="#Method_values">method value</a>.
</p>
<p>
@@ -3434,6 +3466,111 @@ It is legal to derive a function value from a method of an interface type.
The resulting function takes an explicit receiver of that interface type.
</p>
+<h3 id="Method_values">Method values</h3>
+
+<p>
+If the expression <code>x</code> has static type <code>T</code> and
+<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
+<code>x.M</code> is called a <i>method value</i>.
+The method value <code>x.M</code> is a function value that is callable
+with the same arguments as a method call of <code>x.M</code>.
+The expression <code>x</code> is evaluated and saved during the evaluation of the
+method value; the saved copy is then used as the receiver in any calls,
+which may be executed later.
+</p>
+
+<p>
+The type <code>T</code> may be an interface or non-interface type.
+</p>
+
+<p>
+As in the discussion of <a href="#Method_expressions">method expressions</a> above,
+consider a struct type <code>T</code> with two methods,
+<code>Mv</code>, whose receiver is of type <code>T</code>, and
+<code>Mp</code>, whose receiver is of type <code>*T</code>.
+</p>
+
+<pre>
+type T struct {
+ a int
+}
+func (tv T) Mv(a int) int { return 0 } // value receiver
+func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
+
+var t T
+var pt *T
+func makeT() T
+</pre>
+
+<p>
+The expression
+</p>
+
+<pre>
+t.Mv
+</pre>
+
+<p>
+yields a function value of type
+</p>
+
+<pre>
+func(int) int
+</pre>
+
+<p>
+These two invocations are equivalent:
+</p>
+
+<pre>
+t.Mv(7)
+f := t.Mv; f(7)
+</pre>
+
+<p>
+Similarly, the expression
+</p>
+
+<pre>
+pt.Mp
+</pre>
+
+<p>
+yields a function value of type
+</p>
+
+<pre>
+func(float32) float32
+</pre>
+
+<p>
+As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
+using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
+</p>
+
+<p>
+As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
+using an addressable value will automatically take the address of that value: <code>t.Mv</code> is equivalent to <code>(&amp;t).Mv</code>.
+</p>
+
+<pre>
+f := t.Mv; f(7) // like t.Mv(7)
+f := pt.Mp; f(7) // like pt.Mp(7)
+f := pt.Mv; f(7) // like (*pt).Mv(7)
+f := t.Mp; f(7) // like (&amp;t).Mp(7)
+f := makeT().Mp // invalid: result of makeT() is not addressable
+</pre>
+
+<p>
+Although the examples above use non-interface types, it is also legal to create a method value
+from a value of interface type.
+</p>
+
+<pre>
+var i interface { M(int) } = myVal
+f := i.M; f(7) // like i.M(7)
+</pre>
+
<h3 id="Conversions">Conversions</h3>
<p>
@@ -3484,8 +3621,8 @@ type <code>T</code> in any of these cases:
<li>
<code>x</code> is an integer constant and <code>T</code> is a
<a href="#String_types">string type</a>.
- The same rule as for non-constant <code>x</code> applies in this case
- (§<a href="#Conversions_to_and_from_a_string_type">Conversions to and from a string type</a>).
+ The <a href="#Conversions_to_and_from_a_string_type">same rule</a>
+ as for non-constant <code>x</code> applies in this case.
</li>
</ul>
@@ -3683,8 +3820,8 @@ A constant <a href="#Comparison_operators">comparison</a> always yields
an untyped boolean constant. If the left operand of a constant
<a href="#Operators">shift expression</a> is an untyped constant, the
result is an integer constant; otherwise it is a constant of the same
-type as the left operand, which must be of integer type
-(§<a href="#Arithmetic_operators">Arithmetic operators</a>).
+type as the left operand, which must be of
+<a href="#Numeric_types">integer type</a>.
Applying all other operators to untyped constants results in an untyped
constant of the same kind (that is, a boolean, integer, floating-point,
complex, or string constant).
@@ -3698,7 +3835,7 @@ const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer divisio
const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division)
const d = 1 &lt;&lt; 3.0 // d == 8 (untyped integer constant)
const e = 1.0 &lt;&lt; 3 // e == 8 (untyped integer constant)
-const f = int32(1) &lt;&lt; 33 // f == 0 (type int32)
+const f = int32(1) &lt;&lt; 33 // illegal (constant 8589934592 overflows int32)
const g = float64(2) &gt;&gt; 1 // illegal (float64(2) is a typed floating-point constant)
const h = "foo" &gt; "bar" // h == true (untyped boolean constant)
const j = true // j == true (untyped boolean constant)
@@ -3843,6 +3980,84 @@ Statement =
SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
</pre>
+<h3 id="Terminating_statements">Terminating statements</h3>
+
+<p>
+A terminating statement is one of the following:
+</p>
+
+<ol>
+<li>
+ A <a href="#Return_statements">"return"</a> or
+ <a href="#Goto_statements">"goto"</a> statement.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ A call to the built-in function
+ <a href="#Handling_panics"><code>panic</code></a>.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ An <a href="#If_statements">"if" statement</a> in which:
+ <ul>
+ <li>the "else" branch is present, and</li>
+ <li>both branches are terminating statements.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#For_statements">"for" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "for" statement, and</li>
+ <li>the loop condition is absent.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Switch_statements">"switch" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "switch" statement,</li>
+ <li>there is a default case, and</li>
+ <li>the statement lists in each case, including the default, end in a terminating
+ statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
+ statement</a>.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Select_statements">"select" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "select" statement, and</li>
+ <li>the statement lists in each case, including the default if present,
+ end in a terminating statement.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Labeled_statements">labeled statement</a> labeling
+ a terminating statement.
+</li>
+</ol>
+
+<p>
+All other statements are not terminating.
+</p>
+
+<p>
+A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
+is not empty and its final statement is terminating.
+</p>
+
<h3 id="Empty_statements">Empty statements</h3>
@@ -4149,7 +4364,7 @@ the expression <code>true</code>.
<pre class="ebnf">
ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
-ExprCaseClause = ExprSwitchCase ":" { Statement ";" } .
+ExprCaseClause = ExprSwitchCase ":" StatementList .
ExprSwitchCase = "case" ExpressionList | "default" .
</pre>
@@ -4213,7 +4428,7 @@ expression <code>x</code>. As with type assertions, <code>x</code> must be of
<pre class="ebnf">
TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
-TypeCaseClause = TypeSwitchCase ":" { Statement ";" } .
+TypeCaseClause = TypeSwitchCase ":" StatementList .
TypeSwitchCase = "case" TypeList | "default" .
TypeList = Type { "," Type } .
</pre>
@@ -4229,8 +4444,7 @@ in the TypeSwitchGuard.
</p>
<p>
-The type in a case may be <code>nil</code>
-(§<a href="#Predeclared_identifiers">Predeclared identifiers</a>);
+The type in a case may be <a href="#Predeclared_identifiers"><code>nil</code></a>;
that case is used when the expression in the TypeSwitchGuard
is a <code>nil</code> interface value.
</p>
@@ -4382,8 +4596,8 @@ the range clause is equivalent to the same clause with only the first variable p
The range expression is evaluated once before beginning the loop,
with one exception. If the range expression is an array or a pointer to an array
and only the first iteration value is present, only the range expression's
-length is evaluated; if that length is constant by definition
-(see §<a href="#Length_and_capacity">Length and capacity</a>),
+length is evaluated; if that length is constant
+<a href="#Length_and_capacity">by definition</a>,
the range expression itself will not be evaluated.
</p>
@@ -4536,7 +4750,7 @@ cases all referring to communication operations.
<pre class="ebnf">
SelectStmt = "select" "{" { CommClause } "}" .
-CommClause = CommCase ":" { Statement ";" } .
+CommClause = CommCase ":" StatementList .
CommCase = "case" ( SendStmt | RecvStmt ) | "default" .
RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
RecvExpr = Expression .
@@ -4661,7 +4875,7 @@ func complexF2() (re float64, im float64) {
</pre>
</li>
<li>The expression list may be empty if the function's result
- type specifies names for its result parameters (§<a href="#Function_types">Function types</a>).
+ type specifies names for its <a href="#Function_types">result parameters</a>.
The result parameters act as ordinary local variables
and the function may assign values to them as necessary.
The "return" statement returns the values of these variables.
@@ -4681,8 +4895,8 @@ func (devnull) Write(p []byte) (n int, _ error) {
</ol>
<p>
-Regardless of how they are declared, all the result values are initialized to the zero
-values for their type (§<a href="#The_zero_value">The zero value</a>) upon entry to the
+Regardless of how they are declared, all the result values are initialized to
+the <a href="#The_zero_value">zero values</a> for their type upon entry to the
function. A "return" statement that specifies results sets the result parameters before
any deferred functions are executed.
</p>
@@ -4699,7 +4913,9 @@ TODO: Define when return is required.<br />
<p>
A "break" statement terminates execution of the innermost
-"for", "switch" or "select" statement.
+<a href="#For_statements">"for"</a>,
+<a href="#Switch_statements">"switch"</a>, or
+<a href="#Select_statements">"select"</a> statement.
</p>
<pre class="ebnf">
@@ -4708,10 +4924,8 @@ BreakStmt = "break" [ Label ] .
<p>
If there is a label, it must be that of an enclosing
-"for", "switch" or "select" statement, and that is the one whose execution
-terminates
-(§<a href="#For_statements">For statements</a>, §<a href="#Switch_statements">Switch statements</a>,
-§<a href="#Select_statements">Select statements</a>).
+"for", "switch", or "select" statement,
+and that is the one whose execution terminates.
</p>
<pre>
@@ -4728,7 +4942,7 @@ L:
<p>
A "continue" statement begins the next iteration of the
-innermost "for" loop at its post statement (§<a href="#For_statements">For statements</a>).
+innermost <a href="#For_statements">"for" loop</a> at its post statement.
</p>
<pre class="ebnf">
@@ -4738,8 +4952,7 @@ ContinueStmt = "continue" [ Label ] .
<p>
If there is a label, it must be that of an enclosing
"for" statement, and that is the one whose execution
-advances
-(§<a href="#For_statements">For statements</a>).
+advances.
</p>
<h3 id="Goto_statements">Goto statements</h3>
@@ -4958,8 +5171,8 @@ constant and <code>s</code> is evaluated.
<p>
The built-in function <code>new</code> takes a type <code>T</code> and
returns a value of type <code>*T</code>.
-The memory is initialized as described in the section on initial values
-(§<a href="#The_zero_value">The zero value</a>).
+The memory is initialized as described in the section on
+<a href="#The_zero_value">initial values</a>.
</p>
<pre class="grammar">
@@ -4985,14 +5198,12 @@ of the memory.
<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
<p>
-Slices, maps and channels are reference types that do not require the
-extra indirection of an allocation with <code>new</code>.
The built-in function <code>make</code> takes a type <code>T</code>,
which must be a slice, map or channel type,
optionally followed by a type-specific list of expressions.
It returns a value of type <code>T</code> (not <code>*T</code>).
-The memory is initialized as described in the section on initial values
-(§<a href="#The_zero_value">The zero value</a>).
+The memory is initialized as described in the section on
+<a href="#The_zero_value">initial values</a>.
</p>
<pre class="grammar">
@@ -5010,7 +5221,7 @@ make(T, n) channel asynchronous channel of type T, buffer size n
<p>
-The size arguments <code>n</code> and <code>m</code> must be integer values.
+The size arguments <code>n</code> and <code>m</code> must be of integer type or untyped.
A <a href="#Constants">constant</a> size argument must be non-negative and
representable by a value of type <code>int</code>.
If both <code>n</code> and <code>m</code> are provided and are constant, then
@@ -5184,14 +5395,14 @@ func recover() interface{}
</pre>
<p>
-A <code>panic</code> call in a function <code>F</code> terminates the execution
-of <code>F</code>.
+While executing a function <code>F</code>,
+an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
+terminates the execution of <code>F</code>.
Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
-are executed before <code>F</code> returns to its caller. To the caller,
-the call of <code>F</code> then behaves itself like a call to <code>panic</code>,
-terminating its own execution and running deferred functions in the same manner.
-This continues until all functions in the goroutine have ceased execution,
-in reverse order. At that point, the program is terminated and the error
+are then executed as usual.
+Next, any deferred functions run by <code>F's</code> caller are run,
+and so on up to any deferred by the top-level function in the executing goroutine.
+At that point, the program is terminated and the error
condition is reported, including the value of the argument to <code>panic</code>.
This termination sequence is called <i>panicking</i>.
</p>
@@ -5204,17 +5415,36 @@ panic(Error("cannot parse"))
<p>
The <code>recover</code> function allows a program to manage behavior
-of a panicking goroutine. Executing a <code>recover</code> call
-<i>inside</i> a deferred function (but not any function called by it) stops
-the panicking sequence by restoring normal execution, and retrieves
-the error value passed to the call of <code>panic</code>. If
-<code>recover</code> is called outside the deferred function it will
-not stop a panicking sequence. In this case, or when the goroutine
-is not panicking, or if the argument supplied to <code>panic</code>
-was <code>nil</code>, <code>recover</code> returns <code>nil</code>.
+of a panicking goroutine.
+Suppose a function <code>G</code> defers a function <code>D</code> that calls
+<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
+is executing.
+When the running of deferred functions reaches <code>D</code>,
+the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>.
+If <code>D</code> returns normally, without starting a new
+<code>panic</code>, the panicking sequence stops. In that case,
+the state of functions called between <code>G</code> and the call to <code>panic</code>
+is discarded, and normal execution resumes.
+Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
+execution terminates by returning to its caller.
</p>
<p>
+The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds:
+</p>
+<ul>
+<li>
+<code>panic</code>'s argument was <code>nil</code>;
+</li>
+<li>
+the goroutine is not panicking;
+</li>
+<li>
+<code>recover</code> was not called directly by a deferred function.
+</li>
+</ul>
+
+<p>
The <code>protect</code> function in the example below invokes
the function argument <code>g</code> and protects callers from
run-time panics raised by <code>g</code>.
@@ -5367,7 +5597,8 @@ import . "lib/math" Sin
<p>
An import declaration declares a dependency relation between
the importing and imported package.
-It is illegal for a package to import itself or to import a package without
+It is illegal for a package to import itself, directly or indirectly,
+or to directly import a package without
referring to any of its exported identifiers. To import a package solely for
its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
identifier as explicit package name:
@@ -5495,19 +5726,23 @@ in unspecified order.
</p>
<p>
Within a package, package-level variables are initialized,
-and constant values are determined, in
-data-dependent order: if the initializer of <code>A</code>
-depends on the value of <code>B</code>, <code>A</code>
+and constant values are determined, according to
+order of reference: if the initializer of <code>A</code>
+depends on <code>B</code>, <code>A</code>
will be set after <code>B</code>.
-It is an error if such dependencies form a cycle.
-Dependency analysis is done lexically: <code>A</code>
+Dependency analysis does not depend on the actual values
+of the items being initialized, only on their appearance
+in the source.
+<code>A</code>
depends on <code>B</code> if the value of <code>A</code>
contains a mention of <code>B</code>, contains a value
whose initializer
mentions <code>B</code>, or mentions a function that
mentions <code>B</code>, recursively.
+It is an error if such dependencies form a cycle.
If two items are not interdependent, they will be initialized
-in the order they appear in the source.
+in the order they appear in the source, possibly in multiple files,
+as presented to the compiler.
Since the dependency analysis is done per package, it can produce
unspecified results if <code>A</code>'s initializer calls a function defined
in another package that refers to <code>B</code>.
@@ -5645,8 +5880,10 @@ as if <code>v</code> was declared via <code>var v = x</code>.
</p>
<p>
The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
-denoting a struct field of any type and returns the field offset in bytes relative to the
-struct's address.
+<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
+or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
+If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
+without pointer indirections through fields of the struct.
For a struct <code>s</code> with field <code>f</code>:
</p>
@@ -5675,7 +5912,7 @@ Calls to <code>Alignof</code>, <code>Offsetof</code>, and
<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
<p>
-For the numeric types (§<a href="#Numeric_types">Numeric types</a>), the following sizes are guaranteed:
+For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
</p>
<pre class="grammar">
diff --git a/doc/godocs.js b/doc/godocs.js
index 5d12da131..6875f74d8 100644
--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -179,6 +179,13 @@ function fixFocus() {
}).resize();
}
+function toggleHash() {
+ var hash = $(window.location.hash);
+ if (hash.is('.toggle')) {
+ hash.addClass('toggleVisible').removeClass('toggle');
+ }
+}
+
$(document).ready(function() {
bindSearchEvents();
generateTOC();
@@ -190,6 +197,7 @@ $(document).ready(function() {
bindToggleLinks(".indexLink", "");
setupDropdownPlayground();
fixFocus();
+ toggleHash();
});
})();
diff --git a/doc/install.html b/doc/install.html
index 03b13c018..b66781942 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -3,25 +3,34 @@
"Path": "/doc/install"
}-->
-<h2 id="introduction">Introduction</h2>
+<h2 id="download">Download the Go distribution</h2>
<p>
-Go is an open source project with a BSD-style license.
-There are two official Go compiler toolchains: the <code>gc</code> Go compiler
-and the <code>gccgo</code> compiler that is part of the GNU C Compiler (GCC).
+<a href="http://code.google.com/p/go/downloads" id="start" class="download" target="_blank">
+<span class="big">Download Go</span>
+<span class="desc">Click here to visit the downloads page</span>
+</a>
</p>
<p>
-The <code>gc</code> compiler is the more mature and well-tested of the two.
-This page is about installing a binary distribution of the <code>gc</code>
-compiler.
+Click the link above to visit the
+<a href="http://code.google.com/p/go/downloads">Go project's downloads page</a>
+and select the binary distribution that matches your operating system and
+processor architecture.
</p>
<p>
-For information about installing the <code>gc</code> compiler from source, see
-<a href="/doc/install/source">Installing Go from source</a>.
-For information about installing <code>gccgo</code>, see
-<a href="/doc/install/gccgo">Setting up and using gccgo</a>.
+Official binary distributions are available for the FreeBSD, Linux, Mac OS X
+(Snow Leopard, Lion, and Mountain Lion), NetBSD, and Windows operating systems
+and the 32-bit (<code>386</code>) and 64-bit (<code>amd64</code>) x86 processor
+architectures.
+</p>
+
+<p>
+If a binary distribution is not available for your combination of operating
+system and architecture you may want to try
+<a href="/doc/install/source">installing from source</a> or
+<a href="/doc/install/gccgo">installing gccgo instead of gc</a>.
</p>
<h2 id="requirements">System requirements</h2>
@@ -56,29 +65,6 @@ installed Xcode 4.3+, you can install it from the Components tab of the
Downloads preferences panel.
</p>
-<h2 id="download">Download the Go tools</h2>
-
-<p>
-Visit the
-<a href="http://code.google.com/p/go/downloads">Go project's downloads page</a>
-and select the binary distribution that matches
-your operating system and processor architecture.
-</p>
-
-<p>
-Official binary distributions are available
-for the FreeBSD, Linux, Mac OS X (Snow Leopard/Lion), NetBSD, and Windows operating systems
-and the 32-bit (<code>386</code>) and 64-bit (<code>amd64</code>)
-x86 processor architectures.
-</p>
-
-<p>
-If a binary distribution is not available for your
-OS/arch combination you may want to try
-<a href="/doc/install/source">installing from source</a> or
-<a href="/doc/install/gccgo">installing gccgo instead of gc</a>.
-</p>
-
<h2 id="install">Install the Go tools</h2>
<p>
@@ -180,7 +166,7 @@ the <code>GOROOT</code> environment variable to your chosen path.
</p>
<p>
-Add the <code>bin</code> subdirectory of your Go root (for example, <code>c:\Go\bin</code>) to to your <code>PATH</code> environment variable.
+Add the <code>bin</code> subdirectory of your Go root (for example, <code>c:\Go\bin</code>) to your <code>PATH</code> environment variable.
</p>
<h4 id="windows_msi">MSI installer (experimental)</h4>
diff --git a/doc/progs/eff_unused1.go b/doc/progs/eff_unused1.go
new file mode 100644
index 000000000..f990a19f7
--- /dev/null
+++ b/doc/progs/eff_unused1.go
@@ -0,0 +1,18 @@
+// skip
+
+package main
+
+import (
+ "fmt"
+ "io"
+ "log"
+ "os"
+)
+
+func main() {
+ fd, err := os.Open("test.go")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // TODO: use fd.
+}
diff --git a/doc/progs/eff_unused2.go b/doc/progs/eff_unused2.go
new file mode 100644
index 000000000..3e6e041c7
--- /dev/null
+++ b/doc/progs/eff_unused2.go
@@ -0,0 +1,22 @@
+// compile
+
+package main
+
+import (
+ "fmt"
+ "io"
+ "log"
+ "os"
+)
+
+var _ = fmt.Printf // For debugging; delete when done.
+var _ io.Reader // For debugging; delete when done.
+
+func main() {
+ fd, err := os.Open("test.go")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // TODO: use fd.
+ _ = fd
+}
diff --git a/doc/progs/run b/doc/progs/run
index da777f329..71759c565 100755
--- a/doc/progs/run
+++ b/doc/progs/run
@@ -16,6 +16,7 @@ effective_go="
eff_bytesize
eff_qr
eff_sequence
+ eff_unused2
"
error_handling="
diff --git a/doc/progs/unused1.go b/doc/progs/unused1.go
deleted file mode 100644
index 96a6d98a3..000000000
--- a/doc/progs/unused1.go
+++ /dev/null
@@ -1,12 +0,0 @@
-// skip
-
-package main
-
-import (
- "fmt"
- "io"
-)
-
-func main() {
- greeting := "hello, world"
-}
diff --git a/doc/progs/unused2.go b/doc/progs/unused2.go
deleted file mode 100644
index 5c5f9d74f..000000000
--- a/doc/progs/unused2.go
+++ /dev/null
@@ -1,16 +0,0 @@
-// compile
-
-package main
-
-import (
- "fmt"
- "io"
-)
-
-var _ = fmt.Printf
-var _ io.Reader
-
-func main() {
- greeting := "hello, world"
- _ = greeting
-}
diff --git a/doc/reference.html b/doc/reference.html
index 795c5e00e..241d75a43 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -43,7 +43,7 @@ same variable in a different goroutine.
These packages are part of the Go Project but outside the main Go tree.
They are developed under looser <a href="/doc/go1compat.html">compatibility
requirements</a> than the Go core.
-Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".
+Install them with "<code><a href="/cmd/go/#hdr-Download_and_install_packages_and_dependencies">go get</a></code>".
</p>
<ul>
@@ -51,6 +51,10 @@ Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dep
<li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://godoc.org/code.google.com/p/go.crypto">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://godoc.org/code.google.com/p/go.image">docs</a>]
<li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://godoc.org/code.google.com/p/go.net">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=text"><code>code.google.com/p/go.text</code></a> [<a href="http://godoc.org/code.google.com/p/go.text">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=exp"><code>code.google.com/p/go.exp</code></a> [<a href="http://godoc.org/code.google.com/p/go.exp">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=talks"><code>code.google.com/p/go.talks</code></a> [<a href="http://godoc.org/code.google.com/p/go.talks">docs</a>]
+<li><a href="http://code.google.com/p/go/source/browse?repo=blog"><code>code.google.com/p/go.blog</code></a> [<a href="http://godoc.org/code.google.com/p/go.blog">docs</a>]
</ul>
<p>
diff --git a/doc/root.html b/doc/root.html
index 34915c025..81792671b 100644
--- a/doc/root.html
+++ b/doc/root.html
@@ -84,41 +84,38 @@ Linux, Mac OS X, Windows, and more.
<div style="clear: both;"></div>
-<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
-google.load("feeds", "1");
+
+function readableTime(t) {
+ var m = ["January", "February", "March", "April", "May", "June", "July",
+ "August", "September", "October", "November", "December"];
+ var p = t.substring(0, t.indexOf("T")).split("-");
+ var d = new Date(p[0], p[1]-1, p[2]);
+ return d.getDate() + " " + m[d.getMonth()] + " " + d.getFullYear();
+}
function feedLoaded(result) {
- if (result.error) {
- console.log(result.error);
- return;
- }
var blog = document.getElementById("blog");
var read = blog.getElementsByClassName("read")[0];
- for (var i = 0; i < result.feed.entries.length && i < 2; i++) {
- var entry = result.feed.entries[i];
+ for (var i = 0; i < result.length && i < 2; i++) {
+ var entry = result[i];
var title = document.createElement("a");
title.className = "title";
- title.href = entry.link;
- title.innerHTML = entry.title;
+ title.href = entry.Link;
+ title.innerHTML = entry.Title;
blog.insertBefore(title, read);
var extract = document.createElement("div");
extract.className = "extract";
- extract.innerHTML = entry.contentSnippet;
+ extract.innerHTML = entry.Summary;
blog.insertBefore(extract, read);
var when = document.createElement("div");
when.className = "when";
- var pub = entry.publishedDate.split(" ").slice(1,3).join(" ");
- when.innerHTML = "Published " + pub
+ when.innerHTML = "Published " + readableTime(entry.Time);
blog.insertBefore(when, read);
}
}
-function init() {
- // Load blog feed.
- var feed = new google.feeds.Feed("http://blog.golang.org/feeds/posts/default");
- feed.load(feedLoaded);
-
+$(function() {
// Set up playground.
playground({
"codeEl": "#learn .code",
@@ -128,7 +125,11 @@ function init() {
"shareRedirect": "http://play.golang.org/p/",
"toysEl": "#learn .toys select"
});
-}
-google.setOnLoadCallback(init);
+ // Load blog feed.
+ $('<script/>').attr('text', 'text/javascript')
+ .attr('src', 'http://blog.golang.org/.json?jsonp=feedLoaded')
+ .appendTo('body');
+});
+
</script>
diff --git a/doc/style.css b/doc/style.css
index 3d881b03a..5c8e17a29 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -12,7 +12,7 @@ pre {
line-height: 18px;
}
pre .comment {
- color: #375EAB;
+ color: #006600;
}
pre .highlight,
pre .highlight-comment,
@@ -198,6 +198,9 @@ div#blog .read a {
border: 1px solid #375EAB;
background: #E0EBF5;
}
+.download {
+ width: 150px;
+}
div#menu {
float: right;
generated by cgit v1.2.3 (git 2.39.1) at 2024-08-05 08:37:42 +0000