"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/go1.html" (9 Sep 2020, 71461 Bytes) of package /windows/misc/go1.14.9.windows-386.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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