diff options
Diffstat (limited to 'doc/effective_go.html')
| -rw-r--r-- | doc/effective_go.html | 160 |
1 files changed, 24 insertions, 136 deletions
diff --git a/doc/effective_go.html b/doc/effective_go.html index b9e62b6db..80b285183 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -1,11 +1,7 @@ <!--{ - "Title": "Effective Go" + "Title": "Effective Go", + "Template": true }--> -<!-- - DO NOT EDIT: created by - tmpltohtml effective_go.tmpl ---> - <h2 id="introduction">Introduction</h2> @@ -775,7 +771,7 @@ 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: +The signature of <code>File.Write</code> in package <code>os</code> is: </p> <pre> @@ -1331,9 +1327,9 @@ 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. +strings, pointers, interfaces (as long as the dynamic type +supports equality), structs and arrays. Slices cannot be used as map keys, +because equality is not defined on them. Like slices, maps are a reference type. If you pass a map to a function that changes the contents of the map, the changes will be visible in the caller. @@ -1456,7 +1452,7 @@ 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> +the <a href="http://tour.golang.org">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. @@ -1693,47 +1689,13 @@ 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> -<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 @@ -1761,10 +1723,7 @@ var ( <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.) The only restriction is that, although -goroutines can be launched during initialization, they will not begin -execution until it completes; initialization always runs as a single thread -of execution. +<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 @@ -1882,32 +1841,7 @@ by the routines in package <code>sort</code> if it implements 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> @@ -1986,7 +1920,7 @@ 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 +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, @@ -2397,7 +2331,7 @@ it can also be seen as a type-safe generalization of Unix pipes. 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 +function executing concurrently 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 @@ -2418,12 +2352,12 @@ exits, silently. (The effect is similar to the Unix shell's background.) </p> <pre> -go list.Sort() // run list.Sort in parallel; don't wait for it. +go list.Sort() // run list.Sort concurrently; don't wait for it. </pre> <p> A function literal can be handy in a goroutine invocation. <pre> -func Announce(message string, delay int64) { +func Announce(message string, delay time.Duration) { go func() { time.Sleep(delay) fmt.Println(message) @@ -2763,8 +2697,8 @@ it is much more informative than the plain <p> When feasible, error strings should identify their origin, such as by having a prefix naming the package that generated the error. For example, in package -image, the string representation for a decoding error due to an unknown format -is "image: unknown format". +<code>image</code>, the string representation for a decoding error due to an +unknown format is "image: unknown format". </p> <p> @@ -2777,11 +2711,11 @@ field for recoverable failures. <pre> for try := 0; try < 2; try++ { - file, err = os.Open(filename) + file, err = os.Create(filename) if err == nil { return } - if e, ok := err.(*os.PathError); ok && e.Err == os.ENOSPC { + if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC { deleteTempFiles() // Recover some space. continue } @@ -3013,53 +2947,7 @@ for instance, a URL, saving you typing the URL into the phone's tiny keyboard. 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 @@ -3085,19 +2973,19 @@ 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>{{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> <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> +If this is too quick an explanation, see the <a href="/pkg/text/template/">documentation</a> for the template package for a more thorough discussion. </p> <p> |