Go

https://go.dev/ref/
Admin
Go is an open source programming language that makes developers more productive with expressive,...
Tokens:78,656
Snippets:571
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Go statement: grammar and examples of spawning goroutines

Source: https://go.dev/ref/spec

The grammar rule GoStmt and two examples of starting a goroutine. The first, go Server(), starts a function; the second uses an anonymous function with a channel. Execution does not wait for the invoked function to complete.

```bnf
GoStmt = "go" Expression .
```

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

```

--------------------------------

### Basic Struct Examples

Source: https://go.dev/ref/spec

Examples of an empty struct and a struct with multiple fields including padding.

```go
// An empty struct.
struct {}

// A struct with 6 fields.
struct {
	x, y int
	u float32
	_ float32  // padding
	A *[]int
	F func()
}
```

--------------------------------

### Pointer Type Examples

Source: https://go.dev/ref/spec

Examples of pointer type declarations.

```go
*Point
*[4]int
```

--------------------------------

### Example package clause

Source: https://go.dev/ref/spec

Example of a package clause: `package math`. The package name must not be the blank identifier.

```go
package math
```

--------------------------------

### make usage examples

Source: https://go.dev/ref/spec

Examples of calling make for slices, channels, and maps, including legal and illegal cases with comments explaining the results.

```go
s := make([]int, 10, 100)       // slice with len(s) == 10, cap(s) == 100
s := make([]int, 1e3)           // slice with len(s) == cap(s) == 1000
s := make([]int, 1<<63)         // illegal: len(s) is not representable by a value of type int
s := make([]int, 10, 0)         // illegal: len(s) > cap(s)
c := make(chan int, 10)         // channel with a buffer size of 10
m := make(map[string]int, 100)  // map with initial space for approximately 100 elements
```

--------------------------------

### Example function signatures

Source: https://go.dev/ref/spec

Examples of valid function signatures, including variadic and unnamed parameters.

```go
func()
func(x int) int
func(a, _ int, z float32) bool
func(a, b int, z float32) (bool)
func(prefix string, values ...int)
func(a, b int, z float64, opt ...interface{}) (success bool)
func(int, int, float64) (float64, *[]int)
func(n int) func(p *T)

```

--------------------------------

### Pointer and uintptr conversions

Source: https://go.dev/ref/spec

Examples of converting between Pointer and uintptr, including a type parameter example. The effect of such conversions is implementation-defined.

```go
var f float64
bits = *(*uint64)(unsafe.Pointer(&f))

type ptr unsafe.Pointer
bits = *(*uint64)(ptr(&f))

func f[P ~*B, B any](p P) uintptr {
	return uintptr(unsafe.Pointer(p))
}

var p ptr = nil

```

--------------------------------

### Parenthesization examples for conversions

Source: https://go.dev/ref/spec

Examples showing when parentheses are required around a type in a conversion to avoid ambiguity, such as when the type starts with `*`, `<-`, or `func` without a result list.

```go
*Point(p)        // same as *(Point(p))
(*Point)(p)      // p is converted to *Point
<-chan int(c)    // same as <-(chan int(c))
(<-chan int)(c)  // c is converted to <-chan int
func()(x)        // function signature func() x
(func())(x)      // x is converted to func()
(func() int)(x)  // x is converted to func() int
func() int(x)    // x is converted to func() int (unambiguous)

```

--------------------------------

### Array type examples

Source: https://go.dev/ref/spec

Examples of array type declarations, including multi-dimensional arrays.

```go
[32]byte
[2*N] struct { x, y int32 }
[1000]*float64
[3][5]int
[2][2][2]float64  // same as [2]([2]([2]float64))

```

--------------------------------

### Go integer division and remainder examples

Source: https://go.dev/ref/spec

Examples of Go's truncated integer division and remainder for positive and negative operands. Shows that the quotient is truncated towards zero.

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

```

--------------------------------

### Type constraint satisfaction examples

Source: https://go.dev/ref/spec

Examples showing which type arguments satisfy various type constraints, including the exception for comparable constraints.

```go
type argument      type constraint                // constraint satisfaction

int                interface{ ~int }              // satisfied: int implements interface{ ~int }
string             comparable                     // satisfied: string implements comparable (string is strictly comparable)
[]byte             comparable                     // not satisfied: slices are not comparable
any                interface{ comparable; int }   // not satisfied: any does not implement interface{ int }
any                comparable                     // satisfied: any is comparable and implements the basic interface any
struct{f any}      comparable                     // satisfied: struct{f any} is comparable and implements the basic interface any
any                interface{ comparable; m() }   // not satisfied: any does not implement the basic interface interface{ m() }
interface{ m() }   interface{ comparable; m() }   // satisfied: interface{ m() } is comparable and implements the basic interface interface{ m() }
```

--------------------------------

### min and max usage examples

Source: https://go.dev/ref/spec

Examples of using min and max with integers, floats, and strings, including invalid use with slice arguments.

```go
var x, y int
m := min(x)                 // m == x
m := min(x, y)              // m is the smaller of x and y
m := max(x, y, 10)          // m is the larger of x and y but at least 10
c := max(1, 2.0, 10)        // c == 10.0 (floating-point kind)
f := max(0, float32(x))     // type of f is float32
var s []string
_ = min(s...)               // invalid: slice arguments are not permitted
t := max("", "foo", "bar")  // t == "foo" (string kind)
```

--------------------------------

### Examples of panic calls

Source: https://go.dev/ref/spec

Shows three example calls to panic with different argument types: an integer, a string, and an error value.

```go
panic(42)
panic("unreachable")
panic(Error("cannot parse"))

```

--------------------------------

### Short variable declaration examples

Source: https://go.dev/ref/spec

Examples of short variable declarations, including multiple assignment and blank identifiers.

```go
i, j := 0, 10
f := func() int { return 7 }
ch := make(chan int)
r, w, _ := os.Pipe()  // os.Pipe() returns a connected pair of Files and an error, if any
_, y, _ := coord(p)   // coord() returns three values; only interested in y coordinate
```

--------------------------------

### Short variable declaration redeclaration examples

Source: https://go.dev/ref/spec

Examples showing redeclaration rules for short variable declarations, including an illegal case.

```go
field1, offset := nextField(str, 0)
field2, offset := nextField(str, offset)  // redeclares offset
x, y, x := 1, 2, 3                        // illegal: x repeated on left side of :=
```

--------------------------------

### Variable declaration examples

Source: https://go.dev/ref/spec

Examples of variable declarations with and without types, including grouped declarations and blank identifiers.

```go
var i int
var U, V, W float64
var k = 0
var x, y float32 = -1, -2
var (
	i       int
	u, v, s = 2.0, 3.0, "bar"
)
var re, im = complexSqrt(-1)
var _, found = entries[name]  // map lookup; only interested in "found"
```

--------------------------------

### Constant conversion examples

Source: https://go.dev/ref/spec

Examples of converting constant values to various types, including integer, float, complex, string, and custom types. Also shows illegal conversions and cases that are not constants.

```go
uint(iota)               // iota value of type uint
float32(2.718281828)     // 2.718281828 of type float32
complex128(1)            // 1.0 + 0.0i of type complex128
float32(0.49999999)      // 0.5 of type float32
float64(-1e-1000)        // 0.0 of type float64
string('x')              // "x" of type string
string(0x266c)           // "♬" of type string
myString("foo" + "bar")  // "foobar" of type myString
string([]byte{'a'})      // not a constant: []byte{'a'} is not a constant
(*int)(nil)              // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
int(1.2)                 // illegal: 1.2 cannot be represented as an int
string(65.0)             // illegal: 65.0 is not an integer constant

```

--------------------------------

### Comparison examples with untyped boolean constants

Source: https://go.dev/ref/spec

Shows that comparison results are untyped boolean constants or values. The example demonstrates assignment to bool and custom boolean types.

```go
const c = 3 < 4            // c is the untyped boolean constant true

type MyBool bool
var x, y int
var (
	// The result of a comparison is an untyped boolean.
	// The usual assignment rules apply.
	b3        = x == y // b3 has type bool
	b4 bool   = x == y // b4 has type bool
	b5 MyBool = x == y // b5 has type MyBool
)
```

--------------------------------

### copy examples

Source: https://go.dev/ref/spec

Examples of copy usage: copying from an array, copying from an overlapping slice, and copying from a string into a byte slice. The results show the number of elements copied and the resulting slice/byte slice content.

```go
var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
var s = make([]int, 6)
var b = make([]byte, 5)
n1 := copy(s, a[0:])            // n1 == 6, s is []int{0, 1, 2, 3, 4, 5}
n2 := copy(s, s[2:])            // n2 == 4, s is []int{2, 3, 4, 5, 4, 5}
n3 := copy(b, "Hello, World!")  // n3 == 5, b is []byte("Hello")


```

--------------------------------

### Expression switch examples

Source: https://go.dev/ref/spec

Three examples of expression switches: with tag, with missing switch expression (equivalent to true), and with no switch expression.

```go
switch tag {
default: s3()
case 0, 1, 2, 3: s1()
case 4, 5, 6, 7: s2()
}

switch x := f(); {  // missing switch expression means "true"
case x < 0: return -x
default: return x
}

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

--------------------------------

### For statement with for clause example

Source: https://go.dev/ref/spec

Illustrates a classic for loop with init, condition, and post statements: for i := 0; i < 10; i++ { f(i) }.

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

--------------------------------

### Labeled statement grammar and example

Source: https://go.dev/ref/spec

Shows the grammar for a labeled statement and an example of a labeled statement with a log.Panic call. The labeled statement can be the target of goto, break, or continue statements.

```go

LabeledStmt = Label ":" Statement .
Label       = identifier .

```

```go

Error: log.Panic("error encountered")

```

--------------------------------

### Select statement: grammar and communication example

Source: https://go.dev/ref/spec

Grammar rule for select statements and a complete example showing communication on channels with cases, a default case, a loop that generates random bits, and the empty select that blocks forever.

```bnf
SelectStmt = "select" "{" { CommClause } "}" .
CommClause = CommCase ":" StatementList .
CommCase   = "case" ( SendStmt | RecvStmt ) | "default" .
RecvStmt   = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
RecvExpr   = Expression .

```

```go
var a []int
var c, c1, c2, c3, c4 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")
case i3, ok := (<-c3):  // same as: i3, ok := <-c3
	if ok {
		print("received ", i3, " from c3\n")
	} else {
		print("c3 is closed\n")
	}
case a[f()] = <-c4:
	// same as:
	// case t := <-c4
	//	a[f()] = t
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:
	}
}

select {}  // block forever

```

--------------------------------

### Interface type set examples

Source: https://go.dev/ref/spec

Shows interfaces representing specific types, underlying types, and empty type sets.

```go
// An interface representing only the type int.
interface {
	int
}

// An interface representing all types with underlying type int.
interface {
	~int
}

// An interface representing all types with underlying type int that implement the String method.
interface {
	~int
	String() string
}

// An interface representing an empty type set: there is no type that is both an int and a string.
interface {
	int
	string
}
```

--------------------------------

### Generic instantiation substitution examples

Source: https://go.dev/ref/spec

Example table showing valid and invalid type argument substitutions for generic declarations. Illustrates that type arguments must satisfy constraints and that some substitutions are illegal.

```text
type parameter list    type arguments    after substitution

[P any]                int               int satisfies any
[S ~[]E, E any]        []int, int        []int satisfies ~[]int, int satisfies any
[P io.Writer]          string            illegal: string doesn't satisfy io.Writer
[P comparable]         any               any satisfies (but does not implement) comparable

```

--------------------------------

### Valid type parameter list examples

Source: https://go.dev/ref/spec

Shows valid type parameter list examples. All non-blank names must be unique. The underscore is allowed as a blank name. Constraints can be any type, an interface literal, or a type with arguments.

```text
[P any]
[S interface{ ~[]byte|string }]
[S ~[]E, E any]
[P Constraint[int]]
[_ any]

```

--------------------------------

### Valid assignment examples

Source: https://go.dev/ref/spec

Examples of valid assignment statements, including assignment to a variable, pointer dereference, map index, and parenthesized channel receive.

```go
x = 1
*p = f()
a[i] = 23
(k) = <-ch  // same as: k = <-ch
```

--------------------------------

### Defer usage examples

Source: https://go.dev/ref/spec

Examples showing defer with a lock, a loop with deferred prints, and a deferred function modifying a named result parameter. The lock example shows unlocking before the surrounding function returns. The loop prints 3 2 1 0 before the function returns. The function f returns 42 because the deferred function multiplies the result by 7 after it is set to 6.

```go
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)
}

// f returns 42
func f() (result int) {
	defer func() {
		// result is accessed after it was set to 6 by the return statement
		result *= 7
	}()
	return 6
}
```

--------------------------------

### Conversion to a type parameter example

Source: https://go.dev/ref/spec

Example function showing that converting a constant to a type parameter yields a non-constant value, with the value represented using the type argument's precision.

```go
func f[P ~float32|~float64]() {
	… P(1.1) …
}

```

--------------------------------

### Go constant declaration examples

Source: https://go.dev/ref/spec

Examples of constant declarations with explicit types, untyped constants, and multiple identifiers. Shows that untyped constants remain untyped when the expression is untyped.

```go
const Pi float64 = 3.14159265358979323846
const zero = 0.0         // untyped floating-point constant
const (
	size int64 = 1024
	eof        = -1  // untyped integer constant
)
const a, b, c = 3, 4, "foo"  // a = 3, b = 4, c = "foo", untyped integer and string constants
const u, v float32 = 0, 3    // u = 0.0, v = 3.0

```

--------------------------------

### Send value to channel

Source: https://go.dev/ref/spec

A basic send statement example, demonstrating the syntax for sending a value to a channel.

```go
ch <- 3  // send value 3 to channel ch
```

--------------------------------

### append examples

Source: https://go.dev/ref/spec

Examples of append usage: appending single and multiple elements, appending an entire slice with ..., appending an overlapping slice, appending to an interface slice, and appending string bytes with ...

```go
s0 := []int{0, 0}
s1 := append(s0, 2)                // append a single element     s1 is []int{0, 0, 2}
s2 := append(s1, 3, 5, 7)          // append multiple elements    s2 is []int{0, 0, 2, 3, 5, 7}
s3 := append(s2, s0...)            // append a slice              s3 is []int{0, 0, 2, 3, 5, 7, 0, 0}
s4 := append(s3[3:6], s3[2:]...)   // append overlapping slice    s4 is []int{3, 5, 7, 2, 3, 5, 7, 0, 0}

var t []interface{}
t = append(t, 42, 3.1415, "foo")   //                             t is []interface{}{42, 3.1415, "foo"}

var b []byte
b = append(b, "bar"...)            // append string contents      b is []byte{'b', 'a', 'r' }


```

--------------------------------

### Return statement: grammar and no-result example

Source: https://go.dev/ref/spec

Grammar rule for return statements and a minimal example of a function without a result type that uses a bare return. Deferred functions run before returning to the caller.

```bnf
ReturnStmt = "return" [ ExpressionList ] .
```

```go
func noResult() {
	return
}

```

--------------------------------

### Type assertion examples with interface{} and interface I

Source: https://go.dev/ref/spec

Shows the syntax and behavior of type assertions in Go. The first example asserts an int from an interface{} holding 7; the second asserts a string from an interface I, which is illegal because string does not implement I and causes a run-time panic.

```go
var x interface{} = 7          // x has dynamic type int and value 7
i := x.(int)                   // i has type int and value 7

type I interface { m() }

func f(y I) {
	s := y.(string)        // illegal: string does not implement I (method m does not have signature)
}
```

--------------------------------

### Full slice elements check

Source: https://go.dev/ref/spec

Shows the elements of slice t from the preceding full slice example.

```go
t[0] == 2
t[1] == 3
```

--------------------------------

### Bootstrapping functions print and println

Source: https://go.dev/ref/spec

Lists the bootstrapping functions print and println with their behavior. print prints all arguments; println prints spaces between arguments and a newline at the end.

```go
Function   Behavior

print      prints all arguments; formatting of arguments is implementation-specific
println    like print but prints spaces between arguments and a newline at the end

```

--------------------------------

### Anonymous function literal example

Source: https://go.dev/ref/spec

Example of an anonymous function literal with parameters and a return type.

```go
func(a, b int, z float64) bool { return a*b < int(z) }
```

--------------------------------

### Address and pointer indirection examples

Source: https://go.dev/ref/spec

Shows valid address operations (&x, &a[f(2)], &Point{2, 3}) and pointer indirections (*p, *pf(x)). Also demonstrates that evaluating *x or &*x on a nil pointer causes a run-time panic.

```go
&x
&a[f(2)]
&Point{2, 3}
*p
*pf(x)

var x *int = nil
*x   // causes a run-time panic
&*x  // causes a run-time panic
```

--------------------------------

### Go iota usage examples

Source: https://go.dev/ref/spec

Demonstrates iota values in constant declarations, including shifts, multiplication, and separate declarations where iota resets to zero.

```go
const (
	c0 = iota  // c0 == 0
	c1 = iota  // c1 == 1
	c2 = iota  // c2 == 2
)

const (
	a = 1 << iota  // a == 1  (iota == 0)
	b = 1 << iota  // b == 2  (iota == 1)
	c = 3          // c == 3  (iota == 2, unused)
	d = 1 << iota  // d == 8  (iota == 3)
)

const (
	u         = iota * 42  // u == 0     (untyped integer constant)
	v float64 = iota * 42  // v == 42.0  (float64 constant)
	w         = iota * 42  // w == 84    (untyped integer constant)
)

const x = iota  // x == 0
const y = iota  // y == 0

```

--------------------------------

### Simple File interface

Source: https://go.dev/ref/spec

A basic interface with three methods: Read, Write, and Close.

```go
// A simple File interface.
interface {
	Read([]byte) (int, error)
	Write([]byte) (int, error)
	Close() error
}

```

--------------------------------

### Variable declaration type inference examples

Source: https://go.dev/ref/spec

Examples showing type inference for variable declarations, including illegal use of nil.

```go
var d = math.Sin(0.5)  // d is float64
var i = 42             // i is int
var t, ok = x.(T)      // t is T, ok is bool
var n = nil            // illegal
```

--------------------------------

### Concurrent prime sieve example package

Source: https://go.dev/ref/spec

Complete Go package implementing a concurrent prime sieve. It uses goroutines and channels to generate and filter prime numbers, printing each prime as it is found.

```go
package main

import "fmt"

// 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 'src' to channel 'dst',
// removing those divisible by 'prime'.
func filter(src <-chan int, dst chan<- int, prime int) {
	for i := range src {  // Loop over values received from 'src'.
		if i%prime != 0 {
			dst <- i  // Send 'i' to channel 'dst'.
		}
	}
}

// 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
		fmt.Print(prime, "\n")
		ch1 := make(chan int)
		go filter(ch, ch1, prime)
		ch = ch1
	}
}

func main() {
	sieve()
}
```

--------------------------------

### For statement equivalence examples

Source: https://go.dev/ref/spec

Shows that a for loop with only a condition is equivalent to a for loop with empty init and post statements, and that a for loop with no condition is equivalent to a for loop with condition true.

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

--------------------------------

### Function with result parameters and missing return

Source: https://go.dev/ref/spec

Example of a function with result parameters. The function body must end in a terminating statement; this example is invalid because the return statement is missing.

```go
func IndexRune(s string, r rune) int {
	for i, c := range s {
		if c == r {
			return i
		}
	}
	// invalid: missing return statement
}

```

--------------------------------

### Primary expression examples

Source: https://go.dev/ref/spec

Examples of primary expressions: identifiers, literals, parenthesized expressions, function calls, composite literals, index expressions, slice expressions, selectors, and chained calls.

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

--------------------------------

### Type switch with type parameter P

Source: https://go.dev/ref/spec

Demonstrates using a type parameter P in a type switch. If P duplicates another case after instantiation, the first matching case is chosen. The example shows calls with string and byte types.

```go
func f[P any](x any) int {
	switch x.(type) {
	case P:
		return 0
	case string:
		return 1
	case []P:
		return 2
	case []byte:
		return 3
	default:
		return 4
	}
}

var v1 = f[string]("foo")   // v1 == 0
var v2 = f[byte]([]byte{})  // v2 == 2
```

--------------------------------

### Go package initialization: dependency order

Source: https://go.dev/ref/spec

Illustrates that initialization order is determined by dependency analysis and declaration order. The resulting order is d, b, c, a; the order of subexpressions in expressions does not affect the result.

```go
var (
	a = c + b  // == 9
	b = f()    // == 4
	c = f()    // == 5
	d = 3      // == 5 after initialization has finished
)

func f() int {
	d++
	return d
}
```

--------------------------------

### Go pre-1.22 iteration variable output

Source: https://go.dev/ref/spec

Shows the output of the same example when iterations share one set of variables, as in Go versions prior to 1.22. The output is 6, 6, 6.

```text
6
6
6
```

--------------------------------

### Partial type argument list in Go generics

Source: https://go.dev/ref/spec

Illustrates partial type argument lists for generic functions, where the list must be non-empty and is a prefix. Shows that missing arguments can be inferred from context and that empty lists are illegal.

```go
func apply[S ~[]E, E any](s S, f func(E) E) S { … }

f0 := apply[]                  // illegal: type argument list cannot be empty
f1 := apply[[]int]             // type argument for S explicitly provided, type argument for E inferred
f2 := apply[[]string, string]  // both type arguments explicitly provided

var bytes []byte
r := apply(bytes, func(byte) byte { … })  // both type arguments inferred from the function arguments

```

--------------------------------

### Struct tags ignored in conversion example

Source: https://go.dev/ref/spec

Example showing that struct tags are ignored when comparing underlying types for conversion, allowing a pointer to a struct with tags to be converted to a pointer to a struct without tags.

```go
type Person struct {
	Name    string
	Address *struct {
		Street string
		City   string
	}
}

var data *struct {
	Name    string `json:"name"`
	Address *struct {
		Street string `json:"street"`
		City   string `json:"city"`
	} `json:"address"`
}

var person = (*Person)(data)  // ignoring tags, the underlying types are identical

```

--------------------------------

### Comparable implementation examples

Source: https://go.dev/ref/spec

Examples showing which types implement and do not implement comparable. Interfaces with type elements only work as type parameters. Non-interface types that are strictly comparable implement comparable, while interfaces do not strictly compare.

```text
int                          // implements comparable (int is strictly comparable)
[]byte                       // does not implement comparable (slices cannot be compared)
interface{}                  // does not implement comparable (see above)
interface{ ~int | ~string }  // type parameter only: implements comparable (int, string types are strictly comparable)
interface{ comparable }      // type parameter only: implements comparable (comparable implements itself)
interface{ ~int | ~[]byte }  // type parameter only: does not implement comparable (slices are not comparable)
interface{ ~struct{ any } }  // type parameter only: does not implement comparable (field any is not strictly comparable)

```
Tokens:
Raw