Introduction

This is a reference manual for the Go programming language. For more information and other documents, see the Go home page.

Go is a general-purpose language designed with systems programming in mind. It is strongly typed and garbage-collected, and has explicit support for concurrent programming. Programs are constructed from packages, whose properties allow efficient management of dependencies. The existing implementations use a traditional compile/link model to generate executable binaries.

The grammar is compact and regular, allowing for easy analysis by automatic tools such as integrated development environments.

Notation

The syntax is specified using Extended Backus-Naur Form (EBNF):

Production  = production_name "=" Expression .
Expression  = Alternative { "|" Alternative } .
Alternative = Term { Term } .
Term        = production_name | token [ "..." token ] | Group | Option | Repetition .
Group       = "(" Expression ")" .
Option      = "[" Expression ")" .
Repetition  = "{" Expression "}" .

Productions are expressions constructed from terms and the following operators, in increasing precedence:

|   alternation
()  grouping
[]  option (0 or 1 times)
{}  repetition (0 to n times)

Lower-case production names are used to identify lexical tokens. Non-terminals are in CamelCase. Lexical symbols are enclosed in double quotes "" (the double quote symbol is written as '"').

The form "a ... b" represents the set of characters from a through b as alternatives.

Where possible, recursive productions are used to express evaluation order and operator precedence syntactically.

Source code representation

Source code is Unicode text encoded in UTF-8. The text is not canonicalized, so a single accented code point is distinct from the same character constructed from combining an accent and a letter; those are treated as two code points. For simplicity, this document will use the term character to refer to a Unicode code point.

Each code point is distinct; for instance, upper and lower case letters are different characters.

Characters

The following terms are used to denote specific Unicode character classes:

• unicode_char an arbitrary Unicode code point
• unicode_letter a Unicode code point classified as "Letter"
• capital_letter a Unicode code point classified as "Letter, uppercase"
• unicode_digit a Unicode code point classified as "Digit"

Letters and digits

The underscore character _ (U+005F) is considered a letter.

letter        = unicode_letter | "_" .
decimal_digit = "0" ... "9" .
octal_digit   = "0" ... "7" .
hex_digit     = "0" ... "9" | "A" ... "F" | "a" ... "f" .

Lexical elements

Comments

There are two forms of comments. The first starts at the character sequence // and continues through the next newline. The second starts at the character sequence /* and continues through the character sequence */. Comments do not nest.

Tokens

Tokens form the vocabulary of the Go language. There are four classes: identifiers, keywords, operators and delimiters, and literals. White space, formed from blanks, tabs, and newlines, is ignored except as it separates tokens that would otherwise combine into a single token. Comments behave as white space. While breaking the input into tokens, the next token is the longest sequence of characters that form a valid token.

Identifiers

Identifiers name program entities such as variables and types. An identifier is a sequence of one or more letters and digits. The first character in an identifier must be a letter.

identifier    = letter { letter | unicode_digit } .

Exported identifiers (§Exported identifiers) start with a capital_letter.
TODO: This sentence feels out of place.

a
_x9
ThisVariableIsExported
αβ

Keywords

The following keywords are reserved and may not be used as identifiers.

break        default      func         interface    select
case         defer        go           map          struct
chan         else         goto         package      switch
const        fallthrough  if           range        type
continue     for          import       return       var

Operators and Delimiters

The following character sequences represent operators, delimiters, and other special tokens:

+    &     +=    &=     &&    ==    !=    (    )
-    |     -=    |=     ||    <     <=    [    ]
*    ^     *=    ^=     <-    >     >=    {    }
/    <<    /=    <<=    ++    =     :=    ,    ;
%    >>    %=    >>=    --    !     ...   .    :

Integer literals

An integer literal is a sequence of one or more digits in the corresponding base, which may be 8, 10, or 16. An optional prefix sets a non-decimal base: 0 for octal, 0x or 0X for hexadecimal. In hexadecimal literals, letters a-f and A-F represent values 10 through 15.

int_lit       = decimal_lit | octal_lit | hex_lit .
decimal_lit   = ( "1" ... "9" ) { decimal_digit } .
octal_lit     = "0" { octal_digit } .
hex_lit       = "0" ( "x" | "X" ) hex_digit { hex_digit } .

42
0600
0xBadFace
170141183460469231731687303715884105727

Floating-point literals

A floating-point literal is a decimal representation of a floating-point number. It has an integer part, a decimal point, a fractional part, and an exponent part. The integer and fractional part comprise decimal digits; the exponent part is an e or E followed by an optionally signed decimal exponent. One of the integer part or the fractional part may be elided; one of the decimal point or the exponent may be elided.

float_lit    = decimals "." [ decimals ] [ exponent ] |
               decimals exponent |
               "." decimals [ exponent ] .
decimals = decimal_digit { decimal_digit } .
exponent = ( "e" | "E" ) [ "+" | "-" ] decimals .

0.
2.71828
1.e+0
6.67428e-11
1E6
.25
.12345E+5

Ideal numbers

Integer literals represent values of arbitrary precision, or ideal integers. Similarly, floating-point literals represent values of arbitrary precision, or ideal floats. These ideal numbers have no size or type and cannot overflow. However, when (used in an expression) assigned to a variable or typed constant, the destination must be able to represent the assigned value.

Implementation restriction: A compiler may implement ideal numbers by choosing a large internal representation of such numbers.
TODO: This is too vague. It used to say "sufficiently" but that doesn't help. Define a minimum?

Character literals

A character literal represents an integer value, typically a Unicode code point, as one or more characters enclosed in single quotes. Within the quotes, any character may appear except single quote and newline. A single quoted character represents itself, while multi-character sequences beginning with a backslash encode values in various formats.

The simplest form represents the single character within the quotes; since Go source text is Unicode characters encoded in UTF-8, multiple UTF-8-encoded bytes may represent a single integer value. For instance, the literal 'a' holds a single byte representing a literal a, Unicode U+0061, value 0x61, while 'ä' holds two bytes (0xc3 0xa4) representing a literal a-dieresis, U+00E4, value 0xe4.

Several backslash escapes allow arbitrary values to be represented as ASCII text. There are four ways to represent the integer value as a numeric constant: \x followed by exactly two hexadecimal digits; \u followed by exactly four hexadecimal digits; \U followed by exactly eight hexadecimal digits, and a plain backslash \ followed by exactly three octal digits. In each case the value of the literal is the value represented by the digits in the corresponding base.

Although these representations all result in an integer, they have different valid ranges. Octal escapes must represent a value between 0 and 255 inclusive. (Hexadecimal escapes satisfy this condition by construction). The `Unicode' escapes \u and \U represent Unicode code points so within them some values are illegal, in particular those above 0x10FFFF and surrogate halves.

After a backslash, certain single-character escapes represent special values:

\a   U+0007 alert or bell
\b   U+0008 backspace
\f   U+000C form feed
\n   U+000A line feed or newline
\r   U+000D carriage return
\t   U+0009 horizontal tab
\v   U+000b vertical tab
\\   U+005c backslash
\'   U+0027 single quote  (valid escape only within character literals)
\"   U+0022 double quote  (valid escape only within string literals)

All other sequences are illegal inside character literals.

char_lit         = "'" ( unicode_value | byte_value ) "'" .
unicode_value    = unicode_char | little_u_value | big_u_value | escaped_char .
byte_value       = octal_byte_value | hex_byte_value .
octal_byte_value = "\" octal_digit octal_digit octal_digit .
hex_byte_value   = "\" "x" hex_digit hex_digit .
little_u_value   = "\" "u" hex_digit hex_digit hex_digit hex_digit .
big_u_value      = "\" "U" hex_digit hex_digit hex_digit hex_digit
                           hex_digit hex_digit hex_digit hex_digit .
escaped_char     = "\" ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | "\" | "'" | """ ) .

'a'
'ä'
'本'
'\t'
'\000'
'\007'
'\377'
'\x07'
'\xff'
'\u12e4'
'\U00101234'

The value of a character literal is an ideal integer, just as with integer literals.

String literals

String literals represent constant values of type string. There are two forms: raw string literals and interpreted string literals.

Raw string literals are character sequences between back quotes ``. Within the quotes, any character is legal except newline and back quote. The value of a raw string literal is the string composed of the uninterpreted bytes between the quotes; in particular, backslashes have no special meaning.

Interpreted string literals are character sequences between double quotes "". The text between the quotes forms the value of the literal, with backslash escapes interpreted as they are in character literals (except that \' is illegal and \" is legal). The three-digit octal (\000) and two-digit hexadecimal (\x00) escapes represent individual bytes of the resulting string; all other escapes represent the (possibly multi-byte) UTF-8 encoding of individual characters. Thus inside a string literal \377 and \xFF represent a single byte of value 0xFF=255, while ÿ, \u00FF, \U000000FF and \xc3\xbf represent the two bytes 0xc3 0xbf of the UTF-8 encoding of character U+00FF.

string_lit             = raw_string_lit | interpreted_string_lit .
raw_string_lit         = "`" { unicode_char } "`" .
interpreted_string_lit = """ { unicode_value | byte_value } """ .

`abc`
`\n`
"hello, world\n"
"\n"
""
"Hello, world!\n"
"日本語"
"\u65e5本\U00008a9e"
"\xff\u00FF"

These examples all represent the same string:

"日本語"                                 // UTF-8 input text
`日本語`                                 // UTF-8 input text as a raw literal
"\u65e5\u672c\u8a9e"                    // The explicit Unicode code points
"\U000065e5\U0000672c\U00008a9e"        // The explicit Unicode code points
"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e"  // The explicit UTF-8 bytes

Adjacent string literals separated only by the empty string, white space, or comments are concatenated into a single string literal.

StringLit              = string_lit { string_lit } .

"Alea iacta est."
"Alea " /* The die */ `iacta est` /* is cast */ "."

If the source code represents a character as two code points, such as a combining form involving an accent and a letter, the result will be an error if placed in a character literal (it is not a single code point), and will appear as two code points if placed in a string literal.

Declarations and scope rules

Declaration = ConstDecl | TypeDecl | VarDecl | FunctionDecl | MethodDecl .

The ``scope'' of an identifier is the extent of source text within which the identifier denotes the bound entity. No identifier may be declared twice in a single scope. Go is lexically scoped: An identifier denotes the entity it is bound to only within the scope of the identifier.

For instance, for a variable named "x", the scope of identifier "x" is the extent of source text within which "x" denotes that particular variable. It is illegal to declare another identifier "x" within the same scope.

The scope of an identifier depends on the entity declared. The scope for an identifier always excludes scopes redeclaring the identifier in nested blocks. An identifier declared in a nested block is said to ``shadow'' the same identifier declared in an outer block.

1. The scope of predeclared identifiers is the entire source file.
2. The scope of an identifier denoting a type, function or package extends textually from the point of the identifier in the declaration to the end of the innermost surrounding block.
3. The scope of a constant or variable extends textually from after the declaration to the end of the innermost surrounding block. If the variable is declared in the init statement of an if, for, or switch statement, the innermost surrounding block is the block associated with the respective statement.
4. The scope of a parameter or result identifier is the body of the corresponding function.
5. The scope of a field or method identifier is selectors for the corresponding type containing the field or method (§Selectors).
6. The scope of a label is the body of the innermost surrounding function and does not intersect with any non-label scope. Thus, each function has its own private label scope.

Predeclared identifiers

The following identifiers are predeclared:

All basic types:

bool, byte, uint8, uint16, uint32, uint64, int8, int16, int32, int64,
float32, float64, string

uint, int, float, uintptr

true, false, iota, nil

cap(), convert(), len(), make(), new(), panic(), panicln(), print(), println(), typeof(), ...

Exported identifiers

All other identifiers are ``internal''; they are only visible in files belonging to the same package which declares them.

TODO: This should be made clearer. For instance, function-local identifiers are never exported, but non-global fields/methods may be exported.

Const declarations

ConstDecl = "const" ( ConstSpec | "(" [ ConstSpecList ] ")" ) .
ConstSpecList = ConstSpec { ";" ConstSpec } [ ";" ] .
ConstSpec = IdentifierList [ CompleteType ] [ "=" ExpressionList ] .

IdentifierList = identifier { "," identifier } .
ExpressionList = Expression { "," Expression } .

const Pi float64 = 3.14159265358979323846
const E = 2.718281828
const (
	size int64 = 1024;
	eof = -1;
)
const a, b, c = 3, 4, "foo"  // a = 3, b = 4, c = "foo"
const u, v float = 0, 3      // u = 0.0, v = 3.0

Together with the "iota" constant generator implicit repetition of ExpressionLists permit light-weight declaration of enumerated values (§Iota):

const (
	Sunday = iota;
	Monday;
	Tuesday;
	Wednesday;
	Thursday;
	Friday;
	Partyday;
	numberOfDays;  // this constant in not exported
)

const Huge = 1 << 100;
const Four int8 = Huge >> 98;

const x = 3./2. + 3/2;

If the type is missing from a numeric constant declaration, the constant represents a value of abitrary precision, either integer or floating point, determined by the type of the initializing expression. Such a constant may be assigned to any variable that can represent its value accurately, regardless of type. For instance, 3 can be assigned to any integer variable but also to any floating point variable, while 1e12 can be assigned to a "float32", "float64", or even "int64". It is erroneous to assign a value with a non-zero fractional part to an integer, or if the assignment would overflow or underflow.

Iota

const (            // iota is set to 0
	enum0 = iota;  // sets enum0 to 0, etc.
	enum1 = iota;
	enum2 = iota
)

const (
	a = 1 << iota;  // a == 1 (iota has been reset)
	b = 1 << iota;  // b == 2
	c = 1 << iota;  // c == 4
)

const (
	u       = iota * 42;  // u == 0     (ideal integer)
	v float = iota * 42;  // v == 42.0  (float)
	w       = iota * 42;  // w == 84    (ideal integer)
)

const x = iota;  // x == 0 (iota has been reset)
const y = iota;  // y == 0 (iota has been reset)

const (
	base0, mask0 int64 = 1 << iota, i << iota - 1;  // base0 == 1, mask0 = 0
	base1, mask1 int64 = 1 << iota, i << iota - 1;  // base1 == 2, mask1 = 1
	base2, mask2 int64 = 1 << iota, i << iota - 1;  // base2 == 4, mask2 = 3
)

const (
	enum0 = iota;
	enum1;
	enum2
)

const (
	a = 1 << iota;
	b;
	c;
)

const (
	u = iota * 42;
	v float;
	w;
)

const (
	base0, mask0 int64 = 1 << iota, i << iota - 1;
	base1, mask1 int64;
	base2, mask2 int64;
)

Type declarations

TypeDecl = "type" ( TypeSpec | "(" [ TypeSpecList ] ")" ) .
TypeSpecList = TypeSpec { ";" TypeSpec } [ ";" ] .
TypeSpec = identifier Type .

type IntArray [16] int

type (
	Point struct { x, y float };
	Polar Point
)

type TreeNode struct {
	left, right *TreeNode;
	value Point;
}

type Comparable interface {
	cmp(Comparable) int
}

Variable declarations

VarDecl = "var" ( VarSpec | "(" [ VarSpecList ] ")" ) .
VarSpecList = VarSpec { ";" VarSpec } [ ";" ] .
VarSpec = IdentifierList ( CompleteType [ "=" ExpressionList ] | "=" ExpressionList ) .

var i int
var U, V, W float
var k = 0
var x, y float = -1.0, -2.0
var (
	i int;
	u, v, s = 2.0, 3.0, "bar"
)

If the variable type is omitted, an initialization expression (or expression list) must be present, and the variable type is the type of the expression value (in case of a list of variables, the variables assume the types of the corresponding expression values).

If the variable type is omitted, and the corresponding initialization expression is a constant expression of abstract int or floating point type, the type of the variable is "int" or "float" respectively:

var i = 0       // i has int type
var f = 3.1415  // f has float type

SimpleVarDecl = IdentifierList ":=" ExpressionList .

"var" IdentifierList = ExpressionList .

i, j := 0, 10;
f := func() int { return 7; }
ch := new(chan int);

Types

A type may be specified by a type name (§Type declarations) or a type literal. A type literal is a syntactic construct that explicitly specifies the composition of a new type in terms of other (already declared) types.

Type = TypeName | TypeLit | "(" Type ")" .
TypeName = QualifiedIdent.
TypeLit =
	ArrayType | StructType | PointerType | FunctionType | InterfaceType |
	SliceType | MapType | ChannelType .

All other types are called ``composite types'; they are composed from other (basic or composite) types and denoted by their type names or by type literals. There are arrays, structs, pointers, functions, interfaces, slices, maps, and channels.

At a given point in the source code, a type may be ``complete'' or ''incomplete''. Array and struct types are complete when they are fully declared. All other types are always complete (although their components, such as the base type of a pointer type, may be incomplete). Incomplete types are subject to usage restrictions; for instance the type of a variable must be complete where the variable is declared.

CompleteType = Type .

The ``static type'' (or simply ``type'') of a variable is the type defined by the variable's declaration. The ``dynamic type'' of a variable is the actual type of the value stored in a variable at run-time. Except for variables of interface type, the dynamic type of a variable is always its static type.

Variables of interface type may hold values with different dynamic types during execution. However, its dynamic type is always compatible with the static type of the interface variable (§Interface types).

Basic types

Arithmetic types

byte     same as uint8 (for convenience)

uint8    the set of all unsigned  8-bit integers (0 to 255)
uint16   the set of all unsigned 16-bit integers (0 to 65535)
uint32   the set of all unsigned 32-bit integers (0 to 4294967295)
uint64   the set of all unsigned 64-bit integers (0 to 18446744073709551615)

int8     the set of all signed  8-bit integers (-128 to 127)
int16    the set of all signed 16-bit integers (-32768 to 32767)
int32    the set of all signed 32-bit integers (-2147483648 to 2147483647)
int64    the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)

float32  the set of all valid IEEE-754 32-bit floating point numbers
float64  the set of all valid IEEE-754 64-bit floating point numbers

uint     at least 32 bits, at most the size of the largest uint type
int      at least 32 bits, at most the size of the largest int type
float    at least 32 bits, at most the size of the largest float type
uintptr  smallest uint type large enough to store the uninterpreted
		 bits of a pointer value

Except for "byte", which is an alias for "uint8", all numeric types are different from each other to avoid portability issues. Conversions are required when different numeric types are mixed in an expression or assignment. For instance, "int32" and "int" are not the same type even though they may have the same size on a particular platform.

Booleans

Strings

The "string" type represents the set of string values (strings). Strings behave like arrays of bytes, with the following properties:

• They are immutable: after creation, it is not possible to change the contents of a string.
• No internal pointers: it is illegal to create a pointer to an inner element of a string.
• They can be indexed: given string "s1", "s1[i]" is a byte value.
• They can be concatenated: given strings "s1" and "s2", "s1 + s2" is a value combining the elements of "s1" and "s2" in sequence.
• Known length: the length of a string "s1" can be obtained by calling "len(s1)". The length of a string is the number of bytes within. Unlike in C, there is no terminal NUL byte.
• Creation 1: a string can be created from an integer value by a conversion; the result is a string containing the UTF-8 encoding of that code point (§Conversions). "string('x')" yields "x"; "string(0x1234)" yields the equivalent of "\u1234"
• Creation 2: a string can by created from an array of integer values (maybe just array of bytes) by a conversion (§Conversions):

  a [3]byte; a[0] = 'a'; a[1] = 'b'; a[2] = 'c';  string(a) == "abc";
  

Array types

ArrayType = "[" ArrayLength "]" ElementType .
ArrayLength = Expression .
ElementType = CompleteType .

The number of elements of an array "a" can be discovered using the built-in function

len(a)

[32]byte
[2*N] struct { x, y int32 }
[1000]*float64

Struct types

StructType = "struct" [ "{" [ FieldDeclList ] "}" ] .
FieldDeclList = FieldDecl { ";" FieldDecl } [ ";" ] .
FieldDecl = (IdentifierList CompleteType | [ "*" ] TypeName) [ Tag ] .
Tag = StringLit .

// An empty struct.
struct {}

// A struct with 5 fields.
struct {
	x, y int;
	u float;
	A *[]int;
	F func();
}

// A struct with four anonymous fields of type T1, *T2, P.T3 and *P.T4
struct {
	T1;        // the field name is T1
	*T2;       // the field name is T2
	P.T3;      // the field name is the unqualified type name T3
	*P.T4;     // the field name is the unqualified type name T4
	x, y int;  
}

struct {
	T;         // conflicts with anonymous field *T and *P.T
	*T;        // conflicts with anonymous field T and *P.T
	*P.T;      // conflicts with anonymous field T and *T
}

A field declaration may be followed by an optional string literal tag which becomes an ``attribute'' for all the identifiers in the corresponding field declaration. The tags are available via the reflection library but are ignored otherwise. A tag may contain arbitrary application-specific information.

// A struct corresponding to the EventIdMessage protocol buffer.
// The tag strings contain the protocol buffer field tags.
struct {
	time_usec uint64 "1";
	server_ip uint32 "2";
	process_id uint32 "3";
}

type S2 struct // forward declaration of S2
type S1 struct { s2 *S2 }
type S2 struct { s1 *S1 }

Pointer types

PointerType = "*" BaseType .
BaseType = Type .

*int
map[string] chan

type S struct { s *S }

type S2 struct // forward declaration of S2
type S1 struct { s2 *S2 }
type S2 struct { s1 *S1 }

Comparisons: A variable of pointer type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Two variables of equal pointer type can be tested for equality with the operators "==" and "!=" (§Comparison operators). The pointers are equal if they point to the same location. Pointer arithmetic of any kind is not permitted.

Function types

FunctionType = "func" Signature .
Signature = "(" [ ParameterList ] ")" [ Result ] .
ParameterList = ParameterDecl { "," ParameterDecl } .
ParameterDecl = [ IdentifierList ] ( Type | "..." ) .
Result = Type | "(" ParameterList ")" .

For the last incoming parameter only, instead of a parameter type one may write "...". The ellipsis indicates that the last parameter stands for an arbitrary number of additional arguments of any type (including no additional arguments). If the parameters are named, the identifier list immediately preceding "..." must contain only one identifier (the name of the last parameter).

func ()
func (x int)
func () int
func (string, float, ...)
func (a, b int, z float) bool
func (a, b int, z float) (bool)
func (a, b int, z float, opt ...) (success bool)
func (int, int, float) (float, *[]int)

func (n int) (func (p* T))

Comparisons: A variable of function type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Two variables of equal function type can be tested for equality with the operators "==" and "!=" (§Comparison operators). The variables are equal if they refer to the same function.

Interface types

InterfaceType = "interface" [ "{" [ MethodSpecList ] "}" ] .
MethodSpecList = MethodSpec { ";" MethodSpec } [ ";" ] .
MethodSpec = IdentifierList Signature | TypeName .

// An interface specifying a basic File type.
interface {
	Read, Write	(b Buffer) bool;
	Close		();
}

func (p T) Read(b Buffer) bool { return ... }
func (p T) Write(b Buffer) bool { return ... }
func (p T) Close() { ... }

interface {}

type Lock interface {
	Lock, Unlock	();
}

func (p T) Lock() { ... }
func (p T) Unlock() { ... }

An interface may contain a type name T in place of a method specification. T must denote another, complete (and not forward-declared) interface type. Using this notation is equivalent to enumerating the methods of T explicitly in the interface containing T.

type ReadWrite interface {
	Read, Write	(b Buffer) bool;
}

type File interface {
	ReadWrite;  // same as enumerating the methods in ReadWrite
	Lock;       // same as enumerating the methods in Lock
	Close();
}

type T2 interface
type T1 interface {
	foo(T2) int;
}
type T2 interface {
	bar(T1) int;
}

Comparisons: A variable of interface type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Two variables of interface type can be tested for equality with the operators "==" and "!=" (§Comparison operators) if both variables have the same static type. They are equal if both their dynamic types and values are equal. If the dynamic types are equal but the values do not support comparison, a run-time error occurs.

Slice types

SliceType = "[" "]" ElementType .

For slices, the actual array underlying the slice may extend past the current slice length; the maximum length a slice may assume is called its capacity. The capacity of any slice "a" can be discovered using the built-in function

cap(a)

0 <= len(a) <= cap(a)

make([]T, length)
make([]T, length, capacity)

make([]T, length, capacity)

new([capacity]T)[0 : length]

Indexing: Given a (pointer to) a slice variable "a", a slice element is specified with an index operation:

a[i]

Slicing: Given a a slice variable "a", a sub-slice is created with a slice operation:

a[i : j]

Comparisons: A variable of slice type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Map types

MapType = "map" "[" KeyType "]" ValueType .
KeyType = CompleteType .
ValueType = CompleteType .

Upon creation, a map is empty and values may be added and removed during execution.

map [string] int
map [*T] struct { x, y float }
map [string] interface {}

len(m)

my_map := make(M, 100);

Assignment compatibility: A map type is assignment compatible to a variable of map type only if both types are equal.

Comparisons: A variable of map type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Channel types

ChannelType = Channel | SendChannel | RecvChannel .
Channel = "chan" ValueType .
SendChannel = "chan" "<-" ValueType .
RecvChannel = "<-" "chan" ValueType .

chan T         // can send and receive values of type T
chan <- float  // can only be used to send floats
<-chan int     // can only receive ints

my_chan = make(chan int, 100);

Assignment compatibility: A value of type channel can be assigned to a variable of type channel only if a) both types are equal (§Type equality), or b) both have equal channel value types and the value is a bidirectional channel.

Comparisons: A variable of channel type can be compared against "nil" with the operators "==" and "!=" (§Comparison operators). The variable is "nil" only if "nil" is assigned explicitly to the variable (§Assignments), or if the variable has not been modified since creation (§Program initialization and execution).

Two variables of channel type can be tested for equality with the operators "==" and "!=" (§Comparison operators) if both variables have the same ValueType. They are equal if both values were created by the same "make" call (§Making slices, maps, and channels).

Type equality

Types may be ``different'', ``structurally equal'', or ``identical''. Go is a type-safe language; generally different types cannot be mixed in binary operations, and values cannot be assigned to variables of different types. However, values may be assigned to variables of structurally equal types. Finally, type guards succeed only if the dynamic type is identical to or implements the type tested against (§Type guards).

Structural type equality (equality for short) is defined by these rules:

Two type names denote equal types if the types in the corresponding declarations are equal. Two type literals specify equal types if they have the same literal structure and corresponding components have equal types. Loosely speaking, two types are equal if their values have the same layout in memory. More precisely:

• Two array types are equal if they have equal element types and if they have the same array length.
• Two struct types are equal if they have the same number of fields in the same order, corresponding fields either have both the same name or are both anonymous, and corresponding field types are identical.
• Two pointer types are equal if they have equal base types.
• Two function types are equal if they have the same number of parameters and result values and if corresponding parameter and result types are equal (a "..." parameter is equal to another "..." parameter). Note that parameter and result names do not have to match.
• Two slice types are equal if they have equal element types.
• Two channel types are equal if they have equal value types and the same direction.
• Two map types are equal if they have equal key and value types.
• Two interface types are equal if they have the same set of methods with the same names and equal function types. Note that the order of the methods in the respective type declarations is irrelevant.

Type identity is defined by these rules:

Two type names denote identical types if they originate in the same type declaration. Two type literals specify identical types if they have the same literal structure and corresponding components have identical types. More precisely:

• Two array types are identical if they have identical element types and if they have the same array length.
• Two struct types are identical if they have the same number of fields in the same order, corresponding fields either have both the same name or are both anonymous, and corresponding field types are identical.
• Two pointer types are identical if they have identical base types.
• Two function types are identical if they have the same number of parameters and result values both with the same (or absent) names, and if corresponding parameter and result types are identical (a "..." parameter is identical to another "..." parameter with the same name).
• Two slice types are identical if they have identical element types.
• Two channel types are identical if they have identical value types and the same direction.
• Two map types are identical if they have identical key and value types.
• Two interface types are identical if they have the same set of methods with the same names and identical function types. Note that the order of the methods in the respective type declarations is irrelevant.

Finally, two types are different if they are not structurally equal. (By definition, they cannot be identical, either). For instance, given the declarations

type (
	T0 []string;
	T1 []string
	T2 struct { a, b int };
	T3 struct { a, c int };
	T4 func (int, float) *T0
	T5 func (x int, y float) *[]string
)

T0 and T0
T0 and []string
T2 and T3
T4 and T5
T3 and struct { a int; int }

T0 and T0
[]int and []int
struct { a, b *T5 } and struct { a, b *T5 }

Expressions

The type of a constant expression may be an ideal number. The type of such expressions is implicitly converted into the 'expected numeric type' required for the expression. The conversion is legal if the (ideal) expression value is a member of the set represented by the expected numeric type. In all other cases, and specifically if the expected type is not a numeric type, the expression is erroneous.

For instance, if the expected numeric type is a uint32, any ideal number which fits into a uint32 without loss of precision can be legally converted. Thus, the values 991, 42.0, and 1e9 are ok, but -1, 3.14, or 1e100 are not.

Operands

Operand  = Literal | QualifiedIdent | "(" Expression ")" .
Literal  = BasicLit | CompositeLit | FunctionLit .
BasicLit = int_lit | float_lit | char_lit | StringLit .
StringLit = string_lit { string_lit } .

Constants

Qualified identifiers

TODO(gri) expand this section.

QualifiedIdent = { PackageName "." } identifier .
PackageName = identifier .

Composite literals

CompositeLit = LiteralType "(" [ ( ExpressionList | ExprPairList ) [ "," ] ] ")" .
LiteralType = Type | "[" "..." "]" ElementType .
ExprPairList = ExprPair { "," ExprPair } .
ExprPair = Expression ":" Expression .

Given

type Rat struct { num, den int }
type Num struct { r Rat; f float; s string }

pi := Num(Rat(22, 7), 3.14159, "pi");

buffer := [10]string();               // len(buffer) == 10
primes := [6]int(2, 3, 5, 7, 9, 11);  // len(primes) == 6
days := [...]string("sat", "sun");    // len(days) == 2

[]T(x1, x2, ... xn)

[n]T(x1, x2, ... xn)[0 : n]

m := map[string]int("good": 0, "bad": 1, "indifferent": 7);

Function literals

FunctionLit = "func" Signature Block .
Block = "{" [ StatementList ] "}" .

func (a, b int, z float) bool { return a*b < int(z); }

f := func(x, y int) int { return x + y; }
func(ch chan int) { ch <- ACK; } (reply_chan)

Primary expressions

PrimaryExpr =
	Operand |
	PrimaryExpr Selector |
	PrimaryExpr Index |
	PrimaryExpr Slice |
	PrimaryExpr TypeGuard |
	PrimaryExpr Call .

Selector = "." identifier .
Index = "[" Expression "]" .
Slice = "[" Expression ":" Expression "]" .
TypeGuard = "." "(" Type ")" .
Call = "(" [ ExpressionList ] ")" .

x
2
(s + ".txt")
f(3.1415, true)
Point(1, 2)
m["foo"]
s[i : j + 1]
obj.color
Math.sin
f.p[i].x()

Selectors

x.f

A selector f may denote a field f declared in a type T, or it may refer to a field f declared in a nested anonymous field of T. Analogously, f may denote a method f of T, or it may refer to a method f of the type of a nested anonymous field of T. The number of anonymous fields traversed to get to the field or method is called its ``depth'' in T.

More precisely, the depth of a field or method f declared in T is zero. The depth of a field or method f declared anywhere inside an anonymous field A declared in T is the depth of f in A plus one.

The following rules apply to selectors:

1) For a value x of type T or *T where T is not an interface type, x.f denotes the field or method at the shallowest depth in T where there is such an f. The type of x.f is the type of the field or method f. If there is not exactly one f with shallowest depth, the selector expression is illegal.

2) For a variable x of type I or *I where I is an interface type, x.f denotes the actual method with name f of the value assigned to x if there is such a method. The type of x.f is the type of the method f. If no value or nil was assigned to x, x.f is illegal.

3) In all other cases, x.f is illegal.

Thus, selectors automatically dereference pointers as necessary. For instance, for an x of type *T where T declares an f, x.f is a shortcut for (*x).f. Furthermore, for an x of type T containing an anonymous field A declared as *A inside T, and where A contains a field f, x.f is a shortcut for (*x.A).f (assuming that the selector is legal in the first place).

The following examples illustrate selector use in more detail. Given the declarations:

type T0 struct {
	x int;
}

func (recv *T0) M0()

type T1 struct {
	y int;
}

func (recv T1) M1()

type T2 struct {
	z int;
	T1;
	*T0;
}

func (recv *T2) M2()

var p *T2;  // with p != nil and p.T1 != nil

p.z         // (*p).z
p.y         // ((*p).T1).y
p.x         // (*(*p).T0).x

p.M2        // (*p).M2
p.M1        // ((*p).T1).M1
p.M0        // ((*p).T0).M0

Indexes

a[x]

denotes the array or map element x. The value x is called the ``array index'' or ``map key'', respectively. The following rules apply:

For a of type A or *A where A is an array type (§Array types):

• x must be an integer value and 0 <= x < len(a)
• a[x] is the array element at index x and the type of a[x] is the element type of A

For a of type *M, where M is a map type (§Map types):

• x must be of the same type as the key type of M and the map must contain an entry with key x
• a[x] is the map value with key x and the type of a[x] is the value type of M

TODO: Need to expand map rules for assignments of the form v, ok = m[k].

Slices

a := [4]int(1, 2, 3, 4);
s := a[1:3];

s[0] == 2
s[1] == 3

If the sliced operand is a string, the result of the slice operation is another string (§String types). If the sliced operand is an array or slice, the result of the slice operation is a slice (§Slice types).

Type guards

x.(T)

More precisely, if "T" is not an interface type, the expression asserts that the dynamic type of "x" is identical to the type "T" (§Types). If "T" is an interface type, the expression asserts that the dynamic type of T implements the interface "T" (§Interface types). Because it can be verified statically, a type guard in which the static type of "x" implements the interface "T" is illegal. The type guard is said to succeed if the assertion holds.

If the type guard succeeds, the value of the guarded expression is the value stored in "x" and its type is "T". If the type guard fails, a run-time exception occurs. In other words, even though the dynamic type of "x" is only known at run-time, the type of the guarded expression "x.(T)" is known to be "T" in a correct program.

As a special form, if a guarded expression is used in an assignment

v, ok = x.(T)
v, ok := x.(T)

TODO add examples

Calls

p()

A method is called using the notation

receiver.method()

For instance, given a *Point variable pt, one may call

pt.Scale(3.5)

(p *Point, factor float)

There is no distinct method type and there are no method literals.

Parameter passing

*struct {
	arg(0) typeof(arg(0));
	arg(1) typeof(arg(1));
	arg(2) typeof(arg(2));
	...
	arg(n-1) typeof(arg(n-1));
}

func f(x int, s string, f_extra ...)

f(42, "foo", 3.14, true, []int(1, 2, 3))

*struct {
	arg0 float;
	arg1 bool;
	arg2 []int;
}

As a special case, if a function passes a "..." parameter as the argument for a "..." parameter of a function, the parameter is not wrapped again into a struct. Instead it is passed along unchanged. For instance, the function f may call a function g with declaration

func g(x int, g_extra ...)

g(x, f_extra);

Operators

Expression = UnaryExpr | Expression binaryOp UnaryExpr .
UnaryExpr = PrimaryExpr | unary_op UnaryExpr .

binary_op = log_op | com_op | rel_op | add_op | mul_op .
log_op = "||" | "&&" .
com_op = "<-" .
rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" .
add_op = "+" | "-" | "|" | "^" .
mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" .

unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" .

The operand types in binary operations must be equal, with the following exceptions:

• If one operand has numeric type and the other operand is an ideal number, the ideal number is converted to match the type of the other operand (§Expression).
• If both operands are ideal numbers, the conversion is to ideal floats if one of the operands is an ideal float (relevant for "/" and "%").
• The right operand in a shift operation must be always be an unsigned int (or an ideal number that can be safely converted into an unsigned int) (§Arithmetic operators).
• When comparing two operands of channel type, the channel value types must be equal but the channel direction is ignored.

There are six precedence levels for binary operators: multiplication operators bind strongest, followed by addition operators, comparison operators, communication operators, "&&" (logical and), and finally "||" (logical or) with the lowest precedence:

Precedence    Operator
    6             *  /  %  <<  >>  &
    5             +  -  |  ^
    4             ==  !=  <  <=  >  >=
    3             <-
    2             &&
    1             ||

Examples

+x
23 + 3*x[i]
x <= f()
^a >> b
f() || g()
x == y + 1 && <-chan_ptr > 0

Arithmetic operators

Arithmetic operators apply to numeric types and yield a result of the same type as the first operand. The four standard arithmetic operators ("+", "-", "*", "/") apply to both integer and floating point types, while "+" also applies to strings and arrays; all other arithmetic operators apply to integer types only.

+    sum             integers, floats, strings, arrays
-    difference      integers, floats
*    product         integers, floats
/    quotient        integers, floats
%    remainder       integers

&    bitwise and     integers
|    bitwise or      integers
^    bitwise xor     integers

<<   left shift      integer << unsigned integer
>>   right shift     integer >> unsigned integer

s := "hi" + string(c)

For integer values, "/" and "%" satisfy the following relationship:

(a / b) * b + a % b == a

(a / b) is "truncated towards zero".

 x     y     x / y     x % y
 5     3       1         2
-5     3      -1        -2
 5    -3      -1         2
-5    -3       1        -2

 x     x / 4     x % 4     x >> 2     x & 3
 11      2         3         2          3
-11     -2        -3        -3          1

+x                          is 0 + x
-x    negation              is 0 - x
^x    bitwise complement    is m ^ x  with m = "all bits set to 1"

Integer overflow

For signed integers, the operations "+", "-", "*", and "<<" may legally overflow and the resulting value exists and is deterministically defined by the signed integer representation, the operation, and its operands. No exception is raised as a result of overflow. As a consequence, a compiler may not optimize code under the assumption that overflow does not occur. For instance, it may not assume that "x < x + 1" is always true.

Comparison operators

==    equal
!=    not equal
<     less
<=    less or equal
>     greater
>=    greater or equal

Booleans are equal if they are either both "true" or both "false".

Pointers are equal if they point to the same value.

Interface, slice, map, and channel types can be compared for equality according to the rules specified in the section on §Interface types, §Slice types, §Map types, and §Channel types, respectively.

Logical operators

&&    conditional and    p && q  is  "if p then q else false"
||    conditional or     p || q  is  "if p then true else q"
!     not                !p      is  "not p"

Address operators

TODO: This text needs to be cleaned up and go elsewhere, there are no address operators involved.

Methods are a form of function, and a method ``value'' has a function type. Consider the type T with method M:

type T struct {
	a int;
}
func (tp *T) M(a int) int;
var t *T;

t.M

func (t *T, a int) int

var f func (t *T, a int) int;
f = t.M;
x := f(t, 7);

t.M(args)

(t.M)(t, args)

If T is an interface type, the expression t.M does not determine which underlying type's M is called until the point of the call itself. Thus given T1 and T2, both implementing interface I with method M, the sequence

var t1 *T1;
var t2 *T2;
var i I = t1;
m := i.M;
m(t2, 7);

func (recv I, a int) {
	recv.M(a);
}

TODO: Document implementation restriction: It is illegal to take the address of a result parameter (e.g.: func f() (x int, p *int) { return 2, &x }). (TBD: is it an implementation restriction or fact?)

Communication operators

Here the term "channel" means "variable of type chan".

The built-in function "make" makes a new channel value:

ch := make(chan int)

sync_chan := make(chan int)
buffered_chan := make(chan int, 10)

ch <- 3

If the send operation appears in an expression context, the value of the expression is a boolean and the operation is non-blocking. The value of the boolean reports true if the communication succeeded, false if it did not. These two examples are equivalent:

ok := ch <- 3;
if ok { print("sent") } else { print("not sent") }

if ch <- 3 { print("sent") } else { print("not sent") }

TODO: Adjust the above depending on how we rule on the ok semantics. For instance, does the sent expression get evaluated if ok is false?

The receive operation uses the prefix unary operator "<-". The value of the expression is the value received:

<-ch

v1 := <-ch
v2 = <-ch
f(<-ch)

<-strobe  // wait until clock pulse

x, ok = <-ch;  // or: x, ok := <-ch

Constant expressions

len(a)		if a is an array (as opposed to an array slice)

Constant expressions can be evaluated at compile time.

Statements

Statement =
	Declaration | LabelDecl | EmptyStat |
	SimpleStat | GoStat | ReturnStat | BreakStat | ContinueStat | GotoStat |
	FallthroughStat | Block | IfStat | SwitchStat | SelectStat | ForStat |
	DeferStat .

SimpleStat =
	ExpressionStat | IncDecStat | Assignment | SimpleVarDecl .

StatementList = Statement { OptSemicolon Statement } .

A semicolon may be omitted immediately following:

• a closing parenthesis ")" ending a list of declarations (§Declarations and scope rules)
• a closing brace "}" ending a type declaration (§Type declarations)
• a closing brace "}" ending a block (including switch and select statements)
• a label declaration (§Label declarations)

Empty statements

EmptyStat = .

Expression statements

ExpressionStat = Expression .

f(x+y)

IncDec statements

IncDecStat = Expression ( "++" | "--" ) .

IncDec statement    Assignment
x++                 x += 1
x--                 x -= 1

Note that increment and decrement are statements, not expressions. For instance, "x++" cannot be used as an operand in an expression.

Assignments

Assignment = ExpressionList assign_op ExpressionList .

assign_op = [ add_op | mul_op ] "=" .

x = 1
*p = f()
a[i] = 23
k = <-ch

j <<= 2

v1, v2, v3 = e1, e2, e3

a, b = b, a

x, y = f()

value, present = map_var[key]

map_var[key] = value, false

If statements

IfStat = "if" [ [ SimpleStat ] ";" ] [ Expression ] Block [ "else" Statement ] .

if x > 0 {
	return true;
}

if x := f(); x < y {
	return x;
} else if x > z {
	return z;
} else {
	return y;
}

Switch statements

SwitchStat = "switch" [ [ SimpleStat ] ";" ] [ Expression ] "{" { CaseClause } "}" .
CaseClause = SwitchCase ":" [ StatementList ] .
SwitchCase = "case" ExpressionList | "default" .

Each case clause effectively acts as a block for scoping purposes ($Declarations and scope rules).

The expressions do not need to be constants. They will be evaluated top to bottom until the first successful non-default case is reached. If none matches and there is a default case, the statements of the default case are executed.

switch tag {
default: s3()
case 0, 1: s1()
case 2: s2()
}

switch x := f(); true {
case x < 0: return -x
default: return x
}

switch a {
case 1:
	b();
	fallthrough
case 2:
	c();
}

switch {
case x < y: f1();
case x < z: f2();
case x == 4: f3();
}

For statements

ForStat = "for" [ Condition | ForClause | RangeClause ] Block .
Condition = Expression .

for a < b {
	a *= 2
}

ForClause = [ InitStat ] ";" [ Condition ] ";" [ PostStat ] .
InitStat = SimpleStat .
PostStat = SimpleStat .

for i := 0; i < 10; i++ {
	f(i)
}

The init and post statement as well as the condition may be omitted; however if either the init or post statement are present, the separating semicolons must be present. If the condition is absent, it is equivalent to "true". The following statements are equivalent:

for ; cond ; { S() }    is the same as    for cond { S() }
for true { S() }        is the same as    for      { S() }

RangeClause = IdentifierList ( "=" | ":=" ) "range" Expression .

The iteration variables may be declared by the range clause (":="), in which case their scope ends at the end of the for statement block ($Declarations and scope rules, Rule 3). In this case their types are the array index and element, or the map key and value types, respectively.

var a [10]string;
m := map[string]int("mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6);

for i, s := range a {
	// type of i is int
	// type of s is string
	// s == a[i]
	g(i, s)
}

var key string;
var val interface {};  // value type of m is assignment-compatible to val
for key, value = range m {
	h(key, value)
}
// key == last map key encountered in iteration
// val == map[key]

Go statements

GoStat = "go" Expression .

go Server()
go func(ch chan <- bool) { for { sleep(10); ch <- true; }} (c)

Select statements

SelectStat = "select" "{" { CommClause } "}" .
CommClause = CommCase ":" [ StatementList ] .
CommCase = "case" ( SendExpr | RecvExpr) | "default" .
SendExpr =  Expression "<-" Expression .
RecvExpr =  [ Expression ( "=" | ":=" ) ] "<-" Expression .

For all the send and receive expressions in the select statement, the channel expression is evaluated. Any values that appear on the right hand side of send expressions are also evaluated. If any of the resulting channels can proceed, one is chosen and the corresponding communication and statements are evaluated. Otherwise, if there is a default case, that executes; if not, the statement blocks until one of the communications can complete. The channels and send expressions are not re-evaluated. A channel pointer may be nil, which is equivalent to that case not being present in the select statement.

Since all the channels and send expressions are evaluated, any side effects in that evaluation will occur for all the communications in the select.

If the channel sends or receives an interface type, its communication can proceed only if the type of the communication clause matches that of the dynamic value to be exchanged.

If multiple cases can proceed, a uniform fair choice is made regarding which single communication will execute.

The receive case may declare a new variable (via a ":=" assignment). The scope of such variables begins immediately after the variable identifier and ends at the end of the respective "select" case (that is, before the next "case", "default", or closing brace).

var c, c1, c2 chan int;
var i1, i2 int;
select {
case i1 = <-c1:
	print("received ", i1, " from c1\n");
case c2 <- i2:
	print("sent ", i2, " to c2\n");
default:
	print("no communication\n");
}

for {  // send random sequence of bits to c
	select {
	case c <- 0:  // note: no statement, no fallthrough, no folding of cases
	case c <- 1:
	}
}

var ca chan interface {};
var i int;
var f float;
select {
case i = <-ca:
	print("received int ", i, " from ca\n");
case f = <-ca:
	print("received float ", f, " from ca\n");
}

Return statements

ReturnStat = "return" [ ExpressionList ] .

func simple_f() int {
	return 2;
}

func complex_f1() (re float, im float) {
	return -7.0, -4.0;
}

func complex_f2() (re float, im float) {
	re = 7.0;
	im = 4.0;
	return;
}

Break statements

BreakStat = "break" [ identifier ].

L: for i < n {
	switch i {
	case 5: break L
	}
}

Continue statements

ContinueStat = "continue" [ identifier ].

Label declarations

LabelDecl = identifier ":" .

Error:

Goto statements

GotoStat = "goto" identifier .

goto Error

goto L;  // BAD
v := 3;
L:

Fallthrough statements

FallthroughStat = "fallthrough" .

Defer statements

DeferStat = "defer" Expression .

lock(l);
defer unlock(l);  // unlocking happens before surrounding function returns

// prints 3 2 1 0 before surrounding function returns
for i := 0; i <= 3; i++ {
	defer fmt.Print(i);
}

Function declarations

FunctionDecl = "func" identifier Signature [ Block ] .

func min(x int, y int) int {
	if x < y {
		return x;
	}
	return y;
}

func MakeNode(left, right *Node) *Node

Method declarations

MethodDecl = "func" Receiver identifier Signature [ Block ] .
Receiver = "(" [ identifier ] [ "*" ] TypeName ")" .

func (p *Point) Length() float {
	return Math.sqrt(p.x * p.x + p.y * p.y);
}

func (p *Point) Scale(factor float) {
	p.x = p.x * factor;
	p.y = p.y * factor;
}

Predeclared functions

• cap
• convert
• len
• make
• new
• panic
• panicln
• print
• println
• typeof

Length and capacity

Call      Argument type        Result

len(s)    string, *string      string length (in bytes)
		  [n]T, *[n]T          array length (== n)
		  []T, *[]T            slice length
		  map[K]T, *map[K]T    map length
		  chan T               number of elements in channel buffer

cap(s)    []T, *[]T            capacity of s
		  map[K]T, *map[K]T    capacity of s
		  chan T               channel buffer capacity

The type of the result is always "int" and the implementation guarantees that the result always fits into an "int".

The capacity of a slice or map is the number of elements for which there is space allocated in the underlying array (for a slice) or map. For a slice "s", at any time the following relationship holds:

0 <= len(s) <= cap(s)

Conversions

T(value)

The following conversion rules apply:

1) Between integer types. If the value is a signed quantity, it is sign extended to implicit infinite precision; otherwise it is zero extended. It is then truncated to fit in the result type size. For example, uint32(int8(0xFF)) is 0xFFFFFFFF. The conversion always yields a valid value; there is no signal for overflow.

2) Between integer and floating point types, or between floating point types. To avoid overdefining the properties of the conversion, for now it is defined as a ``best effort'' conversion. The conversion always succeeds but the value may be a NaN or other problematic result. TODO: clarify?

3) Strings permit two special conversions.

3a) Converting an integer value yields a string containing the UTF-8 representation of the integer.

string(0x65e5)  // "\u65e5"

string([]byte('h', 'e', 'l', 'l', 'o')) // "hello"

TODO: Do we allow interface/ptr conversions in this form or do they have to be written as type guards? (§Type guards)

Allocation

new(T)

type S struct { a int; b float }
new(S)

TODO Once this has become clearer, connect new() and make() (new() may be explained by make() and vice versa).

Making slices, maps, and channels

make(T [, optional list of expressions])

make(map[string] int)

s := make([]int, 10, 100);        # slice with len(s) == 10, cap(s) == 100
c := make(chan int, 10);          # channel with a buffer size of 10
m := make(map[string] int, 100);  # map with initial space for 100 elements

Packages

Package = PackageClause { ImportDecl [ ";" ] } { Declaration [ ";" ] } .

Every source file identifies the package to which it belongs. The file must begin with a package clause.

PackageClause = "package" PackageName .

package Math

ImportDecl = "import" ( ImportSpec | "(" [ ImportSpecList ] ")" ) .
ImportSpecList = ImportSpec { ";" ImportSpec } [ ";" ] .
ImportSpec = [ "." | PackageName ] PackageFileName .
PackageFileName = StringLit .

In the following discussion, assume we have a package in the file "/lib/math", called package "math", which exports the identifiers "Sin" and "Cos" denoting the respective trigonometric functions.

In the general form, with an explicit package name, the import statement declares that package name as an identifier whose contents are the exported elements of the imported package. For instance, after

import M "/lib/math"

In its simplest form, with no package name, the import statement implicitly uses the imported package name itself as the local package name. After

import "/lib/math"

Finally, if instead of a package name the import statement uses an explicit period, the contents of the imported package are added to the current package. After

import . "/lib/math"

Here is a complete example Go package that implements a concurrent prime sieve:

package main

// Send the sequence 2, 3, 4, ... to channel 'ch'.
func generate(ch chan <- int) {
	for i := 2; ; i++ {
		ch <- i  // Send 'i' to channel 'ch'.
	}
}

// Copy the values from channel 'in' to channel 'out',
// removing those divisible by 'prime'.
func filter(in chan <- int, out *<-chan int, prime int) {
	for {
		i := <-in;  // Receive value of new variable 'i' from 'in'.
		if i % prime != 0 {
			out <- i  // Send 'i' to channel 'out'.
		}
	}
}

// The prime sieve: Daisy-chain filter processes together.
func sieve() {
	ch := make(chan int);  // Create a new channel.
	go generate(ch);  // Start generate() as a subprocess.
	for {
		prime := <-ch;
		print(prime, "\n");
		ch1 := make(chan int);
		go filter(ch, ch1, prime);
		ch = ch1
	}
}

func main() {
	sieve()
}

Program initialization and execution

These two simple declarations are equivalent:

var i int;
var i int = 0;

type T struct { i int; f float; next *T };
t := new(T);

t.i == 0
t.f == 0.0
t.next == nil

Initialization code may contain "go" statements, but the functions they invoke do not begin execution until initialization of the entire program is complete. Therefore, all initialization code is run in a single thread of execution.

Furthermore, an "init()" function cannot be referred to from anywhere in a program. In particular, "init()" cannot be called explicitly, nor can a pointer to "init" be assigned to a function variable).

If a package has imports, the imported packages are initialized before initializing the package itself. If multiple packages import a package P, P will be initialized only once.

The importing of packages, by construction, guarantees that there can be no cyclic dependencies in initialization.

A complete program, possibly created by linking multiple packages, must have one package called main, with a function

func main() { ...  }

Program execution begins by initializing the main package and then invoking main.main().

When main.main() returns, the program exits.

Systems considerations

Package unsafe

The package "unsafe" provides (at least) the following package interface:

package unsafe

const Maxalign int

type Pointer *any

func Alignof(variable any) int
func Offsetof(selector any) int
func Sizeof(variable any) int

Any pointer type as well as values of type "uintptr" can be converted into an "unsafe.Pointer" and vice versa.

The function "Sizeof" takes an expression denoting a variable of any type and returns the size of the variable in bytes.

The function "Offsetof" takes a selector (§Selectors) denoting a struct field of any type and returns the field offset in bytes relative to the struct address. Specifically, the following condition is satisfied for a struct "s" with field "f":

uintptr(unsafe.Pointer(&s)) + uintptr(unsafe.Offsetof(s.f)) ==
uintptr(unsafe.Pointer(&s.f))

The function "Alignof" takes an expression denoting a variable of any type and returns the alignment of the variable in bytes. The following alignment condition is satisfied for a variable "x":

uintptr(unsafe.Pointer(&x)) % uintptr(unsafe.Alignof(x)) == 0

The results of calls to "unsafe.Alignof", "unsafe.Offsetof", and "unsafe.Sizeof" are compile-time constants.

Size and alignment guarantees

type                      size in bytes

byte, uint8, int8         1
uint16, int16             2
uint32, int32, float32    4
uint64, int64, float64    8

A Go compiler guarantees the following minimal alignment properties:

1. For a variable "x" of any type: "1 <= unsafe.Alignof(x) <= unsafe.Maxalign".
2. For a variable "x" of arithmetic type: "unsafe.Alignof(x)" is the smaller of "unsafe.Sizeof(x)" and "unsafe.Maxalign", but at least 1.
3. For a variable "x" of struct type: "unsafe.Alignof(x)" is the largest of all the values "unsafe.Alignof(x.f)" for each field "f" of x, but at least 1.
4. For a variable "x" of array type: "unsafe.Alignof(x)" is the same as unsafe.Alignof(x[0]), but at least 1.

Differences between this doc and implementation - TODO

Current implementation accepts only ASCII digits for digits; doc says Unicode.