github.com/xushiwei/go@v0.0.0-20130601165731-2b9d83f45bc9/doc/go1.1.html (about) 1 <!--{ 2 "Title": "Go 1.1 Release Notes", 3 "Path": "/doc/go1.1", 4 "Template": true 5 }--> 6 7 <h2 id="introduction">Introduction to Go 1.1</h2> 8 9 <p> 10 The release of <a href="/doc/go1.html">Go version 1</a> (Go 1 or Go 1.0 for short) 11 in March of 2012 introduced a new period 12 of stability in the Go language and libraries. 13 That stability has helped nourish a growing community of Go users 14 and systems around the world. 15 Several "point" releases since 16 then—1.0.1, 1.0.2, and 1.0.3—have been issued. 17 These point releases fixed known bugs but made 18 no non-critical changes to the implementation. 19 </p> 20 21 <p> 22 This new release, Go 1.1, keeps the <a href="/doc/go1compat.html">promise 23 of compatibility</a> but adds a couple of significant 24 (backwards-compatible, of course) language changes, has a long list 25 of (again, compatible) library changes, and 26 includes major work on the implementation of the compilers, 27 libraries, and run-time. 28 The focus is on performance. 29 Benchmarking is an inexact science at best, but we see significant, 30 sometimes dramatic speedups for many of our test programs. 31 We trust that many of our users' programs will also see improvements 32 just by updating their Go installation and recompiling. 33 </p> 34 35 <p> 36 This document summarizes the changes between Go 1 and Go 1.1. 37 Very little if any code will need modification to run with Go 1.1, 38 although a couple of rare error cases surface with this release 39 and need to be addressed if they arise. 40 Details appear below; see the discussion of 41 <a href="#int">64-bit ints</a> and <a href="#unicode_literals">Unicode literals</a> 42 in particular. 43 </p> 44 45 <h2 id="language">Changes to the language</h2> 46 47 <p> 48 <a href="/doc/go1compat.html">The Go compatibility document</a> promises 49 that programs written to the Go 1 language specification will continue to operate, 50 and those promises are maintained. 51 In the interest of firming up the specification, though, there are 52 details about some error cases that have been clarified. 53 There are also some new language features. 54 </p> 55 56 <h3 id="divzero">Integer division by zero</h3> 57 58 <p> 59 In Go 1, integer division by a constant zero produced a run-time panic: 60 </p> 61 62 <pre> 63 func f(x int) int { 64 return x/0 65 } 66 </pre> 67 68 <p> 69 In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error. 70 </p> 71 72 <h3 id="unicode_literals">Surrogates in Unicode literals</h3> 73 74 <p> 75 The definition of string and rune literals has been refined to exclude surrogate halves from the 76 set of valid Unicode code points. 77 See the <a href="#unicode">Unicode</a> section for more information. 78 </p> 79 80 <h3 id="method_values">Method values</h3> 81 82 <p> 83 Go 1.1 now implements 84 <a href="/ref/spec#Method_values">method values</a>, 85 which are functions that have been bound to a specific receiver value. 86 For instance, given a 87 <a href="/pkg/bufio/#Writer"><code>Writer</code></a> 88 value <code>w</code>, 89 the expression 90 <code>w.Write</code>, 91 a method value, is a function that will always write to <code>w</code>; it is equivalent to 92 a function literal closing over <code>w</code>: 93 </p> 94 95 <pre> 96 func (p []byte) (n int, err error) { 97 return w.Write(p) 98 } 99 </pre> 100 101 <p> 102 Method values are distinct from method expressions, which generate functions 103 from methods of a given type; the method expression <code>(*bufio.Writer).Write</code> 104 is equivalent to a function with an extra first argument, a receiver of type 105 <code>(*bufio.Writer)</code>: 106 </p> 107 108 <pre> 109 func (w *bufio.Writer, p []byte) (n int, err error) { 110 return w.Write(p) 111 } 112 </pre> 113 114 <p> 115 <em>Updating</em>: No existing code is affected; the change is strictly backward-compatible. 116 </p> 117 118 <h3 id="return">Return requirements</h3> 119 120 <p> 121 Before Go 1.1, a function that returned a value needed an explicit "return" 122 or call to <code>panic</code> at 123 the end of the function; this was a simple way to make the programmer 124 be explicit about the meaning of the function. But there are many cases 125 where a final "return" is clearly unnecessary, such as a function with 126 only an infinite "for" loop. 127 </p> 128 129 <p> 130 In Go 1.1, the rule about final "return" statements is more permissive. 131 It introduces the concept of a 132 <a href="/ref/spec/#Terminating_statements"><em>terminating statement</em></a>, 133 a statement that is guaranteed to be the last one a function executes. 134 Examples include 135 "for" loops with no condition and "if-else" 136 statements in which each half ends in a "return". 137 If the final statement of a function can be shown <em>syntactically</em> to 138 be a terminating statement, no final "return" statement is needed. 139 </p> 140 141 <p> 142 Note that the rule is purely syntactic: it pays no attention to the values in the 143 code and therefore requires no complex analysis. 144 </p> 145 146 <p> 147 <em>Updating</em>: The change is backward-compatible, but existing code 148 with superfluous "return" statements and calls to <code>panic</code> may 149 be simplified manually. 150 Such code can be identified by <code>go vet</code>. 151 </p> 152 153 <h2 id="impl">Changes to the implementations and tools</h2> 154 155 <h3 id="gccgo">Status of gccgo</h3> 156 157 <p> 158 The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in 159 <code>gccgo</code>'s releases. 160 The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of <code>gccgo</code>. 161 Its library is a little behind the release, but the biggest difference is that method values are not implemented. 162 Sometime around May 2013, we expect 4.8.1 of GCC to ship with a <code>gccgo</code> 163 providing a complete Go 1.1 implementaiton. 164 </p> 165 166 <h3 id="gc_flag">Command-line flag parsing</h3> 167 168 <p> 169 In the gc tool chain, the compilers and linkers now use the 170 same command-line flag parsing rules as the Go flag package, a departure 171 from the traditional Unix flag parsing. This may affect scripts that invoke 172 the tool directly. 173 For example, 174 <code>go tool 6c -Fw -Dfoo</code> must now be written 175 <code>go tool 6c -F -w -D foo</code>. 176 </p> 177 178 <h3 id="int">Size of int on 64-bit platforms</h3> 179 180 <p> 181 The language allows the implementation to choose whether the <code>int</code> type and 182 <code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code> 183 and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations 184 now make 185 <code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64. 186 Among other things, this enables the allocation of slices with 187 more than 2 billion elements on 64-bit platforms. 188 </p> 189 190 <p> 191 <em>Updating</em>: 192 Most programs will be unaffected by this change. 193 Because Go does not allow implicit conversions between distinct 194 <a href="/ref/spec/#Numeric_types">numeric types</a>, 195 no programs will stop compiling due to this change. 196 However, programs that contain implicit assumptions 197 that <code>int</code> is only 32 bits may change behavior. 198 For example, this code prints a positive number on 64-bit systems and 199 a negative one on 32-bit systems: 200 201 <pre> 202 x := ^uint32(0) // x is 0xffffffff 203 i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit 204 fmt.Println(i) 205 </pre> 206 207 <p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems) 208 would instead say: 209 </p> 210 211 <pre> 212 i := int(int32(x)) 213 </pre> 214 215 <h3 id="heap">Heap size on 64-bit architectures</h3> 216 217 <p> 218 On 64-bit architectures, the maximum heap size has been enlarged substantially, 219 from a few gigabytes to several tens of gigabytes. 220 (The exact details depend on the system and may change.) 221 </p> 222 223 <p> 224 On 32-bit architectures, the heap size has not changed. 225 </p> 226 227 <p> 228 <em>Updating</em>: 229 This change should have no effect on existing programs beyond allowing them 230 to run with larger heaps. 231 </p> 232 233 <h3 id="unicode">Unicode</h3> 234 235 <p> 236 To make it possible to represent code points greater than 65535 in UTF-16, 237 Unicode defines <em>surrogate halves</em>, 238 a range of code points to be used only in the assembly of large values, and only in UTF-16. 239 The code points in that surrogate range are illegal for any other purpose. 240 In Go 1.1, this constraint is honored by the compiler, libraries, and run-time: 241 a surrogate half is illegal as a rune value, when encoded as UTF-8, or when 242 encoded in isolation as UTF-16. 243 When encountered, for example in converting from a rune to UTF-8, it is 244 treated as an encoding error and will yield the replacement rune, 245 <a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>, 246 U+FFFD. 247 </p> 248 249 <p> 250 This program, 251 </p> 252 253 <pre> 254 import "fmt" 255 256 func main() { 257 fmt.Printf("%+q\n", string(0xD800)) 258 } 259 </pre> 260 261 <p> 262 printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1. 263 </p> 264 265 <p> 266 Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as 267 <code>'\ud800'</code> and <code>"\ud800"</code> are now rejected by the compilers. 268 When written explicitly as UTF-8 encoded bytes, 269 such strings can still be created, as in <code>"\xed\xa0\x80"</code>. 270 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> 271 values. 272 </p> 273 274 <p> 275 The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first 276 character of a Go source file. 277 Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary, 278 some editors add the mark as a kind of "magic number" identifying a UTF-8 encoded file. 279 </p> 280 281 <p> 282 <em>Updating</em>: 283 Most programs will be unaffected by the surrogate change. 284 Programs that depend on the old behavior should be modified to avoid the issue. 285 The byte-order-mark change is strictly backward-compatible. 286 </p> 287 288 <h3 id="race">Race detector</h3> 289 290 <p> 291 A major addition to the tools is a <em>race detector</em>, a way to 292 find bugs in programs caused by concurrent access of the same 293 variable, where at least one of the accesses is a write. 294 This new facility is built into the <code>go</code> tool. 295 For now, it is only available on Linux, Mac OS X, and Windows systems with 296 64-bit x86 processors. 297 To enable it, set the <code>-race</code> flag when building or testing your program 298 (for instance, <code>go test -race</code>). 299 The race detector is documented in <a href="/doc/articles/race_detector.html">a separate article</a>. 300 </p> 301 302 <h3 id="gc_asm">The gc assemblers</h3> 303 304 <p> 305 Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and 306 a new internal <a href="http://golang.org/s/go11func">representation of functions</a>, 307 the arrangement of function arguments on the stack has changed in the gc tool chain. 308 Functions written in assembly will need to be revised at least 309 to adjust frame pointer offsets. 310 </p> 311 312 <p> 313 <em>Updating</em>: 314 The <code>go vet</code> command now checks that functions implemented in assembly 315 match the Go function prototypes they implement. 316 </p> 317 318 <h3 id="gocmd">Changes to the go command</h3> 319 320 <p> 321 The <a href="/cmd/go/"><code>go</code></a> command has acquired several 322 changes intended to improve the experience for new Go users. 323 </p> 324 325 <p> 326 First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages, 327 including a list of paths searched, when a package cannot be located. 328 </p> 329 330 <pre> 331 $ go build foo/quxx 332 can't load package: package foo/quxx: cannot find package "foo/quxx" in any of: 333 /home/you/go/src/pkg/foo/quxx (from $GOROOT) 334 /home/you/src/foo/quxx (from $GOPATH) 335 </pre> 336 337 <p> 338 Second, the <code>go get</code> command no longer allows <code>$GOROOT</code> 339 as the default destination when downloading package source. 340 To use the <code>go get</code> 341 command, a <a href="/doc/code.html#GOPATH">valid <code>$GOPATH</code></a> is now required. 342 </p> 343 344 <pre> 345 $ GOPATH= go get code.google.com/p/foo/quxx 346 package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath 347 </pre> 348 349 <p> 350 Finally, as a result of the previous change, the <code>go get</code> command will also fail 351 when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value. 352 </p> 353 354 <pre> 355 $ GOPATH=$GOROOT go get code.google.com/p/foo/quxx 356 warning: GOPATH set to GOROOT (/home/you/go) has no effect 357 package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath 358 </pre> 359 360 <h3 id="gotest">Changes to the go test command</h3> 361 362 <p> 363 The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a> 364 command no longer deletes the binary when run with profiling enabled, 365 to make it easier to analyze the profile. 366 The implementation sets the <code>-c</code> flag automatically, so after running, 367 </p> 368 369 <pre> 370 $ go test -cpuprofile cpuprof.out mypackage 371 </pre> 372 373 <p> 374 the file <code>mypackage.test</code> will be left in the directory where <code>go test</code> was run. 375 </p> 376 377 <p> 378 The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a> 379 command can now generate profiling information 380 that reports where goroutines are blocked, that is, 381 where they tend to stall waiting for an event such as a channel communication. 382 The information is presented as a 383 <em>blocking profile</em> 384 enabled with the 385 <code>-blockprofile</code> 386 option of 387 <code>go test</code>. 388 Run <code>go help test</code> for more information. 389 </p> 390 391 <h3 id="gofix">Changes to the go fix command</h3> 392 393 <p> 394 The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as 395 <code>go fix</code>, no longer applies fixes to update code from 396 before Go 1 to use Go 1 APIs. 397 To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain 398 to convert the code to Go 1.0 first. 399 </p> 400 401 <h3 id="tags">Build constraints</h3> 402 403 <p> 404 The "<code>go1.1</code>" tag has been added to the list of default 405 <a href="/pkg/go/build/#hdr-Build_Constraints">build constraints</a>. 406 This permits packages to take advantage of the new features in Go 1.1 while 407 remaining compatible with earlier versions of Go. 408 </p> 409 410 <p> 411 To build a file only with Go 1.1 and above, add this build constraint: 412 </p> 413 414 <pre> 415 // +build go1.1 416 </pre> 417 418 <p> 419 To build a file only with Go 1.0.x, use the converse constraint: 420 </p> 421 422 <pre> 423 // +build !go1.1 424 </pre> 425 426 <h3 id="platforms">Additional platforms</h3> 427 428 <p> 429 The Go 1.1 tool chain adds experimental support for <code>freebsd/arm</code>, 430 <code>netbsd/386</code>, <code>netbsd/amd64</code>, <code>netbsd/arm</code>, 431 <code>openbsd/386</code> and <code>openbsd/amd64</code> platforms. 432 </p> 433 434 <p> 435 An ARMv6 or later processor is required for <code>freebsd/arm</code> or 436 <code>netbsd/arm</code>. 437 </p> 438 439 <p> 440 Go 1.1 adds experimental support for <code>cgo</code> on <code>linux/arm</code>. 441 </p> 442 443 <h3 id="crosscompile">Cross compilation</h3> 444 445 <p> 446 When cross-compiling, the <code>go</code> tool will disable <code>cgo</code> 447 support by default. 448 </p> 449 450 <p> 451 To explicitly enable <code>cgo</code>, set <code>CGO_ENABLED=1</code>. 452 </p> 453 454 <h2 id="performance">Performance</h2> 455 456 <p> 457 The performance of code compiled with the Go 1.1 gc tool suite should be noticeably 458 better for most Go programs. 459 Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes 460 much more, but occasionally less or even non-existent. 461 There are too many small performance-driven tweaks through the tools and libraries 462 to list them all here, but the following major changes are worth noting: 463 </p> 464 465 <ul> 466 <li>The gc compilers generate better code in many cases, most noticeably for 467 floating point on the 32-bit Intel architecture.</li> 468 <li>The gc compilers do more in-lining, including for some operations 469 in the run-time such as <a href="/pkg/builtin/#append"><code>append</code></a> 470 and interface conversions.</li> 471 <li>There is a new implementation of Go maps with significant reduction in 472 memory footprint and CPU time.</li> 473 <li>The garbage collector has been made more parallel, which can reduce 474 latencies for programs running on multiple CPUs.</li> 475 <li>The garbage collector is also more precise, which costs a small amount of 476 CPU time but can reduce the size of the heap significantly, especially 477 on 32-bit architectures.</li> 478 <li>Due to tighter coupling of the run-time and network libraries, fewer 479 context switches are required on network operations.</li> 480 </ul> 481 482 <h2 id="library">Changes to the standard library</h2> 483 484 <h3 id="bufio_scanner">bufio.Scanner</h3> 485 486 <p> 487 The various routines to scan textual input in the 488 <a href="/pkg/bufio/"><code>bufio</code></a> 489 package, 490 <a href="/pkg/bufio/#Reader.ReadBytes"><code>ReadBytes</code></a>, 491 <a href="/pkg/bufio/#Reader.ReadString"><code>ReadString</code></a> 492 and particularly 493 <a href="/pkg/bufio/#Reader.ReadLine"><code>ReadLine</code></a>, 494 are needlessly complex to use for simple purposes. 495 In Go 1.1, a new type, 496 <a href="/pkg/bufio/#Scanner"><code>Scanner</code></a>, 497 has been added to make it easier to do simple tasks such as 498 read the input as a sequence of lines or space-delimited words. 499 It simplifies the problem by terminating the scan on problematic 500 input such as pathologically long lines, and having a simple 501 default: line-oriented input, with each line stripped of its terminator. 502 Here is code to reproduce the input a line at a time: 503 </p> 504 505 <pre> 506 scanner := bufio.NewScanner(os.Stdin) 507 for scanner.Scan() { 508 fmt.Println(scanner.Text()) // Println will add back the final '\n' 509 } 510 if err := scanner.Err(); err != nil { 511 fmt.Fprintln(os.Stderr, "reading standard input:", err) 512 } 513 </pre> 514 515 <p> 516 Scanning behavior can be adjusted through a function to control subdividing the input 517 (see the documentation for <a href="/pkg/bufio/#SplitFunc"><code>SplitFunc</code></a>), 518 but for tough problems or the need to continue past errors, the older interface 519 may still be required. 520 </p> 521 522 <h3 id="net">net</h3> 523 524 <p> 525 The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly 526 lax about the network name passed in. 527 Although the documentation was clear 528 that the only valid networks for 529 <a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a> 530 are <code>"tcp"</code>, 531 <code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string. 532 The Go 1.1 implementation returns an error if the network is not one of those strings. 533 The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>, 534 <a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and 535 <a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>. 536 </p> 537 538 <p> 539 The previous implementation of 540 <a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a> 541 returned a 542 <a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as 543 a representation of the connection endpoint. 544 The Go 1.1 implementation instead returns a 545 <a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> 546 to allow reading and writing 547 with its 548 <a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a> 549 and 550 <a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a> 551 methods. 552 </p> 553 554 <p> 555 The data structures 556 <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>, 557 <a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>, and 558 <a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a> 559 add a new string field called <code>Zone</code>. 560 Code using untagged composite literals (e.g. <code>net.TCPAddr{ip, port}</code>) 561 instead of tagged literals (<code>net.TCPAddr{IP: ip, Port: port}</code>) 562 will break due to the new field. 563 The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages. 564 </p> 565 566 <p> 567 <em>Updating</em>: 568 To correct breakage caused by the new struct field, 569 <code>go fix</code> will rewrite code to add tags for these types. 570 More generally, <code>go vet</code> will identify composite literals that 571 should be revised to use field tags. 572 </p> 573 574 <h3 id="reflect">reflect</h3> 575 576 <p> 577 The <a href="/pkg/reflect/"><code>reflect</code></a> package has several significant additions. 578 </p> 579 580 <p> 581 It is now possible to run a "select" statement using 582 the <code>reflect</code> package; see the description of 583 <a href="/pkg/reflect/#Select"><code>Select</code></a> 584 and 585 <a href="/pkg/reflect/#SelectCase"><code>SelectCase</code></a> 586 for details. 587 </p> 588 589 <p> 590 The new method 591 <a href="/pkg/reflect/#Value.Convert"><code>Value.Convert</code></a> 592 (or 593 <a href="/pkg/reflect/#Type"><code>Type.ConvertibleTo</code></a>) 594 provides functionality to execute a Go conversion or type assertion operation 595 on a 596 <a href="/pkg/reflect/#Value"><code>Value</code></a> 597 (or test for its possibility). 598 </p> 599 600 <p> 601 The new function 602 <a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a> 603 creates a wrapper function to make it easier to call a function with existing 604 <a href="/pkg/reflect/#Value"><code>Values</code></a>, 605 doing the standard Go conversions among the arguments, for instance 606 to pass an actual <code>int</code> to a formal <code>interface{}</code>. 607 </p> 608 609 <p> 610 Finally, the new functions 611 <a href="/pkg/reflect/#ChanOf"><code>ChanOf</code></a>, 612 <a href="/pkg/reflect/#MapOf"><code>MapOf</code></a> 613 and 614 <a href="/pkg/reflect/#SliceOf"><code>SliceOf</code></a> 615 construct new 616 <a href="/pkg/reflect/#Type"><code>Types</code></a> 617 from existing types, for example to construct the type <code>[]T</code> given 618 only <code>T</code>. 619 </p> 620 621 622 <h3 id="time">time</h3> 623 <p> 624 On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the 625 <a href="/pkg/time/"><code>time</code></a> package 626 returned times with microsecond precision. 627 The Go 1.1 implementation on these 628 systems now returns times with nanosecond precision. 629 Programs that write to an external format with microsecond precision 630 and read it back, expecting to recover the original value, will be affected 631 by the loss of precision. 632 There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>, 633 <a href="/pkg/time/#Time.Round"><code>Round</code></a> 634 and 635 <a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>, 636 that can be used to remove precision from a time before passing it to 637 external storage. 638 </p> 639 640 <p> 641 The new method 642 <a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a> 643 returns the one-indexed integral day number of the year specified by the time value. 644 </p> 645 646 <p> 647 The 648 <a href="/pkg/time/#Timer"><code>Timer</code></a> 649 type has a new method 650 <a href="/pkg/time/#Timer.Reset"><code>Reset</code></a> 651 that modifies the timer to expire after a specified duration. 652 </p> 653 654 <p> 655 Finally, the new function 656 <a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a> 657 is like the existing 658 <a href="/pkg/time/#Parse"><code>Parse</code></a> 659 but parses the time in the context of a location (time zone), ignoring 660 time zone information in the parsed string. 661 This function addresses a common source of confusion in the time API. 662 </p> 663 664 <p> 665 <em>Updating</em>: 666 Code that needs to read and write times using an external format with 667 lower precision should be modified to use the new methods. 668 669 <h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3> 670 671 <p> 672 To make it easier for binary distributions to access them if desired, the <code>exp</code> 673 and <code>old</code> source subtrees, which are not included in binary distributions, 674 have been moved to the new <code>go.exp</code> subrepository at 675 <code>code.google.com/p/go.exp</code>. To access the <code>ssa</code> package, 676 for example, run 677 </p> 678 679 <pre> 680 $ go get code.google.com/p/go.exp/ssa 681 </pre> 682 683 <p> 684 and then in Go source, 685 </p> 686 687 <pre> 688 import "code.google.com/p/go.exp/ssa" 689 </pre> 690 691 <p> 692 The old package <code>exp/norm</code> has also been moved, but to a new repository 693 <code>go.text</code>, where the Unicode APIs and other text-related packages will 694 be developed. 695 </p> 696 697 <h3 id="new_packages">New packages</h3> 698 699 <p> 700 There are three new packages. 701 </p> 702 703 <ul> 704 <li> 705 The <a href="/pkg/go/format/"><code>go/format</code></a> package provides 706 a convenient way for a program to access the formatting capabilities of the 707 <a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command. 708 It has two functions, 709 <a href="/pkg/go/format/#Node"><code>Node</code></a> to format a Go parser 710 <a href="/pkg/go/ast/#Node"><code>Node</code></a>, 711 and 712 <a href="/pkg/go/format/#Source"><code>Source</code></a> 713 to reformat arbitrary Go source code into the standard format as provided by the 714 <a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command. 715 </li> 716 717 <li> 718 The <a href="/pkg/net/http/cookiejar/"><code>net/http/cookiejar</code></a> package provides the basics for managing HTTP cookies. 719 </li> 720 721 <li> 722 The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package provides low-level facilities for data race detection. 723 It is internal to the race detector and does not otherwise export any user-visible functionality. 724 </li> 725 </ul> 726 727 <h3 id="minor_library_changes">Minor changes to the library</h3> 728 729 <p> 730 The following list summarizes a number of minor changes to the library, mostly additions. 731 See the relevant package documentation for more information about each change. 732 </p> 733 734 <ul> 735 <li> 736 The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions, 737 <a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a> 738 and 739 <a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>, 740 with self-evident properties. 741 Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type 742 has a new method 743 <a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that 744 provides some control over memory allocation inside the buffer. 745 Finally, the 746 <a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a 747 <a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method 748 so it implements the 749 <a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface. 750 </li> 751 752 <li> 753 The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package has 754 a new <a href="/pkg/compress/gzip/#Writer.Flush"><code>Flush</code></a> 755 method for its 756 <a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a> 757 type that flushes its underlying <code>flate.Writer</code>. 758 </li> 759 760 <li> 761 The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function, 762 <a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs. 763 </li> 764 765 <li> 766 The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package 767 now supports PEM blocks (see 768 <a href="/pkg/crypto/x509/#DecryptPEMBlock"><code>DecryptPEMBlock</code></a> for instance), 769 and a new function 770 <a href="/pkg/crypto/x509/#ParseECPrivateKey"><code>ParseECPrivateKey</code></a> to parse elliptic curve private keys. 771 </li> 772 773 <li> 774 The <a href="/pkg/database/sql/"><code>database/sql</code></a> package 775 has a new 776 <a href="/pkg/database/sql/#DB.Ping"><code>Ping</code></a> 777 method for its 778 <a href="/pkg/database/sql/#DB"><code>DB</code></a> 779 type that tests the health of the connection. 780 </li> 781 782 <li> 783 The <a href="/pkg/database/sql/driver/"><code>database/sql/driver</code></a> package 784 has a new 785 <a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a> 786 interface that a 787 <a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a> 788 may implement to improve performance. 789 </li> 790 791 <li> 792 The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package's 793 <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a> 794 has a new method 795 <a href="/pkg/encoding/json/#Decoder.Buffered"><code>Buffered</code></a> 796 to provide access to the remaining data in its buffer, 797 as well as a new method 798 <a href="/pkg/encoding/json/#Decoder.UseNumber"><code>UseNumber</code></a> 799 to unmarshal a value into the new type 800 <a href="/pkg/encoding/json/#Number"><code>Number</code></a>, 801 a string, rather than a float64. 802 </li> 803 804 <li> 805 The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package 806 has a new function, 807 <a href="/pkg/encoding/xml/#EscapeText"><code>EscapeText</code></a>, 808 which writes escaped XML output, 809 and a method on 810 <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>, 811 <a href="/pkg/encoding/xml/#Encoder.Indent"><code>Indent</code></a>, 812 to specify indented output. 813 </li> 814 815 <li> 816 In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a 817 new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a> 818 and associated methods makes it easier to extract and process comments in Go programs. 819 </li> 820 821 <li> 822 In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package, 823 the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code> 824 throughout the code, 825 information that the <a href="/cmd/godoc/"><code>godoc</code></a> 826 command can filter or present according to the value of the <code>-notes</code> flag. 827 </li> 828 829 <li> 830 The undocumented and only partially implemented "noescape" feature of the 831 <a href="/pkg/html/template/"><code>html/template</code></a> 832 package has been removed; programs that depend on it will break. 833 </li> 834 835 <li> 836 The <a href="/pkg/image/jpeg/"><code>image/jpeg</code></a> package now 837 reads progressive JPEG files and handles a few more subsampling configurations. 838 </li> 839 840 <li> 841 The <a href="/pkg/io/"><code>io</code></a> package now exports the 842 <a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common 843 functionality of writing a byte at a time. 844 It also exports a new error, <a href="/pkg/io/#ErrNoProgress"><code>ErrNoProgress</code></a>, 845 used to indicate a <code>Read</code> implementation is looping without delivering data. 846 </li> 847 848 <li> 849 The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support 850 for OS-specific logging features. 851 </li> 852 853 <li> 854 The <a href="/pkg/math/big/"><code>math/big</code></a> package's 855 <a href="/pkg/math/big/#Int"><code>Int</code></a> type 856 now has methods 857 <a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a> 858 and 859 <a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a> 860 to convert to and from a JSON representation. 861 Also, 862 <a href="/pkg/math/big/#Int"><code>Int</code></a> 863 can now convert directly to and from a <code>uint64</code> using 864 <a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a> 865 and 866 <a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>, 867 while 868 <a href="/pkg/math/big/#Rat"><code>Rat</code></a> 869 can do the same with <code>float64</code> using 870 <a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a> 871 and 872 <a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>. 873 </li> 874 875 <li> 876 The <a href="/pkg/mime/multipart/"><code>mime/multipart</code></a> package 877 has a new method for its 878 <a href="/pkg/mime/multipart/#Writer"><code>Writer</code></a>, 879 <a href="/pkg/mime/multipart/#Writer.SetBoundary"><code>SetBoundary</code></a>, 880 to define the boundary separator used to package the output. 881 The <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> also now 882 transparently decodes any <code>quoted-printable</code> parts and removes 883 the <code>Content-Transfer-Encoding</code> header when doing so. 884 </li> 885 886 <li> 887 The 888 <a href="/pkg/net/"><code>net</code></a> package's 889 <a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a> 890 function has changed return types: it now returns a 891 <a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> 892 rather than a 893 <a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>, which was 894 clearly a mistake in Go 1.0. 895 Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules. 896 </li> 897 898 <li> 899 The <a href="/pkg/net/"><code>net</code></a> package includes a new type, 900 <a href="/pkg/net/#Dialer"><code>Dialer</code></a>, to supply options to 901 <a href="/pkg/net/#Dialer.Dial"><code>Dial</code></a>. 902 </li> 903 904 <li> 905 The <a href="/pkg/net/"><code>net</code></a> package adds support for 906 link-local IPv6 addresses with zone qualifiers, such as <code>fe80::1%lo0</code>. 907 The address structures <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>, 908 <a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>, and 909 <a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a> 910 record the zone in a new field, and functions that expect string forms of these addresses, such as 911 <a href="/pkg/net/#Dial"><code>Dial</code></a>, 912 <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>, 913 <a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and 914 <a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>, 915 now accept the zone-qualified form. 916 </li> 917 918 <li> 919 The <a href="/pkg/net/"><code>net</code></a> package adds 920 <a href="/pkg/net/#LookupNS"><code>LookupNS</code></a> to its suite of resolving functions. 921 <code>LookupNS</code> returns the <a href="/pkg/net/#NS">NS records</a> for a host name. 922 </li> 923 924 <li> 925 The <a href="/pkg/net/"><code>net</code></a> package adds protocol-specific 926 packet reading and writing methods to 927 <a href="/pkg/net/#IPConn"><code>IPConn</code></a> 928 (<a href="/pkg/net/#IPConn.ReadMsgIP"><code>ReadMsgIP</code></a> 929 and <a href="/pkg/net/#IPConn.WriteMsgIP"><code>WriteMsgIP</code></a>) and 930 <a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> 931 (<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>ReadMsgUDP</code></a> and 932 <a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>WriteMsgUDP</code></a>). 933 These are specialized versions of <a href="/pkg/net/#PacketConn"><code>PacketConn</code></a>'s 934 <code>ReadFrom</code> and <code>WriteTo</code> methods that provide access to out-of-band data associated 935 with the packets. 936 </li> 937 938 <li> 939 The <a href="/pkg/net/"><code>net</code></a> package adds methods to 940 <a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> to allow closing half of the connection 941 (<a href="/pkg/net/#UnixConn.CloseRead"><code>CloseRead</code></a> and 942 <a href="/pkg/net/#UnixConn.CloseWrite"><code>CloseWrite</code></a>), 943 matching the existing methods of <a href="/pkg/net/#TCPConn"><code>TCPConn</code></a>. 944 </li> 945 946 <li> 947 The <a href="/pkg/net/http/"><code>net/http</code></a> package includes several new additions. 948 <a href="/pkg/net/http/#ParseTime"><code>ParseTime</code></a> parses a time string, trying 949 several common HTTP time formats. 950 The <a href="/pkg/net/http/#Request.PostFormValue"><code>PostFormValue</code></a> method of 951 <a href="/pkg/net/http/#Request"><code>Request</code></a> is like 952 <a href="/pkg/net/http/#Request.FormValue"><code>FormValue</code></a> but ignores URL parameters. 953 The <a href="/pkg/net/http/#CloseNotifier"><code>CloseNotifier</code></a> interface provides a mechanism 954 for a server handler to discover when a client has disconnected. 955 The <code>ServeMux</code> type now has a 956 <a href="/pkg/net/http/#ServeMux.Handler"><code>Handler</code></a> method to access a path's 957 <code>Handler</code> without executing it. 958 The <code>Transport</code> can now cancel an in-flight request with 959 <a href="/pkg/net/http/#Transport.CancelRequest"><code>CancelRequest</code></a>. 960 Finally, the Transport is now more aggressive at closing TCP connections when 961 a <a href="/pkg/net/http/#Response"><code>Response.Body</code></a> is closed before 962 being fully consumed. 963 </li> 964 965 <li> 966 The <a href="/pkg/net/mail/"><code>net/mail</code></a> package has two new functions, 967 <a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and 968 <a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>, 969 to parse RFC 5322-formatted mail addresses into 970 <a href="/pkg/net/mail/#Address"><code>Address</code></a> structures. 971 </li> 972 973 <li> 974 The <a href="/pkg/net/smtp/"><code>net/smtp</code></a> package's 975 <a href="/pkg/net/smtp/#Client"><code>Client</code></a> type has a new method, 976 <a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>, 977 which transmits a <code>HELO</code> or <code>EHLO</code> message to the server. 978 </li> 979 980 <li> 981 The <a href="/pkg/net/textproto/"><code>net/textproto</code></a> package 982 has two new functions, 983 <a href="/pkg/net/textproto/#TrimBytes"><code>TrimBytes</code></a> and 984 <a href="/pkg/net/textproto/#TrimString"><code>TrimString</code></a>, 985 which do ASCII-only trimming of leading and trailing spaces. 986 </li> 987 988 <li> 989 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. 990 </li> 991 992 <li> 993 The <a href="/pkg/os/signal/"><code>os/signal</code></a> package has a new function, 994 <a href="/pkg/os/signal/#Stop"><code>Stop</code></a>, which stops the package delivering 995 any further signals to the channel. 996 </li> 997 998 <li> 999 The <a href="/pkg/regexp/"><code>regexp</code></a> package 1000 now supports Unix-original leftmost-longest matches through the 1001 <a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a> 1002 method, while 1003 <a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices 1004 strings into pieces based on separators defined by the regular expression. 1005 </li> 1006 1007 <li> 1008 The <a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package 1009 has three new functions regarding memory usage. 1010 The <a href="/pkg/runtime/debug/#FreeOSMemory"><code>FreeOSMemory</code></a> 1011 function triggers a run of the garbage collector and then attempts to return unused 1012 memory to the operating system; 1013 the <a href="/pkg/runtime/debug/#ReadGCStats"><code>ReadGCStats</code></a> 1014 function retrieves statistics about the collector; and 1015 <a href="/pkg/runtime/debug/#SetGCPercent"><code>SetGCPercent</code></a> 1016 provides a programmatic way to control how often the collector runs, 1017 including disabling it altogether. 1018 </li> 1019 1020 <li> 1021 The <a href="/pkg/sort/"><code>sort</code></a> package has a new function, 1022 <a href="/pkg/sort/#Reverse"><code>Reverse</code></a>. 1023 Wrapping the argument of a call to 1024 <a href="/pkg/sort/#Sort"><code>sort.Sort</code></a> 1025 with a call to <code>Reverse</code> causes the sort order to be reversed. 1026 </li> 1027 1028 <li> 1029 The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions, 1030 <a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a> 1031 and 1032 <a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a> 1033 with self-evident properties, and the new method 1034 <a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the 1035 <a href="/pkg/strings/#Reader"><code>Reader</code></a> 1036 type now implements the 1037 <a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface. 1038 </li> 1039 1040 <li> 1041 The <a href="/pkg/syscall/"><code>syscall</code></a> package's 1042 <a href="/pkg/syscall/#Fchflags"><code>Fchflags</code></a> function on various BSDs 1043 (including Darwin) has changed signature. 1044 It now takes an int as the first parameter instead of a string. 1045 Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules. 1046 </li> 1047 <li> 1048 The <a href="/pkg/syscall/"><code>syscall</code></a> package also has received many updates 1049 to make it more inclusive of constants and system calls for each supported operating system. 1050 </li> 1051 1052 <li> 1053 The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation 1054 statistics in tests and benchmarks using the new 1055 <a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function. And the 1056 <a href="/pkg/testing/#B.ReportAllocs"><code>ReportAllocs</code></a> 1057 method on <a href="/pkg/testing/#B"><code>testing.B</code></a> will enable printing of 1058 memory allocation statistics for the calling benchmark. It also introduces the 1059 <a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of 1060 <a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>. 1061 There is also a new 1062 <a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code> 1063 command-line flag, 1064 and a new 1065 <a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of 1066 <a href="/pkg/testing/#B"><code>testing.B</code></a> and 1067 <a href="/pkg/testing/#T"><code>testing.T</code></a> 1068 to simplify skipping an inappropriate test. 1069 </li> 1070 1071 <li> 1072 In the <a href="/pkg/text/template/"><code>text/template</code></a> 1073 and 1074 <a href="/pkg/html/template/"><code>html/template</code></a> packages, 1075 templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines. 1076 Also, as part of the new parser, the 1077 <a href="/pkg/text/template/parse/#Node"><code>Node</code></a> interface got two new methods to provide 1078 better error reporting. 1079 Although this violates the Go 1 compatibility rules, 1080 no existing code should be affected because this interface is explicitly intended only to be used 1081 by the 1082 <a href="/pkg/text/template/"><code>text/template</code></a> 1083 and 1084 <a href="/pkg/html/template/"><code>html/template</code></a> 1085 packages and there are safeguards to guarantee that. 1086 </li> 1087 1088 <li> 1089 The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0. 1090 </li> 1091 1092 <li> 1093 In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package, 1094 the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point. 1095 To be valid, a rune must be in range and not be a surrogate half. 1096 </li> 1097 </ul>