# Use of this source code is governed by a BSD-style
# license that can be found in the LICENSE file.
-HTML=\
- articles/defer_panic_recover.html\
- articles/error_handling.html\
- articles/slices_usage_and_internals.html\
- articles/laws_of_reflection.html\
- effective_go.html\
- go1.html\
+RAWHTML=\
+ articles/defer_panic_recover.rawhtml\
+ articles/error_handling.rawhtml\
+ articles/slices_usage_and_internals.rawhtml\
+ articles/laws_of_reflection.rawhtml\
+ effective_go.rawhtml\
+ go1.rawhtml\
-all: tmpltohtml $(HTML)
+all: $(RAWHTML)
-tmpltohtml: tmpltohtml.go
- go build tmpltohtml.go
-
-%.html: %.tmpl tmpltohtml
- ./tmpltohtml $*.tmpl > $@
+%.rawhtml: %.html
+ godoc -url /doc/$* >$@
clean:
- rm -f $(HTML) tmpltohtml
+ rm -f $(RAWHTML)
<!--{
- "Title": "Defer, Panic, and Recover"
+ "Title": "Defer, Panic, and Recover",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml articles/defer_panic_recover.tmpl
--->
<p>
Go has the usual mechanisms for control flow: if, for, switch, goto. It also
contents of one file to the other:
</p>
-<pre><!--{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
--->func CopyFile(dstName, srcName string) (written int64, err error) {
- src, err := os.Open(srcName)
- if err != nil {
- return
- }
-
- dst, err := os.Create(dstName)
- if err != nil {
- return
- }
-
- written, err = io.Copy(dst, src)
- dst.Close()
- src.Close()
- return
-}</pre>
+{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}
<p>
This works, but there is a bug. If the call to os.Create fails, the
files are always closed:
</p>
-<pre><!--{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
--->func CopyFile(dstName, srcName string) (written int64, err error) {
- src, err := os.Open(srcName)
- if err != nil {
- return
- }
- defer src.Close()
-
- dst, err := os.Create(dstName)
- if err != nil {
- return
- }
- defer dst.Close()
-
- return io.Copy(dst, src)
-}</pre>
+{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}
<p>
Defer statements allow us to think about closing each file right after opening
deferred. The deferred call will print "0" after the function returns.
</p>
-<pre><!--{{code "progs/defer.go" `/func a/` `/STOP/`}}
--->func a() {
- i := 0
- defer fmt.Println(i)
- i++
- return
-}</pre>
+{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}
<p>
2. <i>Deferred function calls are executed in Last In First Out order
This function prints "3210":
</p>
-<pre><!--{{code "progs/defer.go" `/func b/` `/STOP/`}}
--->func b() {
- for i := 0; i < 4; i++ {
- defer fmt.Print(i)
- }
-}</pre>
+{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}
<p>
3. <i>Deferred functions may read and assign to the returning function's named
the surrounding function returns. Thus, this function returns 2:
</p>
-<pre><!--{{code "progs/defer.go" `/func c/` `/STOP/`}}
--->func c() (i int) {
- defer func() { i++ }()
- return 1
-}</pre>
+{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}
<p>
This is convenient for modifying the error return value of a function; we will
Here's an example program that demonstrates the mechanics of panic and defer:
</p>
-<pre><!--{{code "progs/defer2.go" `/package main/` `/STOP/`}}
--->package main
-
-import "fmt"
-
-func main() {
- f()
- fmt.Println("Returned normally from f.")
-}
-
-func f() {
- defer func() {
- if r := recover(); r != nil {
- fmt.Println("Recovered in f", r)
- }
- }()
- fmt.Println("Calling g.")
- g(0)
- fmt.Println("Returned normally from g.")
-}
-
-func g(i int) {
- if i > 3 {
- fmt.Println("Panicking!")
- panic(fmt.Sprintf("%v", i))
- }
- defer fmt.Println("Defer in g", i)
- fmt.Println("Printing in g", i)
- g(i + 1)
-}</pre>
+{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}
<p>
The function g takes the int i, and panics if i is greater than 3, or else it
+++ /dev/null
-<!--{
- "Title": "Defer, Panic, and Recover"
-}-->
-{{donotedit}}
-<p>
-Go has the usual mechanisms for control flow: if, for, switch, goto. It also
-has the go statement to run code in a separate goroutine. Here I'd like to
-discuss some of the less common ones: defer, panic, and recover.
-</p>
-
-<p>
-A <b>defer statement</b> pushes a function call onto a list. The list of saved
-calls is executed after the surrounding function returns. Defer is commonly
-used to simplify functions that perform various clean-up actions.
-</p>
-
-<p>
-For example, let's look at a function that opens two files and copies the
-contents of one file to the other:
-</p>
-
-{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
-
-<p>
-This works, but there is a bug. If the call to os.Create fails, the
-function will return without closing the source file. This can be easily
-remedied by putting a call to src.Close() before the second return statement,
-but if the function were more complex the problem might not be so easily
-noticed and resolved. By introducing defer statements we can ensure that the
-files are always closed:
-</p>
-
-{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
-
-<p>
-Defer statements allow us to think about closing each file right after opening
-it, guaranteeing that, regardless of the number of return statements in the
-function, the files <i>will</i> be closed.
-</p>
-
-<p>
-The behavior of defer statements is straightforward and predictable. There are
-three simple rules:
-</p>
-
-<p>
-1. <i>A deferred function's arguments are evaluated when the defer statement is
-evaluated.</i>
-</p>
-
-<p>
-In this example, the expression "i" is evaluated when the Println call is
-deferred. The deferred call will print "0" after the function returns.
-</p>
-
-{{code "progs/defer.go" `/func a/` `/STOP/`}}
-
-<p>
-2. <i>Deferred function calls are executed in Last In First Out order
-</i>after<i> the surrounding function returns.</i>
-</p>
-
-<p>
-This function prints "3210":
-</p>
-
-{{code "progs/defer.go" `/func b/` `/STOP/`}}
-
-<p>
-3. <i>Deferred functions may read and assign to the returning function's named
-return values.</i>
-</p>
-
-<p>
-In this example, a deferred function increments the return value i <i>after</i>
-the surrounding function returns. Thus, this function returns 2:
-</p>
-
-{{code "progs/defer.go" `/func c/` `/STOP/`}}
-
-<p>
-This is convenient for modifying the error return value of a function; we will
-see an example of this shortly.
-</p>
-
-<p>
-<b>Panic</b> is a built-in function that stops the ordinary flow of control and
-begins <i>panicking</i>. When the function F calls panic, execution of F stops,
-any deferred functions in F are executed normally, and then F returns to its
-caller. To the caller, F then behaves like a call to panic. The process
-continues up the stack until all functions in the current goroutine have
-returned, at which point the program crashes. Panics can be initiated by
-invoking panic directly. They can also be caused by runtime errors, such as
-out-of-bounds array accesses.
-</p>
-
-<p>
-<b>Recover</b> is a built-in function that regains control of a panicking
-goroutine. Recover is only useful inside deferred functions. During normal
-execution, a call to recover will return nil and have no other effect. If the
-current goroutine is panicking, a call to recover will capture the value given
-to panic and resume normal execution.
-</p>
-
-<p>
-Here's an example program that demonstrates the mechanics of panic and defer:
-</p>
-
-{{code "progs/defer2.go" `/package main/` `/STOP/`}}
-
-<p>
-The function g takes the int i, and panics if i is greater than 3, or else it
-calls itself with the argument i+1. The function f defers a function that calls
-recover and prints the recovered value (if it is non-nil). Try to picture what
-the output of this program might be before reading on.
-</p>
-
-<p>
-The program will output:
-</p>
-
-<pre>Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-Recovered in f 4
-Returned normally from f.</pre>
-
-<p>
-If we remove the deferred function from f the panic is not recovered and
-reaches the top of the goroutine's call stack, terminating the program. This
-modified program will output:
-</p>
-
-<pre>Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-panic: 4
-
-panic PC=0x2a9cd8
-[stack trace omitted]</pre>
-
-<p>
-For a real-world example of <b>panic</b> and <b>recover</b>, see the
-<a href="/pkg/encoding/json/">json package</a> from the Go standard library.
-It decodes JSON-encoded data with a set of recursive functions.
-When malformed JSON is encountered, the parser calls panic to unwind the
-stack to the top-level function call, which recovers from the panic and returns
-an appropriate error value (see the 'error' and 'unmarshal' functions in
-<a href="/src/pkg/encoding/json/decode.go">decode.go</a>).
-</p>
-
-<p>
-The convention in the Go libraries is that even when a package uses panic
-internally, its external API still presents explicit error return values.
-</p>
-
-<p>
-Other uses of <b>defer</b> (beyond the file.Close() example given earlier)
-include releasing a mutex:
-</p>
-
-<pre>mu.Lock()
-defer mu.Unlock()</pre>
-
-<p>
-printing a footer:
-</p>
-
-<pre>printHeader()
-defer printFooter()</pre>
-
-<p>
-and more.
-</p>
-
-<p>
-In summary, the defer statement (with or without panic and recover) provides an
-unusual and powerful mechanism for control flow. It can be used to model a
-number of features implemented by special-purpose structures in other
-programming languages. Try it out.
-</p>
<!--{
- "Title": "Error Handling and Go"
+ "Title": "Error Handling and Go",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml articles/error_handling.tmpl
--->
<p>
If you have written any Go code you have probably encountered the built-in
returns a non-nil <code>error</code> value when it fails to open a file.
</p>
-<pre><!--{{code "progs/error.go" `/func Open/`}}
--->func Open(name string) (file *File, err error)</pre>
+{{code "/doc/progs/error.go" `/func Open/`}}
<p>
The following code uses <code>os.Open</code> to open a file. If an error
occurs it calls <code>log.Fatal</code> to print the error message and stop.
</p>
-<pre><!--{{code "progs/error.go" `/func openFile/` `/STOP/`}}
---> f, err := os.Open("filename.ext")
- if err != nil {
- log.Fatal(err)
- }
- // do something with the open *File f</pre>
+{{code "/doc/progs/error.go" `/func openFile/` `/STOP/`}}
<p>
You can get a lot done in Go knowing just this about the <code>error</code>
<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
</p>
-<pre><!--{{code "progs/error.go" `/errorString/` `/STOP/`}}
--->// errorString is a trivial implementation of error.
-type errorString struct {
- s string
-}
-
-func (e *errorString) Error() string {
- return e.s
-}</pre>
+{{code "/doc/progs/error.go" `/errorString/` `/STOP/`}}
<p>
You can construct one of these values with the <code>errors.New</code>
and returns as an <code>error</code> value.
</p>
-<pre><!--{{code "progs/error.go" `/New/` `/STOP/`}}
--->// New returns an error that formats as the given text.
-func New(text string) error {
- return &errorString{text}
-}</pre>
+{{code "/doc/progs/error.go" `/New/` `/STOP/`}}
<p>
Here's how you might use <code>errors.New</code>:
</p>
-<pre><!--{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
--->func Sqrt(f float64) (float64, error) {
- if f < 0 {
- return 0, errors.New("math: square root of negative number")
- }
- // implementation
-}</pre>
+{{code "/doc/progs/error.go" `/func Sqrt/` `/STOP/`}}
<p>
A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
<code>Error</code> method, or by just printing it:
</p>
-<pre><!--{{code "progs/error.go" `/func printErr/` `/STOP/`}}
---> f, err := Sqrt(-1)
- if err != nil {
- fmt.Println(err)
- }</pre>
+{{code "/doc/progs/error.go" `/func printErr/` `/STOP/`}}
<p>
The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
<code>errors.New</code>.
</p>
-<pre><!--{{code "progs/error.go" `/fmtError/` `/STOP/`}}
---> if f < 0 {
- return 0, fmt.Errorf("math: square root of negative number %g", f)
- }</pre>
+{{code "/doc/progs/error.go" `/fmtError/` `/STOP/`}}
<p>
In many cases <code>fmt.Errorf</code> is good enough, but since
error implementation instead of using <code>errors.errorString</code>:
</p>
-<pre><!--{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
--->type NegativeSqrtError float64
-
-func (f NegativeSqrtError) Error() string {
- return fmt.Sprintf("math: square root of negative number %g", float64(f))
-}</pre>
+{{code "/doc/progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
<p>
A sophisticated caller can then use a
returns when it encounters a syntax error parsing a JSON blob.
</p>
-<pre><!--{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
--->type SyntaxError struct {
- msg string // description of error
- Offset int64 // error occurred after reading Offset bytes
-}
-
-func (e *SyntaxError) Error() string { return e.msg }</pre>
+{{code "/doc/progs/error.go" `/type SyntaxError/` `/STOP/`}}
<p>
The <code>Offset</code> field isn't even shown in the default formatting of the
messages:
</p>
-<pre><!--{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
---> if err := dec.Decode(&val); err != nil {
- if serr, ok := err.(*json.SyntaxError); ok {
- line, col := findLine(f, serr.Offset)
- return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err)
- }
- return err
- }</pre>
+{{code "/doc/progs/error.go" `/func decodeError/` `/STOP/`}}
<p>
(This is a slightly simplified version of some
up otherwise.
</p>
-<pre><!--{{code "progs/error.go" `/func netError/` `/STOP/`}}
---> if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
- time.Sleep(1e9)
- continue
- }
- if err != nil {
- log.Fatal(err)
- }</pre>
+{{code "/doc/progs/error.go" `/func netError/` `/STOP/`}}
<p>
<b>Simplifying repetitive error handling</b>
formats it with a template.
</p>
-<pre><!--{{code "progs/error2.go" `/func init/` `/STOP/`}}
--->func init() {
- http.HandleFunc("/view", viewRecord)
-}
-
-func viewRecord(w http.ResponseWriter, r *http.Request) {
- c := appengine.NewContext(r)
- key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
- record := new(Record)
- if err := datastore.Get(c, key, record); err != nil {
- http.Error(w, err.Error(), 500)
- return
- }
- if err := viewTemplate.Execute(w, record); err != nil {
- http.Error(w, err.Error(), 500)
- }
-}</pre>
+{{code "/doc/progs/error2.go" `/func init/` `/STOP/`}}
<p>
This function handles errors returned by the <code>datastore.Get</code>
type that includes an <code>error</code> return value:
</p>
-<pre><!--{{code "progs/error3.go" `/type appHandler/`}}
--->type appHandler func(http.ResponseWriter, *http.Request) error</pre>
+{{code "/doc/progs/error3.go" `/type appHandler/`}}
<p>
Then we can change our <code>viewRecord</code> function to return errors:
</p>
-<pre><!--{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
--->func viewRecord(w http.ResponseWriter, r *http.Request) error {
- c := appengine.NewContext(r)
- key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
- record := new(Record)
- if err := datastore.Get(c, key, record); err != nil {
- return err
- }
- return viewTemplate.Execute(w, record)
-}</pre>
+{{code "/doc/progs/error3.go" `/func viewRecord/` `/STOP/`}}
<p>
This is simpler than the original version, but the <a
<code>ServeHTTP</code> method on <code>appHandler</code>:
</p>
-<pre><!--{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
--->func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
- if err := fn(w, r); err != nil {
- http.Error(w, err.Error(), 500)
- }
-}</pre>
+{{code "/doc/progs/error3.go" `/ServeHTTP/` `/STOP/`}}
<p>
The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
<code>http.HandlerFunc</code>).
</p>
-<pre><!--{{code "progs/error3.go" `/func init/` `/STOP/`}}
--->func init() {
- http.Handle("/view", appHandler(viewRecord))
-}</pre>
+{{code "/doc/progs/error3.go" `/func init/` `/STOP/`}}
<p>
With this basic error handling infrastructure in place, we can make it more
<code>error</code> and some other fields:
</p>
-<pre><!--{{code "progs/error4.go" `/type appError/` `/STOP/`}}
--->type appError struct {
- Error error
- Message string
- Code int
-}</pre>
+{{code "/doc/progs/error4.go" `/type appError/` `/STOP/`}}
<p>
Next we modify the appHandler type to return <code>*appError</code> values:
</p>
-<pre><!--{{code "progs/error4.go" `/type appHandler/`}}
--->type appHandler func(http.ResponseWriter, *http.Request) *appError</pre>
+{{code "/doc/progs/error4.go" `/type appHandler/`}}
<p>
(It's usually a mistake to pass back the concrete type of an error rather than
console:
</p>
-<pre><!--{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
--->func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
- if e := fn(w, r); e != nil { // e is *appError, not os.Error.
- c := appengine.NewContext(r)
- c.Errorf("%v", e.Error)
- http.Error(w, e.Message, e.Code)
- }
-}</pre>
+{{code "/doc/progs/error4.go" `/ServeHTTP/` `/STOP/`}}
<p>
Finally, we update <code>viewRecord</code> to the new function signature and
have it return more context when it encounters an error:
</p>
-<pre><!--{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
--->func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
- c := appengine.NewContext(r)
- key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
- record := new(Record)
- if err := datastore.Get(c, key, record); err != nil {
- return &appError{err, "Record not found", 404}
- }
- if err := viewTemplate.Execute(w, record); err != nil {
- return &appError{err, "Can't display record", 500}
- }
- return nil
-}</pre>
+{{code "/doc/progs/error4.go" `/func viewRecord/` `/STOP/`}}
<p>
This version of <code>viewRecord</code> is the same length as the original, but
+++ /dev/null
-<!--{
- "Title": "Error Handling and Go"
-}-->
-{{donotedit}}
-<p>
-If you have written any Go code you have probably encountered the built-in
-<code>error</code> type. Go code uses <code>error</code> values to
-indicate an abnormal state. For example, the <code>os.Open</code> function
-returns a non-nil <code>error</code> value when it fails to open a file.
-</p>
-
-{{code "progs/error.go" `/func Open/`}}
-
-<p>
-The following code uses <code>os.Open</code> to open a file. If an error
-occurs it calls <code>log.Fatal</code> to print the error message and stop.
-</p>
-
-{{code "progs/error.go" `/func openFile/` `/STOP/`}}
-
-<p>
-You can get a lot done in Go knowing just this about the <code>error</code>
-type, but in this article we'll take a closer look at <code>error</code> and
-discuss some good practices for error handling in Go.
-</p>
-
-<p>
-<b>The error type</b>
-</p>
-
-<p>
-The <code>error</code> type is an interface type. An <code>error</code>
-variable represents any value that can describe itself as a string. Here is the
-interface's declaration:
-</p>
-
-<pre>type error interface {
- Error() string
-}</pre>
-
-<p>
-The <code>error</code> type, as with all built in types, is
-<a href="/doc/go_spec.html#Predeclared_identifiers">predeclared</a> in the
-<a href="/doc/go_spec.html#Blocks">universe block</a>.
-</p>
-
-<p>
-The most commonly-used <code>error</code> implementation is the
-<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
-</p>
-
-{{code "progs/error.go" `/errorString/` `/STOP/`}}
-
-<p>
-You can construct one of these values with the <code>errors.New</code>
-function. It takes a string that it converts to an <code>errors.errorString</code>
-and returns as an <code>error</code> value.
-</p>
-
-{{code "progs/error.go" `/New/` `/STOP/`}}
-
-<p>
-Here's how you might use <code>errors.New</code>:
-</p>
-
-{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
-
-<p>
-A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
-<code>error</code> value (whose concrete representation is an
-<code>errors.errorString</code> value). The caller can access the error string
-("math: square root of...") by calling the <code>error</code>'s
-<code>Error</code> method, or by just printing it:
-</p>
-
-{{code "progs/error.go" `/func printErr/` `/STOP/`}}
-
-<p>
-The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
-by calling its <code>Error() string</code> method.
-</p>
-
-<p>
-It is the error implementation's responsibility to summarize the context.
-The error returned by <code>os.Open</code> formats as "open /etc/passwd:
-permission denied," not just "permission denied." The error returned by our
-<code>Sqrt</code> is missing information about the invalid argument.
-</p>
-
-<p>
-To add that information, a useful function is the <code>fmt</code> package's
-<code>Errorf</code>. It formats a string according to <code>Printf</code>'s
-rules and returns it as an <code>error</code> created by
-<code>errors.New</code>.
-</p>
-
-{{code "progs/error.go" `/fmtError/` `/STOP/`}}
-
-<p>
-In many cases <code>fmt.Errorf</code> is good enough, but since
-<code>error</code> is an interface, you can use arbitrary data structures as
-error values, to allow callers to inspect the details of the error.
-</p>
-
-<p>
-For instance, our hypothetical callers might want to recover the invalid
-argument passed to <code>Sqrt</code>. We can enable that by defining a new
-error implementation instead of using <code>errors.errorString</code>:
-</p>
-
-{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
-
-<p>
-A sophisticated caller can then use a
-<a href="/doc/go_spec.html#Type_assertions">type assertion</a> to check for a
-<code>NegativeSqrtError</code> and handle it specially, while callers that just
-pass the error to <code>fmt.Println</code> or <code>log.Fatal</code> will see
-no change in behavior.
-</p>
-
-<p>
-As another example, the <a href="/pkg/encoding/json/">json</a> package specifies a
-<code>SyntaxError</code> type that the <code>json.Decode</code> function
-returns when it encounters a syntax error parsing a JSON blob.
-</p>
-
-{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
-
-<p>
-The <code>Offset</code> field isn't even shown in the default formatting of the
-error, but callers can use it to add file and line information to their error
-messages:
-</p>
-
-{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
-
-<p>
-(This is a slightly simplified version of some
-<a href="http://camlistore.org/code/?p=camlistore.git;a=blob;f=lib/go/camli/jsonconfig/eval.go#l68">actual code</a>
-from the <a href="http://camlistore.org">Camlistore</a> project.)
-</p>
-
-<p>
-The <code>error</code> interface requires only a <code>Error</code> method;
-specific error implementations might have additional methods. For instance, the
-<a href="/pkg/net/">net</a> package returns errors of type
-<code>error</code>, following the usual convention, but some of the error
-implementations have additional methods defined by the <code>net.Error</code>
-interface:
-</p>
-
-<pre>package net
-
-type Error interface {
- error
- Timeout() bool // Is the error a timeout?
- Temporary() bool // Is the error temporary?
-}</pre>
-
-<p>
-Client code can test for a <code>net.Error</code> with a type assertion and
-then distinguish transient network errors from permanent ones. For instance, a
-web crawler might sleep and retry when it encounters a temporary error and give
-up otherwise.
-</p>
-
-{{code "progs/error.go" `/func netError/` `/STOP/`}}
-
-<p>
-<b>Simplifying repetitive error handling</b>
-</p>
-
-<p>
-In Go, error handling is important. The language's design and conventions
-encourage you to explicitly check for errors where they occur (as distinct from
-the convention in other languages of throwing exceptions and sometimes catching
-them). In some cases this makes Go code verbose, but fortunately there are some
-techniques you can use to minimize repetitive error handling.
-</p>
-
-<p>
-Consider an <a href="http://code.google.com/appengine/docs/go/">App Engine</a>
-application with an HTTP handler that retrieves a record from the datastore and
-formats it with a template.
-</p>
-
-{{code "progs/error2.go" `/func init/` `/STOP/`}}
-
-<p>
-This function handles errors returned by the <code>datastore.Get</code>
-function and <code>viewTemplate</code>'s <code>Execute</code> method. In both
-cases, it presents a simple error message to the user with the HTTP status code
-500 ("Internal Server Error"). This looks like a manageable amount of code, but
-add some more HTTP handlers and you quickly end up with many copies of
-identical error handling code.
-</p>
-
-<p>
-To reduce the repetition we can define our own HTTP <code>appHandler</code>
-type that includes an <code>error</code> return value:
-</p>
-
-{{code "progs/error3.go" `/type appHandler/`}}
-
-<p>
-Then we can change our <code>viewRecord</code> function to return errors:
-</p>
-
-{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
-
-<p>
-This is simpler than the original version, but the <a
-href="/pkg/net/http/">http</a> package doesn't understand functions that return
-<code>error</code>.
-To fix this we can implement the <code>http.Handler</code> interface's
-<code>ServeHTTP</code> method on <code>appHandler</code>:
-</p>
-
-{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
-
-<p>
-The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
-and displays the returned error (if any) to the user. Notice that the method's
-receiver, <code>fn</code>, is a function. (Go can do that!) The method invokes
-the function by calling the receiver in the expression <code>fn(w, r)</code>.
-</p>
-
-<p>
-Now when registering <code>viewRecord</code> with the http package we use the
-<code>Handle</code> function (instead of <code>HandleFunc</code>) as
-<code>appHandler</code> is an <code>http.Handler</code> (not an
-<code>http.HandlerFunc</code>).
-</p>
-
-{{code "progs/error3.go" `/func init/` `/STOP/`}}
-
-<p>
-With this basic error handling infrastructure in place, we can make it more
-user friendly. Rather than just displaying the error string, it would be better
-to give the user a simple error message with an appropriate HTTP status code,
-while logging the full error to the App Engine developer console for debugging
-purposes.
-</p>
-
-<p>
-To do this we create an <code>appError</code> struct containing an
-<code>error</code> and some other fields:
-</p>
-
-{{code "progs/error4.go" `/type appError/` `/STOP/`}}
-
-<p>
-Next we modify the appHandler type to return <code>*appError</code> values:
-</p>
-
-{{code "progs/error4.go" `/type appHandler/`}}
-
-<p>
-(It's usually a mistake to pass back the concrete type of an error rather than
-<code>error</code>, for reasons to be discussed in another article, but
-it's the right thing to do here because <code>ServeHTTP</code> is the only
-place that sees the value and uses its contents.)
-</p>
-
-<p>
-And make <code>appHandler</code>'s <code>ServeHTTP</code> method display the
-<code>appError</code>'s <code>Message</code> to the user with the correct HTTP
-status <code>Code</code> and log the full <code>Error</code> to the developer
-console:
-</p>
-
-{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
-
-<p>
-Finally, we update <code>viewRecord</code> to the new function signature and
-have it return more context when it encounters an error:
-</p>
-
-{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
-
-<p>
-This version of <code>viewRecord</code> is the same length as the original, but
-now each of those lines has specific meaning and we are providing a friendlier
-user experience.
-</p>
-
-<p>
-It doesn't end there; we can further improve the error handling in our
-application. Some ideas:
-</p>
-
-<ul>
-<li>give the error handler a pretty HTML template,
-<li>make debugging easier by writing the stack trace to the HTTP response when
-the user is an administrator,
-<li>write a constructor function for <code>appError</code> that stores the
-stack trace for easier debugging,
-<li>recover from panics inside the <code>appHandler</code>, logging the error
-to the console as "Critical," while telling the user "a serious error
-has occurred." This is a nice touch to avoid exposing the user to inscrutable
-error messages caused by programming errors.
-See the <a href="defer_panic_recover.html">Defer, Panic, and Recover</a>
-article for more details.
-</ul>
-
-<p>
-<b>Conclusion</b>
-</p>
-
-<p>
-Proper error handling is an essential requirement of good software. By
-employing the techniques described in this post you should be able to write
-more reliable and succinct Go code.
-</p>
<!--{
- "Title": "The Laws of Reflection"
+ "Title": "The Laws of Reflection",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml articles/laws_of_reflection.tmpl
--->
-
<p>
Reflection in computing is the
and so on. If we declare
</p>
-<pre><!--{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
--->type MyInt int
-
-var i int
-var j MyInt</pre>
+{{code "/doc/progs/interface.go" `/type MyInt/` `/STOP/`}}
<p>
then <code>i</code> has type <code>int</code> and <code>j</code>
"http://golang.org/pkg/io/">io package</a>:
</p>
-<pre><!--{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
--->// Reader is the interface that wraps the basic Read method.
-type Reader interface {
- Read(p []byte) (n int, err error)
-}
-
-// Writer is the interface that wraps the basic Write method.
-type Writer interface {
- Write(p []byte) (n int, err error)
-}</pre>
+{{code "/doc/progs/interface.go" `/// Reader/` `/STOP/`}}
<p>
Any type that implements a <code>Read</code> (or
<code>Read</code> method:
</p>
-<pre><!--{{code "progs/interface.go" `/func readers/` `/STOP/`}}
---> var r io.Reader
- r = os.Stdin
- r = bufio.NewReader(r)
- r = new(bytes.Buffer)
- // and so on</pre>
+{{code "/doc/progs/interface.go" `/func readers/` `/STOP/`}}
<p>
It's important to be clear that whatever concrete value
of that item. For instance, after
</p>
-<pre><!--{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
---> var r io.Reader
- tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
- if err != nil {
- return nil, err
- }
- r = tty</pre>
+{{code "/doc/progs/interface.go" `/func typeAssertions/` `/STOP/`}}
<p>
<code>r</code> contains, schematically, the (value, type) pair,
like this:
</p>
-<pre><!--{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
---> var w io.Writer
- w = r.(io.Writer)</pre>
+{{code "/doc/progs/interface.go" `/var w io.Writer/` `/STOP/`}}
<p>
The expression in this assignment is a type assertion; what it
Continuing, we can do this:
</p>
-<pre><!--{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
---> var empty interface{}
- empty = w</pre>
+{{code "/doc/progs/interface.go" `/var empty interface{}/` `/STOP/`}}
<p>
and our empty interface value <code>e</code> will again contain
Let's start with <code>TypeOf</code>:
</p>
-<pre><!--{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
--->package main
-
-import (
- "fmt"
- "reflect"
-)
-
-func main() {
- var x float64 = 3.4
- fmt.Println("type:", reflect.TypeOf(x))
-}</pre>
+{{code "/doc/progs/interface2.go" `/package main/` `/STOP main/`}}
<p>
This program prints
the executable code):
</p>
-<pre><!--{{code "progs/interface2.go" `/var x/` `/STOP/`}}
---> var x float64 = 3.4
- fmt.Println("type:", reflect.TypeOf(x))</pre>
+{{code "/doc/progs/interface2.go" `/var x/` `/STOP/`}}
<p>
prints
<code>int64</code> and <code>float64</code>) stored inside:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
---> var x float64 = 3.4
- v := reflect.ValueOf(x)
- fmt.Println("type:", v.Type())
- fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
- fmt.Println("value:", v.Float())</pre>
+{{code "/doc/progs/interface2.go" `/START f1/` `/STOP/`}}
<p>
prints
necessary to convert to the actual type involved:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
---> var x uint8 = 'x'
- v := reflect.ValueOf(x)
- fmt.Println("type:", v.Type()) // uint8.
- fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
- x = uint8(v.Uint()) // v.Uint returns a uint64.</pre>
+{{code "/doc/progs/interface2.go" `/START f2/` `/STOP/`}}
<p>
The second property is that the <code>Kind</code> of a reflection
as in
</p>
-<pre><!--{{code "progs/interface2.go" `/START f3/` `/STOP/`}}
---> type MyInt int
- var x MyInt = 7
- v := reflect.ValueOf(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f3/` `/STOP/`}}
<p>
the <code>Kind</code> of <code>v</code> is still
As a consequence we can say
</p>
-<pre><!--{{code "progs/interface2.go" `/START f3b/` `/STOP/`}}
---> y := v.Interface().(float64) // y will have type float64.
- fmt.Println(y)</pre>
+{{code "/doc/progs/interface2.go" `/START f3b/` `/STOP/`}}
<p>
to print the <code>float64</code> value represented by the
routine:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f3c/` `/STOP/`}}
---> fmt.Println(v.Interface())</pre>
+{{code "/doc/progs/interface2.go" `/START f3c/` `/STOP/`}}
<p>
(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
floating-point format if we want:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
---> fmt.Printf("value is %7.1e\n", v.Interface())</pre>
+{{code "/doc/progs/interface2.go" `/START f3d/` `/STOP/`}}
<p>
and get in this case
Here is some code that does not work, but is worth studying.
</p>
-<pre><!--{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
---> var x float64 = 3.4
- v := reflect.ValueOf(x)
- v.SetFloat(7.1) // Error: will panic.</pre>
+{{code "/doc/progs/interface2.go" `/START f4/` `/STOP/`}}
<p>
If you run this code, it will panic with the cryptic message
settability of a <code>Value</code>; in our case,
</p>
-<pre><!--{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
---> var x float64 = 3.4
- v := reflect.ValueOf(x)
- fmt.Println("settability of v:", v.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f5/` `/STOP/`}}
<p>
prints
item. When we say
</p>
-<pre><!--{{code "progs/interface2.go" `/START f6/` `/STOP/`}}
---> var x float64 = 3.4
- v := reflect.ValueOf(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f6/` `/STOP/`}}
<p>
we pass a <em>copy</em> of <code>x</code> to
statement
</p>
-<pre><!--{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
---> v.SetFloat(7.1)</pre>
+{{code "/doc/progs/interface2.go" `/START f6b/` `/STOP/`}}
<p>
were allowed to succeed, it would not update <code>x</code>, even
<code>p</code>.
</p>
-<pre><!--{{code "progs/interface2.go" `/START f7/` `/STOP/`}}
---> var x float64 = 3.4
- p := reflect.ValueOf(&x) // Note: take the address of x.
- fmt.Println("type of p:", p.Type())
- fmt.Println("settability of p:", p.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f7/` `/STOP/`}}
<p>
The output so far is
<code>v</code>:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f7b/` `/STOP/`}}
---> v := p.Elem()
- fmt.Println("settability of v:", v.CanSet())</pre>
+{{code "/doc/progs/interface2.go" `/START f7b/` `/STOP/`}}
<p>
Now <code>v</code> is a settable reflection object, as the output
<code>x</code>:
</p>
-<pre><!--{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
---> v.SetFloat(7.1)
- fmt.Println(v.Interface())
- fmt.Println(x)</pre>
+{{code "/doc/progs/interface2.go" `/START f7c/` `/STOP/`}}
<p>
The output, as expected, is
objects.
</p>
-<pre><!--{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
---> type T struct {
- A int
- B string
- }
- t := T{23, "skidoo"}
- s := reflect.ValueOf(&t).Elem()
- typeOfT := s.Type()
- for i := 0; i < s.NumField(); i++ {
- f := s.Field(i)
- fmt.Printf("%d: %s %s = %v\n", i,
- typeOfT.Field(i).Name, f.Type(), f.Interface())
- }</pre>
+{{code "/doc/progs/interface2.go" `/START f8/` `/STOP/`}}
<p>
The output of this program is
can modify the fields of the structure.
</p>
-<pre><!--{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
---> s.Field(0).SetInt(77)
- s.Field(1).SetString("Sunset Strip")
- fmt.Println("t is now", t)</pre>
+{{code "/doc/progs/interface2.go" `/START f8b/` `/STOP/`}}
<p>
And here's the result:
and maps, calling methods and functions — but this post is
long enough. We'll cover some of those topics in a later
article.
-</p>
\ No newline at end of file
+</p>
+++ /dev/null
-<!--{
- "Title": "The Laws of Reflection"
-}-->
-{{donotedit}}
-
-<p>
-Reflection in computing is the
-ability of a program to examine its own structure, particularly
-through types; it's a form of metaprogramming. It's also a great
-source of confusion.
-</p>
-
-<p>
-In this article we attempt to clarify things by explaining how
-reflection works in Go. Each language's reflection model is
-different (and many languages don't support it at all), but
-this article is about Go, so for the rest of this article the word
-"reflection" should be taken to mean "reflection in Go".
-</p>
-
-<p><b>Types and interfaces</b></p>
-
-<p>
-Because reflection builds on the type system, let's start with a
-refresher about types in Go.
-</p>
-
-<p>
-Go is statically typed. Every variable has a static type, that is,
-exactly one type known and fixed at compile time: <code>int</code>,
-<code>float32</code>, <code>*MyType</code>, <code>[]byte</code>,
-and so on. If we declare
-</p>
-
-{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
-
-<p>
-then <code>i</code> has type <code>int</code> and <code>j</code>
-has type <code>MyInt</code>. The variables <code>i</code> and
-<code>j</code> have distinct static types and, although they have
-the same underlying type, they cannot be assigned to one another
-without a conversion.
-</p>
-
-<p>
-One important category of type is interface types, which represent
-fixed sets of methods. An interface variable can store any concrete
-(non-interface) value as long as that value implements the
-interface's methods. A well-known pair of examples is
-<code>io.Reader</code> and <code>io.Writer</code>, the types
-<code>Reader</code> and <code>Writer</code> from the <a href=
-"http://golang.org/pkg/io/">io package</a>:
-</p>
-
-{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
-
-<p>
-Any type that implements a <code>Read</code> (or
-<code>Write</code>) method with this signature is said to implement
-<code>io.Reader</code> (or <code>io.Writer</code>). For the
-purposes of this discussion, that means that a variable of type
-<code>io.Reader</code> can hold any value whose type has a
-<code>Read</code> method:
-</p>
-
-{{code "progs/interface.go" `/func readers/` `/STOP/`}}
-
-<p>
-It's important to be clear that whatever concrete value
-<code>r</code> may hold, <code>r</code>'s type is always
-<code>io.Reader</code>: Go is statically typed and the static type
-of <code>r</code> is <code>io.Reader</code>.</p>
-
-<p>
-An extremely important example of an interface type is the empty
-interface:
-</p>
-
-<pre>
-interface{}
-</pre>
-
-<p>
-It represents the empty set of methods and is satisfied by any
-value at all, since any value has zero or more methods.
-</p>
-
-<p>
-Some people say that Go's interfaces are dynamically typed, but
-that is misleading. They are statically typed: a variable of
-interface type always has the same static type, and even though at
-run time the value stored in the interface variable may change
-type, that value will always satisfy the interface.
-</p>
-
-<p>
-We need to be precise about all this because reflection and
-interfaces are closely related.
-</p>
-
-<p><b>The representation of an interface</b></p>
-
-<p>
-Russ Cox has written a <a href=
-"http://research.swtch.com/2009/12/go-data-structures-interfaces.html">
-detailed blog post</a> about the representation of interface values
-in Go. It's not necessary to repeat the full story here, but a
-simplified summary is in order.
-</p>
-
-<p>
-A variable of interface type stores a pair: the concrete value
-assigned to the variable, and that value's type descriptor.
-To be more precise, the value is the underlying concrete data item
-that implements the interface and the type describes the full type
-of that item. For instance, after
-</p>
-
-{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
-
-<p>
-<code>r</code> contains, schematically, the (value, type) pair,
-(<code>tty</code>, <code>*os.File</code>). Notice that the type
-<code>*os.File</code> implements methods other than
-<code>Read</code>; even though the interface value provides access
-only to the <code>Read</code> method, the value inside carries all
-the type information about that value. That's why we can do things
-like this:
-</p>
-
-{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
-
-<p>
-The expression in this assignment is a type assertion; what it
-asserts is that the item inside <code>r</code> also implements
-<code>io.Writer</code>, and so we can assign it to <code>w</code>.
-After the assignment, <code>w</code> will contain the pair
-(<code>tty</code>, <code>*os.File</code>). That's the same pair as
-was held in <code>r</code>. The static type of the interface
-determines what methods may be invoked with an interface variable,
-even though the concrete value inside may have a larger set of
-methods.
-</p>
-
-<p>
-Continuing, we can do this:
-</p>
-
-{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
-
-<p>
-and our empty interface value <code>e</code> will again contain
-that same pair, (<code>tty</code>, <code>*os.File</code>). That's
-handy: an empty interface can hold any value and contains all the
-information we could ever need about that value.
-</p>
-
-<p>
-(We don't need a type assertion here because it's known statically
-that <code>w</code> satisfies the empty interface. In the example
-where we moved a value from a <code>Reader</code> to a
-<code>Writer</code>, we needed to be explicit and use a type
-assertion because <code>Writer</code>'s methods are not a
-subset of <code>Reader</code>'s.)
-</p>
-
-<p>
-One important detail is that the pair inside an interface always
-has the form (value, concrete type) and cannot have the form
-(value, interface type). Interfaces do not hold interface
-values.
-</p>
-
-<p>
-Now we're ready to reflect.
-</p>
-
-<p><b>The first law of reflection</b></p>
-
-<p><b>1. Reflection goes from interface value to reflection object.</b></p>
-
-<p>
-At the basic level, reflection is just a mechanism to examine the
-type and value pair stored inside an interface variable. To get
-started, there are two types we need to know about in
-<a href="http://golang.org/pkg/reflect">package reflect</a>:
-<a href="http://golang.org/pkg/reflect/#Type">Type</a> and
-<a href="http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
-give access to the contents of an interface variable, and two
-simple functions, called <code>reflect.TypeOf</code> and
-<code>reflect.ValueOf</code>, retrieve <code>reflect.Type</code>
-and <code>reflect.Value</code> pieces out of an interface value.
-(Also, from the <code>reflect.Value</code> it's easy to get
-to the <code>reflect.Type</code>, but let's keep the
-<code>Value</code> and <code>Type</code> concepts separate for
-now.)
-</p>
-
-<p>
-Let's start with <code>TypeOf</code>:
-</p>
-
-{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
-
-<p>
-This program prints
-</p>
-
-<pre>
-type: float64
-</pre>
-
-<p>
-You might be wondering where the interface is here, since the
-program looks like it's passing the <code>float64</code>
-variable <code>x</code>, not an interface value, to
-<code>reflect.TypeOf</code>. But it's there; as <a href=
-"http://golang.org/pkg/reflect/#Type.TypeOf">godoc reports</a>, the
-signature of <code>reflect.TypeOf</code> includes an empty
-interface:
-</p>
-
-<pre>
-// TypeOf returns the reflection Type of the value in the interface{}.
-func TypeOf(i interface{}) Type
-</pre>
-
-<p>
-When we call <code>reflect.TypeOf(x)</code>, <code>x</code> is
-first stored in an empty interface, which is then passed as the
-argument; <code>reflect.TypeOf</code> unpacks that empty interface
-to recover the type information.
-</p>
-
-<p>
-The <code>reflect.ValueOf</code> function, of course, recovers the
-value (from here on we'll elide the boilerplate and focus just on
-the executable code):
-</p>
-
-{{code "progs/interface2.go" `/var x/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-value: <float64 Value>
-</pre>
-
-<p>
-Both <code>reflect.Type</code> and <code>reflect.Value</code> have
-lots of methods to let us examine and manipulate them. One
-important example is that <code>Value</code> has a
-<code>Type</code> method that returns the <code>Type</code> of a
-<code>reflect.Value</code>. Another is that both <code>Type</code>
-and <code>Value</code> have a <code>Kind</code> method that returns
-a constant indicating what sort of item is stored:
-<code>Uint</code>, <code>Float64</code>, <code>Slice</code>, and so
-on. Also methods on <code>Value</code> with names like
-<code>Int</code> and <code>Float</code> let us grab values (as
-<code>int64</code> and <code>float64</code>) stored inside:
-</p>
-
-{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-type: float64
-kind is float64: true
-value: 3.4
-</pre>
-
-<p>
-There are also methods like <code>SetInt</code> and
-<code>SetFloat</code> but to use them we need to understand
-settability, the subject of the third law of reflection, discussed
-below.
-</p>
-
-<p>
-The reflection library has a couple of properties worth singling
-out. First, to keep the API simple, the "getter" and "setter"
-methods of <code>Value</code> operate on the largest type that can
-hold the value: <code>int64</code> for all the signed integers, for
-instance. That is, the <code>Int</code> method of
-<code>Value</code> returns an <code>int64</code> and the
-<code>SetInt</code> value takes an <code>int64</code>; it may be
-necessary to convert to the actual type involved:
-</p>
-
-{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
-
-<p>
-The second property is that the <code>Kind</code> of a reflection
-object describes the underlying type, not the static type. If a
-reflection object contains a value of a user-defined integer type,
-as in
-</p>
-
-{{code "progs/interface2.go" `/START f3/` `/STOP/`}}
-
-<p>
-the <code>Kind</code> of <code>v</code> is still
-<code>reflect.Int</code>, even though the static type of
-<code>x</code> is <code>MyInt</code>, not <code>int</code>. In
-other words, the <code>Kind</code> cannot discriminate an int from
-a <code>MyInt</code> even though the <code>Type</code> can.
-</p>
-
-<p><b>The second law of reflection</b></p>
-
-<p><b>2. Reflection goes from reflection object to interface
-value.</b></p>
-
-<p>
-Like physical reflection, reflection in Go generates its own
-inverse.
-</p>
-
-<p>
-Given a <code>reflect.Value</code> we can recover an interface
-value using the <code>Interface</code> method; in effect the method
-packs the type and value information back into an interface
-representation and returns the result:
-</p>
-
-<pre>
-// Interface returns v's value as an interface{}.
-func (v Value) Interface() interface{}
-</pre>
-
-<p>
-As a consequence we can say
-</p>
-
-{{code "progs/interface2.go" `/START f3b/` `/STOP/`}}
-
-<p>
-to print the <code>float64</code> value represented by the
-reflection object <code>v</code>.
-</p>
-
-<p>
-We can do even better, though. The arguments to
-<code>fmt.Println</code>, <code>fmt.Printf</code> and so on are all
-passed as empty interface values, which are then unpacked by the
-<code>fmt</code> package internally just as we have been doing in
-the previous examples. Therefore all it takes to print the contents
-of a <code>reflect.Value</code> correctly is to pass the result of
-the <code>Interface</code> method to the formatted print
-routine:
-</p>
-
-{{code "progs/interface2.go" `/START f3c/` `/STOP/`}}
-
-<p>
-(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
-<code>reflect.Value</code>; we want the concrete value it holds.)
-Since our value is a <code>float64</code>, we can even use a
-floating-point format if we want:
-</p>
-
-{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
-
-<p>
-and get in this case
-</p>
-
-<pre>
-3.4e+00
-</pre>
-
-<p>
-Again, there's no need to type-assert the result of
-<code>v.Interface()</code> to <code>float64</code>; the empty
-interface value has the concrete value's type information inside
-and <code>Printf</code> will recover it.
-</p>
-
-<p>
-In short, the <code>Interface</code> method is the inverse of the
-<code>ValueOf</code> function, except that its result is always of
-static type <code>interface{}</code>.
-</p>
-
-<p>
-Reiterating: Reflection goes from interface values to reflection
-objects and back again.
-</p>
-
-<p><b>The third law of reflection</b></p>
-
-<p><b>3. To modify a reflection object, the value must be settable.</b></p>
-
-<p>
-The third law is the most subtle and confusing, but it's easy
-enough to understand if we start from first principles.
-</p>
-
-<p>
-Here is some code that does not work, but is worth studying.
-</p>
-
-{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
-
-<p>
-If you run this code, it will panic with the cryptic message
-</p>
-
-<pre>
-panic: reflect.Value.SetFloat using unaddressable value
-</pre>
-
-<p>
-The problem is not that the value <code>7.1</code> is not
-addressable; it's that <code>v</code> is not settable. Settability
-is a property of a reflection <code>Value</code>, and not all
-reflection <code>Values</code> have it.
-</p>
-
-<p>
-The <code>CanSet</code> method of <code>Value</code> reports the
-settability of a <code>Value</code>; in our case,
-</p>
-
-{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
-
-<p>
-prints
-</p>
-
-<pre>
-settability of v: false
-</pre>
-
-<p>
-It is an error to call a <code>Set</code> method on an non-settable
-<code>Value</code>. But what is settability?
-</p>
-
-<p>
-Settability is a bit like addressability, but stricter. It's the
-property that a reflection object can modify the actual storage
-that was used to create the reflection object. Settability is
-determined by whether the reflection object holds the original
-item. When we say
-</p>
-
-{{code "progs/interface2.go" `/START f6/` `/STOP/`}}
-
-<p>
-we pass a <em>copy</em> of <code>x</code> to
-<code>reflect.ValueOf</code>, so the interface value created as the
-argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
-<code>x</code>, not <code>x</code> itself. Thus, if the
-statement
-</p>
-
-{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
-
-<p>
-were allowed to succeed, it would not update <code>x</code>, even
-though <code>v</code> looks like it was created from
-<code>x</code>. Instead, it would update the copy of <code>x</code>
-stored inside the reflection value and <code>x</code> itself would
-be unaffected. That would be confusing and useless, so it is
-illegal, and settability is the property used to avoid this
-issue.
-</p>
-
-<p>
-If this seems bizarre, it's not. It's actually a familiar situation
-in unusual garb. Think of passing <code>x</code> to a
-function:
-</p>
-
-<pre>
-f(x)
-</pre>
-
-<p>
-We would not expect <code>f</code> to be able to modify
-<code>x</code> because we passed a copy of <code>x</code>'s value,
-not <code>x</code> itself. If we want <code>f</code> to modify
-<code>x</code> directly we must pass our function the address of
-<code>x</code> (that is, a pointer to <code>x</code>):</p>
-
-<p>
-<code>f(&x)</code>
-</p>
-
-<p>
-This is straightforward and familiar, and reflection works the same
-way. If we want to modify <code>x</code> by reflection, we must
-give the reflection library a pointer to the value we want to
-modify.
-</p>
-
-<p>
-Let's do that. First we initialize <code>x</code> as usual
-and then create a reflection value that points to it, called
-<code>p</code>.
-</p>
-
-{{code "progs/interface2.go" `/START f7/` `/STOP/`}}
-
-<p>
-The output so far is
-</p>
-
-<pre>
-type of p: *float64
-settability of p: false
-</pre>
-
-<p>
-The reflection object <code>p</code> isn't settable, but it's not
-<code>p</code> we want to set, it's (in effect) <code>*p</code>. To
-get to what <code>p</code> points to, we call the <code>Elem</code>
-method of <code>Value</code>, which indirects through the pointer,
-and save the result in a reflection <code>Value</code> called
-<code>v</code>:
-</p>
-
-{{code "progs/interface2.go" `/START f7b/` `/STOP/`}}
-
-<p>
-Now <code>v</code> is a settable reflection object, as the output
-demonstrates,
-</p>
-
-<pre>
-settability of v: true
-</pre>
-
-<p>
-and since it represents <code>x</code>, we are finally able to use
-<code>v.SetFloat</code> to modify the value of
-<code>x</code>:
-</p>
-
-{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
-
-<p>
-The output, as expected, is
-</p>
-
-<pre>
-7.1
-7.1
-</pre>
-
-<p>
-Reflection can be hard to understand but it's doing exactly what
-the language does, albeit through reflection <code>Types</code> and
-<code>Values</code> that can disguise what's going on. Just keep in
-mind that reflection Values need the address of something in order
-to modify what they represent.
-</p>
-
-<p><b>Structs</b></p>
-
-<p>
-In our previous example <code>v</code> wasn't a pointer itself, it
-was just derived from one. A common way for this situation to arise
-is when using reflection to modify the fields of a structure. As
-long as we have the address of the structure, we can modify its
-fields.
-</p>
-
-<p>
-Here's a simple example that analyzes a struct value,
-<code>t</code>. We create the reflection object with the address of
-the struct because we'll want to modify it later. Then we set
-<code>typeOfT</code> to its type and iterate over the fields using
-straightforward method calls (see
-<a href="http://golang.org/pkg/reflect/">package reflect</a> for details).
-Note that we extract the names of the fields from the struct type,
-but the fields themselves are regular <code>reflect.Value</code>
-objects.
-</p>
-
-{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
-
-<p>
-The output of this program is
-</p>
-
-<pre>
-0: A int = 23
-1: B string = skidoo
-</pre>
-
-<p>
-There's one more point about settability introduced in
-passing here: the field names of <code>T</code> are upper case
-(exported) because only exported fields of a struct are
-settable.
-</p>
-
-<p>
-Because <code>s</code> contains a settable reflection object, we
-can modify the fields of the structure.
-</p>
-
-{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
-
-<p>
-And here's the result:
-</p>
-
-<pre>
-t is now {77 Sunset Strip}
-</pre>
-
-<p>
-If we modified the program so that <code>s</code> was created from
-<code>t</code>, not <code>&t</code>, the calls to
-<code>SetInt</code> and <code>SetString</code> would fail as the
-fields of <code>t</code> would not be settable.
-</p>
-
-<p><b>Conclusion</b></p>
-
-<p>
-Here again are the laws of reflection:
-</p>
-
-<ol>
-<li>Reflection goes from interface value to reflection
-object.</li>
-<li>Reflection goes from reflection object to interface
-value.</li>
-<li>To modify a reflection object, the value must be settable.</li>
-</ol>
-
-<p>
-Once you understand these laws reflection in Go becomes much easier
-to use, although it remains subtle. It's a powerful tool that
-should be used with care and avoided unless strictly
-necessary.
-</p>
-
-<p>
-There's plenty more to reflection that we haven't covered —
-sending and receiving on channels, allocating memory, using slices
-and maps, calling methods and functions — but this post is
-long enough. We'll cover some of those topics in a later
-article.
-</p>
\ No newline at end of file
<!--{
- "Title": "Slices: usage and internals"
+ "Title": "Slices: usage and internals",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml articles/slices_usage_and_internals.tmpl
--->
-
<p>
Go's slice type provides a convenient and efficient means of working with
returns the updated slice value:
</p>
-<pre><!--{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
--->func AppendByte(slice []byte, data ...byte) []byte {
- m := len(slice)
- n := m + len(data)
- if n > cap(slice) { // if necessary, reallocate
- // allocate double what's needed, for future growth.
- newSlice := make([]byte, (n+1)*2)
- copy(newSlice, slice)
- slice = newSlice
- }
- slice = slice[0:n]
- copy(slice[m:n], data)
- return slice
-}</pre>
+{{code "/doc/progs/slices.go" `/AppendByte/` `/STOP/`}}
<p>
One could use <code>AppendByte</code> like this:
slice, you can declare a slice variable and then append to it in a loop:
</p>
-<pre><!--{{code "progs/slices.go" `/Filter/` `/STOP/`}}
--->// Filter returns a new slice holding only
-// the elements of s that satisfy f()
-func Filter(s []int, fn func(int) bool) []int {
- var p []int // == nil
- for _, i := range s {
- if fn(i) {
- p = append(p, i)
- }
- }
- return p
-}</pre>
+{{code "/doc/progs/slices.go" `/Filter/` `/STOP/`}}
<p>
<b>A possible "gotcha"</b>
as a new slice.
</p>
-<pre><!--{{code "progs/slices.go" `/digit/` `/STOP/`}}
--->var digitRegexp = regexp.MustCompile("[0-9]+")
-
-func FindDigits(filename string) []byte {
- b, _ := ioutil.ReadFile(filename)
- return digitRegexp.Find(b)
-}</pre>
+{{code "/doc/progs/slices.go" `/digit/` `/STOP/`}}
<p>
This code behaves as advertised, but the returned <code>[]byte</code> points
returning it:
</p>
-<pre><!--{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
--->func CopyDigits(filename string) []byte {
- b, _ := ioutil.ReadFile(filename)
- b = digitRegexp.Find(b)
- c := make([]byte, len(b))
- copy(c, b)
- return c
-}</pre>
+{{code "/doc/progs/slices.go" `/CopyDigits/` `/STOP/`}}
<p>
A more concise version of this function could be constructed by using
+++ /dev/null
-<!--{
- "Title": "Slices: usage and internals"
-}-->
-{{donotedit}}
-
-<p>
-Go's slice type provides a convenient and efficient means of working with
-sequences of typed data. Slices are analogous to arrays in other languages, but
-have some unusual properties. This article will look at what slices are and how
-they are used.
-</p>
-
-<p>
-<b>Arrays</b>
-</p>
-
-<p>
-The slice type is an abstraction built on top of Go's array type, and so to
-understand slices we must first understand arrays.
-</p>
-
-<p>
-An array type definition specifies a length and an element type. For example,
-the type <code>[4]int</code> represents an array of four integers. An array's
-size is fixed; its length is part of its type (<code>[4]int</code> and
-<code>[5]int</code> are distinct, incompatible types). Arrays can be indexed in
-the usual way, so the expression <code>s[n]</code> accesses the <i>n</i>th
-element:
-</p>
-
-<pre>
-var a [4]int
-a[0] = 1
-i := a[0]
-// i == 1
-</pre>
-
-<p>
-Arrays do not need to be initialized explicitly; the zero value of an array is
-a ready-to-use array whose elements are themselves zeroed:
-</p>
-
-<pre>
-// a[2] == 0, the zero value of the int type
-</pre>
-
-<p>
-The in-memory representation of <code>[4]int</code> is just four integer values laid out sequentially:
-</p>
-
-<p>
-<img src="slice-array.png">
-</p>
-
-<p>
-Go's arrays are values. An array variable denotes the entire array; it is not a
-pointer to the first array element (as would be the case in C). This means
-that when you assign or pass around an array value you will make a copy of its
-contents. (To avoid the copy you could pass a <i>pointer</i> to the array, but
-then that's a pointer to an array, not an array.) One way to think about arrays
-is as a sort of struct but with indexed rather than named fields: a fixed-size
-composite value.
-</p>
-
-<p>
-An array literal can be specified like so:
-</p>
-
-<pre>
-b := [2]string{"Penn", "Teller"}
-</pre>
-
-<p>
-Or, you can have the compiler count the array elements for you:
-</p>
-
-<pre>
-b := [...]string{"Penn", "Teller"}
-</pre>
-
-<p>
-In both cases, the type of <code>b</code> is <code>[2]string</code>.
-</p>
-
-<p>
-<b>Slices</b>
-</p>
-
-<p>
-Arrays have their place, but they're a bit inflexible, so you don't see them
-too often in Go code. Slices, though, are everywhere. They build on arrays to
-provide great power and convenience.
-</p>
-
-<p>
-The type specification for a slice is <code>[]T</code>, where <code>T</code> is
-the type of the elements of the slice. Unlike an array type, a slice type has
-no specified length.
-</p>
-
-<p>
-A slice literal is declared just like an array literal, except you leave out
-the element count:
-</p>
-
-<pre>
-letters := []string{"a", "b", "c", "d"}
-</pre>
-
-<p>
-A slice can be created with the built-in function called <code>make</code>,
-which has the signature,
-</p>
-
-<pre>
-func make([]T, len, cap) []T
-</pre>
-
-<p>
-where T stands for the element type of the slice to be created. The
-<code>make</code> function takes a type, a length, and an optional capacity.
-When called, <code>make</code> allocates an array and returns a slice that
-refers to that array.
-</p>
-
-<pre>
-var s []byte
-s = make([]byte, 5, 5)
-// s == []byte{0, 0, 0, 0, 0}
-</pre>
-
-<p>
-When the capacity argument is omitted, it defaults to the specified length.
-Here's a more succinct version of the same code:
-</p>
-
-<pre>
-s := make([]byte, 5)
-</pre>
-
-<p>
-The length and capacity of a slice can be inspected using the built-in
-<code>len</code> and <code>cap</code> functions.
-</p>
-
-<pre>
-len(s) == 5
-cap(s) == 5
-</pre>
-
-<p>
-The next two sections discuss the relationship between length and capacity.
-</p>
-
-<p>
-The zero value of a slice is <code>nil</code>. The <code>len</code> and
-<code>cap</code> functions will both return 0 for a nil slice.
-</p>
-
-<p>
-A slice can also be formed by "slicing" an existing slice or array. Slicing is
-done by specifying a half-open range with two indices separated by a colon. For
-example, the expression <code>b[1:4]</code> creates a slice including elements
-1 through 3 of <code>b</code> (the indices of the resulting slice will be 0
-through 2).
-</p>
-
-<pre>
-b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
-// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
-</pre>
-
-<p>
-The start and end indices of a slice expression are optional; they default to zero and the slice's length respectively:
-</p>
-
-<pre>
-// b[:2] == []byte{'g', 'o'}
-// b[2:] == []byte{'l', 'a', 'n', 'g'}
-// b[:] == b
-</pre>
-
-<p>
-This is also the syntax to create a slice given an array:
-</p>
-
-<pre>
-x := [3]string{"ะะฐะนะบะฐ", "ะะตะปะบะฐ", "ะกััะตะปะบะฐ"}
-s := x[:] // a slice referencing the storage of x
-</pre>
-
-<p>
-<b>Slice internals</b>
-</p>
-
-<p>
-A slice is a descriptor of an array segment. It consists of a pointer to the
-array, the length of the segment, and its capacity (the maximum length of the
-segment).
-</p>
-
-<p>
-<img src="slice-struct.png">
-</p>
-
-<p>
-Our variable <code>s</code>, created earlier by <code>make([]byte, 5)</code>,
-is structured like this:
-</p>
-
-<p>
-<img src="slice-1.png">
-</p>
-
-<p>
-The length is the number of elements referred to by the slice. The capacity is
-the number of elements in the underlying array (beginning at the element
-referred to by the slice pointer). The distinction between length and capacity
-will be made clear as we walk through the next few examples.
-</p>
-
-<p>
-As we slice <code>s</code>, observe the changes in the slice data structure and
-their relation to the underlying array:
-</p>
-
-<pre>
-s = s[2:4]
-</pre>
-
-<p>
-<img src="slice-2.png">
-</p>
-
-<p>
-Slicing does not copy the slice's data. It creates a new slice value that
-points to the original array. This makes slice operations as efficient as
-manipulating array indices. Therefore, modifying the <i>elements</i> (not the
-slice itself) of a re-slice modifies the elements of the original slice:
-</p>
-
-<pre>
-d := []byte{'r', 'o', 'a', 'd'}
-e := d[2:]
-// e == []byte{'a', 'd'}
-e[1] == 'm'
-// e == []byte{'a', 'm'}
-// d == []byte{'r', 'o', 'a', 'm'}
-</pre>
-
-<p>
-Earlier we sliced <code>s</code> to a length shorter than its capacity. We can
-grow s to its capacity by slicing it again:
-</p>
-
-<pre>
-s = s[:cap(s)]
-</pre>
-
-<p>
-<img src="slice-3.png">
-</p>
-
-<p>
-A slice cannot be grown beyond its capacity. Attempting to do so will cause a
-runtime panic, just as when indexing outside the bounds of a slice or array.
-Similarly, slices cannot be re-sliced below zero to access earlier elements in
-the array.
-</p>
-
-<p>
-<b>Growing slices (the copy and append functions)</b>
-</p>
-
-<p>
-To increase the capacity of a slice one must create a new, larger slice and
-copy the contents of the original slice into it. This technique is how dynamic
-array implementations from other languages work behind the scenes. The next
-example doubles the capacity of <code>s</code> by making a new slice,
-<code>t</code>, copying the contents of <code>s</code> into <code>t</code>, and
-then assigning the slice value <code>t</code> to <code>s</code>:
-</p>
-
-<pre>
-t := make([]byte, len(s), (cap(s)+1)*2) // +1 in case cap(s) == 0
-for i := range s {
- t[i] = s[i]
-}
-s = t
-</pre>
-
-<p>
-The looping piece of this common operation is made easier by the built-in copy
-function. As the name suggests, copy copies data from a source slice to a
-destination slice. It returns the number of elements copied.
-</p>
-
-<pre>
-func copy(dst, src []T) int
-</pre>
-
-<p>
-The <code>copy</code> function supports copying between slices of different
-lengths (it will copy only up to the smaller number of elements). In addition,
-<code>copy</code> can handle source and destination slices that share the same
-underlying array, handling overlapping slices correctly.
-</p>
-
-<p>
-Using <code>copy</code>, we can simplify the code snippet above:
-</p>
-
-<pre>
-t := make([]byte, len(s), (cap(s)+1)*2)
-copy(t, s)
-s = t
-</pre>
-
-<p>
-A common operation is to append data to the end of a slice. This function
-appends byte elements to a slice of bytes, growing the slice if necessary, and
-returns the updated slice value:
-</p>
-
-{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
-
-<p>
-One could use <code>AppendByte</code> like this:
-</p>
-
-<pre>
-p := []byte{2, 3, 5}
-p = AppendByte(p, 7, 11, 13)
-// p == []byte{2, 3, 5, 7, 11, 13}
-</pre>
-
-<p>
-Functions like <code>AppendByte</code> are useful because they offer complete
-control over the way the slice is grown. Depending on the characteristics of
-the program, it may be desirable to allocate in smaller or larger chunks, or to
-put a ceiling on the size of a reallocation.
-</p>
-
-<p>
-But most programs don't need complete control, so Go provides a built-in
-<code>append</code> function that's good for most purposes; it has the
-signature
-</p>
-
-<pre>
-func append(s []T, x ...T) []T
-</pre>
-
-<p>
-The <code>append</code> function appends the elements <code>x</code> to the end
-of the slice <code>s</code>, and grows the slice if a greater capacity is
-needed.
-</p>
-
-<pre>
-a := make([]int, 1)
-// a == []int{0}
-a = append(a, 1, 2, 3)
-// a == []int{0, 1, 2, 3}
-</pre>
-
-<p>
-To append one slice to another, use <code>...</code> to expand the second
-argument to a list of arguments.
-</p>
-
-<pre>
-a := []string{"John", "Paul"}
-b := []string{"George", "Ringo", "Pete"}
-a = append(a, b...) // equivalent to "append(a, b[0], b[1], b[2])"
-// a == []string{"John", "Paul", "George", "Ringo", "Pete"}
-</pre>
-
-<p>
-Since the zero value of a slice (<code>nil</code>) acts like a zero-length
-slice, you can declare a slice variable and then append to it in a loop:
-</p>
-
-{{code "progs/slices.go" `/Filter/` `/STOP/`}}
-
-<p>
-<b>A possible "gotcha"</b>
-</p>
-
-<p>
-As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying
-array. The full array will be kept in memory until it is no longer referenced.
-Occasionally this can cause the program to hold all the data in memory when
-only a small piece of it is needed.
-</p>
-
-<p>
-For example, this <code>FindDigits</code> function loads a file into memory and
-searches it for the first group of consecutive numeric digits, returning them
-as a new slice.
-</p>
-
-{{code "progs/slices.go" `/digit/` `/STOP/`}}
-
-<p>
-This code behaves as advertised, but the returned <code>[]byte</code> points
-into an array containing the entire file. Since the slice references the
-original array, as long as the slice is kept around the garbage collector can't
-release the array; the few useful bytes of the file keep the entire contents in
-memory.
-</p>
-
-<p>
-To fix this problem one can copy the interesting data to a new slice before
-returning it:
-</p>
-
-{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
-
-<p>
-A more concise version of this function could be constructed by using
-<code>append</code>. This is left as an exercise for the reader.
-</p>
-
-<p>
-<b>Further Reading</b>
-</p>
-
-<p>
-<a href="/doc/effective_go.html">Effective Go</a> contains an
-in-depth treatment of <a href="/doc/effective_go.html#slices">slices</a>
-and <a href="/doc/effective_go.html#arrays">arrays</a>,
-and the Go <a href="/doc/go_spec.html">language specification</a>
-defines <a href="/doc/go_spec.html#Slice_types">slices</a> and their
-<a href="/doc/go_spec.html#Length_and_capacity">associated</a>
-<a href="/doc/go_spec.html#Making_slices_maps_and_channels">helper</a>
-<a href="/doc/go_spec.html#Appending_and_copying_slices">functions</a>.
-</p>
<!--{
- "Title": "Effective Go"
+ "Title": "Effective Go",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml effective_go.tmpl
--->
-
<h2 id="introduction">Introduction</h2>
expressions can be implicitly repeated, it is easy to build intricate
sets of values.
</p>
-<pre><!--{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
--->type ByteSize float64
-
-const (
- _ = iota // ignore first value by assigning to blank identifier
- KB ByteSize = 1 << (10 * iota)
- MB
- GB
- TB
- PB
- EB
- ZB
- YB
-)</pre>
+{{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.
</p>
-<pre><!--{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
--->func (b ByteSize) String() string {
- switch {
- case b >= YB:
- return fmt.Sprintf("%.2fYB", float64(b/YB))
- case b >= ZB:
- return fmt.Sprintf("%.2fZB", float64(b/ZB))
- case b >= EB:
- return fmt.Sprintf("%.2fEB", float64(b/EB))
- case b >= PB:
- return fmt.Sprintf("%.2fPB", float64(b/PB))
- case b >= TB:
- return fmt.Sprintf("%.2fTB", float64(b/TB))
- case b >= GB:
- return fmt.Sprintf("%.2fGB", float64(b/GB))
- case b >= MB:
- return fmt.Sprintf("%.2fMB", float64(b/MB))
- case b >= KB:
- return fmt.Sprintf("%.2fKB", float64(b/KB))
- }
- return fmt.Sprintf("%.2fB", float64(b))
-}</pre>
+{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
<p>
(The <code>float64</code> conversions prevent <code>Sprintf</code>
from recurring back through the <code>String</code> method for
and it could also have a custom formatter.
In this contrived example <code>Sequence</code> satisfies both.
</p>
-<pre><!--{{code "progs/eff_sequence.go" `/^type/` "$"}}
--->type Sequence []int
-
-// Methods required by sort.Interface.
-func (s Sequence) Len() int {
- return len(s)
-}
-func (s Sequence) Less(i, j int) bool {
- return s[i] < s[j]
-}
-func (s Sequence) Swap(i, j int) {
- s[i], s[j] = s[j], s[i]
-}
-
-// Method for printing - sorts the elements before printing.
-func (s Sequence) String() string {
- sort.Sort(s)
- str := "["
- for i, elem := range s {
- if i > 0 {
- str += " "
- }
- str += fmt.Sprint(elem)
- }
- return str + "]"
-}</pre>
+{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}
<h3 id="conversions">Conversions</h3>
Here's the complete program.
An explanation follows.
</p>
-<pre><!--{{code "progs/eff_qr.go"}}
--->package main
-
-import (
- "flag"
- "log"
- "net/http"
- "text/template"
-)
-
-var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18
-
-var templ = template.Must(template.New("qr").Parse(templateStr))
-
-func main() {
- flag.Parse()
- http.Handle("/", http.HandlerFunc(QR))
- err := http.ListenAndServe(*addr, nil)
- if err != nil {
- log.Fatal("ListenAndServe:", err)
- }
-}
-
-func QR(w http.ResponseWriter, req *http.Request) {
- templ.Execute(w, req.FormValue("s"))
-}
-
-const templateStr = `
-<html>
-<head>
-<title>QR Link Generator</title>
-</head>
-<body>
-{{if .}}
-<img src="http://chart.apis.google.com/chart?chs=300x300&cht=qr&choe=UTF-8&chl={{urlquery .}}" />
-<br>
-{{html .}}
-<br>
-<br>
-{{end}}
-<form action="/" name=f method="GET"><input maxLength=1024 size=70
-name=s value="" title="Text to QR Encode"><input type=submit
-value="Show QR" name=qr>
-</form>
-</body>
-</html>
-`</pre>
+{{code "/doc/progs/eff_qr.go"}}
<p>
The pieces up to <code>main</code> should be easy to follow.
The one flag sets a default HTTP port for our server. The template
form value.
Within the template text (<code>templateStr</code>),
double-brace-delimited pieces denote template actions.
-The piece from <code>{{if .}}</code>
-to <code>{{end}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
+The piece from <code>{{html "{{if .}}"}}</code>
+to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
is non-empty.
That is, when the string is empty, this piece of the template is suppressed.
</p>
<p>
-The snippet <code>{{urlquery .}}</code> says to process the data with the function
+The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
<code>urlquery</code>, which sanitizes the query string
for safe display on the web page.
</p>
+++ /dev/null
-<!--{
- "Title": "Effective Go"
-}-->
-{{donotedit}}
-
-<h2 id="introduction">Introduction</h2>
-
-<p>
-Go is a new language. Although it borrows ideas from
-existing languages,
-it has unusual properties that make effective Go programs
-different in character from programs written in its relatives.
-A straightforward translation of a C++ or Java program into Go
-is unlikely to produce a satisfactory result—Java programs
-are written in Java, not Go.
-On the other hand, thinking about the problem from a Go
-perspective could produce a successful but quite different
-program.
-In other words,
-to write Go well, it's important to understand its properties
-and idioms.
-It's also important to know the established conventions for
-programming in Go, such as naming, formatting, program
-construction, and so on, so that programs you write
-will be easy for other Go programmers to understand.
-</p>
-
-<p>
-This document gives tips for writing clear, idiomatic Go code.
-It augments the <a href="/ref/spec">language specification</a>,
-the <a href="http://tour.golang.org/">Tour of Go</a>,
-and <a href="/doc/code.html">How to Write Go Code</a>,
-all of which you
-should read first.
-</p>
-
-<h3 id="examples">Examples</h3>
-
-<p>
-The <a href="/src/pkg/">Go package sources</a>
-are intended to serve not
-only as the core library but also as examples of how to
-use the language.
-If you have a question about how to approach a problem or how something
-might be implemented, they can provide answers, ideas and
-background.
-</p>
-
-
-<h2 id="formatting">Formatting</h2>
-
-<p>
-Formatting issues are the most contentious
-but the least consequential.
-People can adapt to different formatting styles
-but it's better if they don't have to, and
-less time is devoted to the topic
-if everyone adheres to the same style.
-The problem is how to approach this Utopia without a long
-prescriptive style guide.
-</p>
-
-<p>
-With Go we take an unusual
-approach and let the machine
-take care of most formatting issues.
-The <code>gofmt</code> program
-(also available as <code>go fmt</code>, which
-operates at the package level rather than source file level)
-reads a Go program
-and emits the source in a standard style of indentation
-and vertical alignment, retaining and if necessary
-reformatting comments.
-If you want to know how to handle some new layout
-situation, run <code>gofmt</code>; if the answer doesn't
-seem right, rearrange your program (or file a bug about <code>gofmt</code>),
-don't work around it.
-</p>
-
-<p>
-As an example, there's no need to spend time lining up
-the comments on the fields of a structure.
-<code>Gofmt</code> will do that for you. Given the
-declaration
-</p>
-
-<pre>
-type T struct {
- name string // name of the object
- value int // its value
-}
-</pre>
-
-<p>
-<code>gofmt</code> will line up the columns:
-</p>
-
-<pre>
-type T struct {
- name string // name of the object
- value int // its value
-}
-</pre>
-
-<p>
-All Go code in the standard packages has been formatted with <code>gofmt</code>.
-</p>
-
-
-<p>
-Some formatting details remain. Very briefly,
-</p>
-
-<dl>
- <dt>Indentation</dt>
- <dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
- Use spaces only if you must.
- </dd>
- <dt>Line length</dt>
- <dd>
- Go has no line length limit. Don't worry about overflowing a punched card.
- If a line feels too long, wrap it and indent with an extra tab.
- </dd>
- <dt>Parentheses</dt>
- <dd>
- Go needs fewer parentheses: control structures (<code>if</code>,
- <code>for</code>, <code>switch</code>) do not have parentheses in
- their syntax.
- Also, the operator precedence hierarchy is shorter and clearer, so
-<pre>
-x<<8 + y<<16
-</pre>
- means what the spacing implies.
- </dd>
-</dl>
-
-<h2 id="commentary">Commentary</h2>
-
-<p>
-Go provides C-style <code>/* */</code> block comments
-and C++-style <code>//</code> line comments.
-Line comments are the norm;
-block comments appear mostly as package comments and
-are also useful to disable large swaths of code.
-</p>
-
-<p>
-The programโand web serverโ<code>godoc</code> processes
-Go source files to extract documentation about the contents of the
-package.
-Comments that appear before top-level declarations, with no intervening newlines,
-are extracted along with the declaration to serve as explanatory text for the item.
-The nature and style of these comments determines the
-quality of the documentation <code>godoc</code> produces.
-</p>
-
-<p>
-Every package should have a <i>package comment</i>, a block
-comment preceding the package clause.
-For multi-file packages, the package comment only needs to be
-present in one file, and any one will do.
-The package comment should introduce the package and
-provide information relevant to the package as a whole.
-It will appear first on the <code>godoc</code> page and
-should set up the detailed documentation that follows.
-</p>
-
-<pre>
-/*
- Package regexp implements a simple library for
- regular expressions.
-
- The syntax of the regular expressions accepted is:
-
- regexp:
- concatenation { '|' concatenation }
- concatenation:
- { closure }
- closure:
- term [ '*' | '+' | '?' ]
- term:
- '^'
- '$'
- '.'
- character
- '[' [ '^' ] character-ranges ']'
- '(' regexp ')'
-*/
-package regexp
-</pre>
-
-<p>
-If the package is simple, the package comment can be brief.
-</p>
-
-<pre>
-// Package path implements utility routines for
-// manipulating slash-separated filename paths.
-</pre>
-
-<p>
-Comments do not need extra formatting such as banners of stars.
-The generated output may not even be presented in a fixed-width font, so don't depend
-on spacing for alignment—<code>godoc</code>, like <code>gofmt</code>,
-takes care of that.
-The comments are uninterpreted plain text, so HTML and other
-annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
-not be used.
-Depending on the context, <code>godoc</code> might not even
-reformat comments, so make sure they look good straight up:
-use correct spelling, punctuation, and sentence structure,
-fold long lines, and so on.
-</p>
-
-<p>
-Inside a package, any comment immediately preceding a top-level declaration
-serves as a <i>doc comment</i> for that declaration.
-Every exported (capitalized) name in a program should
-have a doc comment.
-</p>
-
-<p>
-Doc comments work best as complete sentences, which allow
-a wide variety of automated presentations.
-The first sentence should be a one-sentence summary that
-starts with the name being declared.
-</p>
-
-<pre>
-// Compile parses a regular expression and returns, if successful, a Regexp
-// object that can be used to match against text.
-func Compile(str string) (regexp *Regexp, err error) {
-</pre>
-
-<p>
-Go's declaration syntax allows grouping of declarations.
-A single doc comment can introduce a group of related constants or variables.
-Since the whole declaration is presented, such a comment can often be perfunctory.
-</p>
-
-<pre>
-// Error codes returned by failures to parse an expression.
-var (
- ErrInternal = errors.New("regexp: internal error")
- ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
- ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
- ...
-)
-</pre>
-
-<p>
-Even for private names, grouping can also indicate relationships between items,
-such as the fact that a set of variables is protected by a mutex.
-</p>
-
-<pre>
-var (
- countLock sync.Mutex
- inputCount uint32
- outputCount uint32
- errorCount uint32
-)
-</pre>
-
-<h2 id="names">Names</h2>
-
-<p>
-Names are as important in Go as in any other language.
-In some cases they even have semantic effect: for instance,
-the visibility of a name outside a package is determined by whether its
-first character is upper case.
-It's therefore worth spending a little time talking about naming conventions
-in Go programs.
-</p>
-
-
-<h3 id="package-names">Package names</h3>
-
-<p>
-When a package is imported, the package name becomes an accessor for the
-contents. After
-</p>
-
-<pre>
-import "bytes"
-</pre>
-
-<p>
-the importing package can talk about <code>bytes.Buffer</code>. It's
-helpful if everyone using the package can use the same name to refer to
-its contents, which implies that the package name should be good:
-short, concise, evocative. By convention, packages are given
-lower case, single-word names; there should be no need for underscores
-or mixedCaps.
-Err on the side of brevity, since everyone using your
-package will be typing that name.
-And don't worry about collisions <i>a priori</i>.
-The package name is only the default name for imports; it need not be unique
-across all source code, and in the rare case of a collision the
-importing package can choose a different name to use locally.
-In any case, confusion is rare because the file name in the import
-determines just which package is being used.
-</p>
-
-<p>
-Another convention is that the package name is the base name of
-its source directory;
-the package in <code>src/pkg/encoding/base64</code>
-is imported as <code>"encoding/base64"</code> but has name <code>base64</code>,
-not <code>encoding_base64</code> and not <code>encodingBase64</code>.
-</p>
-
-<p>
-The importer of a package will use the name to refer to its contents
-(the <code>import .</code> notation is intended mostly for tests and other
-unusual situations and should be avoided unless necessary),
-so exported names in the package can use that fact
-to avoid stutter.
-For instance, the buffered reader type in the <code>bufio</code> package is called <code>Reader</code>,
-not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
-which is a clear, concise name.
-Moreover,
-because imported entities are always addressed with their package name, <code>bufio.Reader</code>
-does not conflict with <code>io.Reader</code>.
-Similarly, the function to make new instances of <code>ring.Ring</code>—which
-is the definition of a <em>constructor</em> in Go—would
-normally be called <code>NewRing</code>, but since
-<code>Ring</code> is the only type exported by the package, and since the
-package is called <code>ring</code>, it's called just <code>New</code>,
-which clients of the package see as <code>ring.New</code>.
-Use the package structure to help you choose good names.
-</p>
-
-<p>
-Another short example is <code>once.Do</code>;
-<code>once.Do(setup)</code> reads well and would not be improved by
-writing <code>once.DoOrWaitUntilDone(setup)</code>.
-Long names don't automatically make things more readable.
-If the name represents something intricate or subtle, it's usually better
-to write a helpful doc comment than to attempt to put all the information
-into the name.
-</p>
-
-<h3 id="Getters">Getters</h3>
-
-<p>
-Go doesn't provide automatic support for getters and setters.
-There's nothing wrong with providing getters and setters yourself,
-and it's often appropriate to do so, but it's neither idiomatic nor necessary
-to put <code>Get</code> into the getter's name. If you have a field called
-<code>owner</code> (lower case, unexported), the getter method should be
-called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>.
-The use of upper-case names for export provides the hook to discriminate
-the field from the method.
-A setter function, if needed, will likely be called <code>SetOwner</code>.
-Both names read well in practice:
-</p>
-<pre>
-owner := obj.Owner()
-if owner != user {
- obj.SetOwner(user)
-}
-</pre>
-
-<h3 id="interface-names">Interface names</h3>
-
-<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.
-</p>
-
-<p>
-There are a number of such names and it's productive to honor them and the function
-names they capture.
-<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
-<code>String</code> and so on have
-canonical signatures and meanings. To avoid confusion,
-don't give your method one of those names unless it
-has the same signature and meaning.
-Conversely, if your type implements a method with the
-same meaning as a method on a well-known type,
-give it the same name and signature;
-call your string-converter method <code>String</code> not <code>ToString</code>.
-</p>
-
-<h3 id="mixed-caps">MixedCaps</h3>
-
-<p>
-Finally, the convention in Go is to use <code>MixedCaps</code>
-or <code>mixedCaps</code> rather than underscores to write
-multiword names.
-</p>
-
-<h2 id="semicolons">Semicolons</h2>
-
-<p>
-Like C, Go's formal grammar uses semicolons to terminate statements;
-unlike C, those semicolons do not appear in the source.
-Instead the lexer uses a simple rule to insert semicolons automatically
-as it scans, so the input text is mostly free of them.
-</p>
-
-<p>
-The rule is this. If the last token before a newline is an identifier
-(which includes words like <code>int</code> and <code>float64</code>),
-a basic literal such as a number or string constant, or one of the
-tokens
-</p>
-<pre>
-break continue fallthrough return ++ -- ) }
-</pre>
-<p>
-the lexer always inserts a semicolon after the token.
-This could be summarized as, “if the newline comes
-after a token that could end a statement, insert a semicolon”.
-</p>
-
-<p>
-A semicolon can also be omitted immediately before a closing brace,
-so a statement such as
-</p>
-<pre>
- go func() { for { dst <- <-src } }()
-</pre>
-<p>
-needs no semicolons.
-Idiomatic Go programs have semicolons only in places such as
-<code>for</code> loop clauses, to separate the initializer, condition, and
-continuation elements. They are also necessary to separate multiple
-statements on a line, should you write code that way.
-</p>
-
-<p>
-One caveat. You should never put the opening brace of a
-control structure (<code>if</code>, <code>for</code>, <code>switch</code>,
-or <code>select</code>) on the next line. If you do, a semicolon
-will be inserted before the brace, which could cause unwanted
-effects. Write them like this
-</p>
-
-<pre>
-if i < f() {
- g()
-}
-</pre>
-<p>
-not like this
-</p>
-<pre>
-if i < f() // wrong!
-{ // wrong!
- g()
-}
-</pre>
-
-
-<h2 id="control-structures">Control structures</h2>
-
-<p>
-The control structures of Go are related to those of C but differ
-in important ways.
-There is no <code>do</code> or <code>while</code> loop, only a
-slightly generalized
-<code>for</code>;
-<code>switch</code> is more flexible;
-<code>if</code> and <code>switch</code> accept an optional
-initialization statement like that of <code>for</code>;
-and there are new control structures including a type switch and a
-multiway communications multiplexer, <code>select</code>.
-The syntax is also slightly different:
-there are no parentheses
-and the bodies must always be brace-delimited.
-</p>
-
-<h3 id="if">If</h3>
-
-<p>
-In Go a simple <code>if</code> looks like this:
-</p>
-<pre>
-if x > 0 {
- return y
-}
-</pre>
-
-<p>
-Mandatory braces encourage writing simple <code>if</code> statements
-on multiple lines. It's good style to do so anyway,
-especially when the body contains a control statement such as a
-<code>return</code> or <code>break</code>.
-</p>
-
-<p>
-Since <code>if</code> and <code>switch</code> accept an initialization
-statement, it's common to see one used to set up a local variable.
-</p>
-
-<pre>
-if err := file.Chmod(0664); err != nil {
- log.Print(err)
- return err
-}
-</pre>
-
-<p id="else">
-In the Go libraries, you'll find that
-when an <code>if</code> statement doesn't flow into the next statementโthat is,
-the body ends in <code>break</code>, <code>continue</code>,
-<code>goto</code>, or <code>return</code>โthe unnecessary
-<code>else</code> is omitted.
-</p>
-
-<pre>
-f, err := os.Open(name)
-if err != nil {
- return err
-}
-codeUsing(f)
-</pre>
-
-<p>
-This is an example of a common situation where code must guard against a
-sequence of error conditions. The code reads well if the
-successful flow of control runs down the page, eliminating error cases
-as they arise. Since error cases tend to end in <code>return</code>
-statements, the resulting code needs no <code>else</code> statements.
-</p>
-
-<pre>
-f, err := os.Open(name)
-if err != nil {
- return err
-}
-d, err := f.Stat()
-if err != nil {
- f.Close()
- return err
-}
-codeUsing(f, d)
-</pre>
-
-
-<h3 id="redeclaration">Redeclaration</h3>
-
-<p>
-An aside: The last example in the previous section demonstrates a detail of how the
-<code>:=</code> short declaration form works.
-The declaration that calls <code>os.Open</code> reads,
-</p>
-
-<pre>
-f, err := os.Open(name)
-</pre>
-
-<p>
-This statement declares two variables, <code>f</code> and <code>err</code>.
-A few lines later, the call to <code>f.Stat</code> reads,
-</p>
-
-<pre>
-d, err := f.Stat()
-</pre>
-
-<p>
-which looks as if it declares <code>d</code> and <code>err</code>.
-Notice, though, that <code>err</code> appears in both statements.
-This duplication is legal: <code>err</code> is declared by the first statement,
-but only <em>re-assigned</em> in the second.
-This means that the call to <code>f.Stat</code> uses the existing
-<code>err</code> variable declared above, and just gives it a new value.
-</p>
-
-<p>
-In a <code>:=</code> declaration a variable <code>v</code> may appear even
-if it has already been declared, provided:
-</p>
-
-<ul>
-<li>this declaration is in the same scope as the existing declaration of <code>v</code>
-(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable),</li>
-<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
-<li>there is at least one other variable in the declaration that is being declared anew.</li>
-</ul>
-
-<p>
-This unusual property is pure pragmatism,
-making it easy to use a single <code>err</code> value, for example,
-in a long <code>if-else</code> chain.
-You'll see it used often.
-</p>
-
-<h3 id="for">For</h3>
-
-<p>
-The Go <code>for</code> loop is similar to—but not the same as—C's.
-It unifies <code>for</code>
-and <code>while</code> and there is no <code>do-while</code>.
-There are three forms, only one of which has semicolons.
-</p>
-<pre>
-// Like a C for
-for init; condition; post { }
-
-// Like a C while
-for condition { }
-
-// Like a C for(;;)
-for { }
-</pre>
-
-<p>
-Short declarations make it easy to declare the index variable right in the loop.
-</p>
-<pre>
-sum := 0
-for i := 0; i < 10; i++ {
- sum += i
-}
-</pre>
-
-<p>
-If you're looping over an array, slice, string, or map,
-or reading from a channel, a <code>range</code> clause can
-manage the loop.
-</p>
-<pre>
-var m map[string]int
-sum := 0
-for _, value := range m { // key is unused
- sum += value
-}
-</pre>
-
-<p>
-For strings, the <code>range</code> does more work for you, breaking out individual
-Unicode characters by parsing the UTF-8.
-Erroneous encodings consume one byte and produce the
-replacement rune U+FFFD. The loop
-</p>
-<pre>
-for pos, char := range "ๆฅๆฌ่ช" {
- fmt.Printf("character %c starts at byte position %d\n", char, pos)
-}
-</pre>
-<p>
-prints
-</p>
-<pre>
-character ๆฅ starts at byte position 0
-character ๆฌ starts at byte position 3
-character ่ช starts at byte position 6
-</pre>
-
-<p>
-Finally, Go has no comma operator and <code>++</code> and <code>--</code>
-are statements not expressions.
-Thus if you want to run multiple variables in a <code>for</code>
-you should use parallel assignment.
-</p>
-<pre>
-// Reverse a
-for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
- a[i], a[j] = a[j], a[i]
-}
-</pre>
-
-<h3 id="switch">Switch</h3>
-
-<p>
-Go's <code>switch</code> is more general than C's.
-The expressions need not be constants or even integers,
-the cases are evaluated top to bottom until a match is found,
-and if the <code>switch</code> has no expression it switches on
-<code>true</code>.
-It's therefore possible—and idiomatic—to write an
-<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
-chain as a <code>switch</code>.
-</p>
-
-<pre>
-func unhex(c byte) byte {
- switch {
- case '0' <= c && c <= '9':
- return c - '0'
- case 'a' <= c && c <= 'f':
- return c - 'a' + 10
- case 'A' <= c && c <= 'F':
- return c - 'A' + 10
- }
- return 0
-}
-</pre>
-
-<p>
-There is no automatic fall through, but cases can be presented
-in comma-separated lists.
-<pre>
-func shouldEscape(c byte) bool {
- switch c {
- case ' ', '?', '&', '=', '#', '+', '%':
- return true
- }
- return false
-}
-</pre>
-
-<p>
-Here's a comparison routine for byte arrays that uses two
-<code>switch</code> statements:
-<pre>
-// Compare returns an integer comparing the two byte arrays
-// lexicographically.
-// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
-func Compare(a, b []byte) int {
- for i := 0; i < len(a) && i < len(b); i++ {
- switch {
- case a[i] > b[i]:
- return 1
- case a[i] < b[i]:
- return -1
- }
- }
- switch {
- case len(a) < len(b):
- return -1
- case len(a) > len(b):
- return 1
- }
- return 0
-}
-</pre>
-
-<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
-assertion with the keyword <code>type</code> inside the parentheses.
-If the switch declares a variable in the expression, the variable will
-have the corresponding type in each clause.
-</p>
-<pre>
-switch t := interfaceValue.(type) {
-default:
- fmt.Printf("unexpected type %T", t) // %T prints type
-case bool:
- fmt.Printf("boolean %t\n", t)
-case int:
- fmt.Printf("integer %d\n", t)
-case *bool:
- fmt.Printf("pointer to boolean %t\n", *t)
-case *int:
- fmt.Printf("pointer to integer %d\n", *t)
-}
-</pre>
-
-<h2 id="functions">Functions</h2>
-
-<h3 id="multiple-returns">Multiple return values</h3>
-
-<p>
-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.
-</p>
-
-<p>
-In C, a write error is signaled by a negative count with the
-error code secreted away in a volatile location.
-In Go, <code>Write</code>
-can return a count <i>and</i> an error: “Yes, you wrote some
-bytes but not all of them because you filled the device”.
-The signature of <code>*File.Write</code> in package <code>os</code> is:
-</p>
-
-<pre>
-func (file *File) Write(b []byte) (n int, err error)
-</pre>
-
-<p>
-and as the documentation says, it returns the number of bytes
-written and a non-nil <code>error</code> when <code>n</code>
-<code>!=</code> <code>len(b)</code>.
-This is a common style; see the section on error handling for more examples.
-</p>
-
-<p>
-A similar approach obviates the need to pass a pointer to a return
-value to simulate a reference parameter.
-Here's a simple-minded function to
-grab a number from a position in a byte array, returning the number
-and the next position.
-</p>
-
-<pre>
-func nextInt(b []byte, i int) (int, int) {
- for ; i < len(b) && !isDigit(b[i]); i++ {
- }
- x := 0
- for ; i < len(b) && isDigit(b[i]); i++ {
- x = x*10 + int(b[i])-'0'
- }
- return x, i
-}
-</pre>
-
-<p>
-You could use it to scan the numbers in an input array <code>a</code> like this:
-</p>
-
-<pre>
- for i := 0; i < len(a); {
- x, i = nextInt(a, i)
- fmt.Println(x)
- }
-</pre>
-
-<h3 id="named-results">Named result parameters</h3>
-
-<p>
-The return or result "parameters" of a Go function can be given names and
-used as regular variables, just like the incoming parameters.
-When named, they are initialized to the zero values for their types when
-the function begins; if the function executes a <code>return</code> statement
-with no arguments, the current values of the result parameters are
-used as the returned values.
-</p>
-
-<p>
-The names are not mandatory but they can make code shorter and clearer:
-they're documentation.
-If we name the results of <code>nextInt</code> it becomes
-obvious which returned <code>int</code>
-is which.
-</p>
-
-<pre>
-func nextInt(b []byte, pos int) (value, nextPos int) {
-</pre>
-
-<p>
-Because named results are initialized and tied to an unadorned return, they can simplify
-as well as clarify. Here's a version
-of <code>io.ReadFull</code> that uses them well:
-</p>
-
-<pre>
-func ReadFull(r Reader, buf []byte) (n int, err error) {
- for len(buf) > 0 && err == nil {
- var nr int
- nr, err = r.Read(buf)
- n += nr
- buf = buf[nr:]
- }
- return
-}
-</pre>
-
-<h3 id="defer">Defer</h3>
-
-<p>
-Go's <code>defer</code> statement schedules a function call (the
-<i>deferred</i> function) to be run immediately before the function
-executing the <code>defer</code> returns. It's an unusual but
-effective way to deal with situations such as resources that must be
-released regardless of which path a function takes to return. The
-canonical examples are unlocking a mutex or closing a file.
-</p>
-
-<pre>
-// Contents returns the file's contents as a string.
-func Contents(filename string) (string, error) {
- f, err := os.Open(filename)
- if err != nil {
- return "", err
- }
- defer f.Close() // f.Close will run when we're finished.
-
- var result []byte
- buf := make([]byte, 100)
- for {
- n, err := f.Read(buf[0:])
- result = append(result, buf[0:n]...) // append is discussed later.
- if err != nil {
- if err == io.EOF {
- break
- }
- return "", err // f will be closed if we return here.
- }
- }
- return string(result), nil // f will be closed if we return here.
-}
-</pre>
-
-<p>
-Deferring a call to a function such as <code>Close</code> has two advantages. First, it
-guarantees that you will never forget to close the file, a mistake
-that's easy to make if you later edit the function to add a new return
-path. Second, it means that the close sits near the open,
-which is much clearer than placing it at the end of the function.
-</p>
-
-<p>
-The arguments to the deferred function (which include the receiver if
-the function is a method) are evaluated when the <i>defer</i>
-executes, not when the <i>call</i> executes. Besides avoiding worries
-about variables changing values as the function executes, this means
-that a single deferred call site can defer multiple function
-executions. Here's a silly example.
-</p>
-
-<pre>
-for i := 0; i < 5; i++ {
- defer fmt.Printf("%d ", i)
-}
-</pre>
-
-<p>
-Deferred functions are executed in LIFO order, so this code will cause
-<code>4 3 2 1 0</code> to be printed when the function returns. A
-more plausible example is a simple way to trace function execution
-through the program. We could write a couple of simple tracing
-routines like this:
-</p>
-
-<pre>
-func trace(s string) { fmt.Println("entering:", s) }
-func untrace(s string) { fmt.Println("leaving:", s) }
-
-// Use them like this:
-func a() {
- trace("a")
- defer untrace("a")
- // do something....
-}
-</pre>
-
-<p>
-We can do better by exploiting the fact that arguments to deferred
-functions are evaluated when the <code>defer</code> executes. The
-tracing routine can set up the argument to the untracing routine.
-This example:
-</p>
-
-<pre>
-func trace(s string) string {
- fmt.Println("entering:", s)
- return s
-}
-
-func un(s string) {
- fmt.Println("leaving:", s)
-}
-
-func a() {
- defer un(trace("a"))
- fmt.Println("in a")
-}
-
-func b() {
- defer un(trace("b"))
- fmt.Println("in b")
- a()
-}
-
-func main() {
- b()
-}
-</pre>
-
-<p>
-prints
-</p>
-
-<pre>
-entering: b
-in b
-entering: a
-in a
-leaving: a
-leaving: b
-</pre>
-
-<p>
-For programmers accustomed to block-level resource management from
-other languages, <code>defer</code> may seem peculiar, but its most
-interesting and powerful applications come precisely from the fact
-that it's not block-based but function-based. In the section on
-<code>panic</code> and <code>recover</code> we'll see another
-example of its possibilities.
-</p>
-
-<h2 id="data">Data</h2>
-
-<h3 id="allocation_new">Allocation with <code>new</code></h3>
-
-<p>
-Go has two allocation primitives, the built-in functions
-<code>new</code> and <code>make</code>.
-They do different things and apply to different types, which can be confusing,
-but the rules are simple.
-Let's talk about <code>new</code> first.
-It's a built-in function that allocates memory, but unlike its namesakes
-in some other languages it does not <em>initialize</em> the memory,
-it only <em>zeroes</em> it.
-That is,
-<code>new(T)</code> allocates zeroed storage for a new item of type
-<code>T</code> and returns its address, a value of type <code>*T</code>.
-In Go terminology, it returns a pointer to a newly allocated zero value of type
-<code>T</code>.
-</p>
-
-<p>
-Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange
-when designing your data structures that the
-zero value of each type can be used without further initialization. This means a user of
-the data structure can create one with <code>new</code> and get right to
-work.
-For example, the documentation for <code>bytes.Buffer</code> states that
-"the zero value for <code>Buffer</code> is an empty buffer ready to use."
-Similarly, <code>sync.Mutex</code> does not
-have an explicit constructor or <code>Init</code> method.
-Instead, the zero value for a <code>sync.Mutex</code>
-is defined to be an unlocked mutex.
-</p>
-
-<p>
-The zero-value-is-useful property works transitively. Consider this type declaration.
-</p>
-
-<pre>
-type SyncedBuffer struct {
- lock sync.Mutex
- buffer bytes.Buffer
-}
-</pre>
-
-<p>
-Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
-or just declaration. In the next snippet, both <code>p</code> and <code>v</code> will work
-correctly without further arrangement.
-</p>
-
-<pre>
-p := new(SyncedBuffer) // type *SyncedBuffer
-var v SyncedBuffer // type SyncedBuffer
-</pre>
-
-<h3 id="composite_literals">Constructors and composite literals</h3>
-
-<p>
-Sometimes the zero value isn't good enough and an initializing
-constructor is necessary, as in this example derived from
-package <code>os</code>.
-</p>
-
-<pre>
-func NewFile(fd int, name string) *File {
- if fd < 0 {
- return nil
- }
- f := new(File)
- f.fd = fd
- f.name = name
- f.dirinfo = nil
- f.nepipe = 0
- return f
-}
-</pre>
-
-<p>
-There's a lot of boiler plate in there. We can simplify it
-using a <i>composite literal</i>, which is
-an expression that creates a
-new instance each time it is evaluated.
-</p>
-
-<pre>
-func NewFile(fd int, name string) *File {
- if fd < 0 {
- return nil
- }
- f := File{fd, name, nil, 0}
- return &f
-}
-</pre>
-
-<p>
-Note that, unlike in C, it's perfectly OK to return the address of a local variable;
-the storage associated with the variable survives after the function
-returns.
-In fact, taking the address of a composite literal
-allocates a fresh instance each time it is evaluated,
-so we can combine these last two lines.
-</p>
-
-<pre>
- return &File{fd, name, nil, 0}
-</pre>
-
-<p>
-The fields of a composite literal are laid out in order and must all be present.
-However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
-pairs, the initializers can appear in any
-order, with the missing ones left as their respective zero values. Thus we could say
-</p>
-
-<pre>
- return &File{fd: fd, name: name}
-</pre>
-
-<p>
-As a limiting case, if a composite literal contains no fields at all, it creates
-a zero value for the type. The expressions <code>new(File)</code> and <code>&File{}</code> are equivalent.
-</p>
-
-<p>
-Composite literals can also be created for arrays, slices, and maps,
-with the field labels being indices or map keys as appropriate.
-In these examples, the initializations work regardless of the values of <code>Enone</code>,
-<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
-</p>
-
-<pre>
-a := [...]string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-s := []string {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-</pre>
-
-<h3 id="allocation_make">Allocation with <code>make</code></h3>
-
-<p>
-Back to allocation.
-The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
-a purpose different from <code>new(T)</code>.
-It creates slices, maps, and channels only, and it returns an <em>initialized</em>
-(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
-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
-capacity, and until those items are initialized, the slice is <code>nil</code>.
-For slices, maps, and channels,
-<code>make</code> initializes the internal data structure and prepares
-the value for use.
-For instance,
-</p>
-
-<pre>
-make([]int, 10, 100)
-</pre>
-
-<p>
-allocates an array of 100 ints and then creates a slice
-structure with length 10 and a capacity of 100 pointing at the first
-10 elements of the array.
-(When making a slice, the capacity can be omitted; see the section on slices
-for more information.)
-In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
-structure, that is, a pointer to a <code>nil</code> slice value.
-
-<p>
-These examples illustrate the difference between <code>new</code> and
-<code>make</code>.
-</p>
-
-<pre>
-var p *[]int = new([]int) // allocates slice structure; *p == nil; rarely useful
-var v []int = make([]int, 100) // the slice v now refers to a new array of 100 ints
-
-// Unnecessarily complex:
-var p *[]int = new([]int)
-*p = make([]int, 100, 100)
-
-// Idiomatic:
-v := make([]int, 100)
-</pre>
-
-<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>.
-</p>
-
-<h3 id="arrays">Arrays</h3>
-
-<p>
-Arrays are useful when planning the detailed layout of memory and sometimes
-can help avoid allocation, but primarily
-they are a building block for slices, the subject of the next section.
-To lay the foundation for that topic, here are a few words about arrays.
-</p>
-
-<p>
-There are major differences between the ways arrays work in Go and C.
-In Go,
-</p>
-<ul>
-<li>
-Arrays are values. Assigning one array to another copies all the elements.
-</li>
-<li>
-In particular, if you pass an array to a function, it
-will receive a <i>copy</i> of the array, not a pointer to it.
-<li>
-The size of an array is part of its type. The types <code>[10]int</code>
-and <code>[20]int</code> are distinct.
-</li>
-</ul>
-
-<p>
-The value property can be useful but also expensive; if you want C-like behavior and efficiency,
-you can pass a pointer to the array.
-</p>
-
-<pre>
-func Sum(a *[3]float64) (sum float64) {
- for _, v := range *a {
- sum += v
- }
- return
-}
-
-array := [...]float64{7.0, 8.5, 9.1}
-x := Sum(&array) // Note the explicit address-of operator
-</pre>
-
-<p>
-But even this style isn't idiomatic Go. Slices are.
-</p>
-
-<h3 id="slices">Slices</h3>
-
-<p>
-Slices wrap arrays to give a more general, powerful, and convenient
-interface to sequences of data. Except for items with explicit
-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
-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
-and a count; the length within the slice sets an upper
-limit of how much data to read. Here is the signature of the
-<code>Read</code> method of the <code>File</code> type in package
-<code>os</code>:
-</p>
-<pre>
-func (file *File) Read(buf []byte) (n int, err error)
-</pre>
-<p>
-The method returns the number of bytes read and an error value, if
-any. To read into the first 32 bytes of a larger buffer
-<code>b</code>, <i>slice</i> (here used as a verb) the buffer.
-</p>
-<pre>
- n, err := f.Read(buf[0:32])
-</pre>
-<p>
-Such slicing is common and efficient. In fact, leaving efficiency aside for
-the moment, this snippet would also read the first 32 bytes of the buffer.
-</p>
-<pre>
- var n int
- var err error
- for i := 0; i < 32; i++ {
- nbytes, e := f.Read(buf[i:i+1]) // Read one byte.
- if nbytes == 0 || e != nil {
- err = e
- break
- }
- n += nbytes
- }
-</pre>
-<p>
-The length of a slice may be changed as long as it still fits within
-the limits of the underlying array; just assign it to a slice of
-itself. The <i>capacity</i> of a slice, accessible by the built-in
-function <code>cap</code>, reports the maximum length the slice may
-assume. Here is a function to append data to a slice. If the data
-exceeds the capacity, the slice is reallocated. The
-resulting slice is returned. The function uses the fact that
-<code>len</code> and <code>cap</code> are legal when applied to the
-<code>nil</code> slice, and return 0.
-</p>
-<pre>
-func Append(slice, data[]byte) []byte {
- l := len(slice)
- if l + len(data) > cap(slice) { // reallocate
- // Allocate double what's needed, for future growth.
- newSlice := make([]byte, (l+len(data))*2)
- // The copy function is predeclared and works for any slice type.
- copy(newSlice, slice)
- slice = newSlice
- }
- slice = slice[0:l+len(data)]
- for i, c := range data {
- slice[l+i] = c
- }
- return slice
-}
-</pre>
-<p>
-We must return the slice afterwards because, although <code>Append</code>
-can modify the elements of <code>slice</code>, the slice itself (the run-time data
-structure holding the pointer, length, and capacity) is passed by value.
-<p>
-The idea of appending to a slice is so useful it's captured by the
-<code>append</code> built-in function. To understand that function's
-design, though, we need a little more information, so we'll return
-to it later.
-</p>
-
-
-<h3 id="maps">Maps</h3>
-
-<p>
-Maps are a convenient and powerful built-in data structure to associate
-values of different types.
-The key can be of any type for which the equality operator is defined,
-such as integers,
-floating point and complex numbers,
-strings, pointers, and interfaces (as long as the dynamic type
-supports equality). Structs, arrays and slices cannot be used as map keys,
-because equality is not defined on those types.
-Like slices, maps are a reference type. If you pass a map to a function
-that changes the contents of the map, the changes will be visible
-in the caller.
-</p>
-<p>
-Maps can be constructed using the usual composite literal syntax
-with colon-separated key-value pairs,
-so it's easy to build them during initialization.
-</p>
-<pre>
-var timeZone = map[string] int {
- "UTC": 0*60*60,
- "EST": -5*60*60,
- "CST": -6*60*60,
- "MST": -7*60*60,
- "PST": -8*60*60,
-}
-</pre>
-<p>
-Assigning and fetching map values looks syntactically just like
-doing the same for arrays except that the index doesn't need to
-be an integer.
-</p>
-<pre>
-offset := timeZone["EST"]
-</pre>
-<p>
-An attempt to fetch a map value with a key that
-is not present in the map will return the zero value for the type
-of the entries
-in the map. For instance, if the map contains integers, looking
-up a non-existent key will return <code>0</code>.
-A set can be implemented as a map with value type <code>bool</code>.
-Set the map entry to <code>true</code> to put the value in the set, and then
-test it by simple indexing.
-</p>
-<pre>
-attended := map[string] bool {
- "Ann": true,
- "Joe": true,
- ...
-}
-
-if attended[person] { // will be false if person is not in the map
- fmt.Println(person, "was at the meeting")
-}
-</pre>
-<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?
-You can discriminate with a form of multiple assignment.
-</p>
-<pre>
-var seconds int
-var ok bool
-seconds, ok = timeZone[tz]
-</pre>
-<p>
-For obvious reasons this is called the “comma ok” idiom.
-In this example, if <code>tz</code> is present, <code>seconds</code>
-will be set appropriately and <code>ok</code> will be true; if not,
-<code>seconds</code> will be set to zero and <code>ok</code> will
-be false.
-Here's a function that puts it together with a nice error report:
-</p>
-<pre>
-func offset(tz string) int {
- if seconds, ok := timeZone[tz]; ok {
- return seconds
- }
- log.Println("unknown time zone:", tz)
- return 0
-}
-</pre>
-<p>
-To test for presence in the map without worrying about the actual value,
-you can use the <em>blank identifier</em>, a simple underscore (<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.
-</p>
-<pre>
-_, present := timeZone[tz]
-</pre>
-<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
-from the map.
-</p>
-<pre>
-delete(timeZone, "PDT") // Now on Standard Time
-</pre>
-
-<h3 id="printing">Printing</h3>
-
-<p>
-Formatted printing in Go uses a style similar to C's <code>printf</code>
-family but is richer and more general. The functions live in the <code>fmt</code>
-package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
-<code>fmt.Sprintf</code> and so on. The string functions (<code>Sprintf</code> etc.)
-return a string rather than filling in a provided buffer.
-</p>
-<p>
-You don't need to provide a format string. For each of <code>Printf</code>,
-<code>Fprintf</code> and <code>Sprintf</code> there is another pair
-of functions, for instance <code>Print</code> and <code>Println</code>.
-These functions do not take a format string but instead generate a default
-format for each argument. The <code>Println</code> versions also insert a blank
-between arguments and append a newline to the output while
-the <code>Print</code> versions add blanks only if the operand on neither side is a string.
-In this example each line produces the same output.
-</p>
-<pre>
-fmt.Printf("Hello %d\n", 23)
-fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
-fmt.Println("Hello", 23)
-fmt.Println(fmt.Sprint("Hello ", 23))
-</pre>
-<p>
-As mentioned in
-the <a href="http://code.google.com/p/go-tour/">Tour</a>, <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.
-</p>
-<p>
-Here things start to diverge from C. First, the numeric formats such as <code>%d</code>
-do not take flags for signedness or size; instead, the printing routines use the
-type of the argument to decide these properties.
-</p>
-<pre>
-var x uint64 = 1<<64 - 1
-fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
-</pre>
-<p>
-prints
-</p>
-<pre>
-18446744073709551615 ffffffffffffffff; -1 -1
-</pre>
-<p>
-If you just want the default conversion, such as decimal for integers, you can use
-the catchall format <code>%v</code> (for “value”); the result is exactly
-what <code>Print</code> and <code>Println</code> would produce.
-Moreover, that format can print <em>any</em> value, even arrays, structs, and
-maps. Here is a print statement for the time zone map defined in the previous section.
-</p>
-<pre>
-fmt.Printf("%v\n", timeZone) // or just fmt.Println(timeZone)
-</pre>
-<p>
-which gives output
-</p>
-<pre>
-map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
-</pre>
-<p>
-For maps the keys may be output in any order, of course.
-When printing a struct, the modified format <code>%+v</code> annotates the
-fields of the structure with their names, and for any value the alternate
-format <code>%#v</code> prints the value in full Go syntax.
-</p>
-<pre>
-type T struct {
- a int
- b float64
- c string
-}
-t := &T{ 7, -2.35, "abc\tdef" }
-fmt.Printf("%v\n", t)
-fmt.Printf("%+v\n", t)
-fmt.Printf("%#v\n", t)
-fmt.Printf("%#v\n", timeZone)
-</pre>
-<p>
-prints
-</p>
-<pre>
-&{7 -2.35 abc def}
-&{a:7 b:-2.35 c:abc def}
-&main.T{a:7, b:-2.35, c:"abc\tdef"}
-map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
-</pre>
-<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.
-Also, <code>%x</code> works on strings and arrays of bytes as well as on integers,
-generating a long hexadecimal string, and with
-a space in the format (<code>% x</code>) it puts spaces between the bytes.
-</p>
-<p>
-Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
-<pre>
-fmt.Printf("%T\n", timeZone)
-</pre>
-<p>
-prints
-</p>
-<pre>
-map[string] int
-</pre>
-<p>
-If you want to control the default format for a custom type, all that's required is to define
-a method with the signature <code>String() string</code> on the type.
-For our simple type <code>T</code>, that might look like this.
-</p>
-<pre>
-func (t *T) String() string {
- return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
-}
-fmt.Printf("%v\n", t)
-</pre>
-<p>
-to print in the format
-</p>
-<pre>
-7/-2.35/"abc\tdef"
-</pre>
-<p>
-(If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>,
-the receiver for <code>String</code> must be of value type; this example used a pointer because
-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.
-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.
-</p>
-<pre>
-func Printf(format string, v ...interface{}) (n int, err error) {
-</pre>
-<p>
-Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
-<code>[]interface{}</code> but if it is passed to another variadic function, it acts like
-a regular list of arguments.
-Here is the implementation of the
-function <code>log.Println</code> we used above. It passes its arguments directly to
-<code>fmt.Sprintln</code> for the actual formatting.
-</p>
-<pre>
-// Println prints to the standard logger in the manner of fmt.Println.
-func Println(v ...interface{}) {
- std.Output(2, fmt.Sprintln(v...)) // Output takes parameters (int, string)
-}
-</pre>
-<p>
-We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the
-compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass
-<code>v</code> as a single slice argument.
-<p>
-There's even more to printing than we've covered here. See the <code>godoc</code> documentation
-for package <code>fmt</code> for the details.
-</p>
-<p>
-By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code>
-for a min function that chooses the least of a list of integers:
-</p>
-<pre>
-func Min(a ...int) int {
- min := int(^uint(0) >> 1) // largest int
- for _, i := range a {
- if i < min {
- min = i
- }
- }
- return min
-}
-</pre>
-
-<h3 id="append">Append</h3>
-<p>
-Now we have the missing piece we needed to explain the design of
-the <code>append</code> built-in function. The signature of <code>append</code>
-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>
-</pre>
-<p>
-where <i>T</i> is a placeholder for any given type. You can't
-actually write a function in Go where the type <code>T</code>
-is determined by the caller.
-That's why <code>append</code> is built in: it needs support from the
-compiler.
-</p>
-<p>
-What <code>append</code> does is append the elements to the end of
-the slice and return the result. The result needs to be returned
-because, as with our hand-written <code>Append</code>, the underlying
-array may change. This simple example
-</p>
-<pre>
-x := []int{1,2,3}
-x = append(x, 4, 5, 6)
-fmt.Println(x)
-</pre>
-<p>
-prints <code>[1 2 3 4 5 6]</code>. So <code>append</code> works a
-little like <code>Printf</code>, collecting an arbitrary number of
-arguments.
-</p>
-<p>
-But what if we wanted to do what our <code>Append</code> does and
-append a slice to a slice? Easy: use <code>...</code> at the call
-site, just as we did in the call to <code>Output</code> above. This
-snippet produces identical output to the one above.
-</p>
-<pre>
-x := []int{1,2,3}
-y := []int{4,5,6}
-x = append(x, y...)
-fmt.Println(x)
-</pre>
-<p>
-Without that <code>...</code>, it wouldn't compile because the types
-would be wrong; <code>y</code> is not of type <code>int</code>.
-</p>
-
-<h2 id="initialization">Initialization</h2>
-
-<p>
-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
-correctly.
-</p>
-
-<h3 id="constants">Constants</h3>
-
-<p>
-Constants in Go are just that—constant.
-They are created at compile time, even when defined as
-locals in functions,
-and can only be numbers, strings or booleans.
-Because of the compile-time restriction, the expressions
-that define them must be constant expressions,
-evaluatable by the compiler. For instance,
-<code>1<<3</code> is a constant expression, while
-<code>math.Sin(math.Pi/4)</code> is not because
-the function call to <code>math.Sin</code> needs
-to happen at run time.
-</p>
-
-<p>
-In Go, enumerated constants are created using the <code>iota</code>
-enumerator. Since <code>iota</code> can be part of an expression and
-expressions can be implicitly repeated, it is easy to build intricate
-sets of values.
-</p>
-{{code "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.
-</p>
-{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
-<p>
-(The <code>float64</code> conversions prevent <code>Sprintf</code>
-from recurring back through the <code>String</code> method for
-<code>ByteSize</code>.)
-The expression <code>YB</code> prints as <code>1.00YB</code>,
-while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
-</p>
-
-<h3 id="variables">Variables</h3>
-
-<p>
-Variables can be initialized just like constants but the
-initializer can be a general expression computed at run time.
-</p>
-<pre>
-var (
- HOME = os.Getenv("HOME")
- USER = os.Getenv("USER")
- GOROOT = os.Getenv("GOROOT")
-)
-</pre>
-
-<h3 id="init">The init function</h3>
-
-<p>
-Finally, each source file can define its own niladic <code>init</code> function to
-set up whatever state is required. (Actually each file can have multiple
-<code>init</code> functions.)
-And finally means finally: <code>init</code> is called after all the
-variable declarations in the package have evaluated their initializers,
-and those are evaluated only after all the imported packages have been
-initialized.
-</p>
-<p>
-Besides initializations that cannot be expressed as declarations,
-a common use of <code>init</code> functions is to verify or repair
-correctness of the program state before real execution begins.
-</p>
-
-<pre>
-func init() {
- if USER == "" {
- log.Fatal("$USER not set")
- }
- if HOME == "" {
- HOME = "/usr/" + USER
- }
- if GOROOT == "" {
- GOROOT = HOME + "/go"
- }
- // GOROOT may be overridden by --goroot flag on command line.
- flag.StringVar(&GOROOT, "goroot", GOROOT, "Go root directory")
-}
-</pre>
-
-<h2 id="methods">Methods</h2>
-
-<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;
-the receiver does not have to be a struct.
-<p>
-In the discussion of slices above, we wrote an <code>Append</code>
-function. We can define it as a method on slices instead. To do
-this, we first declare a named type to which we can bind the method, and
-then make the receiver for the method a value of that type.
-</p>
-<pre>
-type ByteSlice []byte
-
-func (slice ByteSlice) Append(data []byte) []byte {
- // Body exactly the same as above
-}
-</pre>
-<p>
-This still requires the method to return the updated slice. We can
-eliminate that clumsiness by redefining the method to take a
-<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
-method can overwrite the caller's slice.
-</p>
-<pre>
-func (p *ByteSlice) Append(data []byte) {
- slice := *p
- // Body as above, without the return.
- *p = slice
-}
-</pre>
-<p>
-In fact, we can do even better. If we modify our function so it looks
-like a standard <code>Write</code> method, like this,
-</p>
-<pre>
-func (p *ByteSlice) Write(data []byte) (n int, err error) {
- slice := *p
- // Again as above.
- *p = slice
- return len(data), nil
-}
-</pre>
-<p>
-then the type <code>*ByteSlice</code> satisfies the standard interface
-<code>io.Writer</code>, which is handy. For instance, we can
-print into one.
-</p>
-<pre>
- var b ByteSlice
- fmt.Fprintf(&b, "This hour has %d days\n", 7)
-</pre>
-<p>
-We pass the address of a <code>ByteSlice</code>
-because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
-The rule about pointers vs. values for receivers is that value methods
-can be invoked on pointers and values, but pointer methods can only be
-invoked on pointers. This is because pointer methods can modify the
-receiver; invoking them on a copy of the value would cause those
-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>.
-</p>
-
-<h2 id="interfaces_and_types">Interfaces and other types</h2>
-
-<h3 id="interfaces">Interfaces</h3>
-<p>
-Interfaces in Go provide a way to specify the behavior of an
-object: if something can do <em>this</em>, then it can be used
-<em>here</em>. We've seen a couple of simple examples already;
-custom printers can be implemented by a <code>String</code> method
-while <code>Fprintf</code> can generate output to anything
-with a <code>Write</code> method.
-Interfaces with only one or two methods are common in Go code, and are
-usually given a name derived from the method, such as <code>io.Writer</code>
-for something that implements <code>Write</code>.
-</p>
-<p>
-A type can implement multiple interfaces.
-For instance, a collection can be sorted
-by the routines in package <code>sort</code> if it implements
-<code>sort.Interface</code>, which contains <code>Len()</code>,
-<code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>,
-and it could also have a custom formatter.
-In this contrived example <code>Sequence</code> satisfies both.
-</p>
-{{code "progs/eff_sequence.go" `/^type/` "$"}}
-
-<h3 id="conversions">Conversions</h3>
-
-<p>
-The <code>String</code> method of <code>Sequence</code> is recreating the
-work that <code>Sprint</code> already does for slices. We can share the
-effort if we convert the <code>Sequence</code> to a plain
-<code>[]int</code> before calling <code>Sprint</code>.
-</p>
-<pre>
-func (s Sequence) String() string {
- sort.Sort(s)
- return fmt.Sprint([]int(s))
-}
-</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.
-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
-as though the existing value has a new type.
-(There are other legal conversions, such as from integer to floating point, that
-do create a new value.)
-</p>
-<p>
-It's an idiom in Go programs to convert the
-type of an expression to access a different
-set of methods. As an example, we could use the existing
-type <code>sort.IntSlice</code> to reduce the entire example
-to this:
-</p>
-<pre>
-type Sequence []int
-
-// Method for printing - sorts the elements before printing
-func (s Sequence) String() string {
- sort.IntSlice(s).Sort()
- return fmt.Sprint([]int(s))
-}
-</pre>
-<p>
-Now, instead of having <code>Sequence</code> implement multiple
-interfaces (sorting and printing), we're using the ability of a data item to be
-converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
-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="generality">Generality</h3>
-<p>
-If a type exists only to implement an interface
-and has no exported methods beyond that interface,
-there is no need to export the type itself.
-Exporting just the interface makes it clear that
-it's the behavior that matters, not the implementation,
-and that other implementations with different properties
-can mirror the behavior of the original type.
-It also avoids the need to repeat the documentation
-on every instance of a common method.
-</p>
-<p>
-In such cases, the constructor should return an interface value
-rather than the implementing type.
-As an example, in the hash libraries
-both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
-return the interface type <code>hash.Hash32</code>.
-Substituting the CRC-32 algorithm for Adler-32 in a Go program
-requires only changing the constructor call;
-the rest of the code is unaffected by the change of algorithm.
-</p>
-<p>
-A similar approach allows the streaming cipher algorithms
-in the various <code>crypto</code> packages to be
-separated from the block ciphers they chain together.
-The <code>Block</code> interface
-in the <code>crypto/cipher</code>package specifies the
-behavior of a block cipher, which provides encryption
-of a single block of data.
-Then, by analogy with the <code>bufio</code> package,
-cipher packages that implement this interface
-can be used to construct streaming ciphers, represented
-by the <code>Stream</code> interface, without
-knowing the details of the block encryption.
-</p>
-<p>
-The <code>crypto/cipher</code> interfaces look like this:
-</p>
-<pre>
-type Block interface {
- BlockSize() int
- Encrypt(src, dst []byte)
- Decrypt(src, dst []byte)
-}
-
-type Stream interface {
- XORKeyStream(dst, src []byte)
-}
-</pre>
-
-<p>
-Here's the definition of the counter mode (CTR) stream,
-which turns a block cipher into a streaming cipher; notice
-that the block cipher's details are abstracted away:
-</p>
-
-<pre>
-// NewCTR returns a Stream that encrypts/decrypts using the given Block in
-// counter mode. The length of iv must be the same as the Block's block size.
-func NewCTR(block Block, iv []byte) Stream
-</pre>
-<p>
-<code>NewCTR</code> applies not
-just to one specific encryption algorithm and data source but to any
-implementation of the <code>Block</code> interface and any
-<code>Stream</code>. Because they return
-interface values, replacing CTR
-encryption with other encryption modes is a localized change. The constructor
-calls must be edited, but because the surrounding code must treat the result only
-as a <code>Stream</code>, it won't notice the difference.
-</p>
-
-<h3 id="interface_methods">Interfaces and methods</h3>
-<p>
-Since almost anything can have methods attached, almost anything can
-satisfy an interface. One illustrative example is in the <code>http</code>
-package, which defines the <code>Handler</code> interface. Any object
-that implements <code>Handler</code> can serve HTTP requests.
-</p>
-<pre>
-type Handler interface {
- ServeHTTP(ResponseWriter, *Request)
-}
-</pre>
-<p>
-<code>ResponseWriter</code> is itself an interface that provides access
-to the methods needed to return the response to the client.
-Those methods include the standard <code>Write</code> method, so an
-<code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code>
-can be used.
-<code>Request</code> is a struct containing a parsed representation
-of the request from the client.
-<p>
-For brevity, let's ignore POSTs and assume HTTP requests are always
-GETs; that simplification does not affect the way the handlers are
-set up. Here's a trivial but complete implementation of a handler to
-count the number of times the
-page is visited.
-</p>
-<pre>
-// Simple counter server.
-type Counter struct {
- n int
-}
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
- ctr.n++
- fmt.Fprintf(w, "counter = %d\n", ctr.n)
-}
-</pre>
-<p>
-(Keeping with our theme, note how <code>Fprintf</code> can print to an
-<code>http.ResponseWriter</code>.)
-For reference, here's how to attach such a server to a node on the URL tree.
-<pre>
-import "net/http"
-...
-ctr := new(Counter)
-http.Handle("/counter", ctr)
-</pre>
-<p>
-But why make <code>Counter</code> a struct? An integer is all that's needed.
-(The receiver needs to be a pointer so the increment is visible to the caller.)
-</p>
-<pre>
-// Simpler counter server.
-type Counter int
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
- *ctr++
- fmt.Fprintf(w, "counter = %d\n", *ctr)
-}
-</pre>
-<p>
-What if your program has some internal state that needs to be notified that a page
-has been visited? Tie a channel to the web page.
-</p>
-<pre>
-// A channel that sends a notification on each visit.
-// (Probably want the channel to be buffered.)
-type Chan chan *http.Request
-
-func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
- ch <- req
- fmt.Fprint(w, "notification sent")
-}
-</pre>
-<p>
-Finally, let's say we wanted to present on <code>/args</code> the arguments
-used when invoking the server binary.
-It's easy to write a function to print the arguments.
-</p>
-<pre>
-func ArgServer() {
- for _, s := range os.Args {
- fmt.Println(s)
- }
-}
-</pre>
-<p>
-How do we turn that into an HTTP server? We could make <code>ArgServer</code>
-a method of some type whose value we ignore, but there's a cleaner way.
-Since we can define a method for any type except pointers and interfaces,
-we can write a method for a function.
-The <code>http</code> package contains this code:
-</p>
-<pre>
-// The HandlerFunc type is an adapter to allow the use of
-// ordinary functions as HTTP handlers. If f is a function
-// with the appropriate signature, HandlerFunc(f) is a
-// Handler object that calls f.
-type HandlerFunc func(ResponseWriter, *Request)
-
-// ServeHTTP calls f(c, req).
-func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
- f(w, req)
-}
-</pre>
-<p>
-<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
-so values of that type can serve HTTP requests. Look at the implementation
-of the method: the receiver is a function, <code>f</code>, and the method
-calls <code>f</code>. That may seem odd but it's not that different from, say,
-the receiver being a channel and the method sending on the channel.
-</p>
-<p>
-To make <code>ArgServer</code> into an HTTP server, we first modify it
-to have the right signature.
-</p>
-<pre>
-// Argument server.
-func ArgServer(w http.ResponseWriter, req *http.Request) {
- for _, s := range os.Args {
- fmt.Fprintln(w, s)
- }
-}
-</pre>
-<p>
-<code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
-so it can be converted to that type to access its methods,
-just as we converted <code>Sequence</code> to <code>IntSlice</code>
-to access <code>IntSlice.Sort</code>.
-The code to set it up is concise:
-</p>
-<pre>
-http.Handle("/args", http.HandlerFunc(ArgServer))
-</pre>
-<p>
-When someone visits the page <code>/args</code>,
-the handler installed at that page has value <code>ArgServer</code>
-and type <code>HandlerFunc</code>.
-The HTTP server will invoke the method <code>ServeHTTP</code>
-of that type, with <code>ArgServer</code> as the receiver, which will in turn call
-<code>ArgServer</code> (via the invocation <code>f(c, req)</code>
-inside <code>HandlerFunc.ServeHTTP</code>).
-The arguments will then be displayed.
-</p>
-<p>
-In this section we have made an HTTP server from a struct, an integer,
-a channel, and a function, all because interfaces are just sets of
-methods, which can be defined for (almost) any type.
-</p>
-
-<h2 id="embedding">Embedding</h2>
-
-<p>
-Go does not provide the typical, type-driven notion of subclassing,
-but it does have the ability to “borrow” pieces of an
-implementation by <em>embedding</em> types within a struct or
-interface.
-</p>
-<p>
-Interface embedding is very simple.
-We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before;
-here are their definitions.
-</p>
-<pre>
-type Reader interface {
- Read(p []byte) (n int, err error)
-}
-
-type Writer interface {
- Write(p []byte) (n int, err error)
-}
-</pre>
-<p>
-The <code>io</code> package also exports several other interfaces
-that specify objects that can implement several such methods.
-For instance, there is <code>io.ReadWriter</code>, an interface
-containing both <code>Read</code> and <code>Write</code>.
-We could specify <code>io.ReadWriter</code> by listing the
-two methods explicitly, but it's easier and more evocative
-to embed the two interfaces to form the new one, like this:
-</p>
-<pre>
-// ReadWriter is the interface that combines the Reader and Writer interfaces.
-type ReadWriter interface {
- Reader
- Writer
-}
-</pre>
-<p>
-This says just what it looks like: A <code>ReadWriter</code> can do
-what a <code>Reader</code> does <em>and</em> what a <code>Writer</code>
-does; it is a union of the embedded interfaces (which must be disjoint
-sets of methods).
-Only interfaces can be embedded within interfaces.
-<p>
-The same basic idea applies to structs, but with more far-reaching
-implications. The <code>bufio</code> package has two struct types,
-<code>bufio.Reader</code> and <code>bufio.Writer</code>, each of
-which of course implements the analogous interfaces from package
-<code>io</code>.
-And <code>bufio</code> also implements a buffered reader/writer,
-which it does by combining a reader and a writer into one struct
-using embedding: it lists the types within the struct
-but does not give them field names.
-</p>
-<pre>
-// ReadWriter stores pointers to a Reader and a Writer.
-// It implements io.ReadWriter.
-type ReadWriter struct {
- *Reader // *bufio.Reader
- *Writer // *bufio.Writer
-}
-</pre>
-<p>
-The embedded elements are pointers to structs and of course
-must be initialized to point to valid structs before they
-can be used.
-The <code>ReadWriter</code> struct could be written as
-</p>
-<pre>
-type ReadWriter struct {
- reader *Reader
- writer *Writer
-}
-</pre>
-<p>
-but then to promote the methods of the fields and to
-satisfy the <code>io</code> interfaces, we would also need
-to provide forwarding methods, like this:
-</p>
-<pre>
-func (rw *ReadWriter) Read(p []byte) (n int, err error) {
- return rw.reader.Read(p)
-}
-</pre>
-<p>
-By embedding the structs directly, we avoid this bookkeeping.
-The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code>
-not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>,
-it also satisfies all three interfaces:
-<code>io.Reader</code>,
-<code>io.Writer</code>, and
-<code>io.ReadWriter</code>.
-</p>
-<p>
-There's an important way in which embedding differs from subclassing. When we embed a type,
-the methods of that type become methods of the outer type,
-but when they are invoked the receiver of the method is the inner type, not the outer one.
-In our example, when the <code>Read</code> method of a <code>bufio.ReadWriter</code> is
-invoked, it has exactly the same effect as the forwarding method written out above;
-the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the
-<code>ReadWriter</code> itself.
-</p>
-<p>
-Embedding can also be a simple convenience.
-This example shows an embedded field alongside a regular, named field.
-</p>
-<pre>
-type Job struct {
- Command string
- *log.Logger
-}
-</pre>
-<p>
-The <code>Job</code> type now has the <code>Log</code>, <code>Logf</code>
-and other
-methods of <code>*log.Logger</code>. We could have given the <code>Logger</code>
-a field name, of course, but it's not necessary to do so. And now, once
-initialized, we can
-log to the <code>Job</code>:
-</p>
-<pre>
-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,
-</p>
-<pre>
-func NewJob(command string, logger *log.Logger) *Job {
- return &Job{command, logger}
-}
-</pre>
-<p>
-or with a composite literal,
-</p>
-<pre>
-job := &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
-<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>.
-</p>
-<pre>
-func (job *Job) Logf(format string, args ...interface{}) {
- job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
-}
-</pre>
-<p>
-Embedding types introduces the problem of name conflicts but the rules to resolve
-them are simple.
-First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply
-nested part of the type.
-If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field
-of <code>Job</code> would dominate it.
-</p>
-<p>
-Second, if the same name appears at the same nesting level, it is usually an error;
-it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct
-contained another field or method called <code>Logger</code>.
-However, if the duplicate name is never mentioned in the program outside the type definition, it is OK.
-This qualification provides some protection against changes made to types embedded from outside; there
-is no problem if a field is added that conflicts with another field in another subtype if neither field
-is ever used.
-</p>
-
-
-<h2 id="concurrency">Concurrency</h2>
-
-<h3 id="sharing">Share by communicating</h3>
-
-<p>
-Concurrent programming is a large topic and there is space only for some
-Go-specific highlights here.
-</p>
-<p>
-Concurrent programming in many environments is made difficult by the
-subtleties required to implement correct access to shared variables. Go encourages
-a different approach in which shared values are passed around on channels
-and, in fact, never actively shared by separate threads of execution.
-Only one goroutine has access to the value at any given time.
-Data races cannot occur, by design.
-To encourage this way of thinking we have reduced it to a slogan:
-</p>
-<blockquote>
-Do not communicate by sharing memory;
-instead, share memory by communicating.
-</blockquote>
-<p>
-This approach can be taken too far. Reference counts may be best done
-by putting a mutex around an integer variable, for instance. But as a
-high-level approach, using channels to control access makes it easier
-to write clear, correct programs.
-</p>
-<p>
-One way to think about this model is to consider a typical single-threaded
-program running on one CPU. It has no need for synchronization primitives.
-Now run another such instance; it too needs no synchronization. Now let those
-two communicate; if the communication is the synchronizer, there's still no need
-for other synchronization. Unix pipelines, for example, fit this model
-perfectly. Although Go's approach to concurrency originates in Hoare's
-Communicating Sequential Processes (CSP),
-it can also be seen as a type-safe generalization of Unix pipes.
-</p>
-
-<h3 id="goroutines">Goroutines</h3>
-
-<p>
-They're called <em>goroutines</em> because the existing
-terms—threads, coroutines, processes, and so on—convey
-inaccurate connotations. A goroutine has a simple model: it is a
-function executing in parallel with other goroutines in the same
-address space. It is lightweight, costing little more than the
-allocation of stack space.
-And the stacks start small, so they are cheap, and grow
-by allocating (and freeing) heap storage as required.
-</p>
-<p>
-Goroutines are multiplexed onto multiple OS threads so if one should
-block, such as while waiting for I/O, others continue to run. Their
-design hides many of the complexities of thread creation and
-management.
-</p>
-<p>
-Prefix a function or method call with the <code>go</code>
-keyword to run the call in a new goroutine.
-When the call completes, the goroutine
-exits, silently. (The effect is similar to the Unix shell's
-<code>&</code> notation for running a command in the
-background.)
-</p>
-<pre>
-go list.Sort() // run list.Sort in parallel; don't wait for it.
-</pre>
-<p>
-A function literal can be handy in a goroutine invocation.
-<pre>
-func Announce(message string, delay int64) {
- go func() {
- time.Sleep(delay)
- fmt.Println(message)
- }() // Note the parentheses - must call the function.
-}
-</pre>
-<p>
-In Go, function literals are closures: the implementation makes
-sure the variables referred to by the function survive as long as they are active.
-<p>
-These examples aren't too practical because the functions have no way of signaling
-completion. For that, we need channels.
-</p>
-
-<h3 id="channels">Channels</h3>
-
-<p>
-Like maps, channels are a reference type and are allocated with <code>make</code>.
-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>
-<pre>
-ci := make(chan int) // unbuffered channel of integers
-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—the exchange of a value—with
-synchronization—guaranteeing that two calculations (goroutines) are in
-a known state.
-</p>
-<p>
-There are lots of nice idioms using channels. Here's one to get us started.
-In the previous section we launched a sort in the background. A channel
-can allow the launching goroutine to wait for the sort to complete.
-</p>
-<pre>
-c := make(chan int) // Allocate a channel.
-// Start the sort in a goroutine; when it completes, signal on the channel.
-go func() {
- list.Sort()
- c <- 1 // Send a signal; value does not matter.
-}()
-doSomethingForAWhile()
-<-c // Wait for sort to finish; discard sent value.
-</pre>
-<p>
-Receivers always block until there is data to receive.
-If the channel is unbuffered, the sender blocks until the receiver has
-received the value.
-If the channel has a buffer, the sender blocks only until the
-value has been copied to the buffer; if the buffer is full, this
-means waiting until some receiver has retrieved a value.
-</p>
-<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.
-The capacity of the channel buffer limits the number of
-simultaneous calls to <code>process</code>.
-</p>
-<pre>
-var sem = make(chan int, MaxOutstanding)
-
-func handle(r *Request) {
- sem <- 1 // Wait for active queue to drain.
- process(r) // May take a long time.
- <-sem // Done; enable next request to run.
-}
-
-func Serve(queue chan *Request) {
- for {
- req := <-queue
- go handle(req) // Don't wait for handle to finish.
- }
-}
-</pre>
-<p>
-Here's the same idea implemented by starting a fixed
-number of <code>handle</code> goroutines all reading from the request
-channel.
-The number of goroutines limits the number of simultaneous
-calls to <code>process</code>.
-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 {
- process(r)
- }
-}
-
-func Serve(clientRequests chan *clientRequests, quit chan bool) {
- // Start handlers
- for i := 0; i < MaxOutstanding; i++ {
- go handle(clientRequests)
- }
- <-quit // Wait to be told to exit.
-}
-</pre>
-
-<h3 id="chan_of_chan">Channels of channels</h3>
-<p>
-One of the most important properties of Go is that
-a channel is a first-class value that can be allocated and passed
-around like any other. A common use of this property is
-to implement safe, parallel demultiplexing.
-<p>
-In the example in the previous section, <code>handle</code> was
-an idealized handler for a request but we didn't define the
-type it was handling. If that type includes a channel on which
-to reply, each client can provide its own path for the answer.
-Here's a schematic definition of type <code>Request</code>.
-</p>
-<pre>
-type Request struct {
- args []int
- f func([]int) int
- resultChan chan int
-}
-</pre>
-<p>
-The client provides a function and its arguments, as well as
-a channel inside the request object on which to receive the answer.
-</p>
-<pre>
-func sum(a []int) (s int) {
- for _, v := range a {
- s += v
- }
- return
-}
-
-request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
-// Send request
-clientRequests <- request
-// Wait for response.
-fmt.Printf("answer: %d\n", <-request.resultChan)
-</pre>
-<p>
-On the server side, the handler function is the only thing that changes.
-</p>
-<pre>
-func handle(queue chan *Request) {
- for req := range queue {
- req.resultChan <- req.f(req.args)
- }
-}
-</pre>
-<p>
-There's clearly a lot more to do to make it realistic, but this
-code is a framework for a rate-limited, parallel, non-blocking RPC
-system, and there's not a mutex in sight.
-</p>
-
-<h3 id="parallel">Parallelization</h3>
-<p>
-Another application of these ideas is to parallelize a calculation
-across multiple CPU cores. If the calculation can be broken into
-separate pieces, it can be parallelized, with a channel to signal
-when each piece completes.
-</p>
-<p>
-Let's say we have an expensive operation to perform on a vector of items,
-and that the value of the operation on each item is independent,
-as in this idealized example.
-</p>
-<pre>
-type Vector []float64
-
-// Apply the operation to v[i], v[i+1] ... up to v[n-1].
-func (v Vector) DoSome(i, n int, u Vector, c chan int) {
- for ; i < n; i++ {
- v[i] += u.Op(v[i])
- }
- c <- 1 // signal that this piece is done
-}
-</pre>
-<p>
-We launch the pieces independently in a loop, one per CPU.
-They can complete in any order but it doesn't matter; we just
-count the completion signals by draining the channel after
-launching all the goroutines.
-</p>
-<pre>
-const NCPU = 4 // number of CPU cores
-
-func (v Vector) DoAll(u Vector) {
- c := make(chan int, NCPU) // Buffering optional but sensible.
- for i := 0; i < NCPU; i++ {
- go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
- }
- // Drain the channel.
- for i := 0; i < NCPU; i++ {
- <-c // wait for one task to complete
- }
- // All done.
-}
-
-</pre>
-
-<p>
-The current implementation of <code>gc</code> (<code>6g</code>, etc.)
-will not parallelize this code by default.
-It dedicates only a single core to user-level processing. An
-arbitrary number of goroutines can be blocked in system calls, but
-by default only one can be executing user-level code at any time.
-It should be smarter and one day it will be smarter, but until it
-is if you want CPU parallelism you must tell the run-time
-how many goroutines you want executing code simultaneously. There
-are two related ways to do this. Either run your job with environment
-variable <code>GOMAXPROCS</code> set to the number of cores to use
-or import the <code>runtime</code> package and call
-<code>runtime.GOMAXPROCS(NCPU)</code>.
-A helpful value might be <code>runtime.NumCPU()</code>, which reports the number
-of logical CPUs on the local machine.
-Again, this requirement is expected to be retired as the scheduling and run-time improve.
-</p>
-
-<h3 id="leaky_buffer">A leaky buffer</h3>
-
-<p>
-The tools of concurrent programming can even make non-concurrent
-ideas easier to express. Here's an example abstracted from an RPC
-package. The client goroutine loops receiving data from some source,
-perhaps a network. To avoid allocating and freeing buffers, it keeps
-a free list, and uses a buffered channel to represent it. If the
-channel is empty, a new buffer gets allocated.
-Once the message buffer is ready, it's sent to the server on
-<code>serverChan</code>.
-</p>
-<pre>
-var freeList = make(chan *Buffer, 100)
-var serverChan = make(chan *Buffer)
-
-func client() {
- for {
- var b *Buffer
- // Grab a buffer if available; allocate if not.
- select {
- case b = <-freeList:
- // Got one; nothing more to do.
- default:
- // None free, so allocate a new one.
- b = new(Buffer)
- }
- load(b) // Read next message from the net.
- serverChan <- b // Send to server.
- }
-}
-</pre>
-<p>
-The server loop receives each message from the client, processes it,
-and returns the buffer to the free list.
-</p>
-<pre>
-func server() {
- for {
- b := <-serverChan // Wait for work.
- process(b)
- // Reuse buffer if there's room.
- select {
- case freeList <- b:
- // Buffer on free list; nothing more to do.
- default:
- // Free list full, just carry on.
- }
- }
-}
-</pre>
-<p>
-The client attempts to retrieve a buffer from <code>freeList</code>;
-if none is available, it allocates a fresh one.
-The server's send to <code>freeList</code> puts <code>b</code> back
-on the free list unless the list is full, in which case the
-buffer is dropped on the floor to be reclaimed by
-the garbage collector.
-(The <code>default</code> clauses in the <code>select</code>
-statements execute when no other case is ready,
-meaning that the <code>selects</code> never block.)
-This implementation builds a leaky bucket free list
-in just a few lines, relying on the buffered channel and
-the garbage collector for bookkeeping.
-</p>
-
-<h2 id="errors">Errors</h2>
-
-<p>
-Library routines must often return some sort of error indication to
-the caller. As mentioned earlier, Go's multivalue return makes it
-easy to return a detailed error description alongside the normal
-return value. By convention, errors have type <code>error</code>,
-a simple built-in interface.
-</p>
-<pre>
-type error interface {
- Error() string
-}
-</pre>
-<p>
-A library writer is free to implement this interface with a
-richer model under the covers, making it possible not only
-to see the error but also to provide some context.
-For example, <code>os.Open</code> returns an <code>os.PathError</code>.
-</p>
-<pre>
-// PathError records an error and the operation and
-// file path that caused it.
-type PathError struct {
- Op string // "open", "unlink", etc.
- Path string // The associated file.
- Err error // Returned by the system call.
-}
-
-func (e *PathError) Error() string {
- return e.Op + " " + e.Path + ": " + e.Err.Error()
-}
-</pre>
-<p>
-<code>PathError</code>'s <code>Error</code> generates
-a string like this:
-</p>
-<pre>
-open /etc/passwx: no such file or directory
-</pre>
-<p>
-Such an error, which includes the problematic file name, the
-operation, and the operating system error it triggered, is useful even
-if printed far from the call that caused it;
-it is much more informative than the plain
-"no such file or directory".
-</p>
-
-<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
-image, the string representation for a decoding error due to an unknown format
-is "image: unknown format".
-</p>
-
-<p>
-Callers that care about the precise error details can
-use a type switch or a type assertion to look for specific
-errors and extract details. For <code>PathErrors</code>
-this might include examining the internal <code>Err</code>
-field for recoverable failures.
-</p>
-
-<pre>
-for try := 0; try < 2; try++ {
- file, err = os.Open(filename)
- if err == nil {
- return
- }
- if e, ok := err.(*os.PathError); ok && e.Err == os.ENOSPC {
- deleteTempFiles() // Recover some space.
- continue
- }
- return
-}
-</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>
-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>,
-which we can examine for more information about the error.
-</p>
-
-<h3 id="panic">Panic</h3>
-
-<p>
-The usual way to report an error to a caller is to return an
-<code>error</code> as an extra return value. The canonical
-<code>Read</code> method is a well-known instance; it returns a byte
-count and an <code>error</code>. But what if the error is
-unrecoverable? Sometimes the program simply cannot continue.
-</p>
-
-<p>
-For this purpose, there is a built-in function <code>panic</code>
-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—often a string—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.
-</p>
-
-
-<pre>
-// A toy implementation of cube root using Newton's method.
-func CubeRoot(x float64) float64 {
- z := x/3 // Arbitrary initial value
- for i := 0; i < 1e6; i++ {
- prevz := z
- z -= (z*z*z-x) / (3*z*z)
- if veryClose(z, prevz) {
- return z
- }
- }
- // A million iterations has not converged; something is wrong.
- panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
-}
-</pre>
-
-<p>
-This is only an example but real library functions should
-avoid <code>panic</code>. If the problem can be masked or worked
-around, it's always better to let things continue to run rather
-than taking down the whole program. One possible counterexample
-is during initialization: if the library truly cannot set itself up,
-it might be reasonable to panic, so to speak.
-</p>
-
-<pre>
-var user = os.Getenv("USER")
-
-func init() {
- if user == "" {
- panic("no value for $USER")
- }
-}
-</pre>
-
-<h3 id="recover">Recover</h3>
-
-<p>
-When <code>panic</code> is called, including implicitly for run-time
-errors such as indexing an array out of bounds or failing a type
-assertion, it immediately stops execution of the current function
-and begins unwinding the stack of the goroutine, running any deferred
-functions along the way. If that unwinding reaches the top of the
-goroutine's stack, the program dies. However, it is possible to
-use the built-in function <code>recover</code> to regain control
-of the goroutine and resume normal execution.
-</p>
-
-<p>
-A call to <code>recover</code> stops the unwinding and returns the
-argument passed to <code>panic</code>. Because the only code that
-runs while unwinding is inside deferred functions, <code>recover</code>
-is only useful inside deferred functions.
-</p>
-
-<p>
-One application of <code>recover</code> is to shut down a failing goroutine
-inside a server without killing the other executing goroutines.
-</p>
-
-<pre>
-func server(workChan <-chan *Work) {
- for work := range workChan {
- go safelyDo(work)
- }
-}
-
-func safelyDo(work *Work) {
- defer func() {
- if err := recover(); err != nil {
- log.Println("work failed:", err)
- }
- }()
- do(work)
-}
-</pre>
-
-<p>
-In this example, if <code>do(work)</code> panics, the result will be
-logged and the goroutine will exit cleanly without disturbing the
-others. There's no need to do anything else in the deferred closure;
-calling <code>recover</code> handles the condition completely.
-</p>
-
-<p>
-Because <code>recover</code> always returns <code>nil</code> unless called directly
-from a deferred function, deferred code can call library routines that themselves
-use <code>panic</code> and <code>recover</code> without failing. As an example,
-the deferred function in <code>safelyDo</code> might call a logging function before
-calling <code>recover</code>, and that logging code would run unaffected
-by the panicking state.
-</p>
-
-<p>
-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
-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.
-</p>
-
-<pre>
-// Error is the type of a parse error; it satisfies the error interface.
-type Error string
-func (e Error) Error() string {
- return string(e)
-}
-
-// error is a method of *Regexp that reports parsing errors by
-// panicking with an Error.
-func (regexp *Regexp) error(err string) {
- panic(Error(err))
-}
-
-// Compile returns a parsed representation of the regular expression.
-func Compile(str string) (regexp *Regexp, err error) {
- regexp = new(Regexp)
- // doParse will panic if there is a parse error.
- defer func() {
- if e := recover(); e != nil {
- regexp = nil // Clear return value.
- err = e.(Error) // Will re-panic if not a parse error.
- }
- }()
- return regexp.doParse(str), nil
-}
-</pre>
-
-<p>
-If <code>doParse</code> panics, the recovery block will set the
-return value to <code>nil</code>—deferred functions can modify
-named return values. It then 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
-as an array 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.
-</p>
-
-<p>
-With error handling in place, the <code>error</code> method
-makes it easy to report parse errors without worrying about unwinding
-the parse stack by hand.
-</p>
-
-<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
-<code>error</code> values; it does not expose <code>panics</code>
-to its client. That is a good rule to follow.
-</p>
-
-<p>
-By the way, this re-panic idiom changes the panic value if an actual
-error occurs. However, both the original and new failures will be
-presented in the crash report, so the root cause of the problem will
-still be visible. Thus this simple re-panic approach is usually
-sufficient—it's a crash after all—but if you want to
-display only the original value, you can write a little more code to
-filter unexpected problems and re-panic with the original error.
-That's left as an exercise for the reader.
-</p>
-
-
-<h2 id="web_server">A web server</h2>
-
-<p>
-Let's finish with a complete Go program, a web server.
-This one is actually a kind of web re-server.
-Google provides a service at
-<a href="http://chart.apis.google.com">http://chart.apis.google.com</a>
-that does automatic formatting of data into charts and graphs.
-It's hard to use interactively, though,
-because you need to put the data into the URL as a query.
-The program here provides a nicer interface to one form of data: given a short piece of text,
-it calls on the chart server to produce a QR code, a matrix of boxes that encode the
-text.
-That image can be grabbed with your cell phone's camera and interpreted as,
-for instance, a URL, saving you typing the URL into the phone's tiny keyboard.
-</p>
-<p>
-Here's the complete program.
-An explanation follows.
-</p>
-{{code "progs/eff_qr.go"}}
-<p>
-The pieces up to <code>main</code> should be easy to follow.
-The one flag sets a default HTTP port for our server. The template
-variable <code>templ</code> is where the fun happens. It builds an HTML template
-that will be executed by the server to display the page; more about
-that in a moment.
-</p>
-<p>
-The <code>main</code> function parses the flags and, using the mechanism
-we talked about above, binds the function <code>QR</code> to the root path
-for the server. Then <code>http.ListenAndServe</code> is called to start the
-server; it blocks while the server runs.
-</p>
-<p>
-<code>QR</code> just receives the request, which contains form data, and
-executes the template on the data in the form value named <code>s</code>.
-</p>
-<p>
-The template package is powerful;
-this program just touches on its capabilities.
-In essence, it rewrites a piece of text on the fly by substituting elements derived
-from data items passed to <code>templ.Execute</code>, in this case the
-form value.
-Within the template text (<code>templateStr</code>),
-double-brace-delimited pieces denote template actions.
-The piece from <code>{{html "{{if .}}"}}</code>
-to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
-is non-empty.
-That is, when the string is empty, this piece of the template is suppressed.
-</p>
-<p>
-The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
-<code>urlquery</code>, which sanitizes the query string
-for safe display on the web page.
-</p>
-<p>
-The rest of the template string is just the HTML to show when the page loads.
-If this is too quick an explanation, see the <a href="/pkg/template/">documentation</a>
-for the template package for a more thorough discussion.
-</p>
-<p>
-And there you have it: a useful webserver in a few lines of code plus some
-data-driven HTML text.
-Go is powerful enough to make a lot happen in a few lines.
-</p>
-
-<!--
-TODO
-<pre>
-verifying implementation
-type Color uint32
-
-// Check that Color implements image.Color and image.Image
-var _ image.Color = Black
-var _ image.Image = Black
-</pre>
--->
-
<!--{
- "Title": "Go 1 Release Notes"
+ "Title": "Go 1 Release Notes",
+ "Template": true
}-->
-<!--
- DO NOT EDIT: created by
- tmpltohtml go1.tmpl
--->
-
<h2 id="introduction">Introduction to Go 1</h2>
which is another common case.
</p>
-<pre><!--{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
---> greeting := []byte{}
- greeting = append(greeting, []byte("hello ")...)</pre>
+{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
<p>
By analogy with the similar property of <code>copy</code>, Go 1
The conversion is no longer necessary:
</p>
-<pre><!--{{code "progs/go1.go" `/append.*world/`}}
---> greeting = append(greeting, "world"...)</pre>
+{{code "/doc/progs/go1.go" `/append.*world/`}}
<p>
<em>Updating</em>:
All four of the initializations in this example are legal; the last one was illegal before Go 1.
</p>
-<pre><!--{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
---> type Date struct {
- month string
- day int
- }
- // Struct values, fully qualified; always legal.
- holiday1 := []Date{
- Date{"Feb", 14},
- Date{"Nov", 11},
- Date{"Dec", 25},
- }
- // Struct values, type name elided; always legal.
- holiday2 := []Date{
- {"Feb", 14},
- {"Nov", 11},
- {"Dec", 25},
- }
- // Pointers, fully qualified, always legal.
- holiday3 := []*Date{
- &Date{"Feb", 14},
- &Date{"Nov", 11},
- &Date{"Dec", 25},
- }
- // Pointers, type name elided; legal in Go 1.
- holiday4 := []*Date{
- {"Feb", 14},
- {"Nov", 11},
- {"Dec", 25},
- }</pre>
+{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}}
<p>
<em>Updating</em>:
without introducing a deadlock.
</p>
-<pre><!--{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
--->var PackageGlobal int
-
-func init() {
- c := make(chan int)
- go initializationFunction(c)
- PackageGlobal = <-c
-}</pre>
+{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}}
<p>
<em>Updating</em>:
relatives now take and return a <code>rune</code>.
</p>
-<pre><!--{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
---> delta := 'ฮด' // delta has type rune.
- var DELTA rune
- DELTA = unicode.ToUpper(delta)
- epsilon := unicode.ToLower(DELTA + 1)
- if epsilon != 'ฮด'+1 {
- log.Fatal("inconsistent casing for Greek")
- }</pre>
+{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
<p>
<em>Updating</em>:
function, <code>delete</code>. The call
</p>
-<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}}
---> delete(m, k)</pre>
+{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}}
<p>
will delete the map entry retrieved by the expression <code>m[k]</code>.
Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
</p>
-<pre><!--{{code "progs/go1.go" `/Sunday/` `/^ }/`}}
---> m := map[string]int{"Sunday": 0, "Monday": 1}
- for name, value := range m {
- // This loop should not assume Sunday will be visited first.
- f(name, value)
- }</pre>
+{{code "/doc/progs/go1.go" `/Sunday/` `/^ }/`}}
<p>
<em>Updating</em>:
These examples illustrate the behavior.
</p>
-<pre><!--{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
---> sa := []int{1, 2, 3}
- i := 0
- i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2
-
- sb := []int{1, 2, 3}
- j := 0
- sb[j], j = 2, 1 // sets sb[0] = 2, j = 1
-
- sc := []int{1, 2, 3}
- sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)</pre>
+{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
<p>
<em>Updating</em>:
using element-wise comparison.
</p>
-<pre><!--{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
---> type Day struct {
- long string
- short string
- }
- Christmas := Day{"Christmas", "XMas"}
- Thanksgiving := Day{"Thanksgiving", "Turkey"}
- holiday := map[Day]bool{
- Christmas: true,
- Thanksgiving: true,
- }
- fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])</pre>
+{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}}
<p>
Second, Go 1 removes the definition of equality for function values,
does for <code>String</code>, for easy printing of error values.
</p>
-<pre><!--{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
--->type SyntaxError struct {
- File string
- Line int
- Message string
-}
-
-func (se *SyntaxError) Error() string {
- return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
-}</pre>
+{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
<p>
All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
to turn a string into an error. It replaces the old <code>os.NewError</code>.
</p>
-<pre><!--{{code "progs/go1.go" `/ErrSyntax/`}}
---> var ErrSyntax = errors.New("syntax error")</pre>
+{{code "/doc/progs/go1.go" `/ErrSyntax/`}}
<p>
<em>Updating</em>:
API, an integer nanosecond count since the Unix epoch.
</p>
-<pre><!--{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
--->// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
-func sleepUntil(wakeup time.Time) {
- now := time.Now() // A Time.
- if !wakeup.After(now) {
- return
- }
- delta := wakeup.Sub(now) // A Duration.
- fmt.Printf("Sleeping for %.3fs\n", delta.Seconds())
- time.Sleep(delta)
-}</pre>
+{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}}
<p>
The new types, methods, and constants have been propagated through
formats them: <code>10s</code>, <code>1h30m</code>, etc.
</p>
-<pre><!--{{code "progs/go1.go" `/timeout/`}}
--->var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")</pre>
+{{code "/doc/progs/go1.go" `/timeout/`}}
<p>
<em>Updating</em>:
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
</p>
-<pre><!--{{code "progs/go1.go" `/os\.Open/` `/}/`}}
---> f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
- if os.IsExist(err) {
- log.Printf("%s already exists", name)
- }</pre>
+{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}}
<p>
<em>Updating</em>:
the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
</p>
-<pre><!--{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
---> markFn := func(path string, info os.FileInfo, err error) error {
- if path == "pictures" { // Will skip walking of directory pictures and its contents.
- return filepath.SkipDir
- }
- if err != nil {
- return err
- }
- log.Println(path)
- return nil
- }
- err := filepath.Walk(".", markFn)
- if err != nil {
- log.Fatal(err)
- }</pre>
+{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
<p>
<em>Updating</em>:
logging and failure reporting.
</p>
-<pre><!--{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
--->func BenchmarkSprintf(b *testing.B) {
- // Verify correctness before running benchmark.
- b.StopTimer()
- got := fmt.Sprintf("%x", 23)
- const expect = "17"
- if expect != got {
- b.Fatalf("expected %q; got %q", expect, got)
- }
- b.StartTimer()
- for i := 0; i < b.N; i++ {
- fmt.Sprintf("%x", 23)
- }
-}</pre>
+{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}}
<p>
<em>Updating</em>:
+++ /dev/null
-<!--{
- "Title": "Go 1 Release Notes"
-}-->
-{{donotedit}}
-
-<h2 id="introduction">Introduction to Go 1</h2>
-
-<p>
-Go version 1, Go 1 for short, defines a language and a set of core libraries
-that provide a stable foundation for creating reliable products, projects, and
-publications.
-</p>
-
-<p>
-The driving motivation for Go 1 is stability for its users. People should be able to
-write Go programs and expect that they will continue to compile and run without
-change, on a time scale of years, including in production environments such as
-Google App Engine. Similarly, people should be able to write books about Go, be
-able to say which version of Go the book is describing, and have that version
-number still be meaningful much later.
-</p>
-
-<p>
-Code that compiles in Go 1 should, with few exceptions, continue to compile and
-run throughout the lifetime of that version, even as we issue updates and bug
-fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes
-made to the language and library for subsequent releases of Go 1 may
-add functionality but will not break existing Go 1 programs.
-<a href="go1compat.html">The Go 1 compatibility document</a>
-explains the compatibility guidelines in more detail.
-</p>
-
-<p>
-Go 1 is a representation of Go as it used today, not a wholesale rethinking of
-the language. We avoided designing new features and instead focused on cleaning
-up problems and inconsistencies and improving portability. There are a number
-changes to the Go language and packages that we had considered for some time and
-prototyped but not released primarily because they are significant and
-backwards-incompatible. Go 1 was an opportunity to get them out, which is
-helpful for the long term, but also means that Go 1 introduces incompatibilities
-for old programs. Fortunately, the <code>go</code> <code>fix</code> tool can
-automate much of the work needed to bring programs up to the Go 1 standard.
-</p>
-
-<p>
-This document outlines the major changes in Go 1 that will affect programmers
-updating existing code; its reference point is the prior release, r60 (tagged as
-r60.3). It also explains how to update code from r60 to run under Go 1.
-</p>
-
-<h2 id="language">Changes to the language</h2>
-
-<h3 id="append">Append</h3>
-
-<p>
-The <code>append</code> predeclared variadic function makes it easy to grow a slice
-by adding elements to the end.
-A common use is to add bytes to the end of a byte slice when generating output.
-However, <code>append</code> did not provide a way to append a string to a <code>[]byte</code>,
-which is another common case.
-</p>
-
-{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
-
-<p>
-By analogy with the similar property of <code>copy</code>, Go 1
-permits a string to be appended (byte-wise) directly to a byte
-slice, reducing the friction between strings and byte slices.
-The conversion is no longer necessary:
-</p>
-
-{{code "progs/go1.go" `/append.*world/`}}
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes.
-</p>
-
-<h3 id="close">Close</h3>
-
-<p>
-The <code>close</code> predeclared function provides a mechanism
-for a sender to signal that no more values will be sent.
-It is important to the implementation of <code>for</code> <code>range</code>
-loops over channels and is helpful in other situations.
-Partly by design and partly because of race conditions that can occur otherwise,
-it is intended for use only by the goroutine sending on the channel,
-not by the goroutine receiving data.
-However, before Go 1 there was no compile-time checking that <code>close</code>
-was being used correctly.
-</p>
-
-<p>
-To close this gap, at least in part, Go 1 disallows <code>close</code> on receive-only channels.
-Attempting to close such a channel is a compile-time error.
-</p>
-
-<pre>
- var c chan int
- var csend chan<- int = c
- var crecv <-chan int = c
- close(c) // legal
- close(csend) // legal
- close(crecv) // illegal
-</pre>
-
-<p>
-<em>Updating</em>:
-Existing code that attempts to close a receive-only channel was
-erroneous even before Go 1 and should be fixed. The compiler will
-now reject such code.
-</p>
-
-<h3 id="literals">Composite literals</h3>
-
-<p>
-In Go 1, a composite literal of array, slice, or map type can elide the
-type specification for the elements' initializers if they are of pointer type.
-All four of the initializations in this example are legal; the last one was illegal before Go 1.
-</p>
-
-{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
-
-<p>
-<em>Updating</em>:
-This change has no effect on existing code, but the command
-<code>gofmt</code> <code>-s</code> applied to existing source
-will, among other things, elide explicit element types wherever permitted.
-</p>
-
-
-<h3 id="init">Goroutines during init</h3>
-
-<p>
-The old language defined that <code>go</code> statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete.
-This introduced clumsiness in many places and, in effect, limited the utility
-of the <code>init</code> construct:
-if it was possible for another package to use the library during initialization, the library
-was forced to avoid goroutines.
-This design was done for reasons of simplicity and safety but,
-as our confidence in the language grew, it seemed unnecessary.
-Running goroutines during initialization is no more complex or unsafe than running them during normal execution.
-</p>
-
-<p>
-In Go 1, code that uses goroutines can be called from
-<code>init</code> routines and global initialization expressions
-without introducing a deadlock.
-</p>
-
-{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes,
-although it's possible that code that depends on goroutines not starting before <code>main</code> will break.
-There was no such code in the standard repository.
-</p>
-
-<h3 id="rune">The rune type</h3>
-
-<p>
-The language spec allows the <code>int</code> type to be 32 or 64 bits wide, but current implementations set <code>int</code> to 32 bits even on 64-bit platforms.
-It would be preferable to have <code>int</code> be 64 bits on 64-bit platforms.
-(There are important consequences for indexing large slices.)
-However, this change would waste space when processing Unicode characters with
-the old language because the <code>int</code> type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if <code>int</code> grew from 32 bits to 64.
-</p>
-
-<p>
-To make changing to 64-bit <code>int</code> feasible,
-Go 1 introduces a new basic type, <code>rune</code>, to represent
-individual Unicode code points.
-It is an alias for <code>int32</code>, analogous to <code>byte</code>
-as an alias for <code>uint8</code>.
-</p>
-
-<p>
-Character literals such as <code>'a'</code>, <code>'่ช'</code>, and <code>'\u0345'</code>
-now have default type <code>rune</code>,
-analogous to <code>1.0</code> having default type <code>float64</code>.
-A variable initialized to a character constant will therefore
-have type <code>rune</code> unless otherwise specified.
-</p>
-
-<p>
-Libraries have been updated to use <code>rune</code> rather than <code>int</code>
-when appropriate. For instance, the functions <code>unicode.ToLower</code> and
-relatives now take and return a <code>rune</code>.
-</p>
-
-{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
-
-<p>
-<em>Updating</em>:
-Most source code will be unaffected by this because the type inference from
-<code>:=</code> initializers introduces the new type silently, and it propagates
-from there.
-Some code may get type errors that a trivial conversion will resolve.
-</p>
-
-<h3 id="error">The error type</h3>
-
-<p>
-Go 1 introduces a new built-in type, <code>error</code>, which has the following definition:
-</p>
-
-<pre>
- type error interface {
- Error() string
- }
-</pre>
-
-<p>
-Since the consequences of this type are all in the package library,
-it is discussed <a href="#errors">below</a>.
-</p>
-
-<h3 id="delete">Deleting from maps</h3>
-
-<p>
-In the old language, to delete the entry with key <code>k</code> from map <code>m</code>, one wrote the statement,
-</p>
-
-<pre>
- m[k] = value, false
-</pre>
-
-<p>
-This syntax was a peculiar special case, the only two-to-one assignment.
-It required passing a value (usually ignored) that is evaluated but discarded,
-plus a boolean that was nearly always the constant <code>false</code>.
-It did the job but was odd and a point of contention.
-</p>
-
-<p>
-In Go 1, that syntax has gone; instead there is a new built-in
-function, <code>delete</code>. The call
-</p>
-
-{{code "progs/go1.go" `/delete\(m, k\)/`}}
-
-<p>
-will delete the map entry retrieved by the expression <code>m[k]</code>.
-There is no return value. Deleting a non-existent entry is a no-op.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = value,
-false</code> into <code>delete(m, k)</code> when it is clear that
-the ignored value can be safely discarded from the program and
-<code>false</code> refers to the predefined boolean constant.
-The fix tool
-will flag other uses of the syntax for inspection by the programmer.
-</p>
-
-<h3 id="iteration">Iterating in maps</h3>
-
-<p>
-The old language specification did not define the order of iteration for maps,
-and in practice it differed across hardware platforms.
-This caused tests that iterated over maps to be fragile and non-portable, with the
-unpleasant property that a test might always pass on one machine but break on another.
-</p>
-
-<p>
-In Go 1, the order in which elements are visited when iterating
-over a map using a <code>for</code> <code>range</code> statement
-is defined to be unpredictable, even if the same loop is run multiple
-times with the same map.
-Code should not assume that the elements are visited in any particular order.
-</p>
-
-<p>
-This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem.
-Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.
-</p>
-
-{{code "progs/go1.go" `/Sunday/` `/^ }/`}}
-
-<p>
-<em>Updating</em>:
-This is one change where tools cannot help. Most existing code
-will be unaffected, but some programs may break or misbehave; we
-recommend manual checking of all range statements over maps to
-verify they do not depend on iteration order. There were a few such
-examples in the standard repository; they have been fixed.
-Note that it was already incorrect to depend on the iteration order, which
-was unspecified. This change codifies the unpredictability.
-</p>
-
-<h3 id="multiple_assignment">Multiple assignment</h3>
-
-<p>
-The language specification has long guaranteed that in assignments
-the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned.
-To guarantee predictable behavior,
-Go 1 refines the specification further.
-</p>
-
-<p>
-If the left-hand side of the assignment
-statement contains expressions that require evaluation, such as
-function calls or array indexing operations, these will all be done
-using the usual left-to-right rule before any variables are assigned
-their value. Once everything is evaluated, the actual assignments
-proceed in left-to-right order.
-</p>
-
-<p>
-These examples illustrate the behavior.
-</p>
-
-{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
-
-<p>
-<em>Updating</em>:
-This is one change where tools cannot help, but breakage is unlikely.
-No code in the standard repository was broken by this change, and code
-that depended on the previous unspecified behavior was already incorrect.
-</p>
-
-<h3 id="shadowing">Returns and shadowed variables</h3>
-
-<p>
-A common mistake is to use <code>return</code> (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable.
-This situation is called <em>shadowing</em>: the result variable has been shadowed by another variable with the same name declared in an inner scope.
-</p>
-
-<p>
-In functions with named return values,
-the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement.
-(It isn't part of the specification, because this is one area we are still exploring;
-the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)
-</p>
-
-<p>
-This function implicitly returns a shadowed return value and will be rejected by the compiler:
-</p>
-
-<pre>
- func Bug() (i, j, k int) {
- for i = 0; i < 5; i++ {
- for j := 0; j < 5; j++ { // Redeclares j.
- k += i*j
- if k > 100 {
- return // Rejected: j is shadowed here.
- }
- }
- }
- return // OK: j is not shadowed here.
- }
-</pre>
-
-<p>
-<em>Updating</em>:
-Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand.
-The few cases that arose in the standard repository were mostly bugs.
-</p>
-
-<h3 id="unexported">Copying structs with unexported fields</h3>
-
-<p>
-The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package.
-There was, however, a required exception for a method receiver;
-also, the implementations of <code>copy</code> and <code>append</code> have never honored the restriction.
-</p>
-
-<p>
-Go 1 will allow packages to copy struct values containing unexported fields from other packages.
-Besides resolving the inconsistency,
-this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface.
-The new implementations of <code>time.Time</code> and
-<code>reflect.Value</code> are examples of types taking advantage of this new property.
-</p>
-
-<p>
-As an example, if package <code>p</code> includes the definitions,
-</p>
-
-<pre>
- type Struct struct {
- Public int
- secret int
- }
- func NewStruct(a int) Struct { // Note: not a pointer.
- return Struct{a, f(a)}
- }
- func (s Struct) String() string {
- return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
- }
-</pre>
-
-<p>
-a package that imports <code>p</code> can assign and copy values of type
-<code>p.Struct</code> at will.
-Behind the scenes the unexported fields will be assigned and copied just
-as if they were exported,
-but the client code will never be aware of them. The code
-</p>
-
-<pre>
- import "p"
-
- myStruct := p.NewStruct(23)
- copyOfMyStruct := myStruct
- fmt.Println(myStruct, copyOfMyStruct)
-</pre>
-
-<p>
-will show that the secret field of the struct has been copied to the new value.
-</p>
-
-<p>
-<em>Updating</em>:
-This is a new feature, so existing code needs no changes.
-</p>
-
-<h3 id="equality">Equality</h3>
-
-<p>
-Before Go 1, the language did not define equality on struct and array values.
-This meant,
-among other things, that structs and arrays could not be used as map keys.
-On the other hand, Go did define equality on function and map values.
-Function equality was problematic in the presence of closures
-(when are two closures equal?)
-while map equality compared pointers, not the maps' content, which was usually
-not what the user would want.
-</p>
-
-<p>
-Go 1 addressed these issues.
-First, structs and arrays can be compared for equality and inequality
-(<code>==</code> and <code>!=</code>),
-and therefore be used as map keys,
-provided they are composed from elements for which equality is also defined,
-using element-wise comparison.
-</p>
-
-{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
-
-<p>
-Second, Go 1 removes the definition of equality for function values,
-except for comparison with <code>nil</code>.
-Finally, map equality is gone too, also except for comparison with <code>nil</code>.
-</p>
-
-<p>
-Note that equality is still undefined for slices, for which the
-calculation is in general infeasible. Also note that the ordered
-comparison operators (<code><</code> <code><=</code>
-<code>></code> <code>>=</code>) are still undefined for
-structs and arrays.
-
-<p>
-<em>Updating</em>:
-Struct and array equality is a new feature, so existing code needs no changes.
-Existing code that depends on function or map equality will be
-rejected by the compiler and will need to be fixed by hand.
-Few programs will be affected, but the fix may require some
-redesign.
-</p>
-
-<h2 id="packages">The package hierarchy</h2>
-
-<p>
-Go 1 addresses many deficiencies in the old standard library and
-cleans up a number of packages, making them more internally consistent
-and portable.
-</p>
-
-<p>
-This section describes how the packages have been rearranged in Go 1.
-Some have moved, some have been renamed, some have been deleted.
-New packages are described in later sections.
-</p>
-
-<h3 id="hierarchy">The package hierarchy</h3>
-
-<p>
-Go 1 has a rearranged package hierarchy that groups related items
-into subdirectories. For instance, <code>utf8</code> and
-<code>utf16</code> now occupy subdirectories of <code>unicode</code>.
-Also, <a href="#subrepo">some packages</a> have moved into
-subrepositories of
-<a href="http://code.google.com/p/go"><code>code.google.com/p/go</code></a>
-while <a href="#deleted">others</a> have been deleted outright.
-</p>
-
-<table class="codetable" frame="border" summary="Moved packages">
-<colgroup align="left" width="60%"></colgroup>
-<colgroup align="left" width="40%"></colgroup>
-<tr>
-<th align="left">Old path</th>
-<th align="left">New path</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>asn1</td> <td>encoding/asn1</td></tr>
-<tr><td>csv</td> <td>encoding/csv</td></tr>
-<tr><td>gob</td> <td>encoding/gob</td></tr>
-<tr><td>json</td> <td>encoding/json</td></tr>
-<tr><td>xml</td> <td>encoding/xml</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>exp/template/html</td> <td>html/template</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>big</td> <td>math/big</td></tr>
-<tr><td>cmath</td> <td>math/cmplx</td></tr>
-<tr><td>rand</td> <td>math/rand</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>http</td> <td>net/http</td></tr>
-<tr><td>http/cgi</td> <td>net/http/cgi</td></tr>
-<tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr>
-<tr><td>http/httptest</td> <td>net/http/httptest</td></tr>
-<tr><td>http/pprof</td> <td>net/http/pprof</td></tr>
-<tr><td>mail</td> <td>net/mail</td></tr>
-<tr><td>rpc</td> <td>net/rpc</td></tr>
-<tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr>
-<tr><td>smtp</td> <td>net/smtp</td></tr>
-<tr><td>url</td> <td>net/url</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>exec</td> <td>os/exec</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>scanner</td> <td>text/scanner</td></tr>
-<tr><td>tabwriter</td> <td>text/tabwriter</td></tr>
-<tr><td>template</td> <td>text/template</td></tr>
-<tr><td>template/parse</td> <td>text/template/parse</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>utf8</td> <td>unicode/utf8</td></tr>
-<tr><td>utf16</td> <td>unicode/utf16</td></tr>
-</table>
-
-<p>
-Note that the package names for the old <code>cmath</code> and
-<code>exp/template/html</code> packages have changed to <code>cmplx</code>
-and <code>template</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update all imports and package renames for packages that
-remain inside the standard repository. Programs that import packages
-that are no longer in the standard repository will need to be edited
-by hand.
-</p>
-
-<h3 id="exp">The package tree exp</h3>
-
-<p>
-Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
-standard Go 1 release distributions, although they will be available in source code form
-in <a href="http://code.google.com/p/go/">the repository</a> for
-developers who wish to use them.
-</p>
-
-<p>
-Several packages have moved under <code>exp</code> at the time of Go 1's release:
-</p>
-
-<ul>
-<li><code>ebnf</code></li>
-<li><code>html</code><sup>†</sup></li>
-<li><code>go/types</code></li>
-</ul>
-
-<p>
-(<sup>†</sup>The <code>EscapeString</code> and <code>UnescapeString</code> types remain
-in package <code>html</code>.)
-</p>
-
-<p>
-All these packages are available under the same names, with the prefix <code>exp/</code>: <code>exp/ebnf</code> etc.
-</p>
-
-<p>
-Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>.
-</p>
-
-<p>
-Finally, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
-<code>ebnflint</code> is now in <code>exp/ebnflint</code>.
-If they are installed, they now reside in <code>$GOROOT/bin/tool</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses packages in <code>exp</code> will need to be updated by hand,
-or else compiled from an installation that has <code>exp</code> available.
-The <code>go</code> <code>fix</code> tool or the compiler will complain about such uses.
-</p>
-
-<h3 id="old">The package tree old</h3>
-
-<p>
-Because they are deprecated, the packages under the <code>old</code> directory will not be available in the
-standard Go 1 release distributions, although they will be available in source code form for
-developers who wish to use them.
-</p>
-
-<p>
-The packages in their new locations are:
-</p>
-
-<ul>
-<li><code>old/netchan</code></li>
-<li><code>old/regexp</code></li>
-<li><code>old/template</code></li>
-</ul>
-
-<p>
-<em>Updating</em>:
-Code that uses packages now in <code>old</code> will need to be updated by hand,
-or else compiled from an installation that has <code>old</code> available.
-The <code>go</code> <code>fix</code> tool will warn about such uses.
-</p>
-
-<h3 id="deleted">Deleted packages</h3>
-
-<p>
-Go 1 deletes several packages outright:
-</p>
-
-<ul>
-<li><code>container/vector</code></li>
-<li><code>exp/datafmt</code></li>
-<li><code>go/typechecker</code></li>
-<li><code>try</code></li>
-</ul>
-
-<p>
-and also the command <code>gotry</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses <code>container/vector</code> should be updated to use
-slices directly. See
-<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
-Language Community Wiki</a> for some suggestions.
-Code that uses the other packages (there should be almost zero) will need to be rethought.
-</p>
-
-<h3 id="subrepo">Packages moving to subrepositories</h3>
-
-<p>
-Go 1 has moved a number of packages into other repositories, usually sub-repositories of
-<a href="http://code.google.com/p/go/">the main Go repository</a>.
-This table lists the old and new import paths:
-
-<table class="codetable" frame="border" summary="Sub-repositories">
-<colgroup align="left" width="40%"></colgroup>
-<colgroup align="left" width="60%"></colgroup>
-<tr>
-<th align="left">Old</th>
-<th align="left">New</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>crypto/bcrypt</td> <td>code.google.com/p/go.crypto/bcrypt</tr>
-<tr><td>crypto/blowfish</td> <td>code.google.com/p/go.crypto/blowfish</tr>
-<tr><td>crypto/cast5</td> <td>code.google.com/p/go.crypto/cast5</tr>
-<tr><td>crypto/md4</td> <td>code.google.com/p/go.crypto/md4</tr>
-<tr><td>crypto/ocsp</td> <td>code.google.com/p/go.crypto/ocsp</tr>
-<tr><td>crypto/openpgp</td> <td>code.google.com/p/go.crypto/openpgp</tr>
-<tr><td>crypto/openpgp/armor</td> <td>code.google.com/p/go.crypto/openpgp/armor</tr>
-<tr><td>crypto/openpgp/elgamal</td> <td>code.google.com/p/go.crypto/openpgp/elgamal</tr>
-<tr><td>crypto/openpgp/errors</td> <td>code.google.com/p/go.crypto/openpgp/errors</tr>
-<tr><td>crypto/openpgp/packet</td> <td>code.google.com/p/go.crypto/openpgp/packet</tr>
-<tr><td>crypto/openpgp/s2k</td> <td>code.google.com/p/go.crypto/openpgp/s2k</tr>
-<tr><td>crypto/ripemd160</td> <td>code.google.com/p/go.crypto/ripemd160</tr>
-<tr><td>crypto/twofish</td> <td>code.google.com/p/go.crypto/twofish</tr>
-<tr><td>crypto/xtea</td> <td>code.google.com/p/go.crypto/xtea</tr>
-<tr><td>exp/ssh</td> <td>code.google.com/p/go.crypto/ssh</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image/bmp</td> <td>code.google.com/p/go.image/bmp</tr>
-<tr><td>image/tiff</td> <td>code.google.com/p/go.image/tiff</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>net/dict</td> <td>code.google.com/p/go.net/dict</tr>
-<tr><td>net/websocket</td> <td>code.google.com/p/go.net/websocket</tr>
-<tr><td>exp/spdy</td> <td>code.google.com/p/go.net/spdy</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
-<tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr>
-</table>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update imports of these packages to use the new import paths.
-Installations that depend on these packages will need to install them using
-a <code>go install</code> command.
-</p>
-
-<h2 id="major">Major changes to the library</h2>
-
-<p>
-This section describes significant changes to the core libraries, the ones that
-affect the most programs.
-</p>
-
-<h3 id="errors">The error type and errors package</h3>
-
-<p>
-The placement of <code>os.Error</code> in package <code>os</code> is mostly historical: errors first came up when implementing package <code>os</code>, and they seemed system-related at the time.
-Since then it has become clear that errors are more fundamental than the operating system. For example, it would be nice to use <code>Errors</code> in packages that <code>os</code> depends on, like <code>syscall</code>.
-Also, having <code>Error</code> in <code>os</code> introduces many dependencies on <code>os</code> that would otherwise not exist.
-</p>
-
-<p>
-Go 1 solves these problems by introducing a built-in <code>error</code> interface type and a separate <code>errors</code> package (analogous to <code>bytes</code> and <code>strings</code>) that contains utility functions.
-It replaces <code>os.NewError</code> with
-<a href="/pkg/errors/#New"><code>errors.New</code></a>,
-giving errors a more central place in the environment.
-</p>
-
-<p>
-So the widely-used <code>String</code> method does not cause accidental satisfaction
-of the <code>error</code> interface, the <code>error</code> interface uses instead
-the name <code>Error</code> for that method:
-</p>
-
-<pre>
- type error interface {
- Error() string
- }
-</pre>
-
-<p>
-The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
-does for <code>String</code>, for easy printing of error values.
-</p>
-
-{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
-
-<p>
-All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
-</p>
-
-<p>
-A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
-</p>
-
-<pre>
-func New(text string) error
-</pre>
-
-<p>
-to turn a string into an error. It replaces the old <code>os.NewError</code>.
-</p>
-
-{{code "progs/go1.go" `/ErrSyntax/`}}
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-Code that defines error types with a <code>String</code> method will need to be updated
-by hand to rename the methods to <code>Error</code>.
-</p>
-
-<h3 id="errno">System call errors</h3>
-
-<p>
-The old <code>syscall</code> package, which predated <code>os.Error</code>
-(and just about everything else),
-returned errors as <code>int</code> values.
-In turn, the <code>os</code> package forwarded many of these errors, such
-as <code>EINVAL</code>, but using a different set of errors on each platform.
-This behavior was unpleasant and unportable.
-</p>
-
-<p>
-In Go 1, the
-<a href="/pkg/syscall/"><code>syscall</code></a>
-package instead returns an <code>error</code> for system call errors.
-On Unix, the implementation is done by a
-<a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
-that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
-</p>
-
-<p>
-The changes affecting <code>os.EINVAL</code> and relatives are
-described <a href="#os">elsewhere</a>.
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-Regardless, most code should use the <code>os</code> package
-rather than <code>syscall</code> and so will be unaffected.
-</p>
-
-<h3 id="time">Time</h3>
-
-<p>
-Time is always a challenge to support well in a programming language.
-The old Go <code>time</code> package had <code>int64</code> units, no
-real type safety,
-and no distinction between absolute times and durations.
-</p>
-
-<p>
-One of the most sweeping changes in the Go 1 library is therefore a
-complete redesign of the
-<a href="/pkg/time/"><code>time</code></a> package.
-Instead of an integer number of nanoseconds as an <code>int64</code>,
-and a separate <code>*time.Time</code> type to deal with human
-units such as hours and years,
-there are now two fundamental types:
-<a href="/pkg/time/#Time"><code>time.Time</code></a>
-(a value, so the <code>*</code> is gone), which represents a moment in time;
-and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
-which represents an interval.
-Both have nanosecond resolution.
-A <code>Time</code> can represent any time into the ancient
-past and remote future, while a <code>Duration</code> can
-span plus or minus only about 290 years.
-There are methods on these types, plus a number of helpful
-predefined constant durations such as <code>time.Second</code>.
-</p>
-
-<p>
-Among the new methods are things like
-<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
-which adds a <code>Duration</code> to a <code>Time</code>, and
-<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
-which subtracts two <code>Times</code> to yield a <code>Duration</code>.
-</p>
-
-<p>
-The most important semantic change is that the Unix epoch (Jan 1, 1970) is now
-relevant only for those functions and methods that mention Unix:
-<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
-and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
-and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
-of the <code>Time</code> type.
-In particular,
-<a href="/pkg/time/#Now"><code>time.Now</code></a>
-returns a <code>time.Time</code> value rather than, in the old
-API, an integer nanosecond count since the Unix epoch.
-</p>
-
-{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
-
-<p>
-The new types, methods, and constants have been propagated through
-all the standard packages that use time, such as <code>os</code> and
-its representation of file time stamps.
-</p>
-
-<p>
-<em>Updating</em>:
-The <code>go</code> <code>fix</code> tool will update many uses of the old <code>time</code> package to use the new
-types and methods, although it does not replace values such as <code>1e9</code>
-representing nanoseconds per second.
-Also, because of type changes in some of the values that arise,
-some of the expressions rewritten by the fix tool may require
-further hand editing; in such cases the rewrite will include
-the correct function or method for the old functionality, but
-may have the wrong type or require further analysis.
-</p>
-
-<h2 id="minor">Minor changes to the library</h2>
-
-<p>
-This section describes smaller changes, such as those to less commonly
-used packages or that affect
-few programs beyond the need to run <code>go</code> <code>fix</code>.
-This category includes packages that are new in Go 1.
-Collectively they improve portability, regularize behavior, and
-make the interfaces more modern and Go-like.
-</p>
-
-<h3 id="archive_zip">The archive/zip package</h3>
-
-<p>
-In Go 1, <a href="/pkg/archive/zip/#Writer"><code>*zip.Writer</code></a> no
-longer has a <code>Write</code> method. Its presence was a mistake.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="bufio">The bufio package</h3>
-
-<p>
-In Go 1, <a href="/pkg/bufio/#NewReaderSize"><code>bufio.NewReaderSize</code></a>
-and
-<a href="/pkg/bufio/#NewWriterSize"><code>bufio.NewWriterSize</code></a>
-functions no longer return an error for invalid sizes.
-If the argument size is too small or invalid, it is adjusted.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update calls that assign the error to _.
-Calls that aren't fixed will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="compress">The compress/flate, compress/gzip and compress/zlib packages</h3>
-
-<p>
-In Go 1, the <code>NewWriterXxx</code> functions in
-<a href="/pkg/compress/flate"><code>compress/flate</code></a>,
-<a href="/pkg/compress/gzip"><code>compress/gzip</code></a> and
-<a href="/pkg/compress/zlib"><code>compress/zlib</code></a>
-all return <code>(*Writer, error)</code> if they take a compression level,
-and <code>*Writer</code> otherwise. Package <code>gzip</code>'s
-<code>Compressor</code> and <code>Decompressor</code> types have been renamed
-to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>'s
-<code>WrongValueError</code> type has been removed.
-</p>
-
-<p>
-<em>Updating</em>
-Running <code>go</code> <code>fix</code> will update old names and calls that assign the error to _.
-Calls that aren't fixed will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="crypto_aes_des">The crypto/aes and crypto/des packages</h3>
-
-<p>
-In Go 1, the <code>Reset</code> method has been removed. Go does not guarantee
-that memory is not copied and therefore this method was misleading.
-</p>
-
-<p>
-The cipher-specific types <code>*aes.Cipher</code>, <code>*des.Cipher</code>,
-and <code>*des.TripleDESCipher</code> have been removed in favor of
-<code>cipher.Block</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Remove the calls to Reset. Replace uses of the specific cipher types with
-cipher.Block.
-</p>
-
-<h3 id="crypto_elliptic">The crypto/elliptic package</h3>
-
-<p>
-In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
-has been made an interface to permit alternative implementations. The curve
-parameters have been moved to the
-<a href="/pkg/crypto/elliptic/#CurveParams"><code>elliptic.CurveParams</code></a>
-structure.
-</p>
-
-<p>
-<em>Updating</em>:
-Existing users of <code>*elliptic.Curve</code> will need to change to
-simply <code>elliptic.Curve</code>. Calls to <code>Marshal</code>,
-<code>Unmarshal</code> and <code>GenerateKey</code> are now functions
-in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
-as their first argument.
-</p>
-
-<h3 id="crypto_hmac">The crypto/hmac package</h3>
-
-<p>
-In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
-been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
-a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will perform the needed changes.
-</p>
-
-<h3 id="crypto_x509">The crypto/x509 package</h3>
-
-<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
-<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.
-</p>
-
-<p>
-<em>Updating</em>:
-No changes will be needed.
-</p>
-
-<h3 id="encoding_binary">The encoding/binary package</h3>
-
-<p>
-In Go 1, the <code>binary.TotalSize</code> function has been replaced by
-<a href="/pkg/encoding/binary/#Size"><code>Size</code></a>,
-which takes an <code>interface{}</code> argument rather than
-a <code>reflect.Value</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="encoding_xml">The encoding/xml package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package
-has been brought closer in design to the other marshaling packages such
-as <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a>.
-</p>
-
-<p>
-The old <code>Parser</code> type is renamed
-<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> and has a new
-<a href="/pkg/encoding/xml/#Decoder.Decode"><code>Decode</code></a> method. An
-<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> type was also introduced.
-</p>
-
-<p>
-The functions <a href="/pkg/encoding/xml/#Marshal"><code>Marshal</code></a>
-and <a href="/pkg/encoding/xml/#Unmarshal"><code>Unmarshal</code></a>
-work with <code>[]byte</code> values now. To work with streams,
-use the new <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>
-and <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> types.
-</p>
-
-<p>
-When marshaling or unmarshaling values, the format of supported flags in
-field tags has changed to be closer to the
-<a href="/pkg/encoding/json"><code>json</code></a> package
-(<code>`xml:"name,flag"`</code>). The matching done between field tags, field
-names, and the XML attribute and element names is now case-sensitive.
-The <code>XMLName</code> field tag, if present, must also match the name
-of the XML element being marshaled.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update most uses of the package except for some calls to
-<code>Unmarshal</code>. Special care must be taken with field tags,
-since the fix tool will not update them and if not fixed by hand they will
-misbehave silently in some cases. For example, the old
-<code>"attr"</code> is now written <code>",attr"</code> while plain
-<code>"attr"</code> remains valid but with a different meaning.
-</p>
-
-<h3 id="expvar">The expvar package</h3>
-
-<p>
-In Go 1, the <code>RemoveAll</code> function has been removed.
-The <code>Iter</code> function and Iter method on <code>*Map</code> have
-been replaced by
-<a href="/pkg/expvar/#Do"><code>Do</code></a>
-and
-<a href="/pkg/expvar/#Map.Do"><code>(*Map).Do</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Most code using <code>expvar</code> will not need changing. The rare code that used
-<code>Iter</code> can be updated to pass a closure to <code>Do</code> to achieve the same effect.
-</p>
-
-<h3 id="flag">The flag package</h3>
-
-<p>
-In Go 1, the interface <a href="/pkg/flag/#Value"><code>flag.Value</code></a> has changed slightly.
-The <code>Set</code> method now returns an <code>error</code> instead of
-a <code>bool</code> to indicate success or failure.
-</p>
-
-<p>
-There is also a new kind of flag, <code>Duration</code>, to support argument
-values specifying time intervals.
-Values for such flags must be given units, just as <code>time.Duration</code>
-formats them: <code>10s</code>, <code>1h30m</code>, etc.
-</p>
-
-{{code "progs/go1.go" `/timeout/`}}
-
-<p>
-<em>Updating</em>:
-Programs that implement their own flags will need minor manual fixes to update their
-<code>Set</code> methods.
-The <code>Duration</code> flag is new and affects no existing code.
-</p>
-
-
-<h3 id="go">The go/* packages</h3>
-
-<p>
-Several packages under <code>go</code> have slightly revised APIs.
-</p>
-
-<p>
-A concrete <code>Mode</code> type was introduced for configuration mode flags
-in the packages
-<a href="/pkg/go/scanner/"><code>go/scanner</code></a>,
-<a href="/pkg/go/parser/"><code>go/parser</code></a>,
-<a href="/pkg/go/printer/"><code>go/printer</code></a>, and
-<a href="/pkg/go/doc/"><code>go/doc</code></a>.
-</p>
-
-<p>
-The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
-from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly
-useful for scanning text other then Go source files. Instead, the
-<a href="/pkg/text/scanner/"><code>text/scanner</code></a> package should be used
-for that purpose.
-</p>
-
-<p>
-The <a href="/pkg/go/scanner/#ErrorHandler"><code>ErrorHandler</code></a> provided
-to the scanner's <a href="/pkg/go/scanner/#Scanner.Init"><code>Init</code></a> method is
-now simply a function rather than an interface. The <code>ErrorVector</code> type has
-been removed in favor of the (existing) <a href="/pkg/go/scanner/#ErrorList"><code>ErrorList</code></a>
-type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding
-an <code>ErrorVector</code> in a client of the scanner, now a client should maintain
-an <code>ErrorList</code>.
-</p>
-
-<p>
-The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
-package has been reduced to the primary parse function
-<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
-convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
-and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
-</p>
-
-<p>
-The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional
-configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
-if set, the printer will emit <code>//line</code> comments such that the generated
-output contains the original source code position information. The new type
-<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
-used to provide comments associated with an arbitrary
-<a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
-<a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
-</p>
-
-<p>
-The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
-streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
-is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
-Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,
-in the case of type <code>Value</code>) and <code>Type.Factories</code> has become
-<code>Type.Funcs</code>.
-Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>,
-documentation for a package is created with:
-</p>
-
-<pre>
- doc.New(pkg, importpath, mode)
-</pre>
-
-<p>
-where the new <code>mode</code> parameter specifies the operation mode:
-if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
-(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"><code>ast.CommentGroup</code></a>.
-</p>
-
-<p>
-In package <a href="/pkg/go/token/"><code>go/token</code></a>, the
-<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
-(which originally returned a channel of <code>*token.File</code>s) has been replaced
-with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that
-accepts a function argument instead.
-</p>
-
-<p>
-In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API
-has been nearly completely replaced.
-The package still computes Go package information
-but it does not run the build: the <code>Cmd</code> and <code>Script</code>
-types are gone.
-(To build code, use the new
-<a href="/cmd/go/"><code>go</code></a> command instead.)
-The <code>DirInfo</code> type is now named
-<a href="/pkg/go/build/#Package"><code>Package</code></a>.
-<code>FindTree</code> and <code>ScanDir</code> are replaced by
-<a href="/pkg/go/build/#Import"><code>Import</code></a>
-and
-<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses packages in <code>go</code> will have to be updated by hand; the
-compiler will reject incorrect uses. Templates used in conjunction with any of the
-<code>go/doc</code> types may need manual fixes; the renamed fields will lead
-to run-time errors.
-</p>
-
-<h3 id="hash">The hash package</h3>
-
-<p>
-In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
-a new method, <code>BlockSize</code>. This new method is used primarily in the
-cryptographic libraries.
-</p>
-
-<p>
-The <code>Sum</code> method of the
-<a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> interface now takes a
-<code>[]byte</code> argument, to which the hash value will be appended.
-The previous behavior can be recreated by adding a <code>nil</code> argument to the call.
-</p>
-
-<p>
-<em>Updating</em>:
-Existing implementations of <code>hash.Hash</code> will need to add a
-<code>BlockSize</code> method. Hashes that process the input one byte at
-a time can implement <code>BlockSize</code> to return 1.
-Running <code>go</code> <code>fix</code> will update calls to the <code>Sum</code> methods of the various
-implementations of <code>hash.Hash</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Since the package's functionality is new, no updating is necessary.
-</p>
-
-<h3 id="http">The http package</h3>
-
-<p>
-In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored,
-putting some of the utilities into a
-<a href="/pkg/net/httputil/"><code>httputil</code></a> subdirectory.
-These pieces are only rarely needed by HTTP clients.
-The affected items are:
-</p>
-
-<ul>
-<li>ClientConn</li>
-<li>DumpRequest</li>
-<li>DumpRequest</li>
-<li>DumpRequestOut</li>
-<li>DumpResponse</li>
-<li>NewChunkedReader</li>
-<li>NewChunkedWriter</li>
-<li>NewClientConn</li>
-<li>NewProxyClientConn</li>
-<li>NewServerConn</li>
-<li>NewSingleHostReverseProxy</li>
-<li>ReverseProxy</li>
-<li>ServerConn</li>
-</ul>
-
-<p>
-The <code>Request.RawURL</code> field has been removed; it was a
-historical artifact.
-</p>
-
-<p>
-The <code>Handle</code> and <code>HandleFunc</code>
-functions, and the similarly-named methods of <code>ServeMux</code>,
-now panic if an attempt is made to register the same pattern twice.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update the few programs that are affected except for
-uses of <code>RawURL</code>, which must be fixed by hand.
-</p>
-
-<h3 id="image">The image package</h3>
-
-<p>
-The <a href="/pkg/image/"><code>image</code></a> package has had a number of
-minor changes, rearrangements and renamings.
-</p>
-
-<p>
-Most of the color handling code has been moved into its own package,
-<a href="/pkg/image/color/"><code>image/color</code></a>.
-For the elements that moved, a symmetry arises; for instance,
-each pixel of an
-<a href="/pkg/image/#RGBA"><code>image.RGBA</code></a>
-is a
-<a href="/pkg/image/color/#RGBA"><code>color.RGBA</code></a>.
-</p>
-
-<p>
-The old <code>image/ycbcr</code> package has been folded, with some
-renamings, into the
-<a href="/pkg/image/"><code>image</code></a>
-and
-<a href="/pkg/image/color/"><code>image/color</code></a>
-packages.
-</p>
-
-<p>
-The old <code>image.ColorImage</code> type is still in the <code>image</code>
-package but has been renamed
-<a href="/pkg/image/#Uniform"><code>image.Uniform</code></a>,
-while <code>image.Tiled</code> has been removed.
-</p>
-
-<p>
-This table lists the renamings.
-</p>
-
-<table class="codetable" frame="border" summary="image renames">
-<colgroup align="left" width="50%"></colgroup>
-<colgroup align="left" width="50%"></colgroup>
-<tr>
-<th align="left">Old</th>
-<th align="left">New</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.Color</td> <td>color.Color</td></tr>
-<tr><td>image.ColorModel</td> <td>color.Model</td></tr>
-<tr><td>image.ColorModelFunc</td> <td>color.ModelFunc</td></tr>
-<tr><td>image.PalettedColorModel</td> <td>color.Palette</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.RGBAColor</td> <td>color.RGBA</td></tr>
-<tr><td>image.RGBA64Color</td> <td>color.RGBA64</td></tr>
-<tr><td>image.NRGBAColor</td> <td>color.NRGBA</td></tr>
-<tr><td>image.NRGBA64Color</td> <td>color.NRGBA64</td></tr>
-<tr><td>image.AlphaColor</td> <td>color.Alpha</td></tr>
-<tr><td>image.Alpha16Color</td> <td>color.Alpha16</td></tr>
-<tr><td>image.GrayColor</td> <td>color.Gray</td></tr>
-<tr><td>image.Gray16Color</td> <td>color.Gray16</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.RGBAColorModel</td> <td>color.RGBAModel</td></tr>
-<tr><td>image.RGBA64ColorModel</td> <td>color.RGBA64Model</td></tr>
-<tr><td>image.NRGBAColorModel</td> <td>color.NRGBAModel</td></tr>
-<tr><td>image.NRGBA64ColorModel</td> <td>color.NRGBA64Model</td></tr>
-<tr><td>image.AlphaColorModel</td> <td>color.AlphaModel</td></tr>
-<tr><td>image.Alpha16ColorModel</td> <td>color.Alpha16Model</td></tr>
-<tr><td>image.GrayColorModel</td> <td>color.GrayModel</td></tr>
-<tr><td>image.Gray16ColorModel</td> <td>color.Gray16Model</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>ycbcr.RGBToYCbCr</td> <td>color.RGBToYCbCr</td></tr>
-<tr><td>ycbcr.YCbCrToRGB</td> <td>color.YCbCrToRGB</td></tr>
-<tr><td>ycbcr.YCbCrColorModel</td> <td>color.YCbCrModel</td></tr>
-<tr><td>ycbcr.YCbCrColor</td> <td>color.YCbCr</td></tr>
-<tr><td>ycbcr.YCbCr</td> <td>image.YCbCr</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>ycbcr.SubsampleRatio444</td> <td>image.YCbCrSubsampleRatio444</td></tr>
-<tr><td>ycbcr.SubsampleRatio422</td> <td>image.YCbCrSubsampleRatio422</td></tr>
-<tr><td>ycbcr.SubsampleRatio420</td> <td>image.YCbCrSubsampleRatio420</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>image.ColorImage</td> <td>image.Uniform</td></tr>
-</table>
-
-<p>
-The image package's <code>New</code> functions
-(<a href="/pkg/image/#NewRGBA"><code>NewRGBA</code></a>,
-<a href="/pkg/image/#NewRGBA64"><code>NewRGBA64</code></a>, etc.)
-take an <a href="/pkg/image/#Rectangle"><code>image.Rectangle</code></a> as an argument
-instead of four integers.
-</p>
-
-<p>
-Finally, there are new predefined <code>color.Color</code> variables
-<a href="/pkg/image/color/#Black"><code>color.Black</code></a>,
-<a href="/pkg/image/color/#White"><code>color.White</code></a>,
-<a href="/pkg/image/color/#Opaque"><code>color.Opaque</code></a>
-and
-<a href="/pkg/image/color/#Transparent"><code>color.Transparent</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-</p>
-
-<h3 id="log_syslog">The log/syslog package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>
-function returns an error as well as a <code>log.Logger</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="mime">The mime package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
-of the <code>mime</code> package has been simplified to make it
-consistent with
-<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>.
-It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-What little code is affected will be caught by the compiler and must be updated by hand.
-</p>
-
-<h3 id="net">The net package</h3>
-
-<p>
-In Go 1, the various <code>SetTimeout</code>,
-<code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
-have been replaced with
-<a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
-<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and
-<a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
-respectively. Rather than taking a timeout value in nanoseconds that
-apply to any activity on the connection, the new methods set an
-absolute deadline (as a <code>time.Time</code> value) after which
-reads and writes will time out and no longer block.
-</p>
-
-<p>
-There are also new functions
-<a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a>
-to simplify timing out dialing a network address and
-<a href="/pkg/net/#ListenMulticastUDP"><code>net.ListenMulticastUDP</code></a>
-to allow multicast UDP to listen concurrently across multiple listeners.
-The <code>net.ListenMulticastUDP</code> function replaces the old
-<code>JoinGroup</code> and <code>LeaveGroup</code> methods.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the old methods will fail to compile and must be updated by hand.
-The semantic change makes it difficult for the fix tool to update automatically.
-</p>
-
-<h3 id="os">The os package</h3>
-
-<p>
-The <code>Time</code> function has been removed; callers should use
-the <a href="/pkg/time/#Time"><code>Time</code></a> type from the
-<code>time</code> package.
-</p>
-
-<p>
-The <code>Exec</code> function has been removed; callers should use
-<code>Exec</code> from the <code>syscall</code> package, where available.
-</p>
-
-<p>
-The <code>ShellExpand</code> function has been renamed to <a
-href="/pkg/os/#ExpandEnv"><code>ExpandEnv</code></a>.
-</p>
-
-<p>
-The <a href="/pkg/os/#NewFile"><code>NewFile</code></a> function
-now takes a <code>uintptr</code> fd, instead of an <code>int</code>.
-The <a href="/pkg/os/#File.Fd"><code>Fd</code></a> method on files now
-also returns a <code>uintptr</code>.
-</p>
-
-<p>
-There are no longer error constants such as <code>EINVAL</code>
-in the <code>os</code> package, since the set of values varied with
-the underlying operating system. There are new portable functions like
-<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>
-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>.
-</p>
-
-<p>
-The <code>Getenverror</code> function has been removed. To distinguish
-between a non-existent environment variable and an empty string,
-use <a href="/pkg/os/#Environ"><code>os.Environ</code></a> or
-<a href="/pkg/syscall/#Getenv"><code>syscall.Getenv</code></a>.
-</p>
-
-
-<p>
-The <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> method has
-dropped its option argument and the associated constants are gone
-from the package.
-Also, the function <code>Wait</code> is gone; only the method of
-the <code>Process</code> type persists.
-</p>
-
-<p>
-The <code>Waitmsg</code> type returned by
-<a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a>
-has been replaced with a more portable
-<a href="/pkg/os/#ProcessState"><code>ProcessState</code></a>
-type with accessor methods to recover information about the
-process.
-Because of changes to <code>Wait</code>, the <code>ProcessState</code>
-value always describes an exited process.
-Portability concerns simplified the interface in other ways, but the values returned by the
-<a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and
-<a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a>
-methods can be type-asserted to underlying system-specific data structures such as
-<a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and
-<a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>.
-All other changes will be caught by the compiler and must be updated by hand.
-</p>
-
-<h4 id="os_fileinfo">The os.FileInfo type</h4>
-
-<p>
-Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
-changing it from a struct to an interface:
-</p>
-
-<pre>
- type FileInfo interface {
- Name() string // base name of the file
- Size() int64 // length in bytes
- Mode() FileMode // file mode bits
- ModTime() time.Time // modification time
- IsDir() bool // abbreviation for Mode().IsDir()
- Sys() interface{} // underlying data source (can return nil)
- }
-</pre>
-
-<p>
-The file mode information has been moved into a subtype called
-<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
-a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
-methods.
-</p>
-
-<p>
-The system-specific details of file modes and properties such as (on Unix)
-i-number have been removed from <code>FileInfo</code> altogether.
-Instead, each operating system's <code>os</code> package provides an
-implementation of the <code>FileInfo</code> interface, which
-has a <code>Sys</code> method that returns the
-system-specific representation of file metadata.
-For instance, to discover the i-number of a file on a Unix system, unpack
-the <code>FileInfo</code> like this:
-</p>
-
-<pre>
- fi, err := os.Stat("hello.go")
- if err != nil {
- log.Fatal(err)
- }
- // Check that it's a Unix file.
- unixStat, ok := fi.Sys().(*syscall.Stat_t)
- if !ok {
- log.Fatal("hello.go: not a Unix file")
- }
- fmt.Printf("file i-number: %d\n", unixStat.Ino)
-</pre>
-
-<p>
-Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
-the i-number expression could be contracted to
-</p>
-
-<pre>
- fi.Sys().(*syscall.Stat_t).Ino
-</pre>
-
-<p>
-The vast majority of uses of <code>FileInfo</code> need only the methods
-of the standard interface.
-</p>
-
-<p>
-The <code>os</code> package no longer contains wrappers for the POSIX errors
-such as <code>ENOENT</code>.
-For the few programs that need to verify particular error conditions, there are
-now the boolean functions
-<a href="/pkg/os/#IsExist"><code>IsExist</code></a>,
-<a href="/pkg/os/#IsNotExist"><code>IsNotExist</code></a>
-and
-<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
-</p>
-
-{{code "progs/go1.go" `/os\.Open/` `/}/`}}
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update code that uses the old equivalent of the current <code>os.FileInfo</code>
-and <code>os.FileMode</code> API.
-Code that needs system-specific file details will need to be updated by hand.
-Code that uses the old POSIX error values from the <code>os</code> package
-will fail to compile and will also need to be updated by hand.
-</p>
-
-<h3 id="os_signal">The os/signal package</h3>
-
-<p>
-The <code>os/signal</code> package in Go 1 replaces the
-<code>Incoming</code> function, which returned a channel
-that received all incoming signals,
-with the selective <code>Notify</code> function, which asks
-for delivery of specific signals on an existing channel.
-</p>
-
-<p>
-<em>Updating</em>:
-Code must be updated by hand.
-A literal translation of
-</p>
-<pre>
-c := signal.Incoming()
-</pre>
-<p>
-is
-</p>
-<pre>
-c := make(chan os.Signal)
-signal.Notify(c) // ask for all signals
-</pre>
-<p>
-but most code should list the specific signals it wants to handle instead:
-</p>
-<pre>
-c := make(chan os.Signal)
-signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)
-</pre>
-
-<h3 id="path_filepath">The path/filepath package</h3>
-
-<p>
-In Go 1, the <a href="/pkg/path/filepath/#Walk"><code>Walk</code></a> function of the
-<code>path/filepath</code> package
-has been changed to take a function value of type
-<a href="/pkg/path/filepath/#WalkFunc"><code>WalkFunc</code></a>
-instead of a <code>Visitor</code> interface value.
-<code>WalkFunc</code> unifies the handling of both files and directories.
-</p>
-
-<pre>
- type WalkFunc func(path string, info os.FileInfo, err error) error
-</pre>
-
-<p>
-The <code>WalkFunc</code> function will be called even for files or directories that could not be opened;
-in such cases the error argument will describe the failure.
-If a directory's contents are to be skipped,
-the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
-</p>
-
-{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
-
-<p>
-<em>Updating</em>:
-The change simplifies most code but has subtle consequences, so affected programs
-will need to be updated by hand.
-The compiler will catch code using the old interface.
-</p>
-
-<h3 id="regexp">The regexp package</h3>
-
-<p>
-The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten.
-It has the same interface but the specification of the regular expressions
-it supports has changed from the old "egrep" form to that of
-<a href="http://code.google.com/p/re2/">RE2</a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the package should have its regular expressions checked by hand.
-</p>
-
-<h3 id="runtime">The runtime package</h3>
-
-<p>
-In Go 1, much of the API exported by package
-<code>runtime</code> has been removed in favor of
-functionality provided by other packages.
-Code using the <code>runtime.Type</code> interface
-or its specific concrete type implementations should
-now use package <a href="/pkg/reflect/"><code>reflect</code></a>.
-Code using <code>runtime.Semacquire</code> or <code>runtime.Semrelease</code>
-should use channels or the abstractions in package <a href="/pkg/sync/"><code>sync</code></a>.
-The <code>runtime.Alloc</code>, <code>runtime.Free</code>,
-and <code>runtime.Lookup</code> functions, an unsafe API created for
-debugging the memory allocator, have no replacement.
-</p>
-
-<p>
-Before, <code>runtime.MemStats</code> was a global variable holding
-statistics about memory allocation, and calls to <code>runtime.UpdateMemStats</code>
-ensured that it was up to date.
-In Go 1, <code>runtime.MemStats</code> is a struct type, and code should use
-<a href="/pkg/runtime/#ReadMemStats"><code>runtime.ReadMemStats</code></a>
-to obtain the current statistics.
-</p>
-
-<p>
-The package adds a new function,
-<a href="/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available
-for parallel execution, as reported by the operating system kernel.
-Its value can inform the setting of <code>GOMAXPROCS</code>.
-The <code>runtime.Cgocalls</code> and <code>runtime.Goroutines</code> functions
-have been renamed to <code>runtime.NumCgoCall</code> and <code>runtime.NumGoroutine</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update code for the function renamings.
-Other code will need to be updated by hand.
-</p>
-
-<h3 id="strconv">The strconv package</h3>
-
-<p>
-In Go 1, the
-<a href="/pkg/strconv/"><code>strconv</code></a>
-package has been significantly reworked to make it more Go-like and less C-like,
-although <code>Atoi</code> lives on (it's similar to
-<code>int(ParseInt(x, 10, 0))</code>, as does
-<code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>).
-There are also new variants of some of the functions that append to byte slices rather than
-return strings, to allow control over allocation.
-</p>
-
-<p>
-This table summarizes the renamings; see the
-<a href="/pkg/strconv/">package documentation</a>
-for full details.
-</p>
-
-<table class="codetable" frame="border" summary="strconv renames">
-<colgroup align="left" width="50%"></colgroup>
-<colgroup align="left" width="50%"></colgroup>
-<tr>
-<th align="left">Old call</th>
-<th align="left">New call</th>
-</tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)ยง</td></tr>
-<tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr>
-<tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr>
-<tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)ยง</td></tr>
-<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)ยง</td></tr>
-<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr>
-<tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(float64(x), f, p, 32)</td></tr>
-<tr><td>Ftoa64(x, f, p)</td> <td>FormatFloat(x, f, p, 64)</td></tr>
-<tr><td>FtoaN(x, f, p, n)</td> <td>FormatFloat(x, f, p, n)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Itoa(x)</td> <td>Itoa(x)</td></tr>
-<tr><td>Itoa(x)</td> <td>FormatInt(int64(x), 10)</td></tr>
-<tr><td>Itoa64(x)</td> <td>FormatInt(x, 10)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Itob(x, b)</td> <td>FormatInt(int64(x), b)</td></tr>
-<tr><td>Itob64(x, b)</td> <td>FormatInt(x, b)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Uitoa(x)</td> <td>FormatUint(uint64(x), 10)</td></tr>
-<tr><td>Uitoa64(x)</td> <td>FormatUint(x, 10)</td></tr>
-<tr>
-<td colspan="2"><hr></td>
-</tr>
-<tr><td>Uitob(x, b)</td> <td>FormatUint(uint64(x), b)</td></tr>
-<tr><td>Uitob64(x, b)</td> <td>FormatUint(x, b)</td></tr>
-</table>
-
-<p>
-<em>Updating</em>:
-Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
-<br>
-ยง <code>Atoi</code> persists but <code>Atoui</code> and <code>Atof32</code> do not, so
-they may require
-a cast that must be added by hand; the <code>go</code> <code>fix</code> tool will warn about it.
-</p>
-
-
-<h3 id="templates">The template packages</h3>
-
-<p>
-The <code>template</code> and <code>exp/template/html</code> packages have moved to
-<a href="/pkg/text/template/"><code>text/template</code></a> and
-<a href="/pkg/html/template/"><code>html/template</code></a>.
-More significant, the interface to these packages has been simplified.
-The template language is the same, but the concept of "template set" is gone
-and the functions and methods of the packages have changed accordingly,
-often by elimination.
-</p>
-
-<p>
-Instead of sets, a <code>Template</code> object
-may contain multiple named template definitions,
-in effect constructing
-name spaces for template invocation.
-A template can invoke any other template associated with it, but only those
-templates associated with it.
-The simplest way to associate templates is to parse them together, something
-made easier with the new structure of the packages.
-</p>
-
-<p>
-<em>Updating</em>:
-The imports will be updated by fix tool.
-Single-template uses will be otherwise be largely unaffected.
-Code that uses multiple templates in concert will need to be updated by hand.
-The <a href="/pkg/text/template/#examples">examples</a> in
-the documentation for <code>text/template</code> can provide guidance.
-</p>
-
-<h3 id="testing">The testing package</h3>
-
-<p>
-The testing package has a type, <code>B</code>, passed as an argument to benchmark functions.
-In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, enabling
-logging and failure reporting.
-</p>
-
-{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
-
-<p>
-<em>Updating</em>:
-Existing code is unaffected, although benchmarks that use <code>println</code>
-or <code>panic</code> should be updated to use the new methods.
-</p>
-
-<h3 id="testing_script">The testing/script package</h3>
-
-<p>
-The testing/script package has been deleted. It was a dreg.
-</p>
-
-<p>
-<em>Updating</em>:
-No code is likely to be affected.
-</p>
-
-<h3 id="unsafe">The unsafe package</h3>
-
-<p>
-In Go 1, the functions
-<code>unsafe.Typeof</code>, <code>unsafe.Reflect</code>,
-<code>unsafe.Unreflect</code>, <code>unsafe.New</code>, and
-<code>unsafe.NewArray</code> have been removed;
-they duplicated safer functionality provided by
-package <a href="/pkg/reflect/"><code>reflect</code></a>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code using these functions must be rewritten to use
-package <a href="/pkg/reflect/"><code>reflect</code></a>.
-The changes to <a href="http://code.google.com/p/go/source/detail?r=2646dc956207">encoding/gob</a> and the <a href="http://code.google.com/p/goprotobuf/source/detail?r=5340ad310031">protocol buffer library</a>
-may be helpful as examples.
-</p>
-
-<h3 id="url">The url package</h3>
-
-<p>
-In Go 1 several fields from the <a href="/pkg/net/url/#URL"><code>url.URL</code></a> type
-were removed or replaced.
-</p>
-
-<p>
-The <a href="/pkg/net/url/#URL.String"><code>String</code></a> method now
-predictably rebuilds an encoded URL string using all of <code>URL</code>'s
-fields as necessary. The resulting string will also no longer have
-passwords escaped.
-</p>
-
-<p>
-The <code>Raw</code> field has been removed. In most cases the <code>String</code>
-method may be used in its place.
-</p>
-
-<p>
-The old <code>RawUserinfo</code> field is replaced by the <code>User</code>
-field, of type <a href="/pkg/net/url/#Userinfo"><code>*net.Userinfo</code></a>.
-Values of this type may be created using the new <a href="/pkg/net/url/#User"><code>net.User</code></a>
-and <a href="/pkg/net/url/#UserPassword"><code>net.UserPassword</code></a>
-functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code>
-functions are also gone.
-</p>
-
-<p>
-The <code>RawAuthority</code> field has been removed. The same information is
-available in the <code>Host</code> and <code>User</code> fields.
-</p>
-
-<p>
-The <code>RawPath</code> field and the <code>EncodedPath</code> method have
-been removed. The path information in rooted URLs (with a slash following the
-schema) is now available only in decoded form in the <code>Path</code> field.
-Occasionally, the encoded data may be required to obtain information that
-was lost in the decoding process. These cases must be handled by accessing
-the data the URL was built from.
-</p>
-
-<p>
-URLs with non-rooted paths, such as <code>"mailto:dev@golang.org?subject=Hi"</code>,
-are also handled differently. The <code>OpaquePath</code> boolean field has been
-removed and a new <code>Opaque</code> string field introduced to hold the encoded
-path for such URLs. In Go 1, the cited URL parses as:
-</p>
-
-<pre>
- URL{
- Scheme: "mailto",
- Opaque: "dev@golang.org",
- RawQuery: "subject=Hi",
- }
-</pre>
-
-<p>
-A new <a href="/pkg/net/url/#URL.RequestURI"><code>RequestURI</code></a> method was
-added to <code>URL</code>.
-</p>
-
-<p>
-The <code>ParseWithReference</code> function has been renamed to <code>ParseWithFragment</code>.
-</p>
-
-<p>
-<em>Updating</em>:
-Code that uses the old fields will fail to compile and must be updated by hand.
-The semantic changes make it difficult for the fix tool to update automatically.
-</p>
-
-<h2 id="cmd_go">The go command</h2>
-
-<p>
-Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching,
-building, and installing Go packages and commands. The <code>go</code> command
-does away with makefiles, instead using Go source code to find dependencies and
-determine build conditions. Most existing Go programs will no longer require
-makefiles to be built.
-</p>
-
-<p>
-See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the
-<code>go</code> command and the <a href="/cmd/go/">go command documentation</a>
-for the full details.
-</p>
-
-<p>
-<em>Updating</em>:
-Projects that depend on the Go project's old makefile-based build
-infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should
-switch to using the <code>go</code> command for building Go code and, if
-necessary, rewrite their makefiles to perform any auxiliary build tasks.
-</p>
-
-<h2 id="cmd_cgo">The cgo command</h2>
-
-<p>
-In Go 1, the <a href="/cmd/cgo">cgo command</a>
-uses a different <code>_cgo_export.h</code>
-file, which is generated for packages containing <code>//export</code> lines.
-The <code>_cgo_export.h</code> file now begins with the C preamble comment,
-so that exported function definitions can use types defined there.
-This has the effect of compiling the preamble multiple times, so a
-package using <code>//export</code> must not put function definitions
-or variable initializations in the C preamble.
-</p>
-
-<h2 id="releases">Packaged releases</h2>
-
directory containing alternate template files; if set,
the directory may provide alternative template files
for the files in $GOROOT/lib/godoc
+ -url=path
+ print to standard output the data that would be served by
+ an HTTP request for path
-zip=""
zip file providing the file system to serve; disabled if empty
log.Printf("decoding metadata %s: %v", relpath, err)
}
+ // evaluate as template if indicated
+ if meta.Template {
+ tmpl, err := template.New("main").Funcs(templateFuncs).Parse(string(src))
+ if err != nil {
+ log.Printf("parsing template %s: %v", relpath, err)
+ serveError(w, r, relpath, err)
+ return
+ }
+ var buf bytes.Buffer
+ if err := tmpl.Execute(&buf, nil); err != nil {
+ log.Printf("executing template %s: %v", relpath, err)
+ serveError(w, r, relpath, err)
+ return
+ }
+ src = buf.Bytes()
+ }
+
// if it's the language spec, add tags to EBNF productions
if strings.HasSuffix(abspath, "go_spec.html") {
var buf bytes.Buffer
type Metadata struct {
Title string
Subtitle string
+ Template bool // execute as template
Path string // canonical path for this page
filePath string // filesystem path relative to goroot
}
"log"
"net/http"
_ "net/http/pprof" // to serve /debug/pprof/*
+ "net/url"
"os"
pathpkg "path"
"path/filepath"
// layout control
html = flag.Bool("html", false, "print HTML in command-line mode")
srcMode = flag.Bool("src", false, "print (exported) source in command-line mode")
+ urlFlag = flag.String("url", "", "print HTML for named URL")
// command-line searches
query = flag.Bool("q", false, "arguments are considered search queries")
flag.Parse()
// Check usage: either server and no args, command line and args, or index creation mode
- if (*httpAddr != "") != (flag.NArg() == 0) && !*writeIndex {
+ if (*httpAddr != "" || *urlFlag != "") != (flag.NArg() == 0) && !*writeIndex {
usage()
}
return
}
+ // Print content that would be served at the URL *urlFlag.
+ if *urlFlag != "" {
+ registerPublicHandlers(http.DefaultServeMux)
+ // Try up to 10 fetches, following redirects.
+ urlstr := *urlFlag
+ for i := 0; i < 10; i++ {
+ // Prepare request.
+ u, err := url.Parse(urlstr)
+ if err != nil {
+ log.Fatal(err)
+ }
+ req := &http.Request{
+ URL: u,
+ }
+
+ // Invoke default HTTP handler to serve request
+ // to our buffering httpWriter.
+ w := &httpWriter{h: http.Header{}, code: 200}
+ http.DefaultServeMux.ServeHTTP(w, req)
+
+ // Return data, error, or follow redirect.
+ switch w.code {
+ case 200: // ok
+ os.Stdout.Write(w.Bytes())
+ return
+ case 301, 302, 303, 307: // redirect
+ redirect := w.h.Get("Location")
+ if redirect == "" {
+ log.Fatalf("HTTP %d without Location header", w.code)
+ }
+ urlstr = redirect
+ default:
+ log.Fatalf("HTTP error %d", w.code)
+ }
+ }
+ log.Fatalf("too many redirects")
+ }
+
if *httpAddr != "" {
// HTTP server mode.
var handler http.Handler = http.DefaultServeMux
log.Printf("packageText.Execute: %s", err)
}
}
+
+// An httpWriter is an http.ResponseWriter writing to a bytes.Buffer.
+type httpWriter struct {
+ bytes.Buffer
+ h http.Header
+ code int
+}
+
+func (w *httpWriter) Header() http.Header { return w.h }
+func (w *httpWriter) WriteHeader(code int) { w.code = code }
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Template support for writing HTML documents.
+// Documents that include Template: true in their
+// metadata are executed as input to text/template.
+//
+// This file defines functions for those templates to invoke.
+
// The template uses the function "code" to inject program
// source into the output by extracting code from files and
// injecting them as HTML-escaped <pre> blocks.
package main
import (
- "flag"
"fmt"
- "io/ioutil"
"log"
- "os"
- "path/filepath"
"regexp"
"strings"
"text/template"
)
-func Usage() {
- fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
- os.Exit(2)
-}
+// Functions in this file panic on error, but the panic is recovered
+// to an error by 'code'.
var templateFuncs = template.FuncMap{
- "code": code,
- "donotedit": donotedit,
-}
-
-func main() {
- flag.Usage = Usage
- flag.Parse()
- if len(flag.Args()) != 1 {
- Usage()
- }
-
- // Read and parse the input.
- name := flag.Arg(0)
- tmpl := template.New(filepath.Base(name)).Funcs(templateFuncs)
- if _, err := tmpl.ParseFiles(name); err != nil {
- log.Fatal(err)
- }
-
- // Execute the template.
- if err := tmpl.Execute(os.Stdout, 0); err != nil {
- log.Fatal(err)
- }
+ "code": code,
}
-// contents reads a file by name and returns its contents as a string.
+// contents reads and returns the content of the named file
+// (from the virtual file system, so for example /doc refers to $GOROOT/doc).
func contents(name string) string {
- file, err := ioutil.ReadFile(name)
+ file, err := ReadFile(fs, name)
if err != nil {
- log.Fatal(err)
+ log.Panic(err)
}
return string(file)
}
}
return fmt.Sprintf("%q", arg)
default:
- log.Fatalf("unrecognized argument: %v type %T", arg, arg)
+ log.Panicf("unrecognized argument: %v type %T", arg, arg)
}
return ""
}
-func donotedit() string {
- // No editing please.
- return fmt.Sprintf("<!--\n DO NOT EDIT: created by\n tmpltohtml %s\n-->\n", flag.Args()[0])
-}
+func code(file string, arg ...interface{}) (s string, err error) {
+ defer func() {
+ if r := recover(); r != nil {
+ err = fmt.Errorf("%v", r)
+ }
+ }()
-func code(file string, arg ...interface{}) (string, error) {
text := contents(file)
var command string
switch len(arg) {
switch n := arg.(type) {
case int:
if n <= 0 || n > max {
- log.Fatalf("%q:%d is out of range", file, n)
+ log.Panicf("%q:%d is out of range", file, n)
}
return n, "", true
case string:
return 0, n, false
}
- log.Fatalf("unrecognized argument %v type %T", arg, arg)
+ log.Panicf("unrecognized argument %v type %T", arg, arg)
return
}
if !isInt2 {
line2 = match(file, line1, lines, pattern2)
} else if line2 < line1 {
- log.Fatalf("lines out of order for %q: %d %d", text, line1, line2)
+ log.Panicf("lines out of order for %q: %d %d", text, line1, line2)
}
for k := line1 - 1; k < line2; k++ {
if strings.HasSuffix(lines[k], "OMIT\n") {
// $ matches the end of the file.
if pattern == "$" {
if len(lines) == 0 {
- log.Fatalf("%q: empty file", file)
+ log.Panicf("%q: empty file", file)
}
return len(lines)
}
if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
re, err := regexp.Compile(pattern[1 : len(pattern)-1])
if err != nil {
- log.Fatal(err)
+ log.Panic(err)
}
for i := start; i < len(lines); i++ {
if re.MatchString(lines[i]) {
return i + 1
}
}
- log.Fatalf("%s: no match for %#q", file, pattern)
+ log.Panicf("%s: no match for %#q", file, pattern)
}
- log.Fatalf("unrecognized pattern: %q", pattern)
+ log.Panicf("unrecognized pattern: %q", pattern)
return 0
}