qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-20 08:34:41 -07:00
Code Releases Activity
1ce0d72fdf
go/doc/go1.1.html
Rob Pike ee5a794fbb 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
2013-03-19 16:40:19 -07:00

608 lines
19 KiB
HTML
Raw Blame History

<!--{
"Title": "Go 1.1 Release Notes",
"Path": "/doc/go1.1",
"Template": true
}-->
<h2 id="introduction">Introduction to Go 1.1</h2>
TODO
- overview
- link back to Go 1 and also Go 1 Compatibility docs.
<h2 id="language">Changes to the language</h2>
<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>
<p>
In Go 1, integer division by a constant zero produced a runtime panic:
</p>
<pre>
func f(x int) int {
return x/0
}
</pre>
<p>
In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
</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>
<p>
TODO: more
</p>
<h3 id="gc_flag">Command-line flag parsing</h3>
<p>
In the gc tool chain, the compilers and linkers now use the
same command-line flag parsing rules as the Go flag package, a departure
from the traditional Unix flag parsing. This may affect scripts that invoke
the tool directly.
For example,
<code>go tool 6c -Fw -Dfoo</code> must now be written
<code>go tool 6c -F -w -D foo</code>.
</p>
<h3 id="int">Size of int on 64-bit platforms</h3>
<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
<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
more than 2 billion elements on 64-bit platforms.
</p>
<p>
<em>Updating</em>:
Most programs will be unaffected by this change.
Because Go does not allow implicit conversions between distinct
<a href="/ref/spec/#Numeric_types">numeric types</a>,
no programs will stop compiling due to this change.
However, programs that contain implicit assumptions
that <code>int</code> is only 32 bits may change behavior.
For example, this code prints a positive number on 64-bit systems and
a negative one on 32-bit systems:
<pre>
x := ^uint32(0) // x is 0xffffffff
i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit
fmt.Println(i)
</pre>
<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems)
would instead say:
</p>
<pre>
i := int(int32(x))
</pre>
<h3 id="unicode">Unicode</h3>
<p>
To make it possible to represent code points greater than 65535 in UTF-16,
Unicode defines <em>surrogate halves</em>,
a range of code points to be used only in the assembly of large values, and only in UTF-16.
The code points in that surrogate range are illegal for any other purpose.
In Go 1.1, this constraint is honored by the compiler, libraries, and run-time:
a surrogate half is illegal as a rune value, when encoded as UTF-8, or when
encoded in isolation as UTF-16.
When encountered, for example in converting from a rune to UTF-8, it is
treated as an encoding error and will yield the replacement rune,
<a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>,
U+FFFD.
</p>
<p>
This program,
</p>
<pre>
import "fmt"
func main() {
fmt.Printf("%+q\n", string(0xD800))
}
</pre>
<p>
printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1.
</p>
<p>
The Unicode byte order marks U+FFFE and U+FEFF, encoded in UTF-8, are now permitted as the first
character of a Go source file.
Even though their appearance in the byte-order-free UTF-8 encoding is clearly unnecessary,
some editors add them as a kind of "magic number" identifying a UTF-8 encoded file.
</p>
<p>
<em>Updating</em>:
Most programs will be unaffected by the surrogate change.
Programs that depend on the old behavior should be modified to avoid the issue.
The byte-order-mark change is strictly backwards-compatible.
</p>
<h3 id="gc_asm">The gc assemblers</h3>
<p>
Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and some other changes,
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
to adjust frame pointer offsets.
</p>
<p>
TODO: Point to cmd/vet once it handles this.
</p>
<h3 id="gocmd">Changes to the go command</h3>
<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>
<pre>
$ go build foo/quxx
can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
/home/you/go/src/pkg/foo/quxx (from $GOROOT)
/home/you/src/foo/quxx (from $GOPATH)
</pre>
<p>
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>
<pre>
$ 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
</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>
<pre>
$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx
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
</pre>
<p>
TODO: go test uses -c with a profile flag.
</p>
<h3 id="gofix">Changes to go fix</h3>
<p>
The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as
<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.
</p>
<h2 id="performance">Performance</h2>
<p>
TODO introduction
</p>
<ul>
<li>TODO better code generation (inlining, ...?)</li>
<li>TODO parallel gc</li>
<li>TODO more precise gc</li>
<li>TODO networking is more efficient (known to runtime)</li>
</ul>
<h2 id="library">Changes to the standard library</h2>
<h3 id="bufio_scanner">bufio.Scanner</h3>
<p>
TODO
</p>
<h3 id="debug_elf">debug/elf</h3>
<p>
TODO: Decide whether to keep this change. See CL 6848044.
</p>
<p>
Previous versions of the <a href="/debug/elf/"><code>debug/elf</code></a> package
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>
<h3 id="net">net</h3>
<p>
The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly
lax about the network name passed in.
Although the documentation was clear
that the only valid networks for
<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>
are <code>"tcp"</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>
The previous implementation of
<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
returned a
<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
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>
<h3 id="reflect">reflect</h3>
<p>
TODO:
<code>reflect</code>: Select, ChanOf, MakeFunc, MapOf, SliceOf, Convert, Type.ConvertibleTo
</p>
<h3 id="runtime">runtime</h3>
<p>
TODO:
<code>runtime</code>: BlockProfile
</p>
<h3 id="time">time</h3>
<p>
On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the
<a href="/pkg/time/"><code>time</code></a> package
returned times with microsecond precision.
The Go 1.1 implementation on these
systems now returns times with nanosecond precision.
Programs that write to an external format with microsecond precision
and read it back, expecting to recover the original value, will be affected
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
external storage.
</p>
<p>
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>
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>
To make it easier for binary distributions to access them if desired, the <code>exp</code>
and <code>old</code> source subtrees, which are not included in binary distributions,
have been moved to the new <code>go.exp</code> subrepository at
<code>code.google.com/p/go.exp</code>. To access the <code>ssa</code> package,
for example, run
</p>
<pre>
$ go get code.google.com/p/go.exp/ssa
</pre>
<p>
and then in Go source,
</p>
<pre>
import "code.google.com/p/go.exp/ssa"
</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>
<p>
The following list summarizes a number of minor changes to the library, mostly additions.
See the relevant package documentation for more information about each change.
</p>
<ul>
<li>
The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions,
<a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a>
and
<a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>,
with self-evident properties.
Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
has a new method
<a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that
provides some control over memory allocation inside the buffer.
Finally, the
<a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a
<a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method
so it implements the
<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
</li>
<li>
The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function,
<a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs.
</li>
<li> TODO:
<code>crypto/x509</code>: DecryptPEMBlock, EncryptPEMBlock etc.
</li>
<li> TODO:
<code>database/sql/driver</code>: Queryer
</li>
<li> TODO:
<code>database/sql</code>: Ping, SetMaxIdleConns
</li>
<li> TODO:
<code>encoding/json</code>: Decoder.Buffered, UseNumber, Number
</li>
<li> TODO:
<code>encoding/xml</code>: EscapeText Encoder.Indent
</li>
<li>
In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a
new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a>
and associated methods makes it easier to extract and process comments in Go programs.
</li>
<li>
In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package,
the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code>
throughout the code,
information that the <a href="/cmd/godoc/"><code>godoc</code></a>
command can filter or present according to the value of the <code>-notes</code> flag.
</li>
<li> TODO:
<code>go/format</code>: Node, Source
</li>
<li>
The undocumented and only partially implemented "noescape" feature of the
<a href="/pkg/html/template/">html/template</a>
package has been removed; programs that depend on it will break.
</li>
<li>
The <a href="/pkg/io/">io</a> package now exports the
<a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common
functionality of writing a byte at a time.
</li>
<li>
The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support
for OS-specific logging features.
</li>
<li>
The <a href="/pkg/math/big/"><code>math/big</code></a> package's
<a href="/pkg/math/big/#Int"><code>Int</code></a> type now has
now has methods
<a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a>
and
<a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a>
to convert to and from a JSON representation.
Also,
<a href="/pkg/math/big/#Int"><code>Int</code></a>
can now convert directly to and from a <code>uint64</code> using
<a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a>
and
<a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>,
while
<a href="/pkg/math/big/#Rat"><code>Rat</code></a>
can do the same with <code>float64</code> using
<a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a>
and
<a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>.
</li>
<li> TODO:
<code>mime/multipart</code>: Writer.SetBoundary
</li>
<li>
The new <a href="/pkg/net/http/cookiejar/">net/http/cookiejar</a> package provides the basics for managing HTTP cookies.
</li>
<li> TODO:
<code>net/http</code>: ParseTime, CloseNotifier, Request.PostFormValue, ServeMux.Handler, Transport.CancelRequest
</li>
<li> TODO:
<code>net/mail</code>: ParseAddress, ParseAddressList
</li>
<li> TODO:
<code>net/smtp</code>: Client.Hello
</li>
<li> TODO:
<code>net/textproto</code>: TrimBytes, TrimString
</li>
<li>
<code>net</code>: DialOption, DialOpt, ListenUnixgram, LookupNS, IPConn.ReadMsgIP, IPConn.WriteMsgIP, UDPConn.ReadMsgUDP, UDPConn.WriteMsgUDP, UnixConn.CloseRead, UnixConn.CloseWrite
</li>
<li>
The new method <a href="/pkg/os/#FileMode.IsRegular"><code>os.FileMode.IsRegular</code> </a> makes it easy to ask if a file is a plain file.
</li>
<li> TODO:
<code>pkg/image</code>: new subsamplings
</li>
<li>
The <a href="/pkg/regexp/"><code>regexp</code></a> package
now supports Unix-original leftmost-longest matches through the
<a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a>
method, while
<a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices
strings into pieces based on separators defined by the regular expression.
</li>
<li> TODO:
<code>runtime/debug</code>: FreeOSMemory, ReadGCStats, SetGCPercent
</li>
<li>
The <a href="/pkg/sort/"><code>sort</code></a> package has a new function,
<a href="/pkg/sort/#Reverse"><code>Reverse</code></a>.
Wrapping the argument of a call to
<a href="/pkg/sort/#Sort"><code>sort.Sort</code></a>
with a call to <code>Reverse</code> causes the sort order to be reversed.
</li>
<li>
The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions,
<a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a>
and
<a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a>
with self-evident properties, and the the new method
<a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the
<a href="/pkg/strings/#Reader"><code>Reader</code></a>
type now implements the
<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
</li>
<li>
The <a href="/pkg/syscall/"><code>syscall</code></a> package has received many updates to make it more inclusive of constants and system calls for each supported operating system.
</li>
<li>
The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation
statistics in benchmarks using the new
<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function and the
<a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of
<a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>.
There is also a new
<a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code>
command-line flag,
and a new
<a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of
<a href="/pkg/testing/#B"><code>testing.B</code></a> and
<a href="/pkg/testing/#T"><code>testing.T</code></a>
to simplify skipping an inappropriate test.
</li>
<li>
In the <a href="/pkg/text/template/"><code>text/template</code></a>
and
<a href="/pkg/html/template/"><code>html/template</code></a> packages,
templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines.
TODO: Link to example.
</li>
<li>
In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package,
the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point.
To be valid, a rune must be in range and not be a surrogate half.
</li>
<li>
The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0.
</li>
</ul>
View Git Blame Copy Permalink