Introduction to Go 1

For a full explanation of the motivation and design of Go 1, see XXX. Here follows a summary.

Go 1 is intended to be a stable language and core library set that will form a reliable foundation for people and organizations that want to make a long-term commitment to developing in the Go programming language. Go will continue to develop, but in a way that guarantees code written to the Go 1 specification will continue to work. For instance, Go 1 will be a supported platform on Google App Engine for the next few years. Incompatible changes to the environment, should they arise, will be done in a distinct version.

This document describes the changes in the language and libraries in Go 1, relative to the previous release, r60 (at the time of writing, tagged as r60.3). It also explains how to update code at r60 to compile and run under Go 1. Finally, it outlines the new go command for building Go programs and the new binary release process being introduced. Most of these topics have more thorough presentations elsewhere; such documents are linked below.

Changes to the language

Append

The append built-in function is variadic, so one can append to a byte slice using the ... syntax in the call.

    greeting := []byte{}
    greeting = append(greeting, []byte("hello ")...)

By analogy with the similar property of copy, Go 1 permits a string to be appended (byte-wise) directly to a byte slice; the conversion is no longer necessary:

    greeting = append(greeting, "world"...)

Updating: This is a new feature, so existing code needs no changes.

Close

The close built-in function lets a sender tell a receiver that no more data will be transmitted on the channel. In Go 1 the type system enforces the directionality when possible: it is illegal to call close on a receive-only channel:

    var c chan int
    var csend chan<- int = c
    var crecv <-chan int = c
    close(c)     // legal
    close(csend) // legal
    close(crecv) // illegal

Updating: Existing code that attempts to close a receive-only channel was erroneous even before Go 1 and should be fixed. The compiler will now reject such code.

Composite literals

In Go 1, a composite literal of array, slice, or map type can elide the type specification for the elements' initializers if they are of pointer type. All four of the initializations in this example are legal; the last one was illegal before Go 1.

    type Date struct {
        month string
        day   int
    }
    // Struct values, fully qualified; always legal.
    holiday1 := []Date{
        Date{"Feb", 14},
        Date{"Nov", 11},
        Date{"Dec", 25},
    }
    // Struct values, type name elided; always legal.
    holiday2 := []Date{
        {"Feb", 14},
        {"Nov", 11},
        {"Dec", 25},
    }
    // Pointers, fully qualified, always legal.
    holiday3 := []*Date{
        &Date{"Feb", 14},
        &Date{"Nov", 11},
        &Date{"Dec", 25},
    }
    // Pointers, type name elided; legal in Go 1.
    holiday4 := []*Date{
        {"Feb", 14},
        {"Nov", 11},
        {"Dec", 25},
    }

Updating: This change has no effect on existing code, but the command gofmt -s applied to existing source will, among other things, elide explicit element types wherever permitted.

Goroutines during init

Go 1 allows goroutines to be created and run during initialization. (They used to be created but were not run until after initialization completed.) Code that uses goroutines can now be called from init routines and global initialization expressions without introducing a deadlock.

var PackageGlobal int

func init() {
    c := make(chan int)
    go initializationFunction(c)
    PackageGlobal = <-c
}

Updating: This is a new feature, so existing code needs no changes, although it's possible that code that depends on goroutines not starting before main will break. There was no such code in the standard repository.

The rune type

Go 1 introduces a new basic type, rune, to be used to represent individual Unicode code points. It is an alias for int32, analogous to byte as an alias for uint8.

Character literals such as 'a', '語', and '\u0345' now have default type rune, analogous to 1.0 having default type float64. A variable initialized to a character constant will therefore have type rune unless otherwise specified.

Libraries have been updated to use rune rather than int when appropriate. For instance, the functions unicode.ToLower and relatives now take and return a rune.

    delta := 'δ' // delta has type rune.
    var DELTA rune
    DELTA = unicode.ToUpper(delta)
    epsilon := unicode.ToLower(DELTA + 1)
    if epsilon != 'δ'+1 {
        log.Fatal("inconsistent casing for Greek")
    }

Updating: Most source code will be unaffected by this because the type inference from := initializers introduces the new type silently, and it propagates from there. Some code may get type errors that a trivial conversion will resolve.

The error type

Go 1 introduces a new built-in type, error, which has the following definition:

    type error interface {
        Error() string
    }

Since the consequences of this type are all in the package library, it is discussed below.

Deleting from maps

The original syntax for deleting an element in a map was:

    m[k] = ignored, false

In Go 1, that syntax has gone; instead there is a new built-in function, delete. The call

    delete(m, k)

will delete the map entry retrieved by the expression m[k]. There is no return value. Deleting a non-existent entry is a no-op.

Updating: Gofix will convert expressions of the form m[k] = ignored, false into delete(m, k) when it is clear that the ignored value can be safely discarded from the program and false refers to the predefined boolean constant. Gofix will flag other uses of the syntax for inspection by the programmer.

Iterating in maps

In Go 1, the order in which elements are visited when iterating over a map using a for range statement is defined to be unpredictable, even if the same loop is run multiple times with the same map. Code should not assume that the elements are visited in any particular order.

    m := map[string]int{"Sunday": 0, "Monday": 1}
    for name, value := range m {
        // This loop should not assume Sunday will be visited first.
        f(name, value)
    }

Updating: This is one change where tools cannot help. Most existing code will be unaffected, but some programs may break or misbehave; we recommend manual checking of all range statements over maps to verify they do not depend on iteration order. There were a few such examples in the standard repository; they have been fixed. Note that it was already incorrect to depend on the iteration order, which was unspecified. This change codifies the unpredictability.

Multiple assignment

Go 1 fully specifies the evaluation order in multiple assignment statements. In particular, if the left-hand side of the assignment statement contains expressions that require evaluation, such as function calls or array indexing operations, these will all be done using the usual left-to-right rule before any variables are assigned their value. Once everything is evaluated, the actual assignments proceed in left-to-right order.

These examples illustrate the behavior.

    sa := []int{1, 2, 3}
    i := 0
    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2

    sb := []int{1, 2, 3}
    j := 0
    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1

    sc := []int{1, 2, 3}
    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)

Updating: This is one change where tools cannot help, but breakage is unlikely. No code in the standard repository was broken by this change, and code that depended on the previous unspecified behavior was already incorrect.

Returns and shadowed variables

A shadowed variable is one that has the same name as another variable in an inner scope. In functions with named return values, 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. (It isn't part of the specification, because this is one area we are still exploring; the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)

This function implicitly returns a shadowed return value and will be rejected by the compiler:

    func Bug() (i, j, k int) {
        for i = 0; i < 5; i++ {
            for j := 0; j < 5; j++ { // Redeclares j.
                k += i*j
                if k > 100 {
                    return // Rejected: j is shadowed here.
                }
            }
        }
        return // OK: j is not shadowed here.
    }

Updating: Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. The few cases that arose in the standard repository were mostly bugs.

Copying structs with unexported fields

Go 1 relaxes the rules about accessing structs with unexported (lower-case) fields, permitting a client package to assign (and therefore copy) such a struct. Of course, the client package still cannot access such fields individually.

As an example, if package p includes the definitions,

    type Struct struct {
        Public int
        secret int
    }
    func NewStruct(a int) Struct {  // Note: not a pointer.
        return Struct{a, f(a)}
    }
    func (s Struct) String() string {
        return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
    }

a package that imports p can assign and copy values of type p.Struct at will. Behind the scenes the unexported fields will be assigned and copied just as if they were exported, but the client code will never be aware of them. The code

    import "p"

    myStruct := p.NewStruct(23)
    copyOfMyStruct := myStruct
    fmt.Println(myStruct, copyOfMyStruct)

will show that the secret field of the struct has been copied to the new value.

Updating: This is a new feature, so existing code needs no changes.

Equality of structs and arrays

Go 1 defines equality and inequality (== and !=) for struct and array values, respectively, provided the elements of the data structures can themselves be compared. That is, if equality is defined for all the fields of a struct (or an array element), then it is defined for the struct (or array).

As a result, structs and arrays can now be used as map keys:

    type Day struct {
        long  string
        short string
    }
    Christmas := Day{"Christmas", "XMas"}
    Thanksgiving := Day{"Thanksgiving", "Turkey"}
    holiday := map[Day]bool{
        Christmas:    true,
        Thanksgiving: true,
    }
    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])

Note that equality is still undefined for slices, for which the calculation is in general infeasible. Also note that the ordered comparison operators (< <= > >=) are still undefined for structs and arrays.

Updating: This is a new feature, so existing code needs no changes.

Function and map equality

Go 1 disallows checking for equality of functions and maps, respectively, except to compare them directly to nil.

Updating: Existing code that depends on function or map equality will be rejected by the compiler and will need to be fixed by hand. Few programs will be affected, but the fix may require some redesign.

Changes to the library

The package hierarchy

Go 1 has a rearranged package hierarchy that groups related items into subdirectories. For instance, utf8 and utf16 now occupy subdirectories of unicode. Also, some packages have moved into subrepositories of code.google.com/p/go while others have been deleted outright.

Note that the package names for the old cmath and exp/template/html packages have changed to cmplx and template.

Updating: Gofix will update all imports and package renames for packages that remain inside the standard repository. Programs that import packages that are no longer in the standard repository will need to be edited by hand.
TODO: gofix should warn about deletions.
TODO: gofix should also handle packages that move to subrepos.

The error type and errors package

As mentioned above, Go 1 introduces a new built-in interface type called error. Its intent is to replace the old os.Error type with a more central concept. So the widely-used String method does not cause accidental satisfaction of the error interface, the error interface uses instead the name Error for that method:

    type error interface {
        Error() string
    }

The fmt library automatically invokes Error, as it already does for String, for easy printing of error values.

type SyntaxError struct {
    File    string
    Line    int
    Message string
}

func (se *SyntaxError) Error() string {
    return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
}

All standard packages have been updated to use the new interface; the old os.Error is gone.

A new package, errors, contains the function

func New(text string) error

to turn a string into an error. It replaces the old os.NewError.

    var ErrSyntax = errors.New("syntax error")

Updating: Gofix will update almost all code affected by the change. Code that defines error types with a String method will need to be updated by hand to rename the methods to Error.

System call errors

In Go 1, the syscall package returns an error for system call errors, rather than plain integer errno values. On Unix, the implementation is done by a syscall.Errno type that satisfies error and replaces the old os.Errno.

Updating: Gofix will update almost all code affected by the change. Regardless, most code should use the os package rather than syscall and so will be unaffected.

Time

One of the most sweeping changes in the Go 1 library is the complete redesign of the time package. Instead of an integer number of nanoseconds as an int64, and a separate *time.Time type to deal with human units such as hours and years, there are now two fundamental types: time.Time (a value, so the * is gone), which represents a moment in time; and time.Duration, which represents an interval. Both have nanosecond resolution. A Time can represent any time into the ancient past and remote future, while a Duration can span plus or minus only about 290 years. There are methods on these types, plus a number of helpful predefined constant durations such as time.Second.

Among the new methods are things like Time.Add, which adds a Duration to a Time, and Time.Sub, which subtracts two Times to yield a Duration.

The most important semantic change is that the Unix epoch (Jan 1, 1970) is now relevant only for those functions and methods that mention Unix: time.Unix and the Unix and UnixNano methods of the Time type. In particular, time.Now returns a time.Time value rather than, in the old API, an integer nanosecond count since the Unix epoch.

// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
func sleepUntil(wakeup time.Time) {
    now := time.Now() // A Time.
    if !wakeup.After(now) {
        return
    }
    delta := wakeup.Sub(now) // A Duration.
    log.Printf("Sleeping for %.3fs", delta.Seconds())
    time.Sleep(delta)
}

The new types, methods, and constants have been propagated through all the standard packages that use time, such as os and its representation of file time stamps.

Updating: Gofix will update many uses of the old time package to use the new types and methods, although it does not replace values such as 1e9 representing nanoseconds per second. Also, because of type changes in some of the values that arise, some of the expressions rewritten by gofix may require further hand editing; in such cases the rewrite will include the correct function or method for the old functionality, but may have the wrong type or require further analysis.

The hash package

In Go 1, the definition of hash.Hash includes a new method, BlockSize. This new method is used primarily in the cryptographic libraries.

Updating: Existing implementations of hash.Hash will need to add a BlockSize method. Hashes that process the input one byte at a time can implement BlockSize to return 1.

The html package

The html package in Go 1 provides a full parser for HTML5.

Updating: Since the package's functionality is new, no updating is necessary.

The http package

In Go 1 the http package is refactored, putting some of the utilities into a httputil subdirectory. These pieces are only rarely needed by HTTP clients. The affected items are:

• ClientConn
• DumpRequest
• DumpRequest
• DumpRequestOut
• DumpResponse
• NewChunkedReader
• NewChunkedWriter
• NewClientConn
• NewProxyClientConn
• NewServerConn
• NewSingleHostReverseProxy
• ReverseProxy
• ServerConn

Also, the Request.RawURL field has been removed; it was a historical artifact.

Updating: Gofix will update the few programs that are affected except for uses of RawURL, which must be fixed by hand.

The net package

In Go 1, the various SetTimeout, SetReadTimeout, and SetWriteTimeout methods have been replaced with SetDeadline, SetReadDeadline, and SetWriteDeadline, respectively. Rather than taking a timeout value in nanoseconds that apply to any activity on the connection, the new methods set an absolute deadline (as a time.Time value) after which reads and writes will time out and no longer block.

The strconv package

In Go 1, the strconv package has been significantly reworked to make it more Go-like and less C-like, although Atoi lives on (it's similar to int(ParseInt(x, 10, 0)), as does Itoa(x) (FormatInt(int64(x), 10)). There are also new variants of some of the functions that append to byte slices rather than return strings, to allow control over allocation.

This table summarizes the renamings; see the package documentation for full details.

Updating: Gofix will update almost all code affected by the change.
§ Atoi persists but Atoui and Atof32 do not, so they may require a cast that must be added by hand; gofix will warn about it.

The os.FileInfo type

Go 1 redefines the os.FileInfo type, changing it from a struct to an interface:

    type FileInfo interface {
        Name() string       // base name of the file
        Size() int64        // length in bytes
        Mode() FileMode     // file mode bits
        ModTime() time.Time // modification time
        IsDir() bool        // abbreviation for Mode().IsDir()
    }

The file mode information has been moved into a subtype called os.FileMode, a simple integer type with IsDir, Perm, and String methods.

The system-specific details of file modes and properties such as (on Unix) i-number have been removed from FileInfo altogether. Instead, each operating system's os package provides an implementation of the FileInfo interface, *os.FileStat, which in turn contains a Sys field that stores the system-specific representation of file metadata. For instance, to discover the i-number of a file on a Unix system, unpack the FileInfo like this:

    fi, err := os.Stat("hello.go")
    if err != nil {
        log.Fatal(err)
    }
    // Make sure it's an implementation known to package os.
    fileStat, ok := fi.(*os.FileStat)
    if !ok {
        log.Fatal("hello.go: not an os File")
    }
    // Now check that it's a Unix file.
    unixStat, ok := fileStat.Sys.(*syscall.Stat_t)
    if !ok {
        log.Fatal("hello.go: not a Unix file")
    }
    fmt.Printf("file i-number: %d\n", unixStat.Ino)

Assuming (which is unwise) that "hello.go" is a Unix file, the i-number expression could be contracted to

    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino

The vast majority of uses of FileInfo need only the methods of the standard interface.

Updating: Gofix will update code that uses the old equivalent of the current os.FileInfo and os.FileMode API. Code that needs system-specific file details will need to be updated by hand.

The package tree go

Several packages under go have slightly revised APIs.

The modes AllowIllegalChars and InsertSemis have been removed from the go/scanner package. They were mostly useful for scanning text other then Go source files. Instead, the text/scanner package should be used for that purpose.

The set of parse functions provided by the go/parser package has been reduced to the primary parse function ParseFile, and a couple of convenience functions ParseDir and ParseExpr.

The type names of the go/doc package have been streamlined by removing the Doc suffix: PackageDoc is now Package, ValueDoc is Value, etc. Also, all types now consistently have a Name field (or Names, in the case of type Value), Type.Factories has become Type.Funcs, and there is a new type Method that describes methods in more detail. Instead of calling doc.NewPackageDoc(pkg, importpath), documentation for a package is created with:

    doc.New(pkg, importpath, mode)

where the new mode parameter specifies the operation mode: if set to AllDecls, all declarations (not just exported ones) are considered. The function NewFileDoc was removed, and the function CommentText has become the method Text of ast.CommentGroup.

In package go/token, the token.FileSet method Files (which originally returned a channel of *token.Files) has been replaced with the iterator Iterate that accepts a function argument instead.

Updating: Code that uses packages in go will have to be updated by hand; the compiler will reject incorrect uses. Templates used in conjuction with any of the go/doc types may need manual fixes; the renamed fields will lead to run-time errors.

The package tree exp

Because they are not standardized, the packages under the exp directory will not be available in the standard Go 1 release distributions, although they will be available in source code form in the repository for developers who wish to use them.

Several packages have moved under exp at the time of Go 1's release:

• ebnf
• go/types
• http/spdy

Also, the utf8.String type has been moved to its own package, exp/utf8string.

All these packages are available under the same names, with exp/ prefixed: exp/ebnf etc.

Also, the gotype command now resides in exp/gotype, while ebnflint is now in exp/ebnflint

Updating: Code that uses packages in exp will need to be updated by hand, or else compiled from an installation that has exp available. Gofix or the compiler will complain about such uses.
TODO: gofix should warn about such uses.

The package tree old

Because they are deprecated, the packages under the old directory will not be available in the standard Go 1 release distributions, although they will be available in source code form for developers who wish to use them.

The packages in their new locations are:

• old/netchan
• old/regexp
• old/template

Updating: Code that uses packages now in old will need to be updated by hand, or else compiled from an installation that has old available. Gofix will warn about such uses.
TODO: gofix should warn about such uses.

Deleted packages

Go 1 deletes several packages outright:

• container/vector
• exp/datafmt
• go/typechecker
• try

and also the command gotry.

Updating: Code that uses container/vector should be updated to use slices directly. See the Go Language Community Wiki for some suggestions. Code that uses the other packages (there should be almost zero) will need to be rethought.
TODO: gofix should warn such uses.

Packages moving to subrepositories

The go command

Packaged releases