vendor/golang.org/x/net/html/testdata/go1.html

   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="plusone"><g:plusone size="small" annotation="none"></g:plusone></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(&#34;hello &#34;)...)</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, &#34;world&#34;...)</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&lt;- int = c
 149     var crecv &lt;-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{&#34;Feb&#34;, 14},
 178         Date{&#34;Nov&#34;, 11},
 179         Date{&#34;Dec&#34;, 25},
 180     }
 181     <span class="comment">// Struct values, type name elided; always legal.</span>
 182     holiday2 := []Date{
 183         {&#34;Feb&#34;, 14},
 184         {&#34;Nov&#34;, 11},
 185         {&#34;Dec&#34;, 25},
 186     }
 187     <span class="comment">// Pointers, fully qualified, always legal.</span>
 188     holiday3 := []*Date{
 189         &amp;Date{&#34;Feb&#34;, 14},
 190         &amp;Date{&#34;Nov&#34;, 11},
 191         &amp;Date{&#34;Dec&#34;, 25},
 192     }
 193     <span class="comment">// Pointers, type name elided; legal in Go 1.</span>
 194     holiday4 := []*Date{
 195         {&#34;Feb&#34;, 14},
 196         {&#34;Nov&#34;, 11},
 197         {&#34;Dec&#34;, 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 = &lt;-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 := &#39;δ&#39; <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 != &#39;δ&#39;+1 {
 281         log.Fatal(&#34;inconsistent casing for Greek&#34;)
 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{&#34;Sunday&#34;: 0, &#34;Monday&#34;: 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 &lt; 5; i++ {
 451             for j := 0; j &lt; 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{&#34;Christmas&#34;, &#34;XMas&#34;}
 554     Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
 555     holiday := map[Day]bool{
 556         Christmas:    true,
 557         Thanksgiving: true,
 558     }
 559     fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, 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>&lt;</code> <code>&lt;=</code>
 571 <code>&gt;</code> <code>&gt;=</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>&#8224;</sup></li>
 695 <li><code>go/types</code></li>
 696 </ul>
 697
 698 <p>
 699 (<sup>&#8224;</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(&#34;%s:%d: %s&#34;, 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(&#34;syntax error&#34;)</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&#39;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(&#34;Sleeping for %.3fs\n&#34;, 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(&#34;timeout&#34;, 30*time.Second, &#34;how long to wait for completion&#34;)</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(&#34;%s already exists&#34;, 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 == &#34;pictures&#34; { <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(&#34;.&#34;, 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(&#34;%x&#34;, 23)
2041     const expect = &#34;17&#34;
2042     if expect != got {
2043         b.Fatalf(&#34;expected %q; got %q&#34;, expect, got)
2044     }
2045     b.StartTimer()
2046     for i := 0; i &lt; b.N; i++ {
2047         fmt.Sprintf(&#34;%x&#34;, 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/plusone.js';
2233     var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
2234   })();
2235 </script>
2236 </html>
2237