diff options
Diffstat (limited to 'doc/go1.html')
| -rw-r--r-- | doc/go1.html | 1570 |
1 files changed, 1570 insertions, 0 deletions
diff --git a/doc/go1.html b/doc/go1.html new file mode 100644 index 000000000..23ed3709f --- /dev/null +++ b/doc/go1.html @@ -0,0 +1,1570 @@ +<!--{ + "Title": "Go 1 Release Notes" +}--> +<!-- + DO NOT EDIT: created by + tmpltohtml go1.tmpl +--> + + +<h2 id="introduction">Introduction to Go 1</h2> + +<p> +For a full explanation of the motivation and design of Go 1, see XXX. +Here follows a summary. +</p> + +<p> +Go 1 is intended to be a stable language and core library set that +will form a reliable foundation for people and organizations that +want to make a long-term commitment to developing in the Go programming +language. Go will continue to develop, but in a way that guarantees +code written to the Go 1 specification will continue to work. For +instance, Go 1 will be a supported platform on Google App Engine +for the next few years. Incompatible changes to the environment, +should they arise, will be done in a distinct version. +</p> + +<p> +This document describes the changes in the language and libraries +in Go 1, relative to the previous release, r60 (at the time of +writing, tagged as r60.3). It also explains how to update code at +r60 to compile and run under Go 1. Finally, it outlines the new +<code>go</code> command for building Go programs and the new binary +release process being introduced. Most of these topics have more +thorough presentations elsewhere; such documents are linked below. +</p> + +<h2 id="language">Changes to the language</h2> + +<h3 id="append">Append</h3> + +<p> +The <code>append</code> built-in function is variadic, so one can +append to a byte slice using the <code>...</code> syntax in the +call. +</p> + +<pre><!--{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}} +--> greeting := []byte{} + greeting = append(greeting, []byte("hello ")...)</pre> + +<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; the conversion is no longer necessary: +</p> + +<pre><!--{{code "progs/go1.go" `/append.*world/`}} +--> greeting = append(greeting, "world"...)</pre> + +<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> built-in function lets a sender tell a receiver +that no more data will be transmitted on the channel. In Go 1 the +type system enforces the directionality when possible: it is illegal +to call <code>close</code> on a receive-only channel: +</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> + +<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> + +<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> +Go 1 allows goroutines to be created and run during initialization. +(They used to be created but were not run until after initialization +completed.) Code that uses goroutines can now be called from +<code>init</code> routines and global initialization expressions +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> + +<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> +Go 1 introduces a new basic type, <code>rune</code>, to be used 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> + +<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> + +<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> +The original syntax for deleting an element in a map was: +</p> + +<pre> + m[k] = ignored, false +</pre> + +<p> +In Go 1, that syntax has gone; instead there is a new built-in +function, <code>delete</code>. The call +</p> + +<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}} +--> delete(m, k)</pre> + +<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>: +Gofix will convert expressions of the form <code>m[k] = ignored, +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. Gofix +will flag other uses of the syntax for inspection by the programmer. +</p> + +<h3 id="iteration">Iterating in maps</h3> + +<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> + +<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> + +<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> +Go 1 fully specifies the evaluation order in multiple assignment +statements. In particular, 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> + +<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> + +<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 shadowed variable is one that has the same name as another variable in an inner scope. +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> +Go 1 relaxes the rules about accessing structs with unexported (lower-case) fields, +permitting a client package to assign (and therefore copy) such a struct. +Of course, the client package still cannot access such fields individually. +</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 of structs and arrays</h3> + +<p> +Go 1 defines equality and inequality (<code>==</code> and +<code>!=</code>) for struct and array values, respectively, provided +the elements of the data structures can themselves be compared. +That is, if equality is defined for all the fields of a struct (or +an array element), then it is defined for the struct (or array). +</p> + +<p> +As a result, structs and arrays can now be used as map keys: +</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> + +<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>: +This is a new feature, so existing code needs no changes. +</p> + +<h3 id="funcs">Function and map equality</h3> + +<p> +Go 1 disallows checking for equality of functions and maps, +respectively, except to compare them directly to <code>nil</code>. +</p> + +<p> +<em>Updating</em>: +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> +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>: +Gofix 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. +<br> +<font color="red">TODO: gofix should warn about deletions.</font> +</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>go/types</code></li> +<li><code>http/spdy</code></li> +</ul> + +<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> +</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. +Gofix or the compiler will complain about such uses. +<br> +<font color="red">TODO: gofix should warn about such uses.</font> +</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. +Gofix will warn about such uses. +<br> +<font color="red">TODO: gofix should warn about such uses.</font> +</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. +<br> +<font color="red">TODO: gofix should warn such uses.</font> +</p> + +<h3 id="subrepo">Packages moving to subrepositories</h3> + +<p> +Go 1 has moved a number of packages into 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>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> +</table> + +<p> +<em>Updating</em>: +Gofix 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> +As mentioned above, Go 1 introduces a new built-in interface type called <code>error</code>. +Its intent is to replace the old <code>os.Error</code> type with a more central concept. +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> + +<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> + +<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> + +<pre><!--{{code "progs/go1.go" `/ErrSyntax/`}} +--> var ErrSyntax = errors.New("syntax error")</pre> + +<p> +<em>Updating</em>: +Gofix 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> +In Go 1, the +<a href="/pkg/syscall/"><code>syscall</code></a> +package returns an <code>error</code> for system call errors, +rather than plain integer <code>errno</code> values. +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> +<em>Updating</em>: +Gofix 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> +One of the most sweeping changes in the Go 1 library is the +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> + +<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. + log.Printf("Sleeping for %.3fs", delta.Seconds()) + time.Sleep(delta) +}</pre> + +<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>: +Gofix 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 gofix 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 gofix. +This category includes packages that are new in Go 1. +</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_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="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> + +<pre><!--{{code "progs/go1.go" `/timeout/`}} +-->var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")</pre> + +<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> +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 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 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> +<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 conjuction 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. +Gofix 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> +Also, the <code>Request.RawURL</code> field has been removed; it was a +historical artifact. +</p> + +<p> +<em>Updating</em>: +Gofix 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 renamed +<a href="/pkg/image/#Repeated"><code>image.Repeated</code></a>. +</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> +<tr><td>image.Tiled</td> <td>image.Repeated</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>: +Gofix will update almost all code affected by the change. +</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 is also a new <a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a> method to simplify +timing out dialing a network address. +</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 gofix to update automatically. +</p> + +<h3 id="os_fileinfo">The os.FileInfo type</h3> + +<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() + } +</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, <code>*os.FileStat</code>, +which in turn contains a <code>Sys</code> field that stores 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) + } + // Make sure it's an implementation known to package os. + fileStat, ok := fi.(*os.FileStat) + if !ok { + log.Fatal("hello.go: not an os File") + } + // Now check that it's a Unix file. + unixStat, ok := fileStat.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.(*os.FileStat).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> +<em>Updating</em>: +Gofix 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. +</p> + +<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 os.Error) os.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 <code>SkipDir</code>. +</p> + +<p> +<font color="red">TODO: add an example?</font> +</p> + +<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="runtime">The runtime package</h3> + +<p> +The <code>runtime</code> package in Go 1 includes a new niladic 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>. +</p> + +<p> +<em>Updating</em>: +No existing code is affected. +</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(x, float64(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>: +Gofix 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; gofix will warn about it. +</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> + +<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> + +<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="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> +<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 gofix to update automatically. +</p> + +<h3 id="xml">The 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>: +Gofix will update most uses of the package except for some calls to +<code>Unmarshal</code>. Special care must be taken with field tags, +since gofix 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> + +<h2 id="go_command">The go command</h2> + +<h2 id="releases">Packaged releases</h2> + |