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.
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 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.
The following terms are used to denote specific Unicode character classes:
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" .
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 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 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 } .
a _x9 ThisVariableIsExported αβSome identifiers are predeclared (§Predeclared identifiers).
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
The following character sequences represent operators, delimiters, and other special tokens:
+ & += &= && == != ( )
- | -= |= || < <= [ ]
* ^ *= ^= <- > >= { }
/ << /= <<= ++ = := , ;
% >> %= >>= -- ! ... . :
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
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
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?
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 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.
A declaration binds an identifier to a language entity such as a variable or function and specifies properties such as its type. Every identifier in a program must be declared.
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, but inner blocks can declare a new entity with the same identifier, in which case the scope created by the outer declaration excludes that created by the inner.
There are levels of scoping in effect before each source file is compiled. In order from outermost to innermost:
The scope of an identifier depends on the entity declared:
if , for,
or switch statement, the
innermost surrounding block is the block associated
with that statement.The following identifiers are implicitly declared in the outermost scope:
Basic types: bool byte float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 Platform-specific convenience types: float int uint uintptr Constants: true false iota nil Functions: cap convert len make new panic panicln print println typeof (TODO: typeof??) Packages: sys unsafe (TODO: does sys endure?)
By default, identifiers are visible only within the package in which they are declared. Some identifiers are exported and can be referenced using qualified identifiers in other packages (§Qualified identifiers). If an identifier satisfies these two conditions:
it will be exported automatically.
A constant declaration binds a list of identifiers (the names of the constants) to the values of a list of constant expressions (§Constant expressions). The number of identifiers must be equal to the number of expressions, and the nth identifier on the left is bound to value of the nth expression on the right.
ConstDecl = "const" ( ConstSpec | "(" [ ConstSpecList ] ")" ) .
ConstSpecList = ConstSpec { ";" ConstSpec } [ ";" ] .
ConstSpec = IdentifierList [ CompleteType ] [ "=" ExpressionList ] .
IdentifierList = identifier { "," identifier } .
ExpressionList = Expression { "," Expression } .
CompleteType = Type .
If the type (CompleteType) is omitted, the constants take the individual types of the corresponding expressions, which may be ``ideal integer'' or ``ideal float'' (§Ideal number). If the type is present, all constants take the type specified, and the types of all the expressions must be assignment-compatible with that type.
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
Within a parenthesized const declaration list the
expression list may be omitted from any but the first declaration.
Such an empty list is equivalent to the textual substitution of the
first preceding non-empty expression list. Omitting the list of
expressions is therefore equivalent to repeating the previous list.
The number of identifiers must be equal to the number of expressions
in the previous list. Together with the iota constant generator
(§Iota) this mechanism permits light-weight declaration of sequential values:
const ( Sunday = iota; Monday; Tuesday; Wednesday; Thursday; Friday; Partyday; numberOfDays; // this constant is not exported )
Within a constant declaration, the predeclared pseudo-constant
iota represents successive integers. It is reset to 0
whenever the reserved word const appears in the source
and increments with each semicolon. It can be used to construct a
set of related constants:
const ( // iota is reset to 0 c0 = iota; // c0 == 0 c1 = iota; // c1 == 1 c2 = iota // c2 == 2 ) 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)
Within an ExpressionList, the value of each iota is the same because
it is only incremented at a semicolon:
const ( bit0, mask0 = 1 << iota, 1 << iota - 1; // bit0 == 1, mask0 == 0 bit1, mask1; // bit1 == 2, mask1 == 1 bit2, mask2; // bit2 == 4, mask2 == 3 )
This last example exploits the implicit repetition of the last non-empty expression list.
A type declaration binds an identifier, the type name, to a new type. TODO: what exactly is a "new type"?
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
}
A variable declaration creates a variable, binds an identifier to it and gives it a type and optionally an initial value. The variable type must be a complete type (§Types).
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 there are expressions, their number must be equal to the number of identifiers, and the nth variable is initialized to the value of the nth expression. Otherwise, each variable is initialized to the zero of the type (§Program initialization and execution). The expressions can be general expressions; they need not be constants.
Either the type or the expression list must be present. If the type is present, it sets the type of each variable and the expressions (if any) must be assignment-compatible to that type. If the type is absent, the variables take the types of the corresponding expressions.
If the type is absent and the corresponding expression is a constant
expression of ideal integer or ideal float type, the type of the
declared variable is int or float
respectively:
var i = 0 // i has type int var f = 3.1415 // f has type float
SimpleVarDecl = IdentifierList ":=" ExpressionList .and is shorthand for the declaration syntax
"var" IdentifierList = ExpressionList .
i, j := 0, 10;
f := func() int { return 7; }
ch := new(chan int);
Unlike regular variable declarations, short variable declarations can be used, by analogy with tuple assignment (§Assignments), to receive the individual elements of a multi-valued expression such as a call to a multi-valued function. In this form, the ExpressionLIst must be a single such multi-valued expression, the number of identifiers must equal the number of values, and the declared variables will be assigned the corresponding values.
count, error := os.Close(fd); // os.Close() returns two values
Short variable declarations may appear only inside functions.
In some contexts such as the initializers for if,
for, or switch statements,
they can be used to declare local temporary variables (§Statements).
A function declaration binds an identifier to a function (§Function types).
FunctionDecl = "func" identifier Signature [ Block ] .
func min(x int, y int) int {
if x < y {
return x;
}
return y;
}
A function must be declared or forward-declared before it can be invoked (§Forward declarations). Implementation restriction: Functions can only be declared at the package level.
A method declaration binds an identifier to a method, which is a function with a receiver.
MethodDecl = "func" Receiver identifier Signature [ Block ] .
Receiver = "(" [ identifier ] [ "*" ] TypeName ")" .
The receiver type must be a type name or a pointer to a type name, and that name is called the receiver base type or just base type. The base type must not be a pointer type and must be declared in the same source file as the method. The method is said to be bound to the base type and is visible only within selectors for that type (§Type declarations, §Selectors).
All methods bound to a base type must have the same receiver type,
either all pointers to the base type or all the base type itself.
Given type Point, the declarations
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;
}
bind the methods Length and Scale
to the base type Point.
If the receiver's value is not referenced inside the the body of the method, its identifier may be omitted in the declaration. The same applies in general to parameters of functions and methods.
Methods can be declared only after their base type is declared or forward-declared, and invoked only after their own declaration or forward-declaration (§Forward declarations). Implementation restriction: They can only be declared at package level.
Mutually-recursive types struct or interface types require that one be forward declared so that it may be named in the other. A forward declaration of a type omits the block containing the fields or methods of the type.
type List struct // forward declaration of List
type Item struct {
value int;
next *List;
}
type List struct {
head, tail *Item
}
A forward-declared type is incomplete (§Types) until it is fully declared. The full declaration must follow before the end of the block containing the forward declaration.
Functions and methods may similarly be forward-declared by omitting their body.
func F(a int) int // forward declaration of F
func G(a, b int) int {
return F(a) + F(b)
}
func F(a int) int {
if a <= 0 { return 0 }
return G(a-1, b+1)
}
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 .
Some types are predeclared and denoted by their type names; these are called
``basic types''. Generally (except for strings) they are not composed of more
elementary types; instead they model elementary machine data types.
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. The ``interface'' of a type is the set of methods bound to it (§Method declarations). The interface of a pointer type is the interface of the pointer base type (§Pointer types). All types have an interface; if they have no methods associated with them, their interface is called the ``empty'' interface.
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).
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 numbersInteger types are represented in the usual binary format; the value of an n-bit integer is n bits wide. A negative signed integer is represented as the two's complement of its absolute value. Additionally, Go declares a set of platform-specific numeric types for convenience:
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 valueFor instance, int might have the same size as int32 on a 32-bit architecture, or int64 on a 64-bit architecture.
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.
The "string" type represents the set of string values (strings). Strings behave like arrays of bytes, with the following properties:
a [3]byte; a[0] = 'a'; a[1] = 'b'; a[2] = 'c'; string(a) == "abc";
ArrayType = "[" ArrayLength "]" ElementType . ArrayLength = Expression . ElementType = CompleteType .The array length and its value are part of the array type. The array length must be a constant expression (§Constant expressions) that evaluates to an integer value >= 0.
The number of elements of an array "a" can be discovered using the built-in function
len(a)The length of arrays is known at compile-time, and the result of a call to "len(a)" is a compile-time constant.
[32]byte
[2*N] struct { x, y int32 }
[1000]*float64
Assignment compatibility: Arrays can be assigned to variables of equal type
and to slice variables with equal element type. When assigning to a slice
variable, the array is not copied but a slice comprising the entire array
is created.
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 may contain ``anonymous fields'', which are declared with a type
but no explicit field identifier. An anonymous field type must be specified as
a type name "T", or as a pointer to a type name ``*T'', and T itself may not be
a pointer or interface type. The unqualified type name acts as the field identifier.
// 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;
}
The unqualified type name of an anonymous field must not conflict with the
field identifier (or unqualified type name for an anonymous field) of any
other field within the struct. The following declaration is illegal:
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
}
Fields and methods (§Method declarations) of an anonymous field become directly
accessible as fields and methods of the struct without the need to provide the
type name of the respective anonymous field (§Selectors).
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";
}
Assignment compatibility: Structs are assignment compatible to variables of
equal type only.
PointerType = "*" BaseType . BaseType = Type .
*int map[string] chanThe pointer base type may be denoted by an identifier referring to an incomplete type (§Types), possibly declared via a forward declaration. This allows the construction of recursive and mutually recursive types such as:
type S struct { s *S }
type S2 struct // forward declaration of S2
type S1 struct { s2 *S2 }
type S2 struct { s1 *S1 }
Assignment compatibility: A pointer is assignment compatible to a variable
of pointer type, only if both types are equal.
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.
FunctionType = "func" Signature .
Signature = "(" [ ParameterList ] ")" [ Result ] .
ParameterList = ParameterDecl { "," ParameterDecl } .
ParameterDecl = [ IdentifierList ] ( Type | "..." ) .
Result = Type | "(" ParameterList ")" .
In ParameterList, the parameter names (IdentifierList) either must all be
present, or all be absent. If the parameters are named, each name stands
for one parameter of the specified type. If the parameters are unnamed, each
type stands for one parameter of that type.
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)If the result type of a function is itself a function type, the result type must be parenthesized to resolve a parsing ambiguity:
func (n int) (func (p* T))Assignment compatibility: A function can be assigned to a function variable only if both function types are equal.
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.
InterfaceType = "interface" [ "{" [ MethodSpecList ] "}" ] .
MethodSpecList = MethodSpec { ";" MethodSpec } [ ";" ] .
MethodSpec = IdentifierList Signature | TypeName .
// An interface specifying a basic File type.
interface {
Read, Write (b Buffer) bool;
Close ();
}
Any type (including interface types) whose interface has, possibly as a
subset, the complete set of methods of an interface I is said to implement
interface I. For instance, if two types S1 and S2 have the methods
func (p T) Read(b Buffer) bool { return ... }
func (p T) Write(b Buffer) bool { return ... }
func (p T) Close() { ... }
(where T stands for either S1 or S2) then the File interface is
implemented by both S1 and S2, regardless of what other methods
S1 and S2 may have or share.
All types implement the empty interface:
interface {}
In general, a type implements an arbitrary number of interfaces.
For instance, consider the interface
type Lock interface {
Lock, Unlock ();
}
If S1 and S2 also implement
func (p T) Lock() { ... }
func (p T) Unlock() { ... }
they implement the Lock interface as well as the File interface.
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();
}
Forward declaration:
A interface type consisting of only the reserved word "interface" may be used in
a type declaration; it declares an incomplete interface type (§Type declarations).
This allows the construction of mutually recursive types such as:
type T2 interface
type T1 interface {
foo(T2) int;
}
type T2 interface {
bar(T1) int;
}
Assignment compatibility: A value can be assigned to an interface variable
if the static type of the value implements the interface or if the value is "nil".
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.
SliceType = "[" "]" ElementType .Syntactically and semantically, arrays and slices look and behave very similarly, but with one important difference: A slice is a descriptor of an array segment; in particular, different variables of a slice type may refer to different (and possibly overlapping) segments of the same underlying array. Thus, with respect to the underlying array, slices behave like references. In contrast, two different variables of array type always denote two different arrays.
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)and the following relationship between "len()" and "cap()" holds:
0 <= len(a) <= cap(a)The value of an uninitialized slice is "nil", and its length and capacity are 0. A new, initialized slice value for a given element type T is made using the built-in function "make", which takes a slice type and parameters specifying the length and optionally the capacity:
make([]T, length) make([]T, length, capacity)The "make()" call allocates a new underlying array to which the returned slice value refers. More precisely, calling "make"
make([]T, length, capacity)is effectively the same as allocating an array and slicing it
new([capacity]T)[0 : length]Assignment compatibility: Slices are assignment compatible to variables of the same type.
Indexing: Given a (pointer to) a slice variable "a", a slice element is specified with an index operation:
a[i]This denotes the slice element at index "i". "i" must be within bounds, that is "0 <= i < len(a)".
Slicing: Given a a slice variable "a", a sub-slice is created with a slice operation:
a[i : j]This creates the sub-slice consisting of the elements "a[i]" through "a[j - 1]" (that is, excluding "a[j]"). The values "i" and "j" must satisfy the condition "0 <= i <= j <= cap(a)". The length of the new slice is "j - i". The capacity of the slice is "cap(a) - i"; thus if "i" is 0, the slice capacity does not change as a result of a slice operation. The type of a sub-slice is the same as the type of the slice. Unlike the capacity, the length of a sub-slice may be larger than the length of the original slice.
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).
MapType = "map" "[" KeyType "]" ValueType . KeyType = CompleteType . ValueType = CompleteType .The comparison operators "==" and "!=" (§Comparison operators) must be defined for operands of the key type; thus the key type must be a basic, pointer, interface, or channel type. If the key type is an interface type, the dynamic key types must support these comparison operators. In this case, inserting a map value with a key that does not support testing for equality is a run-time error.
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 {}
The length of a map "m" can be discovered using the built-in function
len(m)The value of an uninitialized map is "nil". A new, empty map value for given map type M is made using the built-in function "make" which takes the map type and an optional capacity as arguments:
my_map := make(M, 100);The map capacity is an allocation hint for more efficient incremental growth of the map.
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).
ChannelType = Channel | SendChannel | RecvChannel . Channel = "chan" ValueType . SendChannel = "chan" "<-" ValueType . RecvChannel = "<-" "chan" ValueType .Upon creation, a channel can be used both to send and to receive. By conversion or assignment, a channel may be constrained only to send or to receive. This constraint is called a channel's ``direction''; either bi-directional (unconstrained), send, or receive.
chan T // can send and receive values of type T chan <- float // can only be used to send floats <-chan int // can only receive intsThe value of an uninitialized channel is "nil". A new, initialized channel value for a given element type T is made using the built-in function "make", which takes the channel type and an optional capacity as arguments:
my_chan = make(chan int, 100);The capacity sets the size of the buffer in the communication channel. If the capacity is greater than zero, the channel is asynchronous and, provided the buffer is not full, sends can succeed without blocking. If the capacity is zero, the communication succeeds only when both a sender and receiver are ready.
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).
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:
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:
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
)
these are some types that are equal
T0 and T0
T0 and []string
T2 and T3
T4 and T5
T3 and struct { a int; int }
and these are some types that are identical
T0 and T0
[]int and []int
struct { a, b *T5 } and struct { a, b *T5 }
As an example, "T0" and "T1" are equal but not identical because they have
different declarations.
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.
Operand = Literal | QualifiedIdent | "(" Expression ")" .
Literal = BasicLit | CompositeLit | FunctionLit .
BasicLit = int_lit | float_lit | char_lit | StringLit .
StringLit = string_lit { string_lit } .
TODO(gri) expand this section.
QualifiedIdent = { PackageName "." } identifier .
PackageName = identifier .
CompositeLit = LiteralType "(" [ ( ExpressionList | ExprPairList ) [ "," ] ] ")" .
LiteralType = Type | "[" "..." "]" ElementType .
ExprPairList = ExprPair { "," ExprPair } .
ExprPair = Expression ":" Expression .
The LiteralType must be an struct, array, slice, or map type.
The types of the expressions must match the respective field, element, and
key types of the LiteralType; there is no automatic type conversion.
Composite literals are values of the type specified by LiteralType; that is
a new value is created every time the literal is evaluated. To get
a pointer to the literal, the address operator "&" must be used.
Given
type Rat struct { num, den int }
type Num struct { r Rat; f float; s string }
one can write
pi := Num(Rat(22, 7), 3.14159, "pi");The length of an array literal is the length specified in the LiteralType. If fewer elements than the length are provided in the literal, the missing elements are set to the appropriate zero value for the array element type. It is an error to provide more elements than specified in LiteralType. The notation "..." may be used in place of the length expression to denote a length equal to the number of elements in the literal.
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
A slice literal is a slice describing the entire underlying array literal.
Thus, the length and capacity of a slice literal is the number of elements
provided in the literal. A slice literal of the form
[]T(x1, x2, ... xn)is essentially a shortcut for a slice operation applied to an array literal:
[n]T(x1, x2, ... xn)[0 : n]Map literals are similar except the elements of the expression list are key-value pairs separated by a colon:
m := map[string]int("good": 0, "bad": 1, "indifferent": 7);
TODO: Consider adding helper syntax for nested composites
(avoids repeating types but complicates the spec needlessly.)
FunctionLit = "func" Signature Block .
Block = "{" [ StatementList ] "}" .
The type of a function literal is the function type specified.
func (a, b int, z float) bool { return a*b < int(z); }
A function literal can be assigned to a variable of the
corresponding function type, or invoked directly.
f := func(x, y int) int { return x + y; }
func(ch chan int) { ch <- ACK; } (reply_chan)
Function literals are "closures": they may refer to variables
defined in a surrounding function. Those variables are then shared between
the surrounding function and the function literal, and they survive as long
as they are accessible in any way.
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()
x.fdenotes the field or method f of the value denoted by x (or of *x if x is of pointer type). The identifier f is called the (field or method) ``selector''.
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
one can write:
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).M0TODO: Specify what happens to receivers.
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):
For a of type *M, where M is a map type (§Map types):
TODO: Need to expand map rules for assignments of the form v, ok = m[k].
a := [4]int(1, 2, 3, 4); s := a[1:3];the slice "s" has type "[]int", length 2, and elements
s[0] == 2 s[1] == 3The index values in the slice must be in bounds for the original array (or string) and the slice length must be non-negative.
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).
x.(T)asserts that the value stored in "x" is an element of type "T" (§Types). The notation ".(T)" is called a ``type guard'', and "x.(T)" is called a ``guarded expression''. The type of "x" must be an interface type.
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)the result of the guarded expression is a pair of values with types "(T, bool)". If the type guard succeeds, the expression returns the pair "(x.(T), true)"; that is, the value stored in "x" (of type "T") is assigned to "v", and "ok" is set to true. If the type guard fails, the value in "v" is set to the initial value for the type of "v" (§Program initialization and execution), and "ok" is set to false. No run-time exception occurs in this case.
TODO add examples
p()to call the function.
A method is called using the notation
receiver.method()where receiver is a value of the receiver type of the method.
For instance, given a *Point variable pt, one may call
pt.Scale(3.5)The type of a method is the type of a function with the receiver as first argument. For instance, the method "Scale" has type
(p *Point, factor float)However, a function declared this way is not a method.
There is no distinct method type and there are no method literals.
*struct {
arg(0) typeof(arg(0));
arg(1) typeof(arg(1));
arg(2) typeof(arg(2));
...
arg(n-1) typeof(arg(n-1));
}
where the "arg(i)"'s correspond to the actual arguments passed in place
of the "..." parameter (the parameter and type names are for illustration
only). Reflection code may be used to access the struct value and its fields.
Thus, arguments provided in place of a "..." parameter are wrapped into
a corresponding struct, and a pointer to the struct is passed to the
function instead of the actual arguments.
For instance, consider the function
func f(x int, s string, f_extra ...)and the call
f(42, "foo", 3.14, true, []int(1, 2, 3))Upon invocation, the parameters "3.14", "true", and "[]int(1, 2, 3)" are wrapped into a struct and the pointer to the struct is passed to f. In f the type of parameter "f_extra" is "interface{}". The dynamic type of "f_extra" is the type of the value assigned to it upon invocation (the field names "arg0", "arg1", "arg2" are made up for illustration only, they are not accessible via reflection):
*struct {
arg0 float;
arg1 bool;
arg2 []int;
}
The values of the fields "arg0", "arg1", and "arg2" are "3.14", "true",
and "[]int(1, 2, 3)".
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 ...)as
g(x, f_extra);Inside g, the value stored in g_extra is the same as the value stored in f_extra.
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:
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 ||
Binary operators of the same precedence associate from left to right.
For instance, "x / y / z" stands for "(x / y) / z".
Examples
+x 23 + 3*x[i] x <= f() ^a >> b f() || g() x == y + 1 && <-chan_ptr > 0
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 integerStrings can be concatenated using the "+" operator (or the "+=" assignment):
s := "hi" + string(c)String addition creates a new string by copying the elements.
For integer values, "/" and "%" satisfy the following relationship:
(a / b) * b + a % b == aand
(a / b) is "truncated towards zero".Examples:
x y x / y x % y 5 3 1 2 -5 3 -1 -2 5 -3 -1 2 -5 -3 1 -2Note that if the dividend is positive and the divisor is a constant power of 2, the division may be replaced by a left shift, and computing the remainder may be replaced by a bitwise "and" operation:
x x / 4 x % 4 x >> 2 x & 3 11 2 3 2 3 -11 -2 -3 -3 1The shift operators shift the left operand by the shift count specified by the right operand. They implement arithmetic shifts if the left operand is a signed integer, and logical shifts if it is an unsigned integer. The shift count must be an unsigned integer. There is no upper limit on the shift count. It is as if the left operand is shifted "n" times by 1 for a shift count of "n". Specifically, "x << 1" is the same as "x*2"; and "x >> 1" is the same as "x/2 truncated towards negative infinity". For integer operands, the unary operators "+", "-", and "^" are defined as follows:
+x is 0 + x -x negation is 0 - x ^x bitwise complement is m ^ x with m = "all bits set to 1"
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.
== equal != not equal < less <= less or equal > greater >= greater or equalStrings are compared byte-wise (lexically).
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.
&& 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"
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;
To construct the value of method M, one writes
t.Musing the variable t (not the type T). TODO: It makes perfect sense to be able to say T.M (in fact, it makes more sense then t.M, since only the type T is needed to find the method M, i.e., its address). TBD. The expression t.M is a function value with type
func (t *T, a int) intand may be invoked only as a function, not as a method:
var f func (t *T, a int) int; f = t.M; x := f(t, 7);Note that one does not write t.f(7); taking the value of a method demotes it to a function. In general, given type T with method M and variable t of type T, the method invocation
t.M(args)is equivalent to the function call
(t.M)(t, args)TODO: should probably describe the effect of (t.m) under §Expressions if t.m denotes a method: Effect is as described above, converts into function.
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);will invoke t2.M() even though m was constructed with an expression involving t1. Effectively, the value of m is a function literal
func (recv I, a int) {
recv.M(a);
}
that is automatically created.
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?)
Here the term "channel" means "variable of type chan".
The built-in function "make" makes a new channel value:
ch := make(chan int)An optional argument to "make()" specifies a buffer size for an asynchronous channel; if absent or zero, the channel is synchronous:
sync_chan := make(chan int) buffered_chan := make(chan int, 10)The send operation uses the binary operator "<-", which operates on a channel and a value (expression):
ch <- 3In this form, the send operation is an (expression) statement that sends the value on the channel. Both the channel and the expression are evaluated before communication begins. Communication blocks until the send can proceed, at which point the value is transmitted on the channel.
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") }
In other words, if the program tests the value of a send operation,
the send is non-blocking and the value of the expression is the
success of the operation. If the program does not test the value,
the operation blocks until it succeeds.
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:
<-chThe expression blocks until a value is available, which then can be assigned to a variable or used like any other expression:
v1 := <-ch v2 = <-ch f(<-ch)If the receive expression does not save the value, the value is discarded:
<-strobe // wait until clock pulseIf a receive expression is used in a tuple assignment of the form
x, ok = <-ch; // or: x, ok := <-chthe receive operation becomes non-blocking, and the boolean variable "ok" will be set to "true" if the receive operation succeeded, and set to "false" otherwise.
Constant expressions may contain only constants, iota,
numeric literals, string literals, and
some constant-valued built-in functions such as unsafe.Sizeof
and len applied to an array.
In practice, constant expressions are those that can be evaluated at compile time.
The type of a constant expression is determined by the type of its elements. If it contains only numeric literals, its type is ``ideal integer'' or ``ideal float'' (§Ideal number). Whether it is an integer or float depends on whether the value can be represented precisely as an integer (123 vs. 1.23). The nature of the arithmetic operations within the expression depends, elementwise, on the values; for example, 3/2 is an integer division yielding 1, while 3./2. is a floating point division yielding 1.5. Thus
const x = 3./2. + 3/2;
yields a floating point constant of ideal float value 2.5 (1.5 + 1); its constituent expressions are evaluated using distinct rules for division.
Intermediate values and the constants themselves may require precision significantly larger than any concrete type in the language. The following are legal declarations:
const Huge = 1 << 100; const Four int8 = Huge >> 98;
A constant expression may appear in any context, such as assignment
to a variable of any numeric type, as long as the value of the
expression can be represented accurately in that context. 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.
Statement = Declaration | LabelDecl | EmptyStat | SimpleStat | GoStat | ReturnStat | BreakStat | ContinueStat | GotoStat | FallthroughStat | Block | IfStat | SwitchStat | SelectStat | ForStat | DeferStat . SimpleStat = ExpressionStat | IncDecStat | Assignment | SimpleVarDecl .Statements in a statement list are separated by semicolons, which can be omitted in some cases as expressed by the OptSemicolon production.
StatementList = Statement { OptSemicolon Statement } .
A semicolon may be omitted immediately following:
EmptyStat = .
ExpressionStat = Expression .
f(x+y)TODO: specify restrictions. 6g only appears to allow calls here.
IncDecStat = Expression ( "++" | "--" ) .The following assignment statements (§Assignments) are semantically equivalent:
IncDec statement Assignment x++ x += 1 x-- x -= 1Both operators apply to integer and floating point types only.
Note that increment and decrement are statements, not expressions. For instance, "x++" cannot be used as an operand in an expression.
Assignment = ExpressionList assign_op ExpressionList . assign_op = [ add_op | mul_op ] "=" .The left-hand side must be an l-value such as a variable, pointer indirection, or an array index.
x = 1 *p = f() a[i] = 23 k = <-chAs in C, arithmetic binary operators can be combined with assignments:
j <<= 2A tuple assignment assigns the individual elements of a multi-valued operation, such as function evaluation or some channel and map operations, into individual variables. For instance, a tuple assignment such as
v1, v2, v3 = e1, e2, e3assigns the expressions e1, e2, e3 to temporaries and then assigns the temporaries to the variables v1, v2, v3. Thus
a, b = b, aexchanges the values of a and b. The tuple assignment
x, y = f()calls the function f, which must return two values, and assigns them to x and y. As a special case, retrieving a value from a map, when written as a two-element tuple assignment, assign a value and a boolean. If the value is present in the map, the value is assigned and the second, boolean variable is set to true. Otherwise, the variable is unchanged, and the boolean value is set to false.
value, present = map_var[key]To delete a value from a map, use a tuple assignment with the map on the left and a false boolean expression as the second expression on the right, such as:
map_var[key] = value, falseIn assignments, the type of the expression must match the type of the left-hand side.
IfStat = "if" [ [ SimpleStat ] ";" ] [ Expression ] Block [ "else" Statement ] .
if x > 0 {
return true;
}
An "if" statement may include the declaration of a single temporary variable.
The scope of the declared variable extends to the end of the if statement, and
the variable is initialized once before the statement is entered.
if x := f(); x < y {
return x;
} else if x > z {
return z;
} else {
return y;
}
SwitchStat = "switch" [ [ SimpleStat ] ";" ] [ Expression ] "{" { CaseClause } "}" .
CaseClause = SwitchCase ":" [ StatementList ] .
SwitchCase = "case" ExpressionList | "default" .
There can be at most one default case in a switch statement. In a case clause,
the last statement only may be a fallthrough statement ($Fallthrough statement).
It indicates that the control should flow from the end of this case clause to
the first statement of the next clause.
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()
}
A switch statement may include the declaration of a single temporary variable.
The scope of the declared variable extends to the end of the switch statement, and
the variable is initialized once before the switch is entered.
switch x := f(); true {
case x < 0: return -x
default: return x
}
Cases do not fall through unless explicitly marked with a "fallthrough" statement.
switch a {
case 1:
b();
fallthrough
case 2:
c();
}
If the expression is omitted, it is equivalent to "true".
switch {
case x < y: f1();
case x < z: f2();
case x == 4: f3();
}
ForStat = "for" [ Condition | ForClause | RangeClause ] Block . Condition = Expression .In its simplest form, a for statement specifies the repeated execution of a block as long as a condition evaluates to true. The condition is evaluated before each iteration. The type of the condition expression must be boolean. If the condition is absent, it is equivalent to "true".
for a < b {
a *= 2
}
A for statement with a for clause is also controlled by its condition, but
additionally it may specify an init and post statement, such as an assignment,
an increment or decrement statement. The init statement may also be a (simple)
variable declaration; no variables can be declared in the post statement.
ForClause = [ InitStat ] ";" [ Condition ] ";" [ PostStat ] . InitStat = SimpleStat . PostStat = SimpleStat .For instance, one may declare an iteration variable in the init statement:
for i := 0; i < 10; i++ {
f(i)
}
If present, the init statement is executed once before commencing the iteration;
the post statement is executed after each execution of the statement block (and
only if the block was executed). The scope of any variable declared in the init
statement ends with the end of the for statement block ($Declarations and scope
rules, Rule 3).
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() }
Alternatively, a for statement may be controlled by a range clause. A
range clause specifies iteration through all entries of an array or map.
For each entry it first assigns the current index or key to an iteration
variable - or the current (index, element) or (key, value) pair to a pair
of iteration variables - and then executes the block. Iteration terminates
when all entries have been processed, or if the for statement is terminated
early, for instance by a break or return statement.
RangeClause = IdentifierList ( "=" | ":=" ) "range" Expression .The type of the right-hand expression in the range clause must be an array or map, or a pointer to an array or map. If it is a pointer, it must not be nil. The left-hand identifier list must contain one or two identifiers denoting the iteration variables. The first variable is set to the current array index or map key, and the second variable, if present, is set to the corresponding array element or map value. The types of the array index (int) and element, or of the map key and value respectively, must be assignment-compatible to the iteration variables.
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]
If map entries that have not yet been processed are deleted during iteration,
they will not be processed. If map entries are inserted during iteration, the
behavior is implementation-dependent. Likewise, if the range expression is a
pointer variable, the behavior of assigning to that variable is implementation-
dependent. Assigning to the iteration variables during iteration simply changes
the values of those variables for the current iteration; it does not affect any
subsequent iterations.
GoStat = "go" Expression .Unlike with a regular function call, program execution does not wait for the invoked function to complete.
go Server()
go func(ch chan <- bool) { for { sleep(10); ch <- true; }} (c)
SelectStat = "select" "{" { CommClause } "}" .
CommClause = CommCase ":" [ StatementList ] .
CommCase = "case" ( SendExpr | RecvExpr) | "default" .
SendExpr = Expression "<-" Expression .
RecvExpr = [ Expression ( "=" | ":=" ) ] "<-" Expression .
Each communication clause acts as a block for the purpose of scoping
(§Declarations and scope rules).
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");
}
TODO: Make semantics more precise.
ReturnStat = "return" [ ExpressionList ] .There are two ways to return values from a function. The first is to explicitly list the return value or values in the return statement:
func simple_f() int {
return 2;
}
A function may return multiple values.
The syntax of the return clause in that case is the same as
that of a parameter list; in particular, names must be provided for
the elements of the return value.
func complex_f1() (re float, im float) {
return -7.0, -4.0;
}
A second method to return values
is to use those names within the function as variables
to be assigned explicitly; the return statement will then provide no
values:
func complex_f2() (re float, im float) {
re = 7.0;
im = 4.0;
return;
}
BreakStat = "break" [ identifier ].If there is an identifier, it must be a label marking an enclosing for, switch, or select statement, and that is the one whose execution terminates.
L: for i < n {
switch i {
case 5: break L
}
}
ContinueStat = "continue" [ identifier ].The optional identifier is analogous to that of a break statement.
LabelDecl = identifier ":" .Example:
Error:
GotoStat = "goto" identifier .
goto ErrorExecuting the goto statement must not cause any variables to come into scope that were not already in scope at the point of the goto. For instance, this example:
goto L; // BAD v := 3; L:is erroneous because the jump to label L skips the creation of v.
FallthroughStat = "fallthrough" .
DeferStat = "defer" Expression .The expression must be a function or method call. Each time the defer statement executes, the parameters to the function call are evaluated and saved anew but the function is not invoked. Immediately before the innermost function surrounding the defer statement returns, but after its return value (if any) is evaluated, each deferred function is executed with its saved parameters. Deferred functions are executed in LIFO order.
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);
}
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 capacityTODO: confirm len() and cap() for channels
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)
T(value)where "T" is the type name of an arithmetic type or string (§Basic types), and "value" is the value of an expression which can be converted to a value of result type "T".
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"3b) Converting an array of uint8s yields a string whose successive bytes are those of the array. (Recall byte is a synonym for uint8.)
string([]byte('h', 'e', 'l', 'l', 'o')) // "hello"
There is no linguistic mechanism to convert between pointers
and integers. A library may be provided under restricted circumstances
to acccess this conversion in low-level code.
TODO: Do we allow interface/ptr conversions in this form or do they have to be written as type guards? (§Type guards)
new(T)For instance
type S struct { a int; b float }
new(S)
dynamically allocates memory for a variable of type S, initializes it
(a=0, b=0.0), and returns a value of type *S pointing to that variable.
TODO Once this has become clearer, connect new() and make() (new() may be explained by make() and vice versa).
make(T [, optional list of expressions])For instance
make(map[string] int)creates a new map value and initializes it to an empty map. The only defined parameters affect sizes for allocating slices, maps, and buffered channels:
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 elementsTODO Once this has become clearer, connect new() and make() (new() may be explained by make() and vice versa).
Package = PackageClause { ImportDecl [ ";" ] } { Declaration [ ";" ] } .
The source text following the package clause acts like a block for scoping
purposes ($Declarations and scope rules).
Every source file identifies the package to which it belongs. The file must begin with a package clause.
PackageClause = "package" PackageName . package MathA package can gain access to exported identifiers from another package through an import declaration:
ImportDecl = "import" ( ImportSpec | "(" [ ImportSpecList ] ")" ) .
ImportSpecList = ImportSpec { ";" ImportSpec } [ ";" ] .
ImportSpec = [ "." | PackageName ] PackageFileName .
PackageFileName = StringLit .
An import statement makes the exported package-level identifiers of the named
package file accessible to this package.
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"the contents of the package /lib/math can be accessed by "M.Sin", "M.Cos", etc.
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"the contents are accessible by "math.Sin", "math.Cos".
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"the contents are accessible by "Sin" and "Cos". In this instance, it is an error if the import introduces name conflicts.
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()
}
These two simple declarations are equivalent:
var i int; var i int = 0;After
type T struct { i int; f float; next *T };
t := new(T);
the following holds:
t.i == 0 t.f == 0.0 t.next == nilA package with no imports is initialized by assigning initial values to all its global variables in declaration order and then calling any init() functions defined in its source. Since a package may contain more than one source file, there may be more than one init() function, but only one per source file.
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() { ... }
defined. The function main.main() takes no arguments and returns no
value.
Program execution begins by initializing the main package and then invoking main.main().
When main.main() returns, the program exits.
unsafe
The built-in package unsafe, known to the compiler, provides facilities
for low-level programming including operations that violate the type
system. A package using unsafe must be vetted manually for type safety.
The package provides the following interface:
package unsafe const Maxalign int type Pointer *any // "any" is shorthand for any Go type; it is not a real type. func Alignof(variable any) int func Offsetof(selector any) int func Sizeof(variable any) int
Any pointer or value of type uintptr can be converted into
a 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's address. For a struct s with field f:
uintptr(unsafe.Pointer(&s)) + uintptr(unsafe.Offsetof(s.f)) == uintptr(unsafe.Pointer(&s.f))
Computer architectures may require memory addresses to be aligned;
that is, for addresses of a variable to be a multiple of a factor,
the variable's type's alignment. The function Alignof
takes an expression denoting a variable of any type and returns the
alignment of the (type of the) variable in bytes. For a variable
x:
uintptr(unsafe.Pointer(&x)) % uintptr(unsafe.Alignof(x)) == 0
The maximum alignment is given by the constant Maxalign.
It usually corresponds to the value of Sizeof(x) for
a variable x of the largest arithmetic type (8 for a
float64), but may
be smaller on systems with weaker alignment restrictions.
Calls to Alignof, Offsetof, and
Sizeof are constant expressions of type int.
type size in bytes byte, uint8, int8 1 uint16, int16 2 uint32, int32, float32 4 uint64, int64, float64 8
The following minimal alignment properties are guaranteed:
x of any type: 1 <= unsafe.Alignof(x) <= unsafe.Maxalign.
x of arithmetic type: unsafe.Alignof(x) is the smaller
of unsafe.Sizeof(x) and unsafe.Maxalign, but at least 1.
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.
x of array type: unsafe.Alignof(x) is the same as
unsafe.Alignof(x[0]), but at least 1.
Current implementation accepts only ASCII digits for digits; doc says Unicode.