diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/all.css | 5 | ||||
| -rw-r--r-- | doc/contrib.html | 5 | ||||
| -rw-r--r-- | doc/devel/weekly.html | 121 | ||||
| -rw-r--r-- | doc/docs.html | 9 | ||||
| -rw-r--r-- | doc/effective_go.html | 42 | ||||
| -rw-r--r-- | doc/go_spec.html | 126 | ||||
| -rw-r--r-- | doc/go_tutorial.html | 32 | ||||
| -rw-r--r-- | doc/go_tutorial.txt | 32 | ||||
| -rw-r--r-- | doc/root.html | 1 |
9 files changed, 261 insertions, 112 deletions
diff --git a/doc/all.css b/doc/all.css index 84df1f8fa..a985d8ffb 100644 --- a/doc/all.css +++ b/doc/all.css @@ -198,3 +198,8 @@ span.alert { padding: 0.25em 1em; background: #F4F4F4; } +sup.new { + color: red; + font-size: 8px; + line-height: 0; +} diff --git a/doc/contrib.html b/doc/contrib.html index 0efe8147c..84d2cda6a 100644 --- a/doc/contrib.html +++ b/doc/contrib.html @@ -49,7 +49,10 @@ systems and architectures.</p> <p>Features and ideas being developed or discussed by the Go team.</p> <h3 id="release"><a href="devel/release.html">Release History</a></h3> -<p>A summary of the changes between tagged releases of Go.</p> +<p>A summary of the changes between Go releases.</p> + +<h3 id="release"><a href="devel/weekly.html">Weekly Snapshot History</a></h3> +<p>A summary of the changes between weekly snapshots of Go.</p> <h3 id="golang-dev"><a href="http://groups.google.com/group/golang-dev">Developer Mailing List</a></h3> <p>The <a href="http://groups.google.com/group/golang-dev">golang-dev</a> diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html index dc734079b..40b4efe44 100644 --- a/doc/devel/weekly.html +++ b/doc/devel/weekly.html @@ -14,6 +14,127 @@ hg pull hg update weekly.<i>YYYY-MM-DD</i> </pre> +<h2 id="2011-06-02">2011-06-02</h2> + +<pre> +This release includes changes to the exec package that will require changes +to client code. + +The exec package has been re-designed with a more convenient and succinct API. +This code: + args := []string{“diff”, “-u”, “file1.txt”, “file2.txt”} + p, err := exec.Run(“/usr/bin/diff”, args, os.Environ(), "", + exec.DevNull, exec.Pipe, exec.DevNull) + if err != nil { + return nil, err + } + var buf bytes.Buffer + io.Copy(&buf, p.Stdout) + w, err := p.Wait(0) + p.Close() + if err != nil { + return nil, err + } + return buf.Bytes(), err +can be rewritten as: + return exec.Command(“diff”, “-u”, “file1.txt”, “file2.txt”).Output() +See the exec package documentation for the details ("godoc exec"). + +By setting the GOPATH environment variable you can use goinstall to build and +install your own code and external libraries outside of the Go tree (and avoid +writing Makefiles). +See the goinstall command documentation for the details ("godoc goinstall"). + +Other changes: +* 5g: alignment fixes. +* 6l, 8l: fix Mach-O binaries with many dynamic libraries. +* 8l: emit resources (.rsrc) in Windows PE. (thanks Wei Guangjing). +* asn1: fix marshalling of empty optional RawValues (thanks Mikkel Krautz). +* big: make Int and Rat implement fmt.Scanner (thanks Evan Shaw), + ~8x faster number scanning, + remove some unnecessary conversions. +* cgo: restrict #cgo directives to prevent shell expansion (thanks Gustavo Niemeyer), + support pkg-config for flags and libs (thanks Gustavo Niemeyer). +* compress/flate: fix Huffman tree bug, + do not use background goroutines. +* crypto/openpgp: add support for symmetrically encrypting files. +* crypto/tls/generate_cert.go: fix misspelling of O_CREATE. +* dashboard: send notification emails when the build breaks. +* doc: mention go/printer instead of container/vector in effective go, + put Release History link on 'Documentation' page, + put Weekly Snapshot History link on 'Contributing' page. +* encoding/base64: add DecodeString and EncodeToString. +* encoding/binary: add a non-reflect fast path for Read, + add a non-reflect fast path for Write. +* encoding/hex: add hex dumping. +* encoding/line: delete package. Its functionality is now in bufio. +* filepath: Abs must always return a clean path (thanks Gustavo Niemeyer). +* fmt: fix bug in UnreadRune, + make %q work for integers, printing a quoted character literal, + return EOF when out of input in Scan*. +* gc: check parameter declarations in interface fields (thanks Anthony Martin), + disallow ... in type conversions (thanks Anthony Martin), + do not force heap allocation on referencing outer variable in a closure, + fix m[x], _ = y.(T), + implement new shift rules, + patch y.tab.c to fix build when using Bison 2.5, + relax assignability of method receivers (thanks Anthony Martin), + typecheck the whole tree before walking. +* go/scanner: don't allow "0x" and "0X" as integers (thanks Evan Shaw). +* gobuilder: fixes for windows (thanks Alex Brainman). +* godoc: basic setup for running godoc on local app engine emulator, + display advert for the package dashboard on package list page. +* goinstall: fixes for windows (thanks Alex Brainman), + more verbose logging with -v. +* gotest, pkg/exec: use bash to run shell scripts on windows (thanks Alex Brainman). +* http/spdy: redo interfaces, flesh out implementation & frame types (thanks William Chan). +* http: Transport hook to register non-http(s) protocols, + add client+server benchmark, + catch Handler goroutine panics, + fix Set-Cookie date parsing, + have client set Content-Length when possible, + let Transport use a custom net.Dial function, + propagate Set-Cookie in reverse proxy, + ServeFile shouldn't send Content-Length when Content-Encoding is set. +* image: add a SubImage method. +* image/gif: simplify blockReader.Read. +* image/png: fix encoding of images that don't start at (0, 0). +* io, net, http: sendfile support. +* io: add ByteScanner, RuneScanner interfaces. +* ld: add -w to disable dwarf, make errors obviously from dwarf. +* mail: new package. +* mime/multipart: misc code/doc fixes. +* misc/cgo: remove reference to 'destroy' function. +* misc/emacs: don't select the mark after gofmt (thanks Eric Eisner). +* misc/gophertool: Chrome extension to aid in Go development +* misc/vim: limit Fmt command to Go buffers (thanks Yasuhiro Matsumoto). +* net: if we stop polling, remove any pending events for the socket, + update IP multicast socket options (thanks Mikio Hara). +* os: Fix test to work on Solaris, + fix Readdir(0) on EOF, + fix Readdir, Readdirnames (thanks Yuval Pavel Zholkover), + fix os.MkdirAll with backslash path separator (thanks Yasuhiro Matsumoto), + handle OpenFile flag parameter properly on Windows (thanks Alex Brainman). +* path/filepath: remove string constants. +* pkg: spelling tweaks, I-Z (thanks Robert Hencke). +* quietgcc: fix typo, respect $TMPDIR. +* runtime: do not garbage collect windows callbacks (thanks Alex Brainman), + fix mmap error return on linux (thanks Dmitry Chestnykh), + reset GOMAXPROCS during tests, + save cdecl registers in Windows SEH handler (thanks Alexey Borzenkov). +* spec: be precise with the use of the informal ellipsis and the Go token, + clarify rules for shifts. +* strconv: add QuoteRune; analogous to Quote but for runes rather than strings. +* strings: implement UnreadByte, UnreadRune. +* sync: always wake up sleeping goroutines on Cond.Signal (thanks Gustavo Niemeyer). +* sync/atomic: fix check64. +* syscall: add ProcAttr field to pass an unescaped command line on windows (thanks Vincent Vanackere), + add routing messages support for Linux and BSD (thanks Mikio Hara). +* template: fixes and clean-ups (thanks Gustavo Niemeyer). +* time: fix Format bug: midnight/noon are 12AM/PM not 0AM/PM. +* unicode: make the tables smaller. +</pre> + <h2 id="2011-05-22">2011-05-22</h2> <pre> diff --git a/doc/docs.html b/doc/docs.html index 50df2213b..f6ff05c25 100644 --- a/doc/docs.html +++ b/doc/docs.html @@ -59,6 +59,12 @@ An introduction to Go for C++ programmers. <h2 id="tutorials_nonenglish">Non-English Documentation</h2> +<h3 id="docs_be">Belarusian — Беларуская</h3> + +<ul> +<li><a href="http://www.designcontest.com/show/faq-be">faq-be</a> - Frequently Asked Questions.</li> +</ul> + <h3 id="docs_cn">Chinese — 中文</h3> <ul> @@ -113,6 +119,9 @@ The built-in documentation for the Go tools. The official Go Language specification. </p> +<h3 id="release"><a href="devel/release.html">Release History</a></h3> +<p>A summary of the changes between Go releases.</p> + <h3 id="go_mem"><a href="go_mem.html">The Go Memory Model</a></h3> <p> A document that specifies the conditions under which reads of a variable in diff --git a/doc/effective_go.html b/doc/effective_go.html index 86b2d63dc..972772d33 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -297,9 +297,9 @@ determines just which package is being used. <p> Another convention is that the package name is the base name of its source directory; -the package in <code>src/pkg/container/vector</code> -is imported as <code>"container/vector"</code> but has name <code>vector</code>, -not <code>container_vector</code> and not <code>containerVector</code>. +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> @@ -935,13 +935,14 @@ example of its possibilities. <h2 id="data">Data</h2> -<h3 id="allocation_new">Allocation with <code>new()</code></h3> +<h3 id="allocation_new">Allocation with <code>new</code></h3> <p> -Go has two allocation primitives, <code>new()</code> and <code>make()</code>. +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. +Let's talk about <code>new</code> first. It's a built-in function essentially the same as its namesakes in other languages: <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>. @@ -950,9 +951,9 @@ In Go terminology, it returns a pointer to a newly allocated zero value of type </p> <p> -Since the memory returned by <code>new()</code> is zeroed, it's helpful to arrange that the +Since the memory returned by <code>new</code> is zeroed, it's helpful to arrange that the zeroed object 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 +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." @@ -1065,7 +1066,7 @@ 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> +<h3 id="allocation_make">Allocation with <code>make</code></h3> <p> Back to allocation. @@ -1099,8 +1100,8 @@ In contrast, <code>new([]int)</code> returns a pointer to a newly allocated, zer 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>. +These examples illustrate the difference between <code>new</code> and +<code>make</code>. </p> <pre> @@ -1116,9 +1117,9 @@ v := make([]int, 100) </pre> <p> -Remember that <code>make()</code> applies only to maps, slices and channels +Remember that <code>make</code> applies only to maps, slices and channels and does not return a pointer. -To obtain an explicit pointer allocate with <code>new()</code>. +To obtain an explicit pointer allocate with <code>new</code>. </p> <h3 id="arrays">Arrays</h3> @@ -1473,7 +1474,7 @@ 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 <code>String() string</code> on the type. +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> @@ -1495,7 +1496,7 @@ 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 +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> @@ -1683,19 +1684,20 @@ var ( <h3 id="init">The init function</h3> <p> -Finally, each source file can define its own <code>init()</code> function to -set up whatever state is required. The only restriction is that, although +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. -And finally means finally: <code>init()</code> is called after all the +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 +a common use of <code>init</code> functions is to verify or repair correctness of the program state before real execution begins. </p> @@ -1899,7 +1901,7 @@ on every instance of a common method. 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> +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; diff --git a/doc/go_spec.html b/doc/go_spec.html index 5f8b5e6ba..0c08e1464 100644 --- a/doc/go_spec.html +++ b/doc/go_spec.html @@ -1,5 +1,5 @@ <!-- title The Go Programming Language Specification --> -<!-- subtitle Version of May 15, 2011 --> +<!-- subtitle Version of May 24, 2011 --> <!-- TODO @@ -10,7 +10,6 @@ TODO [ ] clarify what a field name is in struct declarations (struct{T} vs struct {T T} vs struct {t T}) [ ] need explicit language about the result type of operations -[ ] may want to have some examples for the types of shift operations [ ] should string(1<<s) and float32(1<<s) be valid? [ ] should probably write something about evaluation order of statements even though obvious @@ -49,7 +48,7 @@ The syntax is specified using Extended Backus-Naur Form (EBNF): Production = production_name "=" [ Expression ] "." . Expression = Alternative { "|" Alternative } . Alternative = Term { Term } . -Term = production_name | token [ "..." token ] | Group | Option | Repetition . +Term = production_name | token [ "…" token ] | Group | Option | Repetition . Group = "(" Expression ")" . Option = "[" Expression "]" . Repetition = "{" Expression "}" . @@ -73,8 +72,12 @@ double quotes <code>""</code> or back quotes <code>``</code>. </p> <p> -The form <code>a ... b</code> represents the set of characters from -<code>a</code> through <code>b</code> as alternatives. +The form <code>a … b</code> represents the set of characters from +<code>a</code> through <code>b</code> as alternatives. The horizontal +ellipis … is also used elsewhere in the spec to informally denote various +enumerations or code snippets that are not further specified. The character … +(as opposed to the three characters <code>...</code>) is not a token of the Go +language. </p> <h2 id="Source_code_representation">Source code representation</h2> @@ -123,9 +126,9 @@ The underscore character <code>_</code> (U+005F) is considered a letter. </p> <pre class="ebnf"> letter = unicode_letter | "_" . -decimal_digit = "0" ... "9" . -octal_digit = "0" ... "7" . -hex_digit = "0" ... "9" | "A" ... "F" | "a" ... "f" . +decimal_digit = "0" … "9" . +octal_digit = "0" … "7" . +hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . </pre> <h2 id="Lexical_elements">Lexical elements</h2> @@ -287,7 +290,7 @@ An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</ </p> <pre class="ebnf"> int_lit = decimal_lit | octal_lit | hex_lit . -decimal_lit = ( "1" ... "9" ) { decimal_digit } . +decimal_lit = ( "1" … "9" ) { decimal_digit } . octal_lit = "0" { octal_digit } . hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } . </pre> @@ -822,7 +825,7 @@ make([]T, length, capacity) </pre> <p> -The <code>make()</code> call allocates a new, hidden array to which the returned +A call to <code>make</code> allocates a new, hidden array to which the returned slice value refers. That is, executing </p> @@ -1054,9 +1057,9 @@ have the method set </p> <pre> -func (p T) Read(b Buffer) bool { return ... } -func (p T) Write(b Buffer) bool { return ... } -func (p T) Close() { ... } +func (p T) Read(b Buffer) bool { return … } +func (p T) Write(b Buffer) bool { return … } +func (p T) Close() { … } </pre> <p> @@ -1094,8 +1097,8 @@ If <code>S1</code> and <code>S2</code> also implement </p> <pre> -func (p T) Lock() { ... } -func (p T) Unlock() { ... } +func (p T) Lock() { … } +func (p T) Unlock() { … } </pre> <p> @@ -1177,7 +1180,6 @@ maps grow to accommodate the number of items stored in them, with the exception of <code>nil</code> maps. A <code>nil</code> map is equivalent to an empty map except that no elements may be added. -</code> <h3 id="Channel_types">Channel types</h3> @@ -1697,7 +1699,7 @@ of an interface type or of elements of a composite type remains unchanged: </p> <pre> -// A Mutex is a data type with two methods Lock and Unlock. +// A Mutex is a data type with two methods, Lock and Unlock. type Mutex struct { /* Mutex fields */ } func (m *Mutex) Lock() { /* Lock implementation */ } func (m *Mutex) Unlock() { /* Unlock implementation */ } @@ -2100,7 +2102,7 @@ element index plus one. A slice literal has the form </p> <pre> -[]T{x1, x2, ... xn} +[]T{x1, x2, … xn} </pre> <p> @@ -2108,7 +2110,7 @@ and is a shortcut for a slice operation applied to an array literal: </p> <pre> -[n]T{x1, x2, ... xn}[0 : n] +[n]T{x1, x2, … xn}[0 : n] </pre> <p> @@ -2134,8 +2136,8 @@ parentheses. </p> <pre> -if x == (T{a,b,c}[i]) { ... } -if (x == T{a,b,c}[i]) { ... } +if x == (T{a,b,c}[i]) { … } +if (x == T{a,b,c}[i]) { … } </pre> <p> @@ -2568,11 +2570,11 @@ Given an expression <code>f</code> of function type </p> <pre> -f(a1, a2, ... an) +f(a1, a2, … an) </pre> <p> -calls <code>f</code> with arguments <code>a1, a2, ... an</code>. +calls <code>f</code> with arguments <code>a1, a2, … an</code>. Except for one special case, arguments must be single-valued expressions <a href="#Assignability">assignable</a> to the parameter types of <code>F</code> and are evaluated before the function is called. @@ -2651,7 +2653,7 @@ arguments bound to the final parameter and may differ for each call site. Given the function and call </p> <pre> -func Greeting(prefix string, who ... string) +func Greeting(prefix string, who ...string) Greeting("hello:", "Joe", "Anna", "Eileen") </pre> @@ -2702,42 +2704,34 @@ unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . <p> Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. For other binary operators, the operand types must be <a href="#Type_identity">identical</a> -unless the operation involves channels, shifts, or untyped <a href="#Constants">constants</a>. +unless the operation involves shifts or untyped <a href="#Constants">constants</a>. For operations involving constants only, see the section on <a href="#Constant_expressions">constant expressions</a>. </p> <p> -In a channel send, the first operand is always a channel and the second -must be a value <a href="#Assignability">assignable</a> -to the channel's element type. -</p> - -<p> -Except for shift operations, -if one operand is an untyped <a href="#Constants">constant</a> +Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> and the other operand is not, the constant is <a href="#Conversions">converted</a> to the type of the other operand. </p> <p> -The right operand in a shift operation must have unsigned integer type +The right operand in a shift expression must have unsigned integer type or be an untyped constant that can be converted to unsigned integer type. -</p> - -<p> -If the left operand of a non-constant shift operation is an untyped constant, -the type of constant is what it would be if the shift operation were replaced by -the left operand alone. +If the left operand of a non-constant shift expression is an untyped constant, +the type of the constant is what it would be if the shift expression were +replaced by its left operand alone. </p> <pre> var s uint = 33 -var i = 1<<s // 1 has type int -var j = int32(1<<s) // 1 has type int32; j == 0 -var u = uint64(1<<s) // 1 has type uint64; u == 1<<33 -var f = float32(1<<s) // illegal: 1 has type float32, cannot shift -var g = float32(1<<33) // legal; 1<<33 is a constant shift operation; g == 1<<33 +var i = 1<<s // 1 has type int +var j int32 = 1<<s // 1 has type int32; j == 0 +var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 +var m int = 1.0<<s // legal: 1.0 has type int +var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift +var v float32 = 1<<s // illegal: 1 has type float32, cannot shift +var w int64 = 1.0<<33 // legal: 1.0<<33 is a constant shift expression </pre> <h3 id="Operator_precedence">Operator precedence</h3> @@ -2869,8 +2863,8 @@ be replaced by a bitwise "and" operation: <p> The shift operators shift the left operand by the shift count specified by the right operand. They implement arithmetic shifts if the left operand is a signed -integer and logical shifts if it is an unsigned integer. The shift count must -be an unsigned integer. There is no upper limit on the shift count. Shifts behave +integer and logical shifts if it is an unsigned integer. +There is no upper limit on the shift count. Shifts behave as if the left operand is shifted <code>n</code> times by 1 for a shift count of <code>n</code>. As a result, <code>x << 1</code> is the same as <code>x*2</code> @@ -3382,21 +3376,35 @@ respectively. Except for shift operations, if the operands of a binary operation are an untyped integer constant and an untyped floating-point constant, the integer constant is converted to an untyped floating-point constant (relevant for <code>/</code> and <code>%</code>). -Similarly, -untyped integer or floating-point constants may be used as operands +Similarly, untyped integer or floating-point constants may be used as operands wherever it is legal to use an operand of complex type; the integer or floating point constant is converted to a complex constant with a zero imaginary part. </p> <p> -Applying an operator to untyped constants results in an untyped +A constant <a href="#Comparison_operators">comparison</a> always yields +a constant of type <code>bool</code>. If the left operand of a constant +<a href="#Operators">shift expression</a> is an untyped constant, the +result is an integer constant; otherwise it is a constant of the same +type as the left operand, which must be of integer type +(§<a href="#Arithmetic_operators">Arithmetic operators</a>). +Applying all other operators to untyped constants results in an untyped constant of the same kind (that is, a boolean, integer, floating-point, -complex, or string constant), except for -<a href="#Comparison_operators">comparison operators</a>, which result in -a constant of type <code>bool</code>. +complex, or string constant). </p> +<pre> +const a = 2 + 3.0 // a == 5.0 (floating-point constant) +const b = 15 / 4 // b == 3 (integer constant) +const c = 15 / 4.0 // c == 3.75 (floating-point constant) +const d = 1 << 3.0 // d == 8 (integer constant) +const e = 1.0 << 3 // e == 8 (integer constant) +const f = int32(1) << 33 // f == 0 (type int32) +const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) +const h = "foo" > "bar" // h == true (type bool) +</pre> + <p> Imaginary literals are untyped complex constants (with zero real part) and may be combined in binary @@ -4886,7 +4894,7 @@ package main import "fmt" -// Send the sequence 2, 3, 4, ... to channel 'ch'. +// Send the sequence 2, 3, 4, … to channel 'ch'. func generate(ch chan<- int) { for i := 2; ; i++ { ch <- i // Send 'i' to channel 'ch'. @@ -4926,7 +4934,7 @@ func main() { <h3 id="The_zero_value">The zero value</h3> <p> When memory is allocated to store a value, either through a declaration -or <code>make()</code> or <code>new()</code> call, +or a call of <code>make</code> or <code>new</code>, and no explicit initialization is provided, the memory is given a default initialization. Each element of such a value is set to the <i>zero value</i> for its type: <code>false</code> for booleans, @@ -4984,7 +4992,7 @@ func init() <p> defined in its source. A package may contain multiple -<code>init()</code> functions, even +<code>init</code> functions, even within a single source file; they execute in unspecified order. </p> @@ -5014,8 +5022,8 @@ program is complete. Therefore, all initialization code is run in a single goroutine. </p> <p> -An <code>init()</code> function cannot be referred to from anywhere -in a program. In particular, <code>init()</code> cannot be called explicitly, +An <code>init</code> function cannot be referred to from anywhere +in a program. In particular, <code>init</code> cannot be called explicitly, nor can a pointer to <code>init</code> be assigned to a function variable. </p> <p> @@ -5037,7 +5045,7 @@ arguments and returns no value. </p> <pre> -func main() { ... } +func main() { … } </pre> <p> diff --git a/doc/go_tutorial.html b/doc/go_tutorial.html index c87254ecb..cfdd0ec6e 100644 --- a/doc/go_tutorial.html +++ b/doc/go_tutorial.html @@ -341,7 +341,7 @@ Using slices one can write this function (from <code>sum.go</code>): 15 } </pre> <p> -Note how the return type (<code>int</code>) is defined for <code>sum()</code> by stating it +Note how the return type (<code>int</code>) is defined for <code>sum</code> by stating it after the parameter list. <p> To call the function, we slice the array. This intricate call (we'll show @@ -373,7 +373,7 @@ There are also maps, which you can initialize like this: m := map[string]int{"one":1 , "two":2} </pre> <p> -The built-in function <code>len()</code>, which returns number of elements, +The built-in function <code>len</code>, which returns number of elements, makes its first appearance in <code>sum</code>. It works on strings, arrays, slices, maps, and channels. <p> @@ -401,7 +401,7 @@ for more examples of its use. Most types in Go are values. If you have an <code>int</code> or a <code>struct</code> or an array, assignment copies the contents of the object. -To allocate a new variable, use <code>new()</code>, which +To allocate a new variable, use the built-in function <code>new</code>, which returns a pointer to the allocated storage. <p> <pre> @@ -418,7 +418,7 @@ or the more idiomatic Some types—maps, slices, and channels (see below)—have reference semantics. If you're holding a slice or a map and you modify its contents, other variables referencing the same underlying data will see the modification. For these three -types you want to use the built-in function <code>make()</code>: +types you want to use the built-in function <code>make</code>: <p> <pre> m := make(map[string]int) @@ -432,11 +432,11 @@ If you just declare the map, as in </pre> <p> it creates a <code>nil</code> reference that cannot hold anything. To use the map, -you must first initialize the reference using <code>make()</code> or by assignment from an +you must first initialize the reference using <code>make</code> or by assignment from an existing map. <p> Note that <code>new(T)</code> returns type <code>*T</code> while <code>make(T)</code> returns type -<code>T</code>. If you (mistakenly) allocate a reference object with <code>new()</code>, +<code>T</code>. If you (mistakenly) allocate a reference object with <code>new</code> rather than <code>make</code>, you receive a pointer to a nil reference, equivalent to declaring an uninitialized variable and taking its address. <p> @@ -767,7 +767,7 @@ Building on the <code>file</code> package, here's a simple version of the Unix u By now this should be easy to follow, but the <code>switch</code> statement introduces some new features. Like a <code>for</code> loop, an <code>if</code> or <code>switch</code> can include an initialization statement. The <code>switch</code> on line 18 uses one to create variables -<code>nr</code> and <code>er</code> to hold the return values from <code>f.Read()</code>. (The <code>if</code> on line 25 +<code>nr</code> and <code>er</code> to hold the return values from the call to <code>f.Read</code>. (The <code>if</code> on line 25 has the same idea.) The <code>switch</code> statement is general: it evaluates the cases from top to bottom looking for the first case that matches the value; the case expressions don't need to be constants or even integers, as long as @@ -779,14 +779,14 @@ in a <code>for</code> statement, a missing value means <code>true</code>. In fa is a form of <code>if-else</code> chain. While we're here, it should be mentioned that in <code>switch</code> statements each <code>case</code> has an implicit <code>break</code>. <p> -Line 25 calls <code>Write()</code> by slicing the incoming buffer, which is itself a slice. +Line 25 calls <code>Write</code> by slicing the incoming buffer, which is itself a slice. Slices provide the standard Go way to handle I/O buffers. <p> Now let's make a variant of <code>cat</code> that optionally does <code>rot13</code> on its input. It's easy to do by just processing the bytes, but instead we will exploit Go's notion of an <i>interface</i>. <p> -The <code>cat()</code> subroutine uses only two methods of <code>f</code>: <code>Read()</code> and <code>String()</code>, +The <code>cat</code> subroutine uses only two methods of <code>f</code>: <code>Read</code> and <code>String</code>, so let's start by defining an interface that has exactly those two methods. Here is code from <code>progs/cat_rot13.go</code>: <p> @@ -838,7 +838,7 @@ To use the new feature, we define a flag: 14 var rot13Flag = flag.Bool("rot13", false, "rot13 the input") </pre> <p> -and use it from within a mostly unchanged <code>cat()</code> function: +and use it from within a mostly unchanged <code>cat</code> function: <p> <pre> <!-- progs/cat_rot13.go /func.cat/ /^}/ --> 52 func cat(r reader) { @@ -866,7 +866,7 @@ and use it from within a mostly unchanged <code>cat()</code> function: 74 } </pre> <p> -(We could also do the wrapping in <code>main</code> and leave <code>cat()</code> mostly alone, except +(We could also do the wrapping in <code>main</code> and leave <code>cat</code> mostly alone, except for changing the type of the argument; consider that an exercise.) Lines 56 through 58 set it all up: If the <code>rot13</code> flag is true, wrap the <code>reader</code> we received into a <code>rotate13</code> and proceed. Note that the interface variables @@ -1055,7 +1055,7 @@ to that of the <code>Printf</code> call above. </pre> <p> If you have your own type you'd like <code>Printf</code> or <code>Print</code> to format, -just give it a <code>String()</code> method that returns a string. The print +just give it a <code>String</code> method that returns a string. The print routines will examine the value to inquire whether it implements the method and if so, use it rather than some other formatting. Here's a simple example. @@ -1076,14 +1076,14 @@ Here's a simple example. 21 } </pre> <p> -Since <code>*testType</code> has a <code>String()</code> method, the +Since <code>*testType</code> has a <code>String</code> method, the default formatter for that type will use it and produce the output <p> <pre> 77 Sunset Strip </pre> <p> -Observe that the <code>String()</code> method calls <code>Sprint</code> (the obvious Go +Observe that the <code>String</code> method calls <code>Sprint</code> (the obvious Go variant that returns a string) to do its formatting; special formatters can use the <code>fmt</code> library recursively. <p> @@ -1096,7 +1096,7 @@ and such, but that's getting a little off the main thread so we'll leave it as an exploration exercise. <p> You might ask, though, how <code>Printf</code> can tell whether a type implements -the <code>String()</code> method. Actually what it does is ask if the value can +the <code>String</code> method. Actually what it does is ask if the value can be converted to an interface variable that implements the method. Schematically, given a value <code>v</code>, it does this: <p> @@ -1141,7 +1141,7 @@ interface type defined in the <code>io</code> library: <p> (This interface is another conventional name, this time for <code>Write</code>; there are also <code>io.Reader</code>, <code>io.ReadWriter</code>, and so on.) -Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write()</code> +Thus you can call <code>Fprintf</code> on any type that implements a standard <code>Write</code> method, not just files but also network channels, buffers, whatever you want. <p> diff --git a/doc/go_tutorial.txt b/doc/go_tutorial.txt index ab02baf2c..ebf58eca6 100644 --- a/doc/go_tutorial.txt +++ b/doc/go_tutorial.txt @@ -272,7 +272,7 @@ Using slices one can write this function (from "sum.go"): --PROG progs/sum.go /sum/ /^}/ -Note how the return type ("int") is defined for "sum()" by stating it +Note how the return type ("int") is defined for "sum" by stating it after the parameter list. To call the function, we slice the array. This intricate call (we'll show @@ -296,7 +296,7 @@ There are also maps, which you can initialize like this: m := map[string]int{"one":1 , "two":2} -The built-in function "len()", which returns number of elements, +The built-in function "len", which returns number of elements, makes its first appearance in "sum". It works on strings, arrays, slices, maps, and channels. @@ -321,7 +321,7 @@ An Interlude about Allocation Most types in Go are values. If you have an "int" or a "struct" or an array, assignment copies the contents of the object. -To allocate a new variable, use "new()", which +To allocate a new variable, use the built-in function "new", which returns a pointer to the allocated storage. type T struct { a, b int } @@ -334,7 +334,7 @@ or the more idiomatic Some types—maps, slices, and channels (see below)—have reference semantics. If you're holding a slice or a map and you modify its contents, other variables referencing the same underlying data will see the modification. For these three -types you want to use the built-in function "make()": +types you want to use the built-in function "make": m := make(map[string]int) @@ -344,11 +344,11 @@ If you just declare the map, as in var m map[string]int it creates a "nil" reference that cannot hold anything. To use the map, -you must first initialize the reference using "make()" or by assignment from an +you must first initialize the reference using "make" or by assignment from an existing map. Note that "new(T)" returns type "*T" while "make(T)" returns type -"T". If you (mistakenly) allocate a reference object with "new()", +"T". If you (mistakenly) allocate a reference object with "new" rather than "make", you receive a pointer to a nil reference, equivalent to declaring an uninitialized variable and taking its address. @@ -526,7 +526,7 @@ Building on the "file" package, here's a simple version of the Unix utility "cat By now this should be easy to follow, but the "switch" statement introduces some new features. Like a "for" loop, an "if" or "switch" can include an initialization statement. The "switch" on line 18 uses one to create variables -"nr" and "er" to hold the return values from "f.Read()". (The "if" on line 25 +"nr" and "er" to hold the return values from the call to "f.Read". (The "if" on line 25 has the same idea.) The "switch" statement is general: it evaluates the cases from top to bottom looking for the first case that matches the value; the case expressions don't need to be constants or even integers, as long as @@ -538,14 +538,14 @@ in a "for" statement, a missing value means "true". In fact, such a "switch" is a form of "if-else" chain. While we're here, it should be mentioned that in "switch" statements each "case" has an implicit "break". -Line 25 calls "Write()" by slicing the incoming buffer, which is itself a slice. +Line 25 calls "Write" by slicing the incoming buffer, which is itself a slice. Slices provide the standard Go way to handle I/O buffers. Now let's make a variant of "cat" that optionally does "rot13" on its input. It's easy to do by just processing the bytes, but instead we will exploit Go's notion of an <i>interface</i>. -The "cat()" subroutine uses only two methods of "f": "Read()" and "String()", +The "cat" subroutine uses only two methods of "f": "Read" and "String", so let's start by defining an interface that has exactly those two methods. Here is code from "progs/cat_rot13.go": @@ -569,11 +569,11 @@ To use the new feature, we define a flag: --PROG progs/cat_rot13.go /rot13Flag/ -and use it from within a mostly unchanged "cat()" function: +and use it from within a mostly unchanged "cat" function: --PROG progs/cat_rot13.go /func.cat/ /^}/ -(We could also do the wrapping in "main" and leave "cat()" mostly alone, except +(We could also do the wrapping in "main" and leave "cat" mostly alone, except for changing the type of the argument; consider that an exercise.) Lines 56 through 58 set it all up: If the "rot13" flag is true, wrap the "reader" we received into a "rotate13" and proceed. Note that the interface variables @@ -701,19 +701,19 @@ to that of the "Printf" call above. --PROG progs/print.go 'NR==21' 'NR==22' If you have your own type you'd like "Printf" or "Print" to format, -just give it a "String()" method that returns a string. The print +just give it a "String" method that returns a string. The print routines will examine the value to inquire whether it implements the method and if so, use it rather than some other formatting. Here's a simple example. --PROG progs/print_string.go 'NR==9' END -Since "*testType" has a "String()" method, the +Since "*testType" has a "String" method, the default formatter for that type will use it and produce the output 77 Sunset Strip -Observe that the "String()" method calls "Sprint" (the obvious Go +Observe that the "String" method calls "Sprint" (the obvious Go variant that returns a string) to do its formatting; special formatters can use the "fmt" library recursively. @@ -726,7 +726,7 @@ and such, but that's getting a little off the main thread so we'll leave it as an exploration exercise. You might ask, though, how "Printf" can tell whether a type implements -the "String()" method. Actually what it does is ask if the value can +the "String" method. Actually what it does is ask if the value can be converted to an interface variable that implements the method. Schematically, given a value "v", it does this: @@ -765,7 +765,7 @@ interface type defined in the "io" library: (This interface is another conventional name, this time for "Write"; there are also "io.Reader", "io.ReadWriter", and so on.) -Thus you can call "Fprintf" on any type that implements a standard "Write()" +Thus you can call "Fprintf" on any type that implements a standard "Write" method, not just files but also network channels, buffers, whatever you want. diff --git a/doc/root.html b/doc/root.html index 6722d0018..8d76928c8 100644 --- a/doc/root.html +++ b/doc/root.html @@ -78,6 +78,7 @@ google.setOnLoadCallback(loadFeed); <li><a href="/doc/effective_go.html">Effective Go</a></li> <li><a href="/doc/go_faq.html">Go FAQ</a></li> <li><a href="/doc/docs.html">Other Documentation</a></li> + <li><a href="http://code.google.com/appengine/docs/go/">Go for Google App Engine</a> <sup class="new">New!</sup></li> </ul> </div> <div id="resources-contributors" > |