.GO File Format – Expressions

Operands

Operand     = Literal | OperandName [ TypeArgs ] | "(" Expression ")" .
Literal     = BasicLit | CompositeLit | FunctionLit .
BasicLit    = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
OperandName = identifier | QualifiedIdent .
QualifiedIdent = PackageName "." identifier .

An operand is a literal, a non-blank identifier denoting a constant, variable or function (possibly qualified with a package name), or a parenthesised expression. A generic function name may be followed by type arguments. The blank identifier may appear as an operand only on the left of an assignment. A qualified identifier such as math.Sin reaches an exported name in an imported package.

Composite literals

CompositeLit = LiteralType LiteralValue .
LiteralType  = StructType | ArrayType | "[" "..." "]" ElementType |
               SliceType | MapType | TypeName [ TypeArgs ] .
LiteralValue = "{" [ ElementList [ "," ] ] "}" .
ElementList  = KeyedElement { "," KeyedElement } .
KeyedElement = [ Key ":" ] Element .
Key          = FieldName | Expression | LiteralValue .
FieldName    = identifier .
Element      = Expression | LiteralValue .

A composite literal constructs a new struct, array, slice or map value each time it is evaluated. Its type must have one of those as its underlying type; for a type parameter, every type in the type set must have the same valid underlying type. Elements must be assignable to the field, element or key types, with no extra conversion. It is an error to give two elements the same field name or constant key. An empty literal is the zero value of its type.

In a struct literal with keys, each key must be a valid field selector for a possibly promoted field of the struct (Go 1.27; earlier versions required a top-level field name). Embedded fields passed through on the way to a key must not be pointer types. A key must not name a promoted field inside an embedded struct if that struct is also given by another key. Specifying a non-exported field of a struct from another package is an error.

type Object struct{ name, color string }
type Point3D struct {
	Object
	x, y, z float64
}
type Line struct {
	Object
	p, q Point3D
}

origin := Point3D{}                                      // zero value for Point3D
line1 := Line{Object{}, origin, Point3D{y: -4, z: 12.3}} // zero value for line1.q.x
line2 := Line{name: "diagonal", q: Point3D{1, 1, 1}}     // Go 1.27: name is promoted from Object

obj := Object{"edge", "black"}
line3 := Line{Object: obj, name: "diagonal"} // invalid: name is inside Object

buffer := [10]string{}             // len(buffer) == 10
intSet := [6]int{1, 2, 3, 5}       // len(intSet) == 6
days := [...]string{"Sat", "Sun"}  // len(days) == 2

vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}

m := map[string]int{"one": 1, "two": 2}

A slice literal describes a whole underlying array: its length and capacity are the largest index plus one. Taking the address of a composite literal, &T{…}, generates a pointer to a new variable holding the value. new([]int) gives a pointer to a nil slice, but &[]int{} a pointer to an empty, non-nil one.

Inside array, slice and map literals, elements and map keys that are composite literals may elide their type if it is identical to the element or key type (spec: Elision of element types); similarly &T may be elided when the element type is *T.

[][]int{{1, 2, 3}, {4, 5}}          // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
[]*Point{{1.5, -3.5}, {}}           // same as []*Point{&Point{1.5, -3.5}, &Point{}}
map[Point]string{{0, 0}: "orig"}    // same as map[Point]string{Point{0, 0}: "orig"}

A composite literal using a type name as an operand of an if, for or switch header, outside parentheses, brackets or braces, would be read as the start of the statement’s block. It must be parenthesised: if x == (T{a, b}) { … }.

Function literals

FunctionLit = "func" Signature FunctionBody .

A function literal is an anonymous function; it cannot declare type parameters. It may be assigned to a variable or called directly. Function literals are closures: they may refer to variables of the surrounding function, which are then shared with the literal and survive as long as they are accessible. See Functions and methods.

Selectors

For an expression x that is not a package name, x.f denotes the field or method f of x (or sometimes of *x). The selector f must not be blank. A selector may reach through embedded fields; the number of embedded fields traversed is its depth (spec: Selectors).

1. For a value of type T or *T, where T is not a pointer or interface type, x.f denotes the field or method at the shallowest depth where one exists. If there is not exactly one at that depth, the selector is illegal.
2. For a value of interface type I, x.f denotes the actual method of the dynamic value; f must be in the method set of I.
3. If x has a defined pointer type and (*x).f is a valid selector of a field (not a method), x.f is shorthand for (*x).f.
4. In all other cases x.f is illegal.
5. If x is a nil pointer and x.f denotes a struct field, evaluating or assigning to it panics.
6. If x is a nil interface, calling or evaluating the method x.f panics.

Selectors also underlie method values and method expressions.

Index expressions

a[x] indexes an array, pointer to array, slice, string or map (spec: Index expressions). Outside maps, the index must be an untyped constant or of integer type, and a constant index must be non-negative and representable by int.

A map index used in a two-value assignment, v, ok := a[x], also yields an untyped boolean saying whether the key is present. Assigning to an element of a nil map panics. For a type parameter operand the operation must be valid for every type in its type set, and their element types must be identical (see Generics).

Slice expressions

Slice expressions build a substring or slice from a string, array, pointer to array or slice. The result shares its underlying data with the operand.

• In the simple form, a missing low defaults to 0 and a missing high to len(a). In the full form only low may be omitted.
• For arrays and strings the indices must satisfy 0 <= low <= high <= len(a); for slices the upper bound is cap(a). For the full form, 0 <= low <= high <= max <= cap(a). Out-of-range indices panic at run time; constant indices that break these are compile errors.
• An array operand must be addressable. Slicing a nil slice gives a nil slice.

a := [5]int{1, 2, 3, 4, 5}
s := a[1:4]        // len 3, cap 4, elements 2, 3, 4
t := a[1:3:5]      // len 2, cap 4, elements 2, 3

a2 := a[2:]        // same as a[2 : len(a)]
a3 := a[:3]        // same as a[0 : 3]
a4 := a[:]         // same as a[0 : len(a)]

Type assertions

For an expression x of interface type (but not a type parameter), x.(T) asserts that x is not nil and that its stored value has type T (spec: Type assertions).

• If T is not an interface type, the dynamic type of x must be identical to T, and T must implement the type of x, or the assertion is invalid.
• If T is an interface type, the dynamic type of x must implement T.
• If the assertion is false, a run-time panic occurs.

Used in a two-value assignment or initialisation, v, ok := x.(T) yields an additional untyped boolean and does not panic; on failure v is the zero value of T. See also type switches.

var x any = 7        // x has dynamic type int and value 7
i := x.(int)         // i has type int and value 7

n, ok := x.(string)  // n == "", ok == false; no panic
r, ok := x.(io.Reader)  // ok reports whether the dynamic type implements io.Reader

Calls

f(a1, a2, … an) calls f. Arguments must be single-valued expressions assignable to the parameter types and are evaluated before the call. They are then passed, which means assigned to the corresponding parameters (spec: Calls).

• A call of a nil function value panics.
• If f is generic, it must be instantiated before it can be called.
• A method call x.m() needs m in the method set of the type of x. If x is addressable and &x’s method set has m, x.m() is shorthand for (&x).m().
• As a special case, the multi-value result of a call can be passed straight to another function if it is the only argument and the values fit the parameters: f(g()). A final ... parameter takes what remains.
• See variadic functions for calls with ....

Operators and precedence

Unary operators have the highest precedence. There are five precedence levels for binary operators, and binary operators of the same precedence associate from left to right. The statements x++ and x-- are outside this hierarchy, so *p++ is (*p)++ (spec: Operator precedence).

x / y * z                  // (x / y) * z
42 + a - b                 // (42 + a) - b
23 + 3*x[i]                // 23 + (3 * x[i])
^a >> b                    // (^a) >> b
x == y+1 && <-chanInt > 0  // (x == (y+1)) && ((<-chanInt) > 0)

For binary operators other than comparisons, the operand types must be identical, unless the operation involves shifts or untyped constants. If one operand is an untyped constant and the other is not, the constant is converted to the other operand’s type, except in shifts.

Constant expressions

Constant expressions have only constant operands and are evaluated at compile time, exactly (spec: Constant expressions).

• A constant comparison gives an untyped boolean constant. A constant shift with an untyped left operand gives an integer constant.
• Any other operation on untyped constants gives an untyped constant of the same kind. If the operands are of different kinds, the result takes the kind appearing later in the list: integer, rune, floating-point, complex.
• Values of typed constants must be representable by their type: uint(-1) and int(3.14) are errors, and so is Four * 300 if Four is an int8.
• The divisor of a constant division or remainder must not be zero.
• len and cap may be constant; see Built-ins.

const a = 2 + 3.0          // a == 5.0   (untyped floating-point constant)
const b = 15 / 4           // b == 3     (untyped integer constant)
const c = 15 / 4.0         // c == 3.75  (untyped floating-point constant)
const Θ float64 = 3/2      // Θ == 1.0   (type float64, 3/2 is integer division)
const d = 1 << 3.0         // d == 8     (untyped integer constant)
const e = 1.0 << 3         // e == 8     (untyped integer constant)
const h = "foo" > "bar"    // h == true  (untyped boolean constant)
const k = 'w' + 1          // k == 'x'   (untyped rune constant)

const Huge = 1 << 100         // Huge == 1267650600228229401496703205376
const Four int8 = Huge >> 98  // Four == 4 (type int8)

Order of evaluation

At package level, initialisation dependencies determine the order of initialisation expressions. Elsewhere, when evaluating the operands of an expression, assignment or return statement, function calls, method calls, receive operations and binary logical operations happen in lexical left-to-right order. The order of other operations relative to those, such as reading a variable, is not specified (spec: Order of evaluation).

y[f()], ok = g(z || h(), i()+x[j()], <-c), k()
// calls and communication happen in the order
// f(), h() (if z is false), i(), j(), <-c, g(), k()

a := 1
f := func() int { a++; return a }
x := []int{a, f()}            // x may be [1, 2] or [2, 2]
m := map[int]int{a: 1, a: 2}  // m may be {2: 1} or {2: 2}
n := map[int]int{a: f()}      // n may be {2: 3} or {3: 3}

Floating-point operations in a single expression are evaluated according to the associativity of the operators; parentheses override it, so x + (y + z) computes y + z first. Assignments have their own two-phase rule: Assignment statements.