diff options
Diffstat (limited to 'doc/go1.1.html')
| -rw-r--r-- | doc/go1.1.html | 1099 |
1 files changed, 0 insertions, 1099 deletions
diff --git a/doc/go1.1.html b/doc/go1.1.html deleted file mode 100644 index f615c97e81..0000000000 --- a/doc/go1.1.html +++ /dev/null @@ -1,1099 +0,0 @@ -<!--{ - "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> |