diff options
Diffstat (limited to 'go/golang/go/doc/go1.1.html')
-rw-r--r-- | go/golang/go/doc/go1.1.html | 1099 |
1 files changed, 1099 insertions, 0 deletions
diff --git a/go/golang/go/doc/go1.1.html b/go/golang/go/doc/go1.1.html new file mode 100644 index 00000000..f615c97e --- /dev/null +++ b/go/golang/go/doc/go1.1.html @@ -0,0 +1,1099 @@ +<!--{ + "Title": "Go 1.1 Release Notes", + "Path": "/doc/go1.1", + "Template": true +}--> + +<h2 id="introduction">Introduction to Go 1.1</h2> + +<p> +The release of <a href="/doc/go1.html">Go version 1</a> (Go 1 or Go 1.0 for short) +in March of 2012 introduced a new period +of stability in the Go language and libraries. +That stability has helped nourish a growing community of Go users +and systems around the world. +Several "point" releases since +then—1.0.1, 1.0.2, and 1.0.3—have been issued. +These point releases fixed known bugs but made +no non-critical changes to the implementation. +</p> + +<p> +This new release, Go 1.1, keeps the <a href="/doc/go1compat.html">promise +of compatibility</a> but adds a couple of significant +(backwards-compatible, of course) language changes, has a long list +of (again, compatible) library changes, and +includes major work on the implementation of the compilers, +libraries, and run-time. +The focus is on performance. +Benchmarking is an inexact science at best, but we see significant, +sometimes dramatic speedups for many of our test programs. +We trust that many of our users' programs will also see improvements +just by updating their Go installation and recompiling. +</p> + +<p> +This document summarizes the changes between Go 1 and Go 1.1. +Very little if any code will need modification to run with Go 1.1, +although a couple of rare error cases surface with this release +and need to be addressed if they arise. +Details appear below; see the discussion of +<a href="#int">64-bit ints</a> and <a href="#unicode_literals">Unicode literals</a> +in particular. +</p> + +<h2 id="language">Changes to the language</h2> + +<p> +<a href="/doc/go1compat.html">The Go compatibility document</a> promises +that programs written to the Go 1 language specification will continue to operate, +and those promises are maintained. +In the interest of firming up the specification, though, there are +details about some error cases that have been clarified. +There are also some new language features. +</p> + +<h3 id="divzero">Integer division by zero</h3> + +<p> +In Go 1, integer division by a constant zero produced a run-time panic: +</p> + +<pre> +func f(x int) int { + return x/0 +} +</pre> + +<p> +In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error. +</p> + +<h3 id="unicode_literals">Surrogates in Unicode literals</h3> + +<p> +The definition of string and rune literals has been refined to exclude surrogate halves from the +set of valid Unicode code points. +See the <a href="#unicode">Unicode</a> section for more information. +</p> + +<h3 id="method_values">Method values</h3> + +<p> +Go 1.1 now implements +<a href="/ref/spec#Method_values">method values</a>, +which are functions that have been bound to a specific receiver value. +For instance, given a +<a href="/pkg/bufio/#Writer"><code>Writer</code></a> +value <code>w</code>, +the expression +<code>w.Write</code>, +a method value, is a function that will always write to <code>w</code>; it is equivalent to +a function literal closing over <code>w</code>: +</p> + +<pre> +func (p []byte) (n int, err error) { + return w.Write(p) +} +</pre> + +<p> +Method values are distinct from method expressions, which generate functions +from methods of a given type; the method expression <code>(*bufio.Writer).Write</code> +is equivalent to a function with an extra first argument, a receiver of type +<code>(*bufio.Writer)</code>: +</p> + +<pre> +func (w *bufio.Writer, p []byte) (n int, err error) { + return w.Write(p) +} +</pre> + +<p> +<em>Updating</em>: No existing code is affected; the change is strictly backward-compatible. +</p> + +<h3 id="return">Return requirements</h3> + +<p> +Before Go 1.1, a function that returned a value needed an explicit "return" +or call to <code>panic</code> at +the end of the function; this was a simple way to make the programmer +be explicit about the meaning of the function. But there are many cases +where a final "return" is clearly unnecessary, such as a function with +only an infinite "for" loop. +</p> + +<p> +In Go 1.1, the rule about final "return" statements is more permissive. +It introduces the concept of a +<a href="/ref/spec#Terminating_statements"><em>terminating statement</em></a>, +a statement that is guaranteed to be the last one a function executes. +Examples include +"for" loops with no condition and "if-else" +statements in which each half ends in a "return". +If the final statement of a function can be shown <em>syntactically</em> to +be a terminating statement, no final "return" statement is needed. +</p> + +<p> +Note that the rule is purely syntactic: it pays no attention to the values in the +code and therefore requires no complex analysis. +</p> + +<p> +<em>Updating</em>: The change is backward-compatible, but existing code +with superfluous "return" statements and calls to <code>panic</code> may +be simplified manually. +Such code can be identified by <code>go vet</code>. +</p> + +<h2 id="impl">Changes to the implementations and tools</h2> + +<h3 id="gccgo">Status of gccgo</h3> + +<p> +The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in +<code>gccgo</code>'s releases. +The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of <code>gccgo</code>. +Its library is a little behind the release, but the biggest difference is that method values are not implemented. +Sometime around July 2013, we expect 4.8.2 of GCC to ship with a <code>gccgo</code> +providing a complete Go 1.1 implementation. +</p> + +<h3 id="gc_flag">Command-line flag parsing</h3> + +<p> +In the gc toolchain, the compilers and linkers now use the +same command-line flag parsing rules as the Go flag package, a departure +from the traditional Unix flag parsing. This may affect scripts that invoke +the tool directly. +For example, +<code>go tool 6c -Fw -Dfoo</code> must now be written +<code>go tool 6c -F -w -D foo</code>. +</p> + +<h3 id="int">Size of int on 64-bit platforms</h3> + +<p> +The language allows the implementation to choose whether the <code>int</code> type and +<code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code> +and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations +now make +<code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64. +Among other things, this enables the allocation of slices with +more than 2 billion elements on 64-bit platforms. +</p> + +<p> +<em>Updating</em>: +Most programs will be unaffected by this change. +Because Go does not allow implicit conversions between distinct +<a href="/ref/spec#Numeric_types">numeric types</a>, +no programs will stop compiling due to this change. +However, programs that contain implicit assumptions +that <code>int</code> is only 32 bits may change behavior. +For example, this code prints a positive number on 64-bit systems and +a negative one on 32-bit systems: +</p> + +<pre> +x := ^uint32(0) // x is 0xffffffff +i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit +fmt.Println(i) +</pre> + +<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems) +would instead say: +</p> + +<pre> +i := int(int32(x)) +</pre> + +<h3 id="heap">Heap size on 64-bit architectures</h3> + +<p> +On 64-bit architectures, the maximum heap size has been enlarged substantially, +from a few gigabytes to several tens of gigabytes. +(The exact details depend on the system and may change.) +</p> + +<p> +On 32-bit architectures, the heap size has not changed. +</p> + +<p> +<em>Updating</em>: +This change should have no effect on existing programs beyond allowing them +to run with larger heaps. +</p> + +<h3 id="unicode">Unicode</h3> + +<p> +To make it possible to represent code points greater than 65535 in UTF-16, +Unicode defines <em>surrogate halves</em>, +a range of code points to be used only in the assembly of large values, and only in UTF-16. +The code points in that surrogate range are illegal for any other purpose. +In Go 1.1, this constraint is honored by the compiler, libraries, and run-time: +a surrogate half is illegal as a rune value, when encoded as UTF-8, or when +encoded in isolation as UTF-16. +When encountered, for example in converting from a rune to UTF-8, it is +treated as an encoding error and will yield the replacement rune, +<a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>, +U+FFFD. +</p> + +<p> +This program, +</p> + +<pre> +import "fmt" + +func main() { + fmt.Printf("%+q\n", string(0xD800)) +} +</pre> + +<p> +printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1. +</p> + +<p> +Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as +<code>'\ud800'</code> and <code>"\ud800"</code> are now rejected by the compilers. +When written explicitly as UTF-8 encoded bytes, +such strings can still be created, as in <code>"\xed\xa0\x80"</code>. +However, when such a string is decoded as a sequence of runes, as in a range loop, it will yield only <code>utf8.RuneError</code> +values. +</p> + +<p> +The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first +character of a Go source file. +Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary, +some editors add the mark as a kind of "magic number" identifying a UTF-8 encoded file. +</p> + +<p> +<em>Updating</em>: +Most programs will be unaffected by the surrogate change. +Programs that depend on the old behavior should be modified to avoid the issue. +The byte-order-mark change is strictly backward-compatible. +</p> + +<h3 id="race">Race detector</h3> + +<p> +A major addition to the tools is a <em>race detector</em>, a way to +find bugs in programs caused by concurrent access of the same +variable, where at least one of the accesses is a write. +This new facility is built into the <code>go</code> tool. +For now, it is only available on Linux, Mac OS X, and Windows systems with +64-bit x86 processors. +To enable it, set the <code>-race</code> flag when building or testing your program +(for instance, <code>go test -race</code>). +The race detector is documented in <a href="/doc/articles/race_detector.html">a separate article</a>. +</p> + +<h3 id="gc_asm">The gc assemblers</h3> + +<p> +Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and +a new internal <a href="//golang.org/s/go11func">representation of functions</a>, +the arrangement of function arguments on the stack has changed in the gc toolchain. +Functions written in assembly will need to be revised at least +to adjust frame pointer offsets. +</p> + +<p> +<em>Updating</em>: +The <code>go vet</code> command now checks that functions implemented in assembly +match the Go function prototypes they implement. +</p> + +<h3 id="gocmd">Changes to the go command</h3> + +<p> +The <a href="/cmd/go/"><code>go</code></a> command has acquired several +changes intended to improve the experience for new Go users. +</p> + +<p> +First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages, +including a list of paths searched, when a package cannot be located. +</p> + +<pre> +$ go build foo/quxx +can't load package: package foo/quxx: cannot find package "foo/quxx" in any of: + /home/you/go/src/pkg/foo/quxx (from $GOROOT) + /home/you/src/foo/quxx (from $GOPATH) +</pre> + +<p> +Second, the <code>go get</code> command no longer allows <code>$GOROOT</code> +as the default destination when downloading package source. +To use the <code>go get</code> +command, a <a href="/doc/code.html#GOPATH">valid <code>$GOPATH</code></a> is now required. +</p> + +<pre> +$ GOPATH= go get code.google.com/p/foo/quxx +package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath +</pre> + +<p> +Finally, as a result of the previous change, the <code>go get</code> command will also fail +when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value. +</p> + +<pre> +$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx +warning: GOPATH set to GOROOT (/home/you/go) has no effect +package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath +</pre> + +<h3 id="gotest">Changes to the go test command</h3> + +<p> +The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a> +command no longer deletes the binary when run with profiling enabled, +to make it easier to analyze the profile. +The implementation sets the <code>-c</code> flag automatically, so after running, +</p> + +<pre> +$ go test -cpuprofile cpuprof.out mypackage +</pre> + +<p> +the file <code>mypackage.test</code> will be left in the directory where <code>go test</code> was run. +</p> + +<p> +The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a> +command can now generate profiling information +that reports where goroutines are blocked, that is, +where they tend to stall waiting for an event such as a channel communication. +The information is presented as a +<em>blocking profile</em> +enabled with the +<code>-blockprofile</code> +option of +<code>go test</code>. +Run <code>go help test</code> for more information. +</p> + +<h3 id="gofix">Changes to the go fix command</h3> + +<p> +The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as +<code>go fix</code>, no longer applies fixes to update code from +before Go 1 to use Go 1 APIs. +To update pre-Go 1 code to Go 1.1, use a Go 1.0 toolchain +to convert the code to Go 1.0 first. +</p> + +<h3 id="tags">Build constraints</h3> + +<p> +The "<code>go1.1</code>" tag has been added to the list of default +<a href="/pkg/go/build/#hdr-Build_Constraints">build constraints</a>. +This permits packages to take advantage of the new features in Go 1.1 while +remaining compatible with earlier versions of Go. +</p> + +<p> +To build a file only with Go 1.1 and above, add this build constraint: +</p> + +<pre> +// +build go1.1 +</pre> + +<p> +To build a file only with Go 1.0.x, use the converse constraint: +</p> + +<pre> +// +build !go1.1 +</pre> + +<h3 id="platforms">Additional platforms</h3> + +<p> +The Go 1.1 toolchain adds experimental support for <code>freebsd/arm</code>, +<code>netbsd/386</code>, <code>netbsd/amd64</code>, <code>netbsd/arm</code>, +<code>openbsd/386</code> and <code>openbsd/amd64</code> platforms. +</p> + +<p> +An ARMv6 or later processor is required for <code>freebsd/arm</code> or +<code>netbsd/arm</code>. +</p> + +<p> +Go 1.1 adds experimental support for <code>cgo</code> on <code>linux/arm</code>. +</p> + +<h3 id="crosscompile">Cross compilation</h3> + +<p> +When cross-compiling, the <code>go</code> tool will disable <code>cgo</code> +support by default. +</p> + +<p> +To explicitly enable <code>cgo</code>, set <code>CGO_ENABLED=1</code>. +</p> + +<h2 id="performance">Performance</h2> + +<p> +The performance of code compiled with the Go 1.1 gc tool suite should be noticeably +better for most Go programs. +Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes +much more, but occasionally less or even non-existent. +There are too many small performance-driven tweaks through the tools and libraries +to list them all here, but the following major changes are worth noting: +</p> + +<ul> +<li>The gc compilers generate better code in many cases, most noticeably for +floating point on the 32-bit Intel architecture.</li> +<li>The gc compilers do more in-lining, including for some operations +in the run-time such as <a href="/pkg/builtin/#append"><code>append</code></a> +and interface conversions.</li> +<li>There is a new implementation of Go maps with significant reduction in +memory footprint and CPU time.</li> +<li>The garbage collector has been made more parallel, which can reduce +latencies for programs running on multiple CPUs.</li> +<li>The garbage collector is also more precise, which costs a small amount of +CPU time but can reduce the size of the heap significantly, especially +on 32-bit architectures.</li> +<li>Due to tighter coupling of the run-time and network libraries, fewer +context switches are required on network operations.</li> +</ul> + +<h2 id="library">Changes to the standard library</h2> + +<h3 id="bufio_scanner">bufio.Scanner</h3> + +<p> +The various routines to scan textual input in the +<a href="/pkg/bufio/"><code>bufio</code></a> +package, +<a href="/pkg/bufio/#Reader.ReadBytes"><code>ReadBytes</code></a>, +<a href="/pkg/bufio/#Reader.ReadString"><code>ReadString</code></a> +and particularly +<a href="/pkg/bufio/#Reader.ReadLine"><code>ReadLine</code></a>, +are needlessly complex to use for simple purposes. +In Go 1.1, a new type, +<a href="/pkg/bufio/#Scanner"><code>Scanner</code></a>, +has been added to make it easier to do simple tasks such as +read the input as a sequence of lines or space-delimited words. +It simplifies the problem by terminating the scan on problematic +input such as pathologically long lines, and having a simple +default: line-oriented input, with each line stripped of its terminator. +Here is code to reproduce the input a line at a time: +</p> + +<pre> +scanner := bufio.NewScanner(os.Stdin) +for scanner.Scan() { + fmt.Println(scanner.Text()) // Println will add back the final '\n' +} +if err := scanner.Err(); err != nil { + fmt.Fprintln(os.Stderr, "reading standard input:", err) +} +</pre> + +<p> +Scanning behavior can be adjusted through a function to control subdividing the input +(see the documentation for <a href="/pkg/bufio/#SplitFunc"><code>SplitFunc</code></a>), +but for tough problems or the need to continue past errors, the older interface +may still be required. +</p> + +<h3 id="net">net</h3> + +<p> +The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly +lax about the network name passed in. +Although the documentation was clear +that the only valid networks for +<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a> +are <code>"tcp"</code>, +<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string. +The Go 1.1 implementation returns an error if the network is not one of those strings. +The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>, +<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and +<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>. +</p> + +<p> +The previous implementation of +<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a> +returned a +<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as +a representation of the connection endpoint. +The Go 1.1 implementation instead returns a +<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> +to allow reading and writing +with its +<a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a> +and +<a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a> +methods. +</p> + +<p> +The data structures +<a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>, +<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>, and +<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a> +add a new string field called <code>Zone</code>. +Code using untagged composite literals (e.g. <code>net.TCPAddr{ip, port}</code>) +instead of tagged literals (<code>net.TCPAddr{IP: ip, Port: port}</code>) +will break due to the new field. +The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages. +</p> + +<p> +<em>Updating</em>: +To correct breakage caused by the new struct field, +<code>go fix</code> will rewrite code to add tags for these types. +More generally, <code>go vet</code> will identify composite literals that +should be revised to use field tags. +</p> + +<h3 id="reflect">reflect</h3> + +<p> +The <a href="/pkg/reflect/"><code>reflect</code></a> package has several significant additions. +</p> + +<p> +It is now possible to run a "select" statement using +the <code>reflect</code> package; see the description of +<a href="/pkg/reflect/#Select"><code>Select</code></a> +and +<a href="/pkg/reflect/#SelectCase"><code>SelectCase</code></a> +for details. +</p> + +<p> +The new method +<a href="/pkg/reflect/#Value.Convert"><code>Value.Convert</code></a> +(or +<a href="/pkg/reflect/#Type"><code>Type.ConvertibleTo</code></a>) +provides functionality to execute a Go conversion or type assertion operation +on a +<a href="/pkg/reflect/#Value"><code>Value</code></a> +(or test for its possibility). +</p> + +<p> +The new function +<a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a> +creates a wrapper function to make it easier to call a function with existing +<a href="/pkg/reflect/#Value"><code>Values</code></a>, +doing the standard Go conversions among the arguments, for instance +to pass an actual <code>int</code> to a formal <code>interface{}</code>. +</p> + +<p> +Finally, the new functions +<a href="/pkg/reflect/#ChanOf"><code>ChanOf</code></a>, +<a href="/pkg/reflect/#MapOf"><code>MapOf</code></a> +and +<a href="/pkg/reflect/#SliceOf"><code>SliceOf</code></a> +construct new +<a href="/pkg/reflect/#Type"><code>Types</code></a> +from existing types, for example to construct the type <code>[]T</code> given +only <code>T</code>. +</p> + + +<h3 id="time">time</h3> +<p> +On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the +<a href="/pkg/time/"><code>time</code></a> package +returned times with microsecond precision. +The Go 1.1 implementation on these +systems now returns times with nanosecond precision. +Programs that write to an external format with microsecond precision +and read it back, expecting to recover the original value, will be affected +by the loss of precision. +There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>, +<a href="/pkg/time/#Time.Round"><code>Round</code></a> +and +<a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>, +that can be used to remove precision from a time before passing it to +external storage. +</p> + +<p> +The new method +<a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a> +returns the one-indexed integral day number of the year specified by the time value. +</p> + +<p> +The +<a href="/pkg/time/#Timer"><code>Timer</code></a> +type has a new method +<a href="/pkg/time/#Timer.Reset"><code>Reset</code></a> +that modifies the timer to expire after a specified duration. +</p> + +<p> +Finally, the new function +<a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a> +is like the existing +<a href="/pkg/time/#Parse"><code>Parse</code></a> +but parses the time in the context of a location (time zone), ignoring +time zone information in the parsed string. +This function addresses a common source of confusion in the time API. +</p> + +<p> +<em>Updating</em>: +Code that needs to read and write times using an external format with +lower precision should be modified to use the new methods. +</p> + +<h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3> + +<p> +To make it easier for binary distributions to access them if desired, the <code>exp</code> +and <code>old</code> source subtrees, which are not included in binary distributions, +have been moved to the new <code>go.exp</code> subrepository at +<code>code.google.com/p/go.exp</code>. To access the <code>ssa</code> package, +for example, run +</p> + +<pre> +$ go get code.google.com/p/go.exp/ssa +</pre> + +<p> +and then in Go source, +</p> + +<pre> +import "code.google.com/p/go.exp/ssa" +</pre> + +<p> +The old package <code>exp/norm</code> has also been moved, but to a new repository +<code>go.text</code>, where the Unicode APIs and other text-related packages will +be developed. +</p> + +<h3 id="new_packages">New packages</h3> + +<p> +There are three new packages. +</p> + +<ul> +<li> +The <a href="/pkg/go/format/"><code>go/format</code></a> package provides +a convenient way for a program to access the formatting capabilities of the +<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command. +It has two functions, +<a href="/pkg/go/format/#Node"><code>Node</code></a> to format a Go parser +<a href="/pkg/go/ast/#Node"><code>Node</code></a>, +and +<a href="/pkg/go/format/#Source"><code>Source</code></a> +to reformat arbitrary Go source code into the standard format as provided by the +<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command. +</li> + +<li> +The <a href="/pkg/net/http/cookiejar/"><code>net/http/cookiejar</code></a> package provides the basics for managing HTTP cookies. +</li> + +<li> +The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package provides low-level facilities for data race detection. +It is internal to the race detector and does not otherwise export any user-visible functionality. +</li> +</ul> + +<h3 id="minor_library_changes">Minor changes to the library</h3> + +<p> +The following list summarizes a number of minor changes to the library, mostly additions. +See the relevant package documentation for more information about each change. +</p> + +<ul> +<li> +The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions, +<a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a> +and +<a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>, +with self-evident properties. +Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type +has a new method +<a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that +provides some control over memory allocation inside the buffer. +Finally, the +<a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a +<a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method +so it implements the +<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface. +</li> + +<li> +The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package has +a new <a href="/pkg/compress/gzip/#Writer.Flush"><code>Flush</code></a> +method for its +<a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a> +type that flushes its underlying <code>flate.Writer</code>. +</li> + +<li> +The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function, +<a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs. +</li> + +<li> +The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package +now supports PEM blocks (see +<a href="/pkg/crypto/x509/#DecryptPEMBlock"><code>DecryptPEMBlock</code></a> for instance), +and a new function +<a href="/pkg/crypto/x509/#ParseECPrivateKey"><code>ParseECPrivateKey</code></a> to parse elliptic curve private keys. +</li> + +<li> +The <a href="/pkg/database/sql/"><code>database/sql</code></a> package +has a new +<a href="/pkg/database/sql/#DB.Ping"><code>Ping</code></a> +method for its +<a href="/pkg/database/sql/#DB"><code>DB</code></a> +type that tests the health of the connection. +</li> + +<li> +The <a href="/pkg/database/sql/driver/"><code>database/sql/driver</code></a> package +has a new +<a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a> +interface that a +<a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a> +may implement to improve performance. +</li> + +<li> +The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package's +<a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a> +has a new method +<a href="/pkg/encoding/json/#Decoder.Buffered"><code>Buffered</code></a> +to provide access to the remaining data in its buffer, +as well as a new method +<a href="/pkg/encoding/json/#Decoder.UseNumber"><code>UseNumber</code></a> +to unmarshal a value into the new type +<a href="/pkg/encoding/json/#Number"><code>Number</code></a>, +a string, rather than a float64. +</li> + +<li> +The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package +has a new function, +<a href="/pkg/encoding/xml/#EscapeText"><code>EscapeText</code></a>, +which writes escaped XML output, +and a method on +<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>, +<a href="/pkg/encoding/xml/#Encoder.Indent"><code>Indent</code></a>, +to specify indented output. +</li> + +<li> +In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a +new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a> +and associated methods makes it easier to extract and process comments in Go programs. +</li> + +<li> +In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package, +the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code> +throughout the code, +information that the <a href="/cmd/godoc/"><code>godoc</code></a> +command can filter or present according to the value of the <code>-notes</code> flag. +</li> + +<li> +The undocumented and only partially implemented "noescape" feature of the +<a href="/pkg/html/template/"><code>html/template</code></a> +package has been removed; programs that depend on it will break. +</li> + +<li> +The <a href="/pkg/image/jpeg/"><code>image/jpeg</code></a> package now +reads progressive JPEG files and handles a few more subsampling configurations. +</li> + +<li> +The <a href="/pkg/io/"><code>io</code></a> package now exports the +<a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common +functionality of writing a byte at a time. +It also exports a new error, <a href="/pkg/io/#ErrNoProgress"><code>ErrNoProgress</code></a>, +used to indicate a <code>Read</code> implementation is looping without delivering data. +</li> + +<li> +The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support +for OS-specific logging features. +</li> + +<li> +The <a href="/pkg/math/big/"><code>math/big</code></a> package's +<a href="/pkg/math/big/#Int"><code>Int</code></a> type +now has methods +<a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a> +and +<a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a> +to convert to and from a JSON representation. +Also, +<a href="/pkg/math/big/#Int"><code>Int</code></a> +can now convert directly to and from a <code>uint64</code> using +<a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a> +and +<a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>, +while +<a href="/pkg/math/big/#Rat"><code>Rat</code></a> +can do the same with <code>float64</code> using +<a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a> +and +<a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>. +</li> + +<li> +The <a href="/pkg/mime/multipart/"><code>mime/multipart</code></a> package +has a new method for its +<a href="/pkg/mime/multipart/#Writer"><code>Writer</code></a>, +<a href="/pkg/mime/multipart/#Writer.SetBoundary"><code>SetBoundary</code></a>, +to define the boundary separator used to package the output. +The <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> also now +transparently decodes any <code>quoted-printable</code> parts and removes +the <code>Content-Transfer-Encoding</code> header when doing so. +</li> + +<li> +The +<a href="/pkg/net/"><code>net</code></a> package's +<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a> +function has changed return types: it now returns a +<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> +rather than a +<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>, which was +clearly a mistake in Go 1.0. +Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules. +</li> + +<li> +The <a href="/pkg/net/"><code>net</code></a> package includes a new type, +<a href="/pkg/net/#Dialer"><code>Dialer</code></a>, to supply options to +<a href="/pkg/net/#Dialer.Dial"><code>Dial</code></a>. +</li> + +<li> +The <a href="/pkg/net/"><code>net</code></a> package adds support for +link-local IPv6 addresses with zone qualifiers, such as <code>fe80::1%lo0</code>. +The address structures <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>, +<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>, and +<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a> +record the zone in a new field, and functions that expect string forms of these addresses, such as +<a href="/pkg/net/#Dial"><code>Dial</code></a>, +<a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>, +<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and +<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>, +now accept the zone-qualified form. +</li> + +<li> +The <a href="/pkg/net/"><code>net</code></a> package adds +<a href="/pkg/net/#LookupNS"><code>LookupNS</code></a> to its suite of resolving functions. +<code>LookupNS</code> returns the <a href="/pkg/net/#NS">NS records</a> for a host name. +</li> + +<li> +The <a href="/pkg/net/"><code>net</code></a> package adds protocol-specific +packet reading and writing methods to +<a href="/pkg/net/#IPConn"><code>IPConn</code></a> +(<a href="/pkg/net/#IPConn.ReadMsgIP"><code>ReadMsgIP</code></a> +and <a href="/pkg/net/#IPConn.WriteMsgIP"><code>WriteMsgIP</code></a>) and +<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> +(<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>ReadMsgUDP</code></a> and +<a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>WriteMsgUDP</code></a>). +These are specialized versions of <a href="/pkg/net/#PacketConn"><code>PacketConn</code></a>'s +<code>ReadFrom</code> and <code>WriteTo</code> methods that provide access to out-of-band data associated +with the packets. + </li> + + <li> +The <a href="/pkg/net/"><code>net</code></a> package adds methods to +<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> to allow closing half of the connection +(<a href="/pkg/net/#UnixConn.CloseRead"><code>CloseRead</code></a> and +<a href="/pkg/net/#UnixConn.CloseWrite"><code>CloseWrite</code></a>), +matching the existing methods of <a href="/pkg/net/#TCPConn"><code>TCPConn</code></a>. +</li> + +<li> +The <a href="/pkg/net/http/"><code>net/http</code></a> package includes several new additions. +<a href="/pkg/net/http/#ParseTime"><code>ParseTime</code></a> parses a time string, trying +several common HTTP time formats. +The <a href="/pkg/net/http/#Request.PostFormValue"><code>PostFormValue</code></a> method of +<a href="/pkg/net/http/#Request"><code>Request</code></a> is like +<a href="/pkg/net/http/#Request.FormValue"><code>FormValue</code></a> but ignores URL parameters. +The <a href="/pkg/net/http/#CloseNotifier"><code>CloseNotifier</code></a> interface provides a mechanism +for a server handler to discover when a client has disconnected. +The <code>ServeMux</code> type now has a +<a href="/pkg/net/http/#ServeMux.Handler"><code>Handler</code></a> method to access a path's +<code>Handler</code> without executing it. +The <code>Transport</code> can now cancel an in-flight request with +<a href="/pkg/net/http/#Transport.CancelRequest"><code>CancelRequest</code></a>. +Finally, the Transport is now more aggressive at closing TCP connections when +a <a href="/pkg/net/http/#Response"><code>Response.Body</code></a> is closed before +being fully consumed. +</li> + +<li> +The <a href="/pkg/net/mail/"><code>net/mail</code></a> package has two new functions, +<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and +<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>, +to parse RFC 5322-formatted mail addresses into +<a href="/pkg/net/mail/#Address"><code>Address</code></a> structures. +</li> + +<li> +The <a href="/pkg/net/smtp/"><code>net/smtp</code></a> package's +<a href="/pkg/net/smtp/#Client"><code>Client</code></a> type has a new method, +<a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>, +which transmits a <code>HELO</code> or <code>EHLO</code> message to the server. +</li> + +<li> +The <a href="/pkg/net/textproto/"><code>net/textproto</code></a> package +has two new functions, +<a href="/pkg/net/textproto/#TrimBytes"><code>TrimBytes</code></a> and +<a href="/pkg/net/textproto/#TrimString"><code>TrimString</code></a>, +which do ASCII-only trimming of leading and trailing spaces. +</li> + +<li> +The new method <a href="/pkg/os/#FileMode.IsRegular"><code>os.FileMode.IsRegular</code></a> makes it easy to ask if a file is a plain file. +</li> + +<li> +The <a href="/pkg/os/signal/"><code>os/signal</code></a> package has a new function, +<a href="/pkg/os/signal/#Stop"><code>Stop</code></a>, which stops the package delivering +any further signals to the channel. +</li> + +<li> +The <a href="/pkg/regexp/"><code>regexp</code></a> package +now supports Unix-original leftmost-longest matches through the +<a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a> +method, while +<a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices +strings into pieces based on separators defined by the regular expression. +</li> + +<li> +The <a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package +has three new functions regarding memory usage. +The <a href="/pkg/runtime/debug/#FreeOSMemory"><code>FreeOSMemory</code></a> +function triggers a run of the garbage collector and then attempts to return unused +memory to the operating system; +the <a href="/pkg/runtime/debug/#ReadGCStats"><code>ReadGCStats</code></a> +function retrieves statistics about the collector; and +<a href="/pkg/runtime/debug/#SetGCPercent"><code>SetGCPercent</code></a> +provides a programmatic way to control how often the collector runs, +including disabling it altogether. +</li> + +<li> +The <a href="/pkg/sort/"><code>sort</code></a> package has a new function, +<a href="/pkg/sort/#Reverse"><code>Reverse</code></a>. +Wrapping the argument of a call to +<a href="/pkg/sort/#Sort"><code>sort.Sort</code></a> +with a call to <code>Reverse</code> causes the sort order to be reversed. +</li> + +<li> +The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions, +<a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a> +and +<a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a> +with self-evident properties, and the new method +<a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the +<a href="/pkg/strings/#Reader"><code>Reader</code></a> +type now implements the +<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface. +</li> + +<li> +The <a href="/pkg/syscall/"><code>syscall</code></a> package's +<a href="/pkg/syscall/#Fchflags"><code>Fchflags</code></a> function on various BSDs +(including Darwin) has changed signature. +It now takes an int as the first parameter instead of a string. +Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules. +</li> +<li> +The <a href="/pkg/syscall/"><code>syscall</code></a> package also has received many updates +to make it more inclusive of constants and system calls for each supported operating system. +</li> + +<li> +The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation +statistics in tests and benchmarks using the new +<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function. And the +<a href="/pkg/testing/#B.ReportAllocs"><code>ReportAllocs</code></a> +method on <a href="/pkg/testing/#B"><code>testing.B</code></a> will enable printing of +memory allocation statistics for the calling benchmark. It also introduces the +<a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of +<a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>. +There is also a new +<a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code> +command-line flag, +and a new +<a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of +<a href="/pkg/testing/#B"><code>testing.B</code></a> and +<a href="/pkg/testing/#T"><code>testing.T</code></a> +to simplify skipping an inappropriate test. +</li> + +<li> +In the <a href="/pkg/text/template/"><code>text/template</code></a> +and +<a href="/pkg/html/template/"><code>html/template</code></a> packages, +templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines. +Also, as part of the new parser, the +<a href="/pkg/text/template/parse/#Node"><code>Node</code></a> interface got two new methods to provide +better error reporting. +Although this violates the Go 1 compatibility rules, +no existing code should be affected because this interface is explicitly intended only to be used +by the +<a href="/pkg/text/template/"><code>text/template</code></a> +and +<a href="/pkg/html/template/"><code>html/template</code></a> +packages and there are safeguards to guarantee that. +</li> + +<li> +The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0. +</li> + +<li> +In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package, +the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point. +To be valid, a rune must be in range and not be a surrogate half. +</li> +</ul> |