mirror of
https://github.com/golang/go.git
synced 2025-05-09 01:23:01 +00:00
doc/go1.1.html: add links to the text, write some new sections
R=golang-dev, rsc, dave CC=golang-dev https://golang.org/cl/7914043
This commit is contained in:
Rob Pike
parent
465ff4cfc0
commit
ee5a794fbb
202
doc/go1.1.html
202
doc/go1.1.html
@ -9,11 +9,17 @@
|
|||||||
TODO
|
TODO
|
||||||
- overview
|
- overview
|
||||||
- link back to Go 1 and also Go 1 Compatibility docs.
|
- link back to Go 1 and also Go 1 Compatibility docs.
|
||||||
- links through body of text
|
|
||||||
|
|
||||||
<h2 id="language">Changes to the language</h2>
|
<h2 id="language">Changes to the language</h2>
|
||||||
|
|
||||||
TODO
|
<p>
|
||||||
|
<a href="/doc/go1compat.html">The Go compatibility document</a> promises
|
||||||
|
that programs written to the Go 1 language specification will continue to operate,
|
||||||
|
and those promises are maintained.
|
||||||
|
In the interest of firming up the specification, though, there are some
|
||||||
|
details about some error cases that have been clarified.
|
||||||
|
There is also some new language features.
|
||||||
|
</p>
|
||||||
|
|
||||||
<h3 id="divzero">Integer division by zero</h3>
|
<h3 id="divzero">Integer division by zero</h3>
|
||||||
|
|
||||||
@ -31,6 +37,25 @@ func f(x int) int {
|
|||||||
In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
|
In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h3 id="unicode_literals">Surrogates in Unicode literals</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The definition of string and rune literals has been refined to exclude surrogate halves from the
|
||||||
|
set of valid Unicode code points.
|
||||||
|
See the <a href="#unicode">Unicode</a> section for more information.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h3 id="method_values">Method values</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
TODO
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h3 id="return">Return requirements</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
TODO
|
||||||
|
</p>
|
||||||
|
|
||||||
<h2 id="impl">Changes to the implementations and tools</h2>
|
<h2 id="impl">Changes to the implementations and tools</h2>
|
||||||
|
|
||||||
@ -38,7 +63,7 @@ In Go 1.1, an integer division by constant zero is not a legal program, so it is
|
|||||||
TODO: more
|
TODO: more
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="gc-flag">Command-line flag parsing</h3>
|
<h3 id="gc_flag">Command-line flag parsing</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
In the gc tool chain, the compilers and linkers now use the
|
In the gc tool chain, the compilers and linkers now use the
|
||||||
@ -53,7 +78,11 @@ For example,
|
|||||||
<h3 id="int">Size of int on 64-bit platforms</h3>
|
<h3 id="int">Size of int on 64-bit platforms</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The language allows the implementation to choose whether the <code>int</code> type and <code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code> and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations (TODO: check that gccgo does) <a href="http://golang.org/issue/2188">now make <code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64</a>.
|
The language allows the implementation to choose whether the <code>int</code> type and
|
||||||
|
<code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code>
|
||||||
|
and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations
|
||||||
|
<a href="http://golang.org/issue/2188">now make
|
||||||
|
<code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64</a>.
|
||||||
Among other things, this enables the allocation of slices with
|
Among other things, this enables the allocation of slices with
|
||||||
more than 2 billion elements on 64-bit platforms.
|
more than 2 billion elements on 64-bit platforms.
|
||||||
</p>
|
</p>
|
||||||
@ -75,7 +104,7 @@ i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit
|
|||||||
fmt.Println(i)
|
fmt.Println(i)
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<p>Portable code intending 32-bit sign extension (yielding -1 on all systems)
|
<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems)
|
||||||
would instead say:
|
would instead say:
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
@ -83,7 +112,7 @@ would instead say:
|
|||||||
i := int(int32(x))
|
i := int(int32(x))
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<h3 id="unicode_surrogates">Unicode</h3>
|
<h3 id="unicode">Unicode</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To make it possible to represent code points greater than 65535 in UTF-16,
|
To make it possible to represent code points greater than 65535 in UTF-16,
|
||||||
@ -129,31 +158,43 @@ Programs that depend on the old behavior should be modified to avoid the issue.
|
|||||||
The byte-order-mark change is strictly backwards-compatible.
|
The byte-order-mark change is strictly backwards-compatible.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="asm">Assembler</h3>
|
<h3 id="gc_asm">The gc assemblers</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Due to the <a href="#int">int</a> and TODO: OTHER changes,
|
Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and some other changes,
|
||||||
the placement of function arguments on the stack has changed.
|
the arrangement of function arguments on the stack has changed in the gc tool chain.
|
||||||
Functions written in assembly will need to be revised at least
|
Functions written in assembly will need to be revised at least
|
||||||
to adjust frame pointer offsets.
|
to adjust frame pointer offsets.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="gotool">Changes to the go tool</h3>
|
<p>
|
||||||
|
TODO: Point to cmd/vet once it handles this.
|
||||||
|
</p>
|
||||||
|
|
||||||
<p>The <code>go</code> tool has acquired several improvements which are intended to improve the experience for new Go users.</p>
|
<h3 id="gocmd">Changes to the go command</h3>
|
||||||
|
|
||||||
<p>Firstly, when compiling, testing, or running Go code, the <code>go</code> tool will now give more detailed errors messages, including a list of paths searched, when a package cannot be located.
|
<p>
|
||||||
|
The <a href="/cmd/go/"><code>go</code></a> command has acquired several
|
||||||
|
changes intended to improve the experience for new Go users.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages,
|
||||||
|
including a list of paths searched, when a package cannot be located.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
$ go build foo/quxx
|
$ go build foo/quxx
|
||||||
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
|
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
|
||||||
/home/User/go/src/pkg/foo/quxx (from $GOROOT)
|
/home/you/go/src/pkg/foo/quxx (from $GOROOT)
|
||||||
/home/User/src/foo/quxx (from $GOPATH)
|
/home/you/src/foo/quxx (from $GOPATH)
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Secondly, the <code>go get</code> command no longer allows <code>$GOROOT</code> as the default destination when downloading package source. To use <code>go get</code> command, a valid <code>$GOPATH</code> is now required.
|
Second, the <code>go get</code> command no longer allows <code>$GOROOT</code>
|
||||||
|
as the default destination when downloading package source.
|
||||||
|
To use the <code>go get</code>
|
||||||
|
command, a valid <code>$GOPATH</code> is now required.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
@ -161,7 +202,9 @@ $ GOPATH= go get code.google.com/p/foo/quxx
|
|||||||
package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath
|
package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<p>Finally, as a result of the previous change, the <code>go get</code> command will also fail when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
|
<p>
|
||||||
|
Finally, as a result of the previous change, the <code>go get</code> command will also fail
|
||||||
|
when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
@ -170,11 +213,17 @@ warning: GOPATH set to GOROOT (/home/User/go) has no effect
|
|||||||
package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath
|
package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
TODO: go test uses -c with a profile flag.
|
||||||
|
</p>
|
||||||
|
|
||||||
<h3 id="gofix">Changes to go fix</h3>
|
<h3 id="gofix">Changes to go fix</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The <code>go fix</code> command no longer applies fixes to update code from
|
The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as
|
||||||
before Go 1 to use Go 1 APIs. To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain
|
<code>go fix</code>, no longer applies fixes to update code from
|
||||||
|
before Go 1 to use Go 1 APIs.
|
||||||
|
To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain
|
||||||
to convert the code to Go 1.0 first.
|
to convert the code to Go 1.0 first.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
@ -200,33 +249,57 @@ TODO
|
|||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="debug_elf">debug/elf</h3>
|
<h3 id="debug_elf">debug/elf</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Previous versions of the debug/elf package intentionally skipped over the first
|
TODO: Decide whether to keep this change. See CL 6848044.
|
||||||
symbol in the ELF symbol table, since it is always an empty symbol. This symbol
|
</p>
|
||||||
is no longer skipped since indexes into the symbol table returned by debug/elf,
|
|
||||||
will be different to indexes into the original ELF symbol table. Any code that
|
<p>
|
||||||
calls the debug/elf functions Symbols or ImportedSymbols may need to be
|
Previous versions of the <a href="/debug/elf/"><code>debug/elf</code></a> package
|
||||||
adjusted to account for the additional symbol and the change in symbol offsets.
|
intentionally skipped over the first
|
||||||
|
symbol in the ELF symbol table, since it is always an empty symbol.
|
||||||
|
This symbol
|
||||||
|
is no longer skipped since indexes into the symbol table returned by <code>debug/elf</code>
|
||||||
|
will be different from indexes into the original ELF symbol table.
|
||||||
|
Any code that calls the methods
|
||||||
|
<a href="/pkg/debug/elf/#File.Symbols"><code>Symbols</code></a>
|
||||||
|
or
|
||||||
|
<a href="/pkg/debug/elf/#File.ImportedSymbols"><code>ImportedSymbols</code></a>
|
||||||
|
of the
|
||||||
|
<a href="/pkg/debug/elf/#File"><code>elf.File</code></a>
|
||||||
|
type may need to be adjusted to account for the additional symbol and the change in symbol offsets.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="net">net</h3>
|
<h3 id="net">net</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The protocol-specific resolvers were formerly
|
The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly
|
||||||
lax about the network name passed in. For example, although the documentation was clear
|
lax about the network name passed in.
|
||||||
that the only valid networks for <code>ResolveTCPAddr</code> are <code>"tcp"</code>,
|
Although the documentation was clear
|
||||||
<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted
|
that the only valid networks for
|
||||||
any string. The Go 1.1 implementation returns an error if the network is not one of those strings.
|
<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>
|
||||||
The same is true of the other protocol-specific resolvers <code>ResolveIPAddr</code>, <code>ResolveUDPAddr</code>, and
|
are <code>"tcp"</code>,
|
||||||
<code>ResolveUnixAddr</code>.
|
<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string.
|
||||||
|
The Go 1.1 implementation returns an error if the network is not one of those strings.
|
||||||
|
The same is true of the other protocol-specific resolvers <a href="/pkg/ResolveIPAddr/"><code>ResolveIPAddr</code></a>,
|
||||||
|
<a href="/pkg/ResolveUDPAddr/"><code>ResolveUDPAddr</code></a>, and
|
||||||
|
<a href="/pkg/ResolveUnixAddr/"><code>ResolveUnixAddr</code></a>.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The previous <code>ListenUnixgram</code> returned <code>UDPConn</code> as
|
The previous implementation of
|
||||||
a representation of the connection endpoint. The Go 1.1 implementation
|
<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
|
||||||
returns <code>UnixConn</code> to allow reading and writing
|
returned a
|
||||||
with <code>ReadFrom</code> and <code>WriteTo</code> methods on
|
<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
|
||||||
the <code>UnixConn</code>.
|
a representation of the connection endpoint.
|
||||||
|
The Go 1.1 implementation instead returns a
|
||||||
|
<a href="/pkg/UnixConn/"><code>UnixConn</code></a>
|
||||||
|
to allow reading and writing
|
||||||
|
with its
|
||||||
|
<a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a>
|
||||||
|
and
|
||||||
|
<a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a>
|
||||||
|
methods.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="reflect">reflect</h3>
|
<h3 id="reflect">reflect</h3>
|
||||||
@ -245,23 +318,52 @@ TODO:
|
|||||||
|
|
||||||
<h3 id="time">time</h3>
|
<h3 id="time">time</h3>
|
||||||
<p>
|
<p>
|
||||||
On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the time package
|
On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the
|
||||||
returned times with microsecond precision. The Go 1.1 implementation of time on these
|
<a href="/pkg/time/"><code>time</code></a> package
|
||||||
systems now returns times with nanosecond precision. Code may exist that expects to be
|
returned times with microsecond precision.
|
||||||
able to store such a time in an external format with only microsecond precision,
|
The Go 1.1 implementation on these
|
||||||
read it back, and recover exactly the same time instant.
|
systems now returns times with nanosecond precision.
|
||||||
In Go 1.1 the same time will not be recovered, since the external storage
|
Programs that write to an external format with microsecond precision
|
||||||
will have discarded nanoseconds.
|
and read it back, expecting to recover the original value, will be affected
|
||||||
To address this case, there are two new methods of time.Time, Round and Truncate,
|
by the loss of precision.
|
||||||
|
There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>,
|
||||||
|
<a href="/pkg/time/#Time.Round"><code>Round</code></a>
|
||||||
|
and
|
||||||
|
<a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>,
|
||||||
that can be used to remove precision from a time before passing it to
|
that can be used to remove precision from a time before passing it to
|
||||||
external storage.
|
external storage.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p> TODO:
|
<p>
|
||||||
<code>time</code>: ParseInLocation, Timer.Reset, Time.YearDay
|
The new method
|
||||||
|
<a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a>
|
||||||
|
returns the one-indexed integral day number of the year specified by the time value.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="exp_old">Exp and old subtrees moved to go.exp subrepo</h3>
|
<p>
|
||||||
|
The
|
||||||
|
<a href="/pkg/time/#Timer"><code>Timer</code></a>
|
||||||
|
type has a new method
|
||||||
|
<a href="/pkg/time/#Timer.Reset"><code>Reset</code></a>
|
||||||
|
that modifies the timer to expire after a specified duration.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
Finally, the new function
|
||||||
|
<a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a>
|
||||||
|
is like the existing
|
||||||
|
<a href="/pkg/time/#Parse"><code>Parse</code></a>
|
||||||
|
but parses the time in the context of a location (time zone), ignoring
|
||||||
|
time zone information in the parsed string.
|
||||||
|
This function addresses a common source of confusion in the time API.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<em>Updating</em>:
|
||||||
|
Code that needs to read and write times using an external format with
|
||||||
|
lower precision should be modified to use the new methods.
|
||||||
|
|
||||||
|
<h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
To make it easier for binary distributions to access them if desired, the <code>exp</code>
|
To make it easier for binary distributions to access them if desired, the <code>exp</code>
|
||||||
@ -283,6 +385,12 @@ and then in Go source,
|
|||||||
import "code.google.com/p/go.exp/ssa"
|
import "code.google.com/p/go.exp/ssa"
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
The old package <code>exp/norm</code> has also been moved, but to a new repository
|
||||||
|
<code>go.text</code>, where the Unicode APIs and other text-related packages will
|
||||||
|
be developed.
|
||||||
|
</p>
|
||||||
|
|
||||||
<h3 id="minor_library_changes">Minor changes to the library</h3>
|
<h3 id="minor_library_changes">Minor changes to the library</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user