golang.org/x/net@v0.25.1-0.20240516223405-c87a5b62e243/html/testdata/go1.html (about) 1 <!DOCTYPE html> 2 <html> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5 6 <title>Go 1 Release Notes - The Go Programming Language</title> 7 8 <link type="text/css" rel="stylesheet" href="/doc/style.css"> 9 <script type="text/javascript" src="/doc/godocs.js"></script> 10 11 <link rel="search" type="application/opensearchdescription+xml" title="godoc" href="/opensearch.xml" /> 12 13 <script type="text/javascript"> 14 var _gaq = _gaq || []; 15 _gaq.push(["_setAccount", "UA-11222381-2"]); 16 _gaq.push(["_trackPageview"]); 17 </script> 18 </head> 19 <body> 20 21 <div id="topbar"><div class="container wide"> 22 23 <form method="GET" action="/search"> 24 <div id="menu"> 25 <a href="/doc/">Documents</a> 26 <a href="/ref/">References</a> 27 <a href="/pkg/">Packages</a> 28 <a href="/project/">The Project</a> 29 <a href="/help/">Help</a> 30 <input type="text" id="search" name="q" class="inactive" value="Search"> 31 </div> 32 <div id="heading"><a href="/">The Go Programming Language</a></div> 33 </form> 34 35 </div></div> 36 37 <div id="page" class="wide"> 38 39 40 <div id="minusone"><g:minusone size="small" annotation="none"></g:minusone></div> 41 <h1>Go 1 Release Notes</h1> 42 43 44 45 46 <div id="nav"></div> 47 48 49 50 51 <h2 id="introduction">Introduction to Go 1</h2> 52 53 <p> 54 Go version 1, Go 1 for short, defines a language and a set of core libraries 55 that provide a stable foundation for creating reliable products, projects, and 56 publications. 57 </p> 58 59 <p> 60 The driving motivation for Go 1 is stability for its users. People should be able to 61 write Go programs and expect that they will continue to compile and run without 62 change, on a time scale of years, including in production environments such as 63 Google App Engine. Similarly, people should be able to write books about Go, be 64 able to say which version of Go the book is describing, and have that version 65 number still be meaningful much later. 66 </p> 67 68 <p> 69 Code that compiles in Go 1 should, with few exceptions, continue to compile and 70 run throughout the lifetime of that version, even as we issue updates and bug 71 fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes 72 made to the language and library for subsequent releases of Go 1 may 73 add functionality but will not break existing Go 1 programs. 74 <a href="go1compat.html">The Go 1 compatibility document</a> 75 explains the compatibility guidelines in more detail. 76 </p> 77 78 <p> 79 Go 1 is a representation of Go as it used today, not a wholesale rethinking of 80 the language. We avoided designing new features and instead focused on cleaning 81 up problems and inconsistencies and improving portability. There are a number 82 changes to the Go language and packages that we had considered for some time and 83 prototyped but not released primarily because they are significant and 84 backwards-incompatible. Go 1 was an opportunity to get them out, which is 85 helpful for the long term, but also means that Go 1 introduces incompatibilities 86 for old programs. Fortunately, the <code>go</code> <code>fix</code> tool can 87 automate much of the work needed to bring programs up to the Go 1 standard. 88 </p> 89 90 <p> 91 This document outlines the major changes in Go 1 that will affect programmers 92 updating existing code; its reference point is the prior release, r60 (tagged as 93 r60.3). It also explains how to update code from r60 to run under Go 1. 94 </p> 95 96 <h2 id="language">Changes to the language</h2> 97 98 <h3 id="append">Append</h3> 99 100 <p> 101 The <code>append</code> predeclared variadic function makes it easy to grow a slice 102 by adding elements to the end. 103 A common use is to add bytes to the end of a byte slice when generating output. 104 However, <code>append</code> did not provide a way to append a string to a <code>[]byte</code>, 105 which is another common case. 106 </p> 107 108 <pre><!--{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}} 109 --> greeting := []byte{} 110 greeting = append(greeting, []byte("hello ")...)</pre> 111 112 <p> 113 By analogy with the similar property of <code>copy</code>, Go 1 114 permits a string to be appended (byte-wise) directly to a byte 115 slice, reducing the friction between strings and byte slices. 116 The conversion is no longer necessary: 117 </p> 118 119 <pre><!--{{code "/doc/progs/go1.go" `/append.*world/`}} 120 --> greeting = append(greeting, "world"...)</pre> 121 122 <p> 123 <em>Updating</em>: 124 This is a new feature, so existing code needs no changes. 125 </p> 126 127 <h3 id="close">Close</h3> 128 129 <p> 130 The <code>close</code> predeclared function provides a mechanism 131 for a sender to signal that no more values will be sent. 132 It is important to the implementation of <code>for</code> <code>range</code> 133 loops over channels and is helpful in other situations. 134 Partly by design and partly because of race conditions that can occur otherwise, 135 it is intended for use only by the goroutine sending on the channel, 136 not by the goroutine receiving data. 137 However, before Go 1 there was no compile-time checking that <code>close</code> 138 was being used correctly. 139 </p> 140 141 <p> 142 To close this gap, at least in part, Go 1 disallows <code>close</code> on receive-only channels. 143 Attempting to close such a channel is a compile-time error. 144 </p> 145 146 <pre> 147 var c chan int 148 var csend chan<- int = c 149 var crecv <-chan int = c 150 close(c) // legal 151 close(csend) // legal 152 close(crecv) // illegal 153 </pre> 154 155 <p> 156 <em>Updating</em>: 157 Existing code that attempts to close a receive-only channel was 158 erroneous even before Go 1 and should be fixed. The compiler will 159 now reject such code. 160 </p> 161 162 <h3 id="literals">Composite literals</h3> 163 164 <p> 165 In Go 1, a composite literal of array, slice, or map type can elide the 166 type specification for the elements' initializers if they are of pointer type. 167 All four of the initializations in this example are legal; the last one was illegal before Go 1. 168 </p> 169 170 <pre><!--{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}} 171 --> type Date struct { 172 month string 173 day int 174 } 175 <span class="comment">// Struct values, fully qualified; always legal.</span> 176 holiday1 := []Date{ 177 Date{"Feb", 14}, 178 Date{"Nov", 11}, 179 Date{"Dec", 25}, 180 } 181 <span class="comment">// Struct values, type name elided; always legal.</span> 182 holiday2 := []Date{ 183 {"Feb", 14}, 184 {"Nov", 11}, 185 {"Dec", 25}, 186 } 187 <span class="comment">// Pointers, fully qualified, always legal.</span> 188 holiday3 := []*Date{ 189 &Date{"Feb", 14}, 190 &Date{"Nov", 11}, 191 &Date{"Dec", 25}, 192 } 193 <span class="comment">// Pointers, type name elided; legal in Go 1.</span> 194 holiday4 := []*Date{ 195 {"Feb", 14}, 196 {"Nov", 11}, 197 {"Dec", 25}, 198 }</pre> 199 200 <p> 201 <em>Updating</em>: 202 This change has no effect on existing code, but the command 203 <code>gofmt</code> <code>-s</code> applied to existing source 204 will, among other things, elide explicit element types wherever permitted. 205 </p> 206 207 208 <h3 id="init">Goroutines during init</h3> 209 210 <p> 211 The old language defined that <code>go</code> statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete. 212 This introduced clumsiness in many places and, in effect, limited the utility 213 of the <code>init</code> construct: 214 if it was possible for another package to use the library during initialization, the library 215 was forced to avoid goroutines. 216 This design was done for reasons of simplicity and safety but, 217 as our confidence in the language grew, it seemed unnecessary. 218 Running goroutines during initialization is no more complex or unsafe than running them during normal execution. 219 </p> 220 221 <p> 222 In Go 1, code that uses goroutines can be called from 223 <code>init</code> routines and global initialization expressions 224 without introducing a deadlock. 225 </p> 226 227 <pre><!--{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}} 228 -->var PackageGlobal int 229 230 func init() { 231 c := make(chan int) 232 go initializationFunction(c) 233 PackageGlobal = <-c 234 }</pre> 235 236 <p> 237 <em>Updating</em>: 238 This is a new feature, so existing code needs no changes, 239 although it's possible that code that depends on goroutines not starting before <code>main</code> will break. 240 There was no such code in the standard repository. 241 </p> 242 243 <h3 id="rune">The rune type</h3> 244 245 <p> 246 The language spec allows the <code>int</code> type to be 32 or 64 bits wide, but current implementations set <code>int</code> to 32 bits even on 64-bit platforms. 247 It would be preferable to have <code>int</code> be 64 bits on 64-bit platforms. 248 (There are important consequences for indexing large slices.) 249 However, this change would waste space when processing Unicode characters with 250 the old language because the <code>int</code> type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if <code>int</code> grew from 32 bits to 64. 251 </p> 252 253 <p> 254 To make changing to 64-bit <code>int</code> feasible, 255 Go 1 introduces a new basic type, <code>rune</code>, to represent 256 individual Unicode code points. 257 It is an alias for <code>int32</code>, analogous to <code>byte</code> 258 as an alias for <code>uint8</code>. 259 </p> 260 261 <p> 262 Character literals such as <code>'a'</code>, <code>'語'</code>, and <code>'\u0345'</code> 263 now have default type <code>rune</code>, 264 analogous to <code>1.0</code> having default type <code>float64</code>. 265 A variable initialized to a character constant will therefore 266 have type <code>rune</code> unless otherwise specified. 267 </p> 268 269 <p> 270 Libraries have been updated to use <code>rune</code> rather than <code>int</code> 271 when appropriate. For instance, the functions <code>unicode.ToLower</code> and 272 relatives now take and return a <code>rune</code>. 273 </p> 274 275 <pre><!--{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}} 276 --> delta := 'δ' <span class="comment">// delta has type rune.</span> 277 var DELTA rune 278 DELTA = unicode.ToUpper(delta) 279 epsilon := unicode.ToLower(DELTA + 1) 280 if epsilon != 'δ'+1 { 281 log.Fatal("inconsistent casing for Greek") 282 }</pre> 283 284 <p> 285 <em>Updating</em>: 286 Most source code will be unaffected by this because the type inference from 287 <code>:=</code> initializers introduces the new type silently, and it propagates 288 from there. 289 Some code may get type errors that a trivial conversion will resolve. 290 </p> 291 292 <h3 id="error">The error type</h3> 293 294 <p> 295 Go 1 introduces a new built-in type, <code>error</code>, which has the following definition: 296 </p> 297 298 <pre> 299 type error interface { 300 Error() string 301 } 302 </pre> 303 304 <p> 305 Since the consequences of this type are all in the package library, 306 it is discussed <a href="#errors">below</a>. 307 </p> 308 309 <h3 id="delete">Deleting from maps</h3> 310 311 <p> 312 In the old language, to delete the entry with key <code>k</code> from map <code>m</code>, one wrote the statement, 313 </p> 314 315 <pre> 316 m[k] = value, false 317 </pre> 318 319 <p> 320 This syntax was a peculiar special case, the only two-to-one assignment. 321 It required passing a value (usually ignored) that is evaluated but discarded, 322 plus a boolean that was nearly always the constant <code>false</code>. 323 It did the job but was odd and a point of contention. 324 </p> 325 326 <p> 327 In Go 1, that syntax has gone; instead there is a new built-in 328 function, <code>delete</code>. The call 329 </p> 330 331 <pre><!--{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}} 332 --> delete(m, k)</pre> 333 334 <p> 335 will delete the map entry retrieved by the expression <code>m[k]</code>. 336 There is no return value. Deleting a non-existent entry is a no-op. 337 </p> 338 339 <p> 340 <em>Updating</em>: 341 Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = value, 342 false</code> into <code>delete(m, k)</code> when it is clear that 343 the ignored value can be safely discarded from the program and 344 <code>false</code> refers to the predefined boolean constant. 345 The fix tool 346 will flag other uses of the syntax for inspection by the programmer. 347 </p> 348 349 <h3 id="iteration">Iterating in maps</h3> 350 351 <p> 352 The old language specification did not define the order of iteration for maps, 353 and in practice it differed across hardware platforms. 354 This caused tests that iterated over maps to be fragile and non-portable, with the 355 unpleasant property that a test might always pass on one machine but break on another. 356 </p> 357 358 <p> 359 In Go 1, the order in which elements are visited when iterating 360 over a map using a <code>for</code> <code>range</code> statement 361 is defined to be unpredictable, even if the same loop is run multiple 362 times with the same map. 363 Code should not assume that the elements are visited in any particular order. 364 </p> 365 366 <p> 367 This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem. 368 Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map. 369 </p> 370 371 <pre><!--{{code "/doc/progs/go1.go" `/Sunday/` `/^ }/`}} 372 --> m := map[string]int{"Sunday": 0, "Monday": 1} 373 for name, value := range m { 374 <span class="comment">// This loop should not assume Sunday will be visited first.</span> 375 f(name, value) 376 }</pre> 377 378 <p> 379 <em>Updating</em>: 380 This is one change where tools cannot help. Most existing code 381 will be unaffected, but some programs may break or misbehave; we 382 recommend manual checking of all range statements over maps to 383 verify they do not depend on iteration order. There were a few such 384 examples in the standard repository; they have been fixed. 385 Note that it was already incorrect to depend on the iteration order, which 386 was unspecified. This change codifies the unpredictability. 387 </p> 388 389 <h3 id="multiple_assignment">Multiple assignment</h3> 390 391 <p> 392 The language specification has long guaranteed that in assignments 393 the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned. 394 To guarantee predictable behavior, 395 Go 1 refines the specification further. 396 </p> 397 398 <p> 399 If the left-hand side of the assignment 400 statement contains expressions that require evaluation, such as 401 function calls or array indexing operations, these will all be done 402 using the usual left-to-right rule before any variables are assigned 403 their value. Once everything is evaluated, the actual assignments 404 proceed in left-to-right order. 405 </p> 406 407 <p> 408 These examples illustrate the behavior. 409 </p> 410 411 <pre><!--{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}} 412 --> sa := []int{1, 2, 3} 413 i := 0 414 i, sa[i] = 1, 2 <span class="comment">// sets i = 1, sa[0] = 2</span> 415 416 sb := []int{1, 2, 3} 417 j := 0 418 sb[j], j = 2, 1 <span class="comment">// sets sb[0] = 2, j = 1</span> 419 420 sc := []int{1, 2, 3} 421 sc[0], sc[0] = 1, 2 <span class="comment">// sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)</span></pre> 422 423 <p> 424 <em>Updating</em>: 425 This is one change where tools cannot help, but breakage is unlikely. 426 No code in the standard repository was broken by this change, and code 427 that depended on the previous unspecified behavior was already incorrect. 428 </p> 429 430 <h3 id="shadowing">Returns and shadowed variables</h3> 431 432 <p> 433 A common mistake is to use <code>return</code> (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable. 434 This situation is called <em>shadowing</em>: the result variable has been shadowed by another variable with the same name declared in an inner scope. 435 </p> 436 437 <p> 438 In functions with named return values, 439 the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. 440 (It isn't part of the specification, because this is one area we are still exploring; 441 the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.) 442 </p> 443 444 <p> 445 This function implicitly returns a shadowed return value and will be rejected by the compiler: 446 </p> 447 448 <pre> 449 func Bug() (i, j, k int) { 450 for i = 0; i < 5; i++ { 451 for j := 0; j < 5; j++ { // Redeclares j. 452 k += i*j 453 if k > 100 { 454 return // Rejected: j is shadowed here. 455 } 456 } 457 } 458 return // OK: j is not shadowed here. 459 } 460 </pre> 461 462 <p> 463 <em>Updating</em>: 464 Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. 465 The few cases that arose in the standard repository were mostly bugs. 466 </p> 467 468 <h3 id="unexported">Copying structs with unexported fields</h3> 469 470 <p> 471 The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package. 472 There was, however, a required exception for a method receiver; 473 also, the implementations of <code>copy</code> and <code>append</code> have never honored the restriction. 474 </p> 475 476 <p> 477 Go 1 will allow packages to copy struct values containing unexported fields from other packages. 478 Besides resolving the inconsistency, 479 this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface. 480 The new implementations of <code>time.Time</code> and 481 <code>reflect.Value</code> are examples of types taking advantage of this new property. 482 </p> 483 484 <p> 485 As an example, if package <code>p</code> includes the definitions, 486 </p> 487 488 <pre> 489 type Struct struct { 490 Public int 491 secret int 492 } 493 func NewStruct(a int) Struct { // Note: not a pointer. 494 return Struct{a, f(a)} 495 } 496 func (s Struct) String() string { 497 return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret) 498 } 499 </pre> 500 501 <p> 502 a package that imports <code>p</code> can assign and copy values of type 503 <code>p.Struct</code> at will. 504 Behind the scenes the unexported fields will be assigned and copied just 505 as if they were exported, 506 but the client code will never be aware of them. The code 507 </p> 508 509 <pre> 510 import "p" 511 512 myStruct := p.NewStruct(23) 513 copyOfMyStruct := myStruct 514 fmt.Println(myStruct, copyOfMyStruct) 515 </pre> 516 517 <p> 518 will show that the secret field of the struct has been copied to the new value. 519 </p> 520 521 <p> 522 <em>Updating</em>: 523 This is a new feature, so existing code needs no changes. 524 </p> 525 526 <h3 id="equality">Equality</h3> 527 528 <p> 529 Before Go 1, the language did not define equality on struct and array values. 530 This meant, 531 among other things, that structs and arrays could not be used as map keys. 532 On the other hand, Go did define equality on function and map values. 533 Function equality was problematic in the presence of closures 534 (when are two closures equal?) 535 while map equality compared pointers, not the maps' content, which was usually 536 not what the user would want. 537 </p> 538 539 <p> 540 Go 1 addressed these issues. 541 First, structs and arrays can be compared for equality and inequality 542 (<code>==</code> and <code>!=</code>), 543 and therefore be used as map keys, 544 provided they are composed from elements for which equality is also defined, 545 using element-wise comparison. 546 </p> 547 548 <pre><!--{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}} 549 --> type Day struct { 550 long string 551 short string 552 } 553 Christmas := Day{"Christmas", "XMas"} 554 Thanksgiving := Day{"Thanksgiving", "Turkey"} 555 holiday := map[Day]bool{ 556 Christmas: true, 557 Thanksgiving: true, 558 } 559 fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])</pre> 560 561 <p> 562 Second, Go 1 removes the definition of equality for function values, 563 except for comparison with <code>nil</code>. 564 Finally, map equality is gone too, also except for comparison with <code>nil</code>. 565 </p> 566 567 <p> 568 Note that equality is still undefined for slices, for which the 569 calculation is in general infeasible. Also note that the ordered 570 comparison operators (<code><</code> <code><=</code> 571 <code>></code> <code>>=</code>) are still undefined for 572 structs and arrays. 573 574 <p> 575 <em>Updating</em>: 576 Struct and array equality is a new feature, so existing code needs no changes. 577 Existing code that depends on function or map equality will be 578 rejected by the compiler and will need to be fixed by hand. 579 Few programs will be affected, but the fix may require some 580 redesign. 581 </p> 582 583 <h2 id="packages">The package hierarchy</h2> 584 585 <p> 586 Go 1 addresses many deficiencies in the old standard library and 587 cleans up a number of packages, making them more internally consistent 588 and portable. 589 </p> 590 591 <p> 592 This section describes how the packages have been rearranged in Go 1. 593 Some have moved, some have been renamed, some have been deleted. 594 New packages are described in later sections. 595 </p> 596 597 <h3 id="hierarchy">The package hierarchy</h3> 598 599 <p> 600 Go 1 has a rearranged package hierarchy that groups related items 601 into subdirectories. For instance, <code>utf8</code> and 602 <code>utf16</code> now occupy subdirectories of <code>unicode</code>. 603 Also, <a href="#subrepo">some packages</a> have moved into 604 subrepositories of 605 <a href="http://code.google.com/p/go"><code>code.google.com/p/go</code></a> 606 while <a href="#deleted">others</a> have been deleted outright. 607 </p> 608 609 <table class="codetable" frame="border" summary="Moved packages"> 610 <colgroup align="left" width="60%"></colgroup> 611 <colgroup align="left" width="40%"></colgroup> 612 <tr> 613 <th align="left">Old path</th> 614 <th align="left">New path</th> 615 </tr> 616 <tr> 617 <td colspan="2"><hr></td> 618 </tr> 619 <tr><td>asn1</td> <td>encoding/asn1</td></tr> 620 <tr><td>csv</td> <td>encoding/csv</td></tr> 621 <tr><td>gob</td> <td>encoding/gob</td></tr> 622 <tr><td>json</td> <td>encoding/json</td></tr> 623 <tr><td>xml</td> <td>encoding/xml</td></tr> 624 <tr> 625 <td colspan="2"><hr></td> 626 </tr> 627 <tr><td>exp/template/html</td> <td>html/template</td></tr> 628 <tr> 629 <td colspan="2"><hr></td> 630 </tr> 631 <tr><td>big</td> <td>math/big</td></tr> 632 <tr><td>cmath</td> <td>math/cmplx</td></tr> 633 <tr><td>rand</td> <td>math/rand</td></tr> 634 <tr> 635 <td colspan="2"><hr></td> 636 </tr> 637 <tr><td>http</td> <td>net/http</td></tr> 638 <tr><td>http/cgi</td> <td>net/http/cgi</td></tr> 639 <tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr> 640 <tr><td>http/httptest</td> <td>net/http/httptest</td></tr> 641 <tr><td>http/pprof</td> <td>net/http/pprof</td></tr> 642 <tr><td>mail</td> <td>net/mail</td></tr> 643 <tr><td>rpc</td> <td>net/rpc</td></tr> 644 <tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr> 645 <tr><td>smtp</td> <td>net/smtp</td></tr> 646 <tr><td>url</td> <td>net/url</td></tr> 647 <tr> 648 <td colspan="2"><hr></td> 649 </tr> 650 <tr><td>exec</td> <td>os/exec</td></tr> 651 <tr> 652 <td colspan="2"><hr></td> 653 </tr> 654 <tr><td>scanner</td> <td>text/scanner</td></tr> 655 <tr><td>tabwriter</td> <td>text/tabwriter</td></tr> 656 <tr><td>template</td> <td>text/template</td></tr> 657 <tr><td>template/parse</td> <td>text/template/parse</td></tr> 658 <tr> 659 <td colspan="2"><hr></td> 660 </tr> 661 <tr><td>utf8</td> <td>unicode/utf8</td></tr> 662 <tr><td>utf16</td> <td>unicode/utf16</td></tr> 663 </table> 664 665 <p> 666 Note that the package names for the old <code>cmath</code> and 667 <code>exp/template/html</code> packages have changed to <code>cmplx</code> 668 and <code>template</code>. 669 </p> 670 671 <p> 672 <em>Updating</em>: 673 Running <code>go</code> <code>fix</code> will update all imports and package renames for packages that 674 remain inside the standard repository. Programs that import packages 675 that are no longer in the standard repository will need to be edited 676 by hand. 677 </p> 678 679 <h3 id="exp">The package tree exp</h3> 680 681 <p> 682 Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the 683 standard Go 1 release distributions, although they will be available in source code form 684 in <a href="http://code.google.com/p/go/">the repository</a> for 685 developers who wish to use them. 686 </p> 687 688 <p> 689 Several packages have moved under <code>exp</code> at the time of Go 1's release: 690 </p> 691 692 <ul> 693 <li><code>ebnf</code></li> 694 <li><code>html</code><sup>†</sup></li> 695 <li><code>go/types</code></li> 696 </ul> 697 698 <p> 699 (<sup>†</sup>The <code>EscapeString</code> and <code>UnescapeString</code> types remain 700 in package <code>html</code>.) 701 </p> 702 703 <p> 704 All these packages are available under the same names, with the prefix <code>exp/</code>: <code>exp/ebnf</code> etc. 705 </p> 706 707 <p> 708 Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>. 709 </p> 710 711 <p> 712 Finally, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while 713 <code>ebnflint</code> is now in <code>exp/ebnflint</code>. 714 If they are installed, they now reside in <code>$GOROOT/bin/tool</code>. 715 </p> 716 717 <p> 718 <em>Updating</em>: 719 Code that uses packages in <code>exp</code> will need to be updated by hand, 720 or else compiled from an installation that has <code>exp</code> available. 721 The <code>go</code> <code>fix</code> tool or the compiler will complain about such uses. 722 </p> 723 724 <h3 id="old">The package tree old</h3> 725 726 <p> 727 Because they are deprecated, the packages under the <code>old</code> directory will not be available in the 728 standard Go 1 release distributions, although they will be available in source code form for 729 developers who wish to use them. 730 </p> 731 732 <p> 733 The packages in their new locations are: 734 </p> 735 736 <ul> 737 <li><code>old/netchan</code></li> 738 <li><code>old/regexp</code></li> 739 <li><code>old/template</code></li> 740 </ul> 741 742 <p> 743 <em>Updating</em>: 744 Code that uses packages now in <code>old</code> will need to be updated by hand, 745 or else compiled from an installation that has <code>old</code> available. 746 The <code>go</code> <code>fix</code> tool will warn about such uses. 747 </p> 748 749 <h3 id="deleted">Deleted packages</h3> 750 751 <p> 752 Go 1 deletes several packages outright: 753 </p> 754 755 <ul> 756 <li><code>container/vector</code></li> 757 <li><code>exp/datafmt</code></li> 758 <li><code>go/typechecker</code></li> 759 <li><code>try</code></li> 760 </ul> 761 762 <p> 763 and also the command <code>gotry</code>. 764 </p> 765 766 <p> 767 <em>Updating</em>: 768 Code that uses <code>container/vector</code> should be updated to use 769 slices directly. See 770 <a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go 771 Language Community Wiki</a> for some suggestions. 772 Code that uses the other packages (there should be almost zero) will need to be rethought. 773 </p> 774 775 <h3 id="subrepo">Packages moving to subrepositories</h3> 776 777 <p> 778 Go 1 has moved a number of packages into other repositories, usually sub-repositories of 779 <a href="http://code.google.com/p/go/">the main Go repository</a>. 780 This table lists the old and new import paths: 781 782 <table class="codetable" frame="border" summary="Sub-repositories"> 783 <colgroup align="left" width="40%"></colgroup> 784 <colgroup align="left" width="60%"></colgroup> 785 <tr> 786 <th align="left">Old</th> 787 <th align="left">New</th> 788 </tr> 789 <tr> 790 <td colspan="2"><hr></td> 791 </tr> 792 <tr><td>crypto/bcrypt</td> <td>code.google.com/p/go.crypto/bcrypt</tr> 793 <tr><td>crypto/blowfish</td> <td>code.google.com/p/go.crypto/blowfish</tr> 794 <tr><td>crypto/cast5</td> <td>code.google.com/p/go.crypto/cast5</tr> 795 <tr><td>crypto/md4</td> <td>code.google.com/p/go.crypto/md4</tr> 796 <tr><td>crypto/ocsp</td> <td>code.google.com/p/go.crypto/ocsp</tr> 797 <tr><td>crypto/openpgp</td> <td>code.google.com/p/go.crypto/openpgp</tr> 798 <tr><td>crypto/openpgp/armor</td> <td>code.google.com/p/go.crypto/openpgp/armor</tr> 799 <tr><td>crypto/openpgp/elgamal</td> <td>code.google.com/p/go.crypto/openpgp/elgamal</tr> 800 <tr><td>crypto/openpgp/errors</td> <td>code.google.com/p/go.crypto/openpgp/errors</tr> 801 <tr><td>crypto/openpgp/packet</td> <td>code.google.com/p/go.crypto/openpgp/packet</tr> 802 <tr><td>crypto/openpgp/s2k</td> <td>code.google.com/p/go.crypto/openpgp/s2k</tr> 803 <tr><td>crypto/ripemd160</td> <td>code.google.com/p/go.crypto/ripemd160</tr> 804 <tr><td>crypto/twofish</td> <td>code.google.com/p/go.crypto/twofish</tr> 805 <tr><td>crypto/xtea</td> <td>code.google.com/p/go.crypto/xtea</tr> 806 <tr><td>exp/ssh</td> <td>code.google.com/p/go.crypto/ssh</tr> 807 <tr> 808 <td colspan="2"><hr></td> 809 </tr> 810 <tr><td>image/bmp</td> <td>code.google.com/p/go.image/bmp</tr> 811 <tr><td>image/tiff</td> <td>code.google.com/p/go.image/tiff</tr> 812 <tr> 813 <td colspan="2"><hr></td> 814 </tr> 815 <tr><td>net/dict</td> <td>code.google.com/p/go.net/dict</tr> 816 <tr><td>net/websocket</td> <td>code.google.com/p/go.net/websocket</tr> 817 <tr><td>exp/spdy</td> <td>code.google.com/p/go.net/spdy</tr> 818 <tr> 819 <td colspan="2"><hr></td> 820 </tr> 821 <tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr> 822 <tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr> 823 <tr> 824 <td colspan="2"><hr></td> 825 </tr> 826 <tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr> 827 </table> 828 829 <p> 830 <em>Updating</em>: 831 Running <code>go</code> <code>fix</code> will update imports of these packages to use the new import paths. 832 Installations that depend on these packages will need to install them using 833 a <code>go get</code> command. 834 </p> 835 836 <h2 id="major">Major changes to the library</h2> 837 838 <p> 839 This section describes significant changes to the core libraries, the ones that 840 affect the most programs. 841 </p> 842 843 <h3 id="errors">The error type and errors package</h3> 844 845 <p> 846 The placement of <code>os.Error</code> in package <code>os</code> is mostly historical: errors first came up when implementing package <code>os</code>, and they seemed system-related at the time. 847 Since then it has become clear that errors are more fundamental than the operating system. For example, it would be nice to use <code>Errors</code> in packages that <code>os</code> depends on, like <code>syscall</code>. 848 Also, having <code>Error</code> in <code>os</code> introduces many dependencies on <code>os</code> that would otherwise not exist. 849 </p> 850 851 <p> 852 Go 1 solves these problems by introducing a built-in <code>error</code> interface type and a separate <code>errors</code> package (analogous to <code>bytes</code> and <code>strings</code>) that contains utility functions. 853 It replaces <code>os.NewError</code> with 854 <a href="/pkg/errors/#New"><code>errors.New</code></a>, 855 giving errors a more central place in the environment. 856 </p> 857 858 <p> 859 So the widely-used <code>String</code> method does not cause accidental satisfaction 860 of the <code>error</code> interface, the <code>error</code> interface uses instead 861 the name <code>Error</code> for that method: 862 </p> 863 864 <pre> 865 type error interface { 866 Error() string 867 } 868 </pre> 869 870 <p> 871 The <code>fmt</code> library automatically invokes <code>Error</code>, as it already 872 does for <code>String</code>, for easy printing of error values. 873 </p> 874 875 <pre><!--{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}} 876 -->type SyntaxError struct { 877 File string 878 Line int 879 Message string 880 } 881 882 func (se *SyntaxError) Error() string { 883 return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message) 884 }</pre> 885 886 <p> 887 All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone. 888 </p> 889 890 <p> 891 A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function 892 </p> 893 894 <pre> 895 func New(text string) error 896 </pre> 897 898 <p> 899 to turn a string into an error. It replaces the old <code>os.NewError</code>. 900 </p> 901 902 <pre><!--{{code "/doc/progs/go1.go" `/ErrSyntax/`}} 903 --> var ErrSyntax = errors.New("syntax error")</pre> 904 905 <p> 906 <em>Updating</em>: 907 Running <code>go</code> <code>fix</code> will update almost all code affected by the change. 908 Code that defines error types with a <code>String</code> method will need to be updated 909 by hand to rename the methods to <code>Error</code>. 910 </p> 911 912 <h3 id="errno">System call errors</h3> 913 914 <p> 915 The old <code>syscall</code> package, which predated <code>os.Error</code> 916 (and just about everything else), 917 returned errors as <code>int</code> values. 918 In turn, the <code>os</code> package forwarded many of these errors, such 919 as <code>EINVAL</code>, but using a different set of errors on each platform. 920 This behavior was unpleasant and unportable. 921 </p> 922 923 <p> 924 In Go 1, the 925 <a href="/pkg/syscall/"><code>syscall</code></a> 926 package instead returns an <code>error</code> for system call errors. 927 On Unix, the implementation is done by a 928 <a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type 929 that satisfies <code>error</code> and replaces the old <code>os.Errno</code>. 930 </p> 931 932 <p> 933 The changes affecting <code>os.EINVAL</code> and relatives are 934 described <a href="#os">elsewhere</a>. 935 936 <p> 937 <em>Updating</em>: 938 Running <code>go</code> <code>fix</code> will update almost all code affected by the change. 939 Regardless, most code should use the <code>os</code> package 940 rather than <code>syscall</code> and so will be unaffected. 941 </p> 942 943 <h3 id="time">Time</h3> 944 945 <p> 946 Time is always a challenge to support well in a programming language. 947 The old Go <code>time</code> package had <code>int64</code> units, no 948 real type safety, 949 and no distinction between absolute times and durations. 950 </p> 951 952 <p> 953 One of the most sweeping changes in the Go 1 library is therefore a 954 complete redesign of the 955 <a href="/pkg/time/"><code>time</code></a> package. 956 Instead of an integer number of nanoseconds as an <code>int64</code>, 957 and a separate <code>*time.Time</code> type to deal with human 958 units such as hours and years, 959 there are now two fundamental types: 960 <a href="/pkg/time/#Time"><code>time.Time</code></a> 961 (a value, so the <code>*</code> is gone), which represents a moment in time; 962 and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>, 963 which represents an interval. 964 Both have nanosecond resolution. 965 A <code>Time</code> can represent any time into the ancient 966 past and remote future, while a <code>Duration</code> can 967 span plus or minus only about 290 years. 968 There are methods on these types, plus a number of helpful 969 predefined constant durations such as <code>time.Second</code>. 970 </p> 971 972 <p> 973 Among the new methods are things like 974 <a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>, 975 which adds a <code>Duration</code> to a <code>Time</code>, and 976 <a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>, 977 which subtracts two <code>Times</code> to yield a <code>Duration</code>. 978 </p> 979 980 <p> 981 The most important semantic change is that the Unix epoch (Jan 1, 1970) is now 982 relevant only for those functions and methods that mention Unix: 983 <a href="/pkg/time/#Unix"><code>time.Unix</code></a> 984 and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a> 985 and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods 986 of the <code>Time</code> type. 987 In particular, 988 <a href="/pkg/time/#Now"><code>time.Now</code></a> 989 returns a <code>time.Time</code> value rather than, in the old 990 API, an integer nanosecond count since the Unix epoch. 991 </p> 992 993 <pre><!--{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}} 994 --><span class="comment">// sleepUntil sleeps until the specified time. It returns immediately if it's too late.</span> 995 func sleepUntil(wakeup time.Time) { 996 now := time.Now() <span class="comment">// A Time.</span> 997 if !wakeup.After(now) { 998 return 999 } 1000 delta := wakeup.Sub(now) <span class="comment">// A Duration.</span> 1001 fmt.Printf("Sleeping for %.3fs\n", delta.Seconds()) 1002 time.Sleep(delta) 1003 }</pre> 1004 1005 <p> 1006 The new types, methods, and constants have been propagated through 1007 all the standard packages that use time, such as <code>os</code> and 1008 its representation of file time stamps. 1009 </p> 1010 1011 <p> 1012 <em>Updating</em>: 1013 The <code>go</code> <code>fix</code> tool will update many uses of the old <code>time</code> package to use the new 1014 types and methods, although it does not replace values such as <code>1e9</code> 1015 representing nanoseconds per second. 1016 Also, because of type changes in some of the values that arise, 1017 some of the expressions rewritten by the fix tool may require 1018 further hand editing; in such cases the rewrite will include 1019 the correct function or method for the old functionality, but 1020 may have the wrong type or require further analysis. 1021 </p> 1022 1023 <h2 id="minor">Minor changes to the library</h2> 1024 1025 <p> 1026 This section describes smaller changes, such as those to less commonly 1027 used packages or that affect 1028 few programs beyond the need to run <code>go</code> <code>fix</code>. 1029 This category includes packages that are new in Go 1. 1030 Collectively they improve portability, regularize behavior, and 1031 make the interfaces more modern and Go-like. 1032 </p> 1033 1034 <h3 id="archive_zip">The archive/zip package</h3> 1035 1036 <p> 1037 In Go 1, <a href="/pkg/archive/zip/#Writer"><code>*zip.Writer</code></a> no 1038 longer has a <code>Write</code> method. Its presence was a mistake. 1039 </p> 1040 1041 <p> 1042 <em>Updating</em>: 1043 What little code is affected will be caught by the compiler and must be updated by hand. 1044 </p> 1045 1046 <h3 id="bufio">The bufio package</h3> 1047 1048 <p> 1049 In Go 1, <a href="/pkg/bufio/#NewReaderSize"><code>bufio.NewReaderSize</code></a> 1050 and 1051 <a href="/pkg/bufio/#NewWriterSize"><code>bufio.NewWriterSize</code></a> 1052 functions no longer return an error for invalid sizes. 1053 If the argument size is too small or invalid, it is adjusted. 1054 </p> 1055 1056 <p> 1057 <em>Updating</em>: 1058 Running <code>go</code> <code>fix</code> will update calls that assign the error to _. 1059 Calls that aren't fixed will be caught by the compiler and must be updated by hand. 1060 </p> 1061 1062 <h3 id="compress">The compress/flate, compress/gzip and compress/zlib packages</h3> 1063 1064 <p> 1065 In Go 1, the <code>NewWriterXxx</code> functions in 1066 <a href="/pkg/compress/flate"><code>compress/flate</code></a>, 1067 <a href="/pkg/compress/gzip"><code>compress/gzip</code></a> and 1068 <a href="/pkg/compress/zlib"><code>compress/zlib</code></a> 1069 all return <code>(*Writer, error)</code> if they take a compression level, 1070 and <code>*Writer</code> otherwise. Package <code>gzip</code>'s 1071 <code>Compressor</code> and <code>Decompressor</code> types have been renamed 1072 to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>'s 1073 <code>WrongValueError</code> type has been removed. 1074 </p> 1075 1076 <p> 1077 <em>Updating</em> 1078 Running <code>go</code> <code>fix</code> will update old names and calls that assign the error to _. 1079 Calls that aren't fixed will be caught by the compiler and must be updated by hand. 1080 </p> 1081 1082 <h3 id="crypto_aes_des">The crypto/aes and crypto/des packages</h3> 1083 1084 <p> 1085 In Go 1, the <code>Reset</code> method has been removed. Go does not guarantee 1086 that memory is not copied and therefore this method was misleading. 1087 </p> 1088 1089 <p> 1090 The cipher-specific types <code>*aes.Cipher</code>, <code>*des.Cipher</code>, 1091 and <code>*des.TripleDESCipher</code> have been removed in favor of 1092 <code>cipher.Block</code>. 1093 </p> 1094 1095 <p> 1096 <em>Updating</em>: 1097 Remove the calls to Reset. Replace uses of the specific cipher types with 1098 cipher.Block. 1099 </p> 1100 1101 <h3 id="crypto_elliptic">The crypto/elliptic package</h3> 1102 1103 <p> 1104 In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a> 1105 has been made an interface to permit alternative implementations. The curve 1106 parameters have been moved to the 1107 <a href="/pkg/crypto/elliptic/#CurveParams"><code>elliptic.CurveParams</code></a> 1108 structure. 1109 </p> 1110 1111 <p> 1112 <em>Updating</em>: 1113 Existing users of <code>*elliptic.Curve</code> will need to change to 1114 simply <code>elliptic.Curve</code>. Calls to <code>Marshal</code>, 1115 <code>Unmarshal</code> and <code>GenerateKey</code> are now functions 1116 in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code> 1117 as their first argument. 1118 </p> 1119 1120 <h3 id="crypto_hmac">The crypto/hmac package</h3> 1121 1122 <p> 1123 In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have 1124 been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes 1125 a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>. 1126 </p> 1127 1128 <p> 1129 <em>Updating</em>: 1130 Running <code>go</code> <code>fix</code> will perform the needed changes. 1131 </p> 1132 1133 <h3 id="crypto_x509">The crypto/x509 package</h3> 1134 1135 <p> 1136 In Go 1, the 1137 <a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a> 1138 and 1139 <a href="/pkg/crypto/x509/#CreateCRL"><code>CreateCRL</code></a> 1140 functions in <code>crypto/x509</code> have been altered to take an 1141 <code>interface{}</code> where they previously took a <code>*rsa.PublicKey</code> 1142 or <code>*rsa.PrivateKey</code>. This will allow other public key algorithms 1143 to be implemented in the future. 1144 </p> 1145 1146 <p> 1147 <em>Updating</em>: 1148 No changes will be needed. 1149 </p> 1150 1151 <h3 id="encoding_binary">The encoding/binary package</h3> 1152 1153 <p> 1154 In Go 1, the <code>binary.TotalSize</code> function has been replaced by 1155 <a href="/pkg/encoding/binary/#Size"><code>Size</code></a>, 1156 which takes an <code>interface{}</code> argument rather than 1157 a <code>reflect.Value</code>. 1158 </p> 1159 1160 <p> 1161 <em>Updating</em>: 1162 What little code is affected will be caught by the compiler and must be updated by hand. 1163 </p> 1164 1165 <h3 id="encoding_xml">The encoding/xml package</h3> 1166 1167 <p> 1168 In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package 1169 has been brought closer in design to the other marshaling packages such 1170 as <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a>. 1171 </p> 1172 1173 <p> 1174 The old <code>Parser</code> type is renamed 1175 <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> and has a new 1176 <a href="/pkg/encoding/xml/#Decoder.Decode"><code>Decode</code></a> method. An 1177 <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> type was also introduced. 1178 </p> 1179 1180 <p> 1181 The functions <a href="/pkg/encoding/xml/#Marshal"><code>Marshal</code></a> 1182 and <a href="/pkg/encoding/xml/#Unmarshal"><code>Unmarshal</code></a> 1183 work with <code>[]byte</code> values now. To work with streams, 1184 use the new <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> 1185 and <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> types. 1186 </p> 1187 1188 <p> 1189 When marshaling or unmarshaling values, the format of supported flags in 1190 field tags has changed to be closer to the 1191 <a href="/pkg/encoding/json"><code>json</code></a> package 1192 (<code>`xml:"name,flag"`</code>). The matching done between field tags, field 1193 names, and the XML attribute and element names is now case-sensitive. 1194 The <code>XMLName</code> field tag, if present, must also match the name 1195 of the XML element being marshaled. 1196 </p> 1197 1198 <p> 1199 <em>Updating</em>: 1200 Running <code>go</code> <code>fix</code> will update most uses of the package except for some calls to 1201 <code>Unmarshal</code>. Special care must be taken with field tags, 1202 since the fix tool will not update them and if not fixed by hand they will 1203 misbehave silently in some cases. For example, the old 1204 <code>"attr"</code> is now written <code>",attr"</code> while plain 1205 <code>"attr"</code> remains valid but with a different meaning. 1206 </p> 1207 1208 <h3 id="expvar">The expvar package</h3> 1209 1210 <p> 1211 In Go 1, the <code>RemoveAll</code> function has been removed. 1212 The <code>Iter</code> function and Iter method on <code>*Map</code> have 1213 been replaced by 1214 <a href="/pkg/expvar/#Do"><code>Do</code></a> 1215 and 1216 <a href="/pkg/expvar/#Map.Do"><code>(*Map).Do</code></a>. 1217 </p> 1218 1219 <p> 1220 <em>Updating</em>: 1221 Most code using <code>expvar</code> will not need changing. The rare code that used 1222 <code>Iter</code> can be updated to pass a closure to <code>Do</code> to achieve the same effect. 1223 </p> 1224 1225 <h3 id="flag">The flag package</h3> 1226 1227 <p> 1228 In Go 1, the interface <a href="/pkg/flag/#Value"><code>flag.Value</code></a> has changed slightly. 1229 The <code>Set</code> method now returns an <code>error</code> instead of 1230 a <code>bool</code> to indicate success or failure. 1231 </p> 1232 1233 <p> 1234 There is also a new kind of flag, <code>Duration</code>, to support argument 1235 values specifying time intervals. 1236 Values for such flags must be given units, just as <code>time.Duration</code> 1237 formats them: <code>10s</code>, <code>1h30m</code>, etc. 1238 </p> 1239 1240 <pre><!--{{code "/doc/progs/go1.go" `/timeout/`}} 1241 -->var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")</pre> 1242 1243 <p> 1244 <em>Updating</em>: 1245 Programs that implement their own flags will need minor manual fixes to update their 1246 <code>Set</code> methods. 1247 The <code>Duration</code> flag is new and affects no existing code. 1248 </p> 1249 1250 1251 <h3 id="go">The go/* packages</h3> 1252 1253 <p> 1254 Several packages under <code>go</code> have slightly revised APIs. 1255 </p> 1256 1257 <p> 1258 A concrete <code>Mode</code> type was introduced for configuration mode flags 1259 in the packages 1260 <a href="/pkg/go/scanner/"><code>go/scanner</code></a>, 1261 <a href="/pkg/go/parser/"><code>go/parser</code></a>, 1262 <a href="/pkg/go/printer/"><code>go/printer</code></a>, and 1263 <a href="/pkg/go/doc/"><code>go/doc</code></a>. 1264 </p> 1265 1266 <p> 1267 The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed 1268 from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly 1269 useful for scanning text other then Go source files. Instead, the 1270 <a href="/pkg/text/scanner/"><code>text/scanner</code></a> package should be used 1271 for that purpose. 1272 </p> 1273 1274 <p> 1275 The <a href="/pkg/go/scanner/#ErrorHandler"><code>ErrorHandler</code></a> provided 1276 to the scanner's <a href="/pkg/go/scanner/#Scanner.Init"><code>Init</code></a> method is 1277 now simply a function rather than an interface. The <code>ErrorVector</code> type has 1278 been removed in favor of the (existing) <a href="/pkg/go/scanner/#ErrorList"><code>ErrorList</code></a> 1279 type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding 1280 an <code>ErrorVector</code> in a client of the scanner, now a client should maintain 1281 an <code>ErrorList</code>. 1282 </p> 1283 1284 <p> 1285 The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a> 1286 package has been reduced to the primary parse function 1287 <a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of 1288 convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a> 1289 and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>. 1290 </p> 1291 1292 <p> 1293 The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional 1294 configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>; 1295 if set, the printer will emit <code>//line</code> comments such that the generated 1296 output contains the original source code position information. The new type 1297 <a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be 1298 used to provide comments associated with an arbitrary 1299 <a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only 1300 <a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information). 1301 </p> 1302 1303 <p> 1304 The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been 1305 streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code> 1306 is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc. 1307 Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>, 1308 in the case of type <code>Value</code>) and <code>Type.Factories</code> has become 1309 <code>Type.Funcs</code>. 1310 Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>, 1311 documentation for a package is created with: 1312 </p> 1313 1314 <pre> 1315 doc.New(pkg, importpath, mode) 1316 </pre> 1317 1318 <p> 1319 where the new <code>mode</code> parameter specifies the operation mode: 1320 if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations 1321 (not just exported ones) are considered. 1322 The function <code>NewFileDoc</code> was removed, and the function 1323 <code>CommentText</code> has become the method 1324 <a href="/pkg/go/ast/#Text"><code>Text</code></a> of 1325 <a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>. 1326 </p> 1327 1328 <p> 1329 In package <a href="/pkg/go/token/"><code>go/token</code></a>, the 1330 <a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code> 1331 (which originally returned a channel of <code>*token.File</code>s) has been replaced 1332 with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that 1333 accepts a function argument instead. 1334 </p> 1335 1336 <p> 1337 In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API 1338 has been nearly completely replaced. 1339 The package still computes Go package information 1340 but it does not run the build: the <code>Cmd</code> and <code>Script</code> 1341 types are gone. 1342 (To build code, use the new 1343 <a href="/cmd/go/"><code>go</code></a> command instead.) 1344 The <code>DirInfo</code> type is now named 1345 <a href="/pkg/go/build/#Package"><code>Package</code></a>. 1346 <code>FindTree</code> and <code>ScanDir</code> are replaced by 1347 <a href="/pkg/go/build/#Import"><code>Import</code></a> 1348 and 1349 <a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>. 1350 </p> 1351 1352 <p> 1353 <em>Updating</em>: 1354 Code that uses packages in <code>go</code> will have to be updated by hand; the 1355 compiler will reject incorrect uses. Templates used in conjunction with any of the 1356 <code>go/doc</code> types may need manual fixes; the renamed fields will lead 1357 to run-time errors. 1358 </p> 1359 1360 <h3 id="hash">The hash package</h3> 1361 1362 <p> 1363 In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes 1364 a new method, <code>BlockSize</code>. This new method is used primarily in the 1365 cryptographic libraries. 1366 </p> 1367 1368 <p> 1369 The <code>Sum</code> method of the 1370 <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> interface now takes a 1371 <code>[]byte</code> argument, to which the hash value will be appended. 1372 The previous behavior can be recreated by adding a <code>nil</code> argument to the call. 1373 </p> 1374 1375 <p> 1376 <em>Updating</em>: 1377 Existing implementations of <code>hash.Hash</code> will need to add a 1378 <code>BlockSize</code> method. Hashes that process the input one byte at 1379 a time can implement <code>BlockSize</code> to return 1. 1380 Running <code>go</code> <code>fix</code> will update calls to the <code>Sum</code> methods of the various 1381 implementations of <code>hash.Hash</code>. 1382 </p> 1383 1384 <p> 1385 <em>Updating</em>: 1386 Since the package's functionality is new, no updating is necessary. 1387 </p> 1388 1389 <h3 id="http">The http package</h3> 1390 1391 <p> 1392 In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored, 1393 putting some of the utilities into a 1394 <a href="/pkg/net/http/httputil/"><code>httputil</code></a> subdirectory. 1395 These pieces are only rarely needed by HTTP clients. 1396 The affected items are: 1397 </p> 1398 1399 <ul> 1400 <li>ClientConn</li> 1401 <li>DumpRequest</li> 1402 <li>DumpRequestOut</li> 1403 <li>DumpResponse</li> 1404 <li>NewChunkedReader</li> 1405 <li>NewChunkedWriter</li> 1406 <li>NewClientConn</li> 1407 <li>NewProxyClientConn</li> 1408 <li>NewServerConn</li> 1409 <li>NewSingleHostReverseProxy</li> 1410 <li>ReverseProxy</li> 1411 <li>ServerConn</li> 1412 </ul> 1413 1414 <p> 1415 The <code>Request.RawURL</code> field has been removed; it was a 1416 historical artifact. 1417 </p> 1418 1419 <p> 1420 The <code>Handle</code> and <code>HandleFunc</code> 1421 functions, and the similarly-named methods of <code>ServeMux</code>, 1422 now panic if an attempt is made to register the same pattern twice. 1423 </p> 1424 1425 <p> 1426 <em>Updating</em>: 1427 Running <code>go</code> <code>fix</code> will update the few programs that are affected except for 1428 uses of <code>RawURL</code>, which must be fixed by hand. 1429 </p> 1430 1431 <h3 id="image">The image package</h3> 1432 1433 <p> 1434 The <a href="/pkg/image/"><code>image</code></a> package has had a number of 1435 minor changes, rearrangements and renamings. 1436 </p> 1437 1438 <p> 1439 Most of the color handling code has been moved into its own package, 1440 <a href="/pkg/image/color/"><code>image/color</code></a>. 1441 For the elements that moved, a symmetry arises; for instance, 1442 each pixel of an 1443 <a href="/pkg/image/#RGBA"><code>image.RGBA</code></a> 1444 is a 1445 <a href="/pkg/image/color/#RGBA"><code>color.RGBA</code></a>. 1446 </p> 1447 1448 <p> 1449 The old <code>image/ycbcr</code> package has been folded, with some 1450 renamings, into the 1451 <a href="/pkg/image/"><code>image</code></a> 1452 and 1453 <a href="/pkg/image/color/"><code>image/color</code></a> 1454 packages. 1455 </p> 1456 1457 <p> 1458 The old <code>image.ColorImage</code> type is still in the <code>image</code> 1459 package but has been renamed 1460 <a href="/pkg/image/#Uniform"><code>image.Uniform</code></a>, 1461 while <code>image.Tiled</code> has been removed. 1462 </p> 1463 1464 <p> 1465 This table lists the renamings. 1466 </p> 1467 1468 <table class="codetable" frame="border" summary="image renames"> 1469 <colgroup align="left" width="50%"></colgroup> 1470 <colgroup align="left" width="50%"></colgroup> 1471 <tr> 1472 <th align="left">Old</th> 1473 <th align="left">New</th> 1474 </tr> 1475 <tr> 1476 <td colspan="2"><hr></td> 1477 </tr> 1478 <tr><td>image.Color</td> <td>color.Color</td></tr> 1479 <tr><td>image.ColorModel</td> <td>color.Model</td></tr> 1480 <tr><td>image.ColorModelFunc</td> <td>color.ModelFunc</td></tr> 1481 <tr><td>image.PalettedColorModel</td> <td>color.Palette</td></tr> 1482 <tr> 1483 <td colspan="2"><hr></td> 1484 </tr> 1485 <tr><td>image.RGBAColor</td> <td>color.RGBA</td></tr> 1486 <tr><td>image.RGBA64Color</td> <td>color.RGBA64</td></tr> 1487 <tr><td>image.NRGBAColor</td> <td>color.NRGBA</td></tr> 1488 <tr><td>image.NRGBA64Color</td> <td>color.NRGBA64</td></tr> 1489 <tr><td>image.AlphaColor</td> <td>color.Alpha</td></tr> 1490 <tr><td>image.Alpha16Color</td> <td>color.Alpha16</td></tr> 1491 <tr><td>image.GrayColor</td> <td>color.Gray</td></tr> 1492 <tr><td>image.Gray16Color</td> <td>color.Gray16</td></tr> 1493 <tr> 1494 <td colspan="2"><hr></td> 1495 </tr> 1496 <tr><td>image.RGBAColorModel</td> <td>color.RGBAModel</td></tr> 1497 <tr><td>image.RGBA64ColorModel</td> <td>color.RGBA64Model</td></tr> 1498 <tr><td>image.NRGBAColorModel</td> <td>color.NRGBAModel</td></tr> 1499 <tr><td>image.NRGBA64ColorModel</td> <td>color.NRGBA64Model</td></tr> 1500 <tr><td>image.AlphaColorModel</td> <td>color.AlphaModel</td></tr> 1501 <tr><td>image.Alpha16ColorModel</td> <td>color.Alpha16Model</td></tr> 1502 <tr><td>image.GrayColorModel</td> <td>color.GrayModel</td></tr> 1503 <tr><td>image.Gray16ColorModel</td> <td>color.Gray16Model</td></tr> 1504 <tr> 1505 <td colspan="2"><hr></td> 1506 </tr> 1507 <tr><td>ycbcr.RGBToYCbCr</td> <td>color.RGBToYCbCr</td></tr> 1508 <tr><td>ycbcr.YCbCrToRGB</td> <td>color.YCbCrToRGB</td></tr> 1509 <tr><td>ycbcr.YCbCrColorModel</td> <td>color.YCbCrModel</td></tr> 1510 <tr><td>ycbcr.YCbCrColor</td> <td>color.YCbCr</td></tr> 1511 <tr><td>ycbcr.YCbCr</td> <td>image.YCbCr</td></tr> 1512 <tr> 1513 <td colspan="2"><hr></td> 1514 </tr> 1515 <tr><td>ycbcr.SubsampleRatio444</td> <td>image.YCbCrSubsampleRatio444</td></tr> 1516 <tr><td>ycbcr.SubsampleRatio422</td> <td>image.YCbCrSubsampleRatio422</td></tr> 1517 <tr><td>ycbcr.SubsampleRatio420</td> <td>image.YCbCrSubsampleRatio420</td></tr> 1518 <tr> 1519 <td colspan="2"><hr></td> 1520 </tr> 1521 <tr><td>image.ColorImage</td> <td>image.Uniform</td></tr> 1522 </table> 1523 1524 <p> 1525 The image package's <code>New</code> functions 1526 (<a href="/pkg/image/#NewRGBA"><code>NewRGBA</code></a>, 1527 <a href="/pkg/image/#NewRGBA64"><code>NewRGBA64</code></a>, etc.) 1528 take an <a href="/pkg/image/#Rectangle"><code>image.Rectangle</code></a> as an argument 1529 instead of four integers. 1530 </p> 1531 1532 <p> 1533 Finally, there are new predefined <code>color.Color</code> variables 1534 <a href="/pkg/image/color/#Black"><code>color.Black</code></a>, 1535 <a href="/pkg/image/color/#White"><code>color.White</code></a>, 1536 <a href="/pkg/image/color/#Opaque"><code>color.Opaque</code></a> 1537 and 1538 <a href="/pkg/image/color/#Transparent"><code>color.Transparent</code></a>. 1539 </p> 1540 1541 <p> 1542 <em>Updating</em>: 1543 Running <code>go</code> <code>fix</code> will update almost all code affected by the change. 1544 </p> 1545 1546 <h3 id="log_syslog">The log/syslog package</h3> 1547 1548 <p> 1549 In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a> 1550 function returns an error as well as a <code>log.Logger</code>. 1551 </p> 1552 1553 <p> 1554 <em>Updating</em>: 1555 What little code is affected will be caught by the compiler and must be updated by hand. 1556 </p> 1557 1558 <h3 id="mime">The mime package</h3> 1559 1560 <p> 1561 In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function 1562 of the <code>mime</code> package has been simplified to make it 1563 consistent with 1564 <a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>. 1565 It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>. 1566 </p> 1567 1568 <p> 1569 <em>Updating</em>: 1570 What little code is affected will be caught by the compiler and must be updated by hand. 1571 </p> 1572 1573 <h3 id="net">The net package</h3> 1574 1575 <p> 1576 In Go 1, the various <code>SetTimeout</code>, 1577 <code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods 1578 have been replaced with 1579 <a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>, 1580 <a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and 1581 <a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>, 1582 respectively. Rather than taking a timeout value in nanoseconds that 1583 apply to any activity on the connection, the new methods set an 1584 absolute deadline (as a <code>time.Time</code> value) after which 1585 reads and writes will time out and no longer block. 1586 </p> 1587 1588 <p> 1589 There are also new functions 1590 <a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a> 1591 to simplify timing out dialing a network address and 1592 <a href="/pkg/net/#ListenMulticastUDP"><code>net.ListenMulticastUDP</code></a> 1593 to allow multicast UDP to listen concurrently across multiple listeners. 1594 The <code>net.ListenMulticastUDP</code> function replaces the old 1595 <code>JoinGroup</code> and <code>LeaveGroup</code> methods. 1596 </p> 1597 1598 <p> 1599 <em>Updating</em>: 1600 Code that uses the old methods will fail to compile and must be updated by hand. 1601 The semantic change makes it difficult for the fix tool to update automatically. 1602 </p> 1603 1604 <h3 id="os">The os package</h3> 1605 1606 <p> 1607 The <code>Time</code> function has been removed; callers should use 1608 the <a href="/pkg/time/#Time"><code>Time</code></a> type from the 1609 <code>time</code> package. 1610 </p> 1611 1612 <p> 1613 The <code>Exec</code> function has been removed; callers should use 1614 <code>Exec</code> from the <code>syscall</code> package, where available. 1615 </p> 1616 1617 <p> 1618 The <code>ShellExpand</code> function has been renamed to <a 1619 href="/pkg/os/#ExpandEnv"><code>ExpandEnv</code></a>. 1620 </p> 1621 1622 <p> 1623 The <a href="/pkg/os/#NewFile"><code>NewFile</code></a> function 1624 now takes a <code>uintptr</code> fd, instead of an <code>int</code>. 1625 The <a href="/pkg/os/#File.Fd"><code>Fd</code></a> method on files now 1626 also returns a <code>uintptr</code>. 1627 </p> 1628 1629 <p> 1630 There are no longer error constants such as <code>EINVAL</code> 1631 in the <code>os</code> package, since the set of values varied with 1632 the underlying operating system. There are new portable functions like 1633 <a href="/pkg/os/#IsPermission"><code>IsPermission</code></a> 1634 to test common error properties, plus a few new error values 1635 with more Go-like names, such as 1636 <a href="/pkg/os/#ErrPermission"><code>ErrPermission</code></a> 1637 and 1638 <a href="/pkg/os/#ErrNoEnv"><code>ErrNoEnv</code></a>. 1639 </p> 1640 1641 <p> 1642 The <code>Getenverror</code> function has been removed. To distinguish 1643 between a non-existent environment variable and an empty string, 1644 use <a href="/pkg/os/#Environ"><code>os.Environ</code></a> or 1645 <a href="/pkg/syscall/#Getenv"><code>syscall.Getenv</code></a>. 1646 </p> 1647 1648 1649 <p> 1650 The <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> method has 1651 dropped its option argument and the associated constants are gone 1652 from the package. 1653 Also, the function <code>Wait</code> is gone; only the method of 1654 the <code>Process</code> type persists. 1655 </p> 1656 1657 <p> 1658 The <code>Waitmsg</code> type returned by 1659 <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> 1660 has been replaced with a more portable 1661 <a href="/pkg/os/#ProcessState"><code>ProcessState</code></a> 1662 type with accessor methods to recover information about the 1663 process. 1664 Because of changes to <code>Wait</code>, the <code>ProcessState</code> 1665 value always describes an exited process. 1666 Portability concerns simplified the interface in other ways, but the values returned by the 1667 <a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and 1668 <a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a> 1669 methods can be type-asserted to underlying system-specific data structures such as 1670 <a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and 1671 <a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix. 1672 </p> 1673 1674 <p> 1675 <em>Updating</em>: 1676 Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>. 1677 All other changes will be caught by the compiler and must be updated by hand. 1678 </p> 1679 1680 <h4 id="os_fileinfo">The os.FileInfo type</h4> 1681 1682 <p> 1683 Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type, 1684 changing it from a struct to an interface: 1685 </p> 1686 1687 <pre> 1688 type FileInfo interface { 1689 Name() string // base name of the file 1690 Size() int64 // length in bytes 1691 Mode() FileMode // file mode bits 1692 ModTime() time.Time // modification time 1693 IsDir() bool // abbreviation for Mode().IsDir() 1694 Sys() interface{} // underlying data source (can return nil) 1695 } 1696 </pre> 1697 1698 <p> 1699 The file mode information has been moved into a subtype called 1700 <a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>, 1701 a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code> 1702 methods. 1703 </p> 1704 1705 <p> 1706 The system-specific details of file modes and properties such as (on Unix) 1707 i-number have been removed from <code>FileInfo</code> altogether. 1708 Instead, each operating system's <code>os</code> package provides an 1709 implementation of the <code>FileInfo</code> interface, which 1710 has a <code>Sys</code> method that returns the 1711 system-specific representation of file metadata. 1712 For instance, to discover the i-number of a file on a Unix system, unpack 1713 the <code>FileInfo</code> like this: 1714 </p> 1715 1716 <pre> 1717 fi, err := os.Stat("hello.go") 1718 if err != nil { 1719 log.Fatal(err) 1720 } 1721 // Check that it's a Unix file. 1722 unixStat, ok := fi.Sys().(*syscall.Stat_t) 1723 if !ok { 1724 log.Fatal("hello.go: not a Unix file") 1725 } 1726 fmt.Printf("file i-number: %d\n", unixStat.Ino) 1727 </pre> 1728 1729 <p> 1730 Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file, 1731 the i-number expression could be contracted to 1732 </p> 1733 1734 <pre> 1735 fi.Sys().(*syscall.Stat_t).Ino 1736 </pre> 1737 1738 <p> 1739 The vast majority of uses of <code>FileInfo</code> need only the methods 1740 of the standard interface. 1741 </p> 1742 1743 <p> 1744 The <code>os</code> package no longer contains wrappers for the POSIX errors 1745 such as <code>ENOENT</code>. 1746 For the few programs that need to verify particular error conditions, there are 1747 now the boolean functions 1748 <a href="/pkg/os/#IsExist"><code>IsExist</code></a>, 1749 <a href="/pkg/os/#IsNotExist"><code>IsNotExist</code></a> 1750 and 1751 <a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>. 1752 </p> 1753 1754 <pre><!--{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}} 1755 --> f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600) 1756 if os.IsExist(err) { 1757 log.Printf("%s already exists", name) 1758 }</pre> 1759 1760 <p> 1761 <em>Updating</em>: 1762 Running <code>go</code> <code>fix</code> will update code that uses the old equivalent of the current <code>os.FileInfo</code> 1763 and <code>os.FileMode</code> API. 1764 Code that needs system-specific file details will need to be updated by hand. 1765 Code that uses the old POSIX error values from the <code>os</code> package 1766 will fail to compile and will also need to be updated by hand. 1767 </p> 1768 1769 <h3 id="os_signal">The os/signal package</h3> 1770 1771 <p> 1772 The <code>os/signal</code> package in Go 1 replaces the 1773 <code>Incoming</code> function, which returned a channel 1774 that received all incoming signals, 1775 with the selective <code>Notify</code> function, which asks 1776 for delivery of specific signals on an existing channel. 1777 </p> 1778 1779 <p> 1780 <em>Updating</em>: 1781 Code must be updated by hand. 1782 A literal translation of 1783 </p> 1784 <pre> 1785 c := signal.Incoming() 1786 </pre> 1787 <p> 1788 is 1789 </p> 1790 <pre> 1791 c := make(chan os.Signal) 1792 signal.Notify(c) // ask for all signals 1793 </pre> 1794 <p> 1795 but most code should list the specific signals it wants to handle instead: 1796 </p> 1797 <pre> 1798 c := make(chan os.Signal) 1799 signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT) 1800 </pre> 1801 1802 <h3 id="path_filepath">The path/filepath package</h3> 1803 1804 <p> 1805 In Go 1, the <a href="/pkg/path/filepath/#Walk"><code>Walk</code></a> function of the 1806 <code>path/filepath</code> package 1807 has been changed to take a function value of type 1808 <a href="/pkg/path/filepath/#WalkFunc"><code>WalkFunc</code></a> 1809 instead of a <code>Visitor</code> interface value. 1810 <code>WalkFunc</code> unifies the handling of both files and directories. 1811 </p> 1812 1813 <pre> 1814 type WalkFunc func(path string, info os.FileInfo, err error) error 1815 </pre> 1816 1817 <p> 1818 The <code>WalkFunc</code> function will be called even for files or directories that could not be opened; 1819 in such cases the error argument will describe the failure. 1820 If a directory's contents are to be skipped, 1821 the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a> 1822 </p> 1823 1824 <pre><!--{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}} 1825 --> markFn := func(path string, info os.FileInfo, err error) error { 1826 if path == "pictures" { <span class="comment">// Will skip walking of directory pictures and its contents.</span> 1827 return filepath.SkipDir 1828 } 1829 if err != nil { 1830 return err 1831 } 1832 log.Println(path) 1833 return nil 1834 } 1835 err := filepath.Walk(".", markFn) 1836 if err != nil { 1837 log.Fatal(err) 1838 }</pre> 1839 1840 <p> 1841 <em>Updating</em>: 1842 The change simplifies most code but has subtle consequences, so affected programs 1843 will need to be updated by hand. 1844 The compiler will catch code using the old interface. 1845 </p> 1846 1847 <h3 id="regexp">The regexp package</h3> 1848 1849 <p> 1850 The <a href="/pkg/regexp/"><code>regexp</code></a> package has been rewritten. 1851 It has the same interface but the specification of the regular expressions 1852 it supports has changed from the old "egrep" form to that of 1853 <a href="http://code.google.com/p/re2/">RE2</a>. 1854 </p> 1855 1856 <p> 1857 <em>Updating</em>: 1858 Code that uses the package should have its regular expressions checked by hand. 1859 </p> 1860 1861 <h3 id="runtime">The runtime package</h3> 1862 1863 <p> 1864 In Go 1, much of the API exported by package 1865 <code>runtime</code> has been removed in favor of 1866 functionality provided by other packages. 1867 Code using the <code>runtime.Type</code> interface 1868 or its specific concrete type implementations should 1869 now use package <a href="/pkg/reflect/"><code>reflect</code></a>. 1870 Code using <code>runtime.Semacquire</code> or <code>runtime.Semrelease</code> 1871 should use channels or the abstractions in package <a href="/pkg/sync/"><code>sync</code></a>. 1872 The <code>runtime.Alloc</code>, <code>runtime.Free</code>, 1873 and <code>runtime.Lookup</code> functions, an unsafe API created for 1874 debugging the memory allocator, have no replacement. 1875 </p> 1876 1877 <p> 1878 Before, <code>runtime.MemStats</code> was a global variable holding 1879 statistics about memory allocation, and calls to <code>runtime.UpdateMemStats</code> 1880 ensured that it was up to date. 1881 In Go 1, <code>runtime.MemStats</code> is a struct type, and code should use 1882 <a href="/pkg/runtime/#ReadMemStats"><code>runtime.ReadMemStats</code></a> 1883 to obtain the current statistics. 1884 </p> 1885 1886 <p> 1887 The package adds a new function, 1888 <a href="/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available 1889 for parallel execution, as reported by the operating system kernel. 1890 Its value can inform the setting of <code>GOMAXPROCS</code>. 1891 The <code>runtime.Cgocalls</code> and <code>runtime.Goroutines</code> functions 1892 have been renamed to <code>runtime.NumCgoCall</code> and <code>runtime.NumGoroutine</code>. 1893 </p> 1894 1895 <p> 1896 <em>Updating</em>: 1897 Running <code>go</code> <code>fix</code> will update code for the function renamings. 1898 Other code will need to be updated by hand. 1899 </p> 1900 1901 <h3 id="strconv">The strconv package</h3> 1902 1903 <p> 1904 In Go 1, the 1905 <a href="/pkg/strconv/"><code>strconv</code></a> 1906 package has been significantly reworked to make it more Go-like and less C-like, 1907 although <code>Atoi</code> lives on (it's similar to 1908 <code>int(ParseInt(x, 10, 0))</code>, as does 1909 <code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>). 1910 There are also new variants of some of the functions that append to byte slices rather than 1911 return strings, to allow control over allocation. 1912 </p> 1913 1914 <p> 1915 This table summarizes the renamings; see the 1916 <a href="/pkg/strconv/">package documentation</a> 1917 for full details. 1918 </p> 1919 1920 <table class="codetable" frame="border" summary="strconv renames"> 1921 <colgroup align="left" width="50%"></colgroup> 1922 <colgroup align="left" width="50%"></colgroup> 1923 <tr> 1924 <th align="left">Old call</th> 1925 <th align="left">New call</th> 1926 </tr> 1927 <tr> 1928 <td colspan="2"><hr></td> 1929 </tr> 1930 <tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr> 1931 <tr> 1932 <td colspan="2"><hr></td> 1933 </tr> 1934 <tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)§</td></tr> 1935 <tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr> 1936 <tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr> 1937 <tr> 1938 <td colspan="2"><hr></td> 1939 </tr> 1940 <tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr> 1941 <tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)§</td></tr> 1942 <tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr> 1943 <tr> 1944 <td colspan="2"><hr></td> 1945 </tr> 1946 <tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)§</td></tr> 1947 <tr><td>Atoui64(x)</td> <td>ParseUint(x, 10, 64)</td></tr> 1948 <tr> 1949 <td colspan="2"><hr></td> 1950 </tr> 1951 <tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr> 1952 <tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr> 1953 <tr> 1954 <td colspan="2"><hr></td> 1955 </tr> 1956 <tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr> 1957 <tr> 1958 <td colspan="2"><hr></td> 1959 </tr> 1960 <tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(float64(x), f, p, 32)</td></tr> 1961 <tr><td>Ftoa64(x, f, p)</td> <td>FormatFloat(x, f, p, 64)</td></tr> 1962 <tr><td>FtoaN(x, f, p, n)</td> <td>FormatFloat(x, f, p, n)</td></tr> 1963 <tr> 1964 <td colspan="2"><hr></td> 1965 </tr> 1966 <tr><td>Itoa(x)</td> <td>Itoa(x)</td></tr> 1967 <tr><td>Itoa(x)</td> <td>FormatInt(int64(x), 10)</td></tr> 1968 <tr><td>Itoa64(x)</td> <td>FormatInt(x, 10)</td></tr> 1969 <tr> 1970 <td colspan="2"><hr></td> 1971 </tr> 1972 <tr><td>Itob(x, b)</td> <td>FormatInt(int64(x), b)</td></tr> 1973 <tr><td>Itob64(x, b)</td> <td>FormatInt(x, b)</td></tr> 1974 <tr> 1975 <td colspan="2"><hr></td> 1976 </tr> 1977 <tr><td>Uitoa(x)</td> <td>FormatUint(uint64(x), 10)</td></tr> 1978 <tr><td>Uitoa64(x)</td> <td>FormatUint(x, 10)</td></tr> 1979 <tr> 1980 <td colspan="2"><hr></td> 1981 </tr> 1982 <tr><td>Uitob(x, b)</td> <td>FormatUint(uint64(x), b)</td></tr> 1983 <tr><td>Uitob64(x, b)</td> <td>FormatUint(x, b)</td></tr> 1984 </table> 1985 1986 <p> 1987 <em>Updating</em>: 1988 Running <code>go</code> <code>fix</code> will update almost all code affected by the change. 1989 <br> 1990 § <code>Atoi</code> persists but <code>Atoui</code> and <code>Atof32</code> do not, so 1991 they may require 1992 a cast that must be added by hand; the <code>go</code> <code>fix</code> tool will warn about it. 1993 </p> 1994 1995 1996 <h3 id="templates">The template packages</h3> 1997 1998 <p> 1999 The <code>template</code> and <code>exp/template/html</code> packages have moved to 2000 <a href="/pkg/text/template/"><code>text/template</code></a> and 2001 <a href="/pkg/html/template/"><code>html/template</code></a>. 2002 More significant, the interface to these packages has been simplified. 2003 The template language is the same, but the concept of "template set" is gone 2004 and the functions and methods of the packages have changed accordingly, 2005 often by elimination. 2006 </p> 2007 2008 <p> 2009 Instead of sets, a <code>Template</code> object 2010 may contain multiple named template definitions, 2011 in effect constructing 2012 name spaces for template invocation. 2013 A template can invoke any other template associated with it, but only those 2014 templates associated with it. 2015 The simplest way to associate templates is to parse them together, something 2016 made easier with the new structure of the packages. 2017 </p> 2018 2019 <p> 2020 <em>Updating</em>: 2021 The imports will be updated by fix tool. 2022 Single-template uses will be otherwise be largely unaffected. 2023 Code that uses multiple templates in concert will need to be updated by hand. 2024 The <a href="/pkg/text/template/#examples">examples</a> in 2025 the documentation for <code>text/template</code> can provide guidance. 2026 </p> 2027 2028 <h3 id="testing">The testing package</h3> 2029 2030 <p> 2031 The testing package has a type, <code>B</code>, passed as an argument to benchmark functions. 2032 In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, enabling 2033 logging and failure reporting. 2034 </p> 2035 2036 <pre><!--{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}} 2037 -->func BenchmarkSprintf(b *testing.B) { 2038 <span class="comment">// Verify correctness before running benchmark.</span> 2039 b.StopTimer() 2040 got := fmt.Sprintf("%x", 23) 2041 const expect = "17" 2042 if expect != got { 2043 b.Fatalf("expected %q; got %q", expect, got) 2044 } 2045 b.StartTimer() 2046 for i := 0; i < b.N; i++ { 2047 fmt.Sprintf("%x", 23) 2048 } 2049 }</pre> 2050 2051 <p> 2052 <em>Updating</em>: 2053 Existing code is unaffected, although benchmarks that use <code>println</code> 2054 or <code>panic</code> should be updated to use the new methods. 2055 </p> 2056 2057 <h3 id="testing_script">The testing/script package</h3> 2058 2059 <p> 2060 The testing/script package has been deleted. It was a dreg. 2061 </p> 2062 2063 <p> 2064 <em>Updating</em>: 2065 No code is likely to be affected. 2066 </p> 2067 2068 <h3 id="unsafe">The unsafe package</h3> 2069 2070 <p> 2071 In Go 1, the functions 2072 <code>unsafe.Typeof</code>, <code>unsafe.Reflect</code>, 2073 <code>unsafe.Unreflect</code>, <code>unsafe.New</code>, and 2074 <code>unsafe.NewArray</code> have been removed; 2075 they duplicated safer functionality provided by 2076 package <a href="/pkg/reflect/"><code>reflect</code></a>. 2077 </p> 2078 2079 <p> 2080 <em>Updating</em>: 2081 Code using these functions must be rewritten to use 2082 package <a href="/pkg/reflect/"><code>reflect</code></a>. 2083 The changes to <a href="http://code.google.com/p/go/source/detail?r=2646dc956207">encoding/gob</a> and the <a href="http://code.google.com/p/goprotobuf/source/detail?r=5340ad310031">protocol buffer library</a> 2084 may be helpful as examples. 2085 </p> 2086 2087 <h3 id="url">The url package</h3> 2088 2089 <p> 2090 In Go 1 several fields from the <a href="/pkg/net/url/#URL"><code>url.URL</code></a> type 2091 were removed or replaced. 2092 </p> 2093 2094 <p> 2095 The <a href="/pkg/net/url/#URL.String"><code>String</code></a> method now 2096 predictably rebuilds an encoded URL string using all of <code>URL</code>'s 2097 fields as necessary. The resulting string will also no longer have 2098 passwords escaped. 2099 </p> 2100 2101 <p> 2102 The <code>Raw</code> field has been removed. In most cases the <code>String</code> 2103 method may be used in its place. 2104 </p> 2105 2106 <p> 2107 The old <code>RawUserinfo</code> field is replaced by the <code>User</code> 2108 field, of type <a href="/pkg/net/url/#Userinfo"><code>*net.Userinfo</code></a>. 2109 Values of this type may be created using the new <a href="/pkg/net/url/#User"><code>net.User</code></a> 2110 and <a href="/pkg/net/url/#UserPassword"><code>net.UserPassword</code></a> 2111 functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code> 2112 functions are also gone. 2113 </p> 2114 2115 <p> 2116 The <code>RawAuthority</code> field has been removed. The same information is 2117 available in the <code>Host</code> and <code>User</code> fields. 2118 </p> 2119 2120 <p> 2121 The <code>RawPath</code> field and the <code>EncodedPath</code> method have 2122 been removed. The path information in rooted URLs (with a slash following the 2123 schema) is now available only in decoded form in the <code>Path</code> field. 2124 Occasionally, the encoded data may be required to obtain information that 2125 was lost in the decoding process. These cases must be handled by accessing 2126 the data the URL was built from. 2127 </p> 2128 2129 <p> 2130 URLs with non-rooted paths, such as <code>"mailto:dev@golang.org?subject=Hi"</code>, 2131 are also handled differently. The <code>OpaquePath</code> boolean field has been 2132 removed and a new <code>Opaque</code> string field introduced to hold the encoded 2133 path for such URLs. In Go 1, the cited URL parses as: 2134 </p> 2135 2136 <pre> 2137 URL{ 2138 Scheme: "mailto", 2139 Opaque: "dev@golang.org", 2140 RawQuery: "subject=Hi", 2141 } 2142 </pre> 2143 2144 <p> 2145 A new <a href="/pkg/net/url/#URL.RequestURI"><code>RequestURI</code></a> method was 2146 added to <code>URL</code>. 2147 </p> 2148 2149 <p> 2150 The <code>ParseWithReference</code> function has been renamed to <code>ParseWithFragment</code>. 2151 </p> 2152 2153 <p> 2154 <em>Updating</em>: 2155 Code that uses the old fields will fail to compile and must be updated by hand. 2156 The semantic changes make it difficult for the fix tool to update automatically. 2157 </p> 2158 2159 <h2 id="cmd_go">The go command</h2> 2160 2161 <p> 2162 Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching, 2163 building, and installing Go packages and commands. The <code>go</code> command 2164 does away with makefiles, instead using Go source code to find dependencies and 2165 determine build conditions. Most existing Go programs will no longer require 2166 makefiles to be built. 2167 </p> 2168 2169 <p> 2170 See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the 2171 <code>go</code> command and the <a href="/cmd/go/">go command documentation</a> 2172 for the full details. 2173 </p> 2174 2175 <p> 2176 <em>Updating</em>: 2177 Projects that depend on the Go project's old makefile-based build 2178 infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should 2179 switch to using the <code>go</code> command for building Go code and, if 2180 necessary, rewrite their makefiles to perform any auxiliary build tasks. 2181 </p> 2182 2183 <h2 id="cmd_cgo">The cgo command</h2> 2184 2185 <p> 2186 In Go 1, the <a href="/cmd/cgo">cgo command</a> 2187 uses a different <code>_cgo_export.h</code> 2188 file, which is generated for packages containing <code>//export</code> lines. 2189 The <code>_cgo_export.h</code> file now begins with the C preamble comment, 2190 so that exported function definitions can use types defined there. 2191 This has the effect of compiling the preamble multiple times, so a 2192 package using <code>//export</code> must not put function definitions 2193 or variable initializations in the C preamble. 2194 </p> 2195 2196 <h2 id="releases">Packaged releases</h2> 2197 2198 <p> 2199 One of the most significant changes associated with Go 1 is the availability 2200 of prepackaged, downloadable distributions. 2201 They are available for many combinations of architecture and operating system 2202 (including Windows) and the list will grow. 2203 Installation details are described on the 2204 <a href="/doc/install">Getting Started</a> page, while 2205 the distributions themselves are listed on the 2206 <a href="http://code.google.com/p/go/downloads/list">downloads page</a>. 2207 2208 2209 </div> 2210 2211 <div id="footer"> 2212 Build version go1.0.1.<br> 2213 A link <a href="http://code.google.com/policies.html#restrictions">noted</a>, 2214 and then, coming up on the very next line, we will 2215 find yet another link, link 3.0 if you will, 2216 after a few more words <a href="/LINK">link text</a>.<br> 2217 <a href="/doc/tos.html">Terms of Service</a> | 2218 <a href="http://www.google.com/intl/en/privacy/privacy-policy.html">Privacy Policy</a> 2219 </div> 2220 2221 <script type="text/javascript"> 2222 (function() { 2223 var ga = document.createElement("script"); ga.type = "text/javascript"; ga.async = true; 2224 ga.src = ("https:" == document.location.protocol ? "https://ssl" : "http://www") + ".google-analytics.com/ga.js"; 2225 var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(ga, s); 2226 })(); 2227 </script> 2228 </body> 2229 <script type="text/javascript"> 2230 (function() { 2231 var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; 2232 po.src = 'https://apis.google.com/js/minusone.js'; 2233 var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s); 2234 })(); 2235 </script> 2236 </html> 2237