diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-16 19:25:22 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-16 19:25:22 +0000 |
| commit | f6ad4dcef54c5ce997a4bad5a6d86de229015700 (patch) | |
| tree | 7cfa4e31ace5c2bd95c72b154d15af494b2bcbef /doc | |
| parent | Initial commit. (diff) | |
| download | golang-1.22-f6ad4dcef54c5ce997a4bad5a6d86de229015700.tar.xz golang-1.22-f6ad4dcef54c5ce997a4bad5a6d86de229015700.zip | |
Adding upstream version 1.22.1.upstream/1.22.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/asm.html | 1073 | ||||
| -rw-r--r-- | doc/go1.17_spec.html | 6864 | ||||
| -rw-r--r-- | doc/go_mem.html | 977 | ||||
| -rw-r--r-- | doc/go_spec.html | 8754 | ||||
| -rw-r--r-- | doc/godebug.md | 273 |
5 files changed, 17941 insertions, 0 deletions
diff --git a/doc/asm.html b/doc/asm.html new file mode 100644 index 0000000..dd395ec --- /dev/null +++ b/doc/asm.html @@ -0,0 +1,1073 @@ +<!--{ + "Title": "A Quick Guide to Go's Assembler", + "Path": "/doc/asm" +}--> + +<h2 id="introduction">A Quick Guide to Go's Assembler</h2> + +<p> +This document is a quick outline of the unusual form of assembly language used by the <code>gc</code> Go compiler. +The document is not comprehensive. +</p> + +<p> +The assembler is based on the input style of the Plan 9 assemblers, which is documented in detail +<a href="https://9p.io/sys/doc/asm.html">elsewhere</a>. +If you plan to write assembly language, you should read that document although much of it is Plan 9-specific. +The current document provides a summary of the syntax and the differences with +what is explained in that document, and +describes the peculiarities that apply when writing assembly code to interact with Go. +</p> + +<p> +The most important thing to know about Go's assembler is that it is not a direct representation of the underlying machine. +Some of the details map precisely to the machine, but some do not. +This is because the compiler suite (see +<a href="https://9p.io/sys/doc/compiler.html">this description</a>) +needs no assembler pass in the usual pipeline. +Instead, the compiler operates on a kind of semi-abstract instruction set, +and instruction selection occurs partly after code generation. +The assembler works on the semi-abstract form, so +when you see an instruction like <code>MOV</code> +what the toolchain actually generates for that operation might +not be a move instruction at all, perhaps a clear or load. +Or it might correspond exactly to the machine instruction with that name. +In general, machine-specific operations tend to appear as themselves, while more general concepts like +memory move and subroutine call and return are more abstract. +The details vary with architecture, and we apologize for the imprecision; the situation is not well-defined. +</p> + +<p> +The assembler program is a way to parse a description of that +semi-abstract instruction set and turn it into instructions to be +input to the linker. +If you want to see what the instructions look like in assembly for a given architecture, say amd64, there +are many examples in the sources of the standard library, in packages such as +<a href="/pkg/runtime/"><code>runtime</code></a> and +<a href="/pkg/math/big/"><code>math/big</code></a>. +You can also examine what the compiler emits as assembly code +(the actual output may differ from what you see here): +</p> + +<pre> +$ cat x.go +package main + +func main() { + println(3) +} +$ GOOS=linux GOARCH=amd64 go tool compile -S x.go # or: go build -gcflags -S x.go +"".main STEXT size=74 args=0x0 locals=0x10 + 0x0000 00000 (x.go:3) TEXT "".main(SB), $16-0 + 0x0000 00000 (x.go:3) MOVQ (TLS), CX + 0x0009 00009 (x.go:3) CMPQ SP, 16(CX) + 0x000d 00013 (x.go:3) JLS 67 + 0x000f 00015 (x.go:3) SUBQ $16, SP + 0x0013 00019 (x.go:3) MOVQ BP, 8(SP) + 0x0018 00024 (x.go:3) LEAQ 8(SP), BP + 0x001d 00029 (x.go:3) FUNCDATA $0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB) + 0x001d 00029 (x.go:3) FUNCDATA $1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB) + 0x001d 00029 (x.go:3) FUNCDATA $2, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB) + 0x001d 00029 (x.go:4) PCDATA $0, $0 + 0x001d 00029 (x.go:4) PCDATA $1, $0 + 0x001d 00029 (x.go:4) CALL runtime.printlock(SB) + 0x0022 00034 (x.go:4) MOVQ $3, (SP) + 0x002a 00042 (x.go:4) CALL runtime.printint(SB) + 0x002f 00047 (x.go:4) CALL runtime.printnl(SB) + 0x0034 00052 (x.go:4) CALL runtime.printunlock(SB) + 0x0039 00057 (x.go:5) MOVQ 8(SP), BP + 0x003e 00062 (x.go:5) ADDQ $16, SP + 0x0042 00066 (x.go:5) RET + 0x0043 00067 (x.go:5) NOP + 0x0043 00067 (x.go:3) PCDATA $1, $-1 + 0x0043 00067 (x.go:3) PCDATA $0, $-1 + 0x0043 00067 (x.go:3) CALL runtime.morestack_noctxt(SB) + 0x0048 00072 (x.go:3) JMP 0 +... +</pre> + +<p> +The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information +for use by the garbage collector; they are introduced by the compiler. +</p> + +<p> +To see what gets put in the binary after linking, use <code>go tool objdump</code>: +</p> + +<pre> +$ go build -o x.exe x.go +$ go tool objdump -s main.main x.exe +TEXT main.main(SB) /tmp/x.go + x.go:3 0x10501c0 65488b0c2530000000 MOVQ GS:0x30, CX + x.go:3 0x10501c9 483b6110 CMPQ 0x10(CX), SP + x.go:3 0x10501cd 7634 JBE 0x1050203 + x.go:3 0x10501cf 4883ec10 SUBQ $0x10, SP + x.go:3 0x10501d3 48896c2408 MOVQ BP, 0x8(SP) + x.go:3 0x10501d8 488d6c2408 LEAQ 0x8(SP), BP + x.go:4 0x10501dd e86e45fdff CALL runtime.printlock(SB) + x.go:4 0x10501e2 48c7042403000000 MOVQ $0x3, 0(SP) + x.go:4 0x10501ea e8e14cfdff CALL runtime.printint(SB) + x.go:4 0x10501ef e8ec47fdff CALL runtime.printnl(SB) + x.go:4 0x10501f4 e8d745fdff CALL runtime.printunlock(SB) + x.go:5 0x10501f9 488b6c2408 MOVQ 0x8(SP), BP + x.go:5 0x10501fe 4883c410 ADDQ $0x10, SP + x.go:5 0x1050202 c3 RET + x.go:3 0x1050203 e83882ffff CALL runtime.morestack_noctxt(SB) + x.go:3 0x1050208 ebb6 JMP main.main(SB) +</pre> + +<h3 id="constants">Constants</h3> + +<p> +Although the assembler takes its guidance from the Plan 9 assemblers, +it is a distinct program, so there are some differences. +One is in constant evaluation. +Constant expressions in the assembler are parsed using Go's operator +precedence, not the C-like precedence of the original. +Thus <code>3&1<<2</code> is 4, not 0—it parses as <code>(3&1)<<2</code> +not <code>3&(1<<2)</code>. +Also, constants are always evaluated as 64-bit unsigned integers. +Thus <code>-2</code> is not the integer value minus two, +but the unsigned 64-bit integer with the same bit pattern. +The distinction rarely matters but +to avoid ambiguity, division or right shift where the right operand's +high bit is set is rejected. +</p> + +<h3 id="symbols">Symbols</h3> + +<p> +Some symbols, such as <code>R1</code> or <code>LR</code>, +are predefined and refer to registers. +The exact set depends on the architecture. +</p> + +<p> +There are four predeclared symbols that refer to pseudo-registers. +These are not real registers, but rather virtual registers maintained by +the toolchain, such as a frame pointer. +The set of pseudo-registers is the same for all architectures: +</p> + +<ul> + +<li> +<code>FP</code>: Frame pointer: arguments and locals. +</li> + +<li> +<code>PC</code>: Program counter: +jumps and branches. +</li> + +<li> +<code>SB</code>: Static base pointer: global symbols. +</li> + +<li> +<code>SP</code>: Stack pointer: the highest address within the local stack frame. +</li> + +</ul> + +<p> +All user-defined symbols are written as offsets to the pseudo-registers +<code>FP</code> (arguments and locals) and <code>SB</code> (globals). +</p> + +<p> +The <code>SB</code> pseudo-register can be thought of as the origin of memory, so the symbol <code>foo(SB)</code> +is the name <code>foo</code> as an address in memory. +This form is used to name global functions and data. +Adding <code><></code> to the name, as in <span style="white-space: nowrap"><code>foo<>(SB)</code></span>, makes the name +visible only in the current source file, like a top-level <code>static</code> declaration in a C file. +Adding an offset to the name refers to that offset from the symbol's address, so +<code>foo+4(SB)</code> is four bytes past the start of <code>foo</code>. +</p> + +<p> +The <code>FP</code> pseudo-register is a virtual frame pointer +used to refer to function arguments. +The compilers maintain a virtual frame pointer and refer to the arguments on the stack as offsets from that pseudo-register. +Thus <code>0(FP)</code> is the first argument to the function, +<code>8(FP)</code> is the second (on a 64-bit machine), and so on. +However, when referring to a function argument this way, it is necessary to place a name +at the beginning, as in <code>first_arg+0(FP)</code> and <code>second_arg+8(FP)</code>. +(The meaning of the offset—offset from the frame pointer—distinct +from its use with <code>SB</code>, where it is an offset from the symbol.) +The assembler enforces this convention, rejecting plain <code>0(FP)</code> and <code>8(FP)</code>. +The actual name is semantically irrelevant but should be used to document +the argument's name. +It is worth stressing that <code>FP</code> is always a +pseudo-register, not a hardware +register, even on architectures with a hardware frame pointer. +</p> + +<p> +For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the argument names +and offsets match. +On 32-bit systems, the low and high 32 bits of a 64-bit value are distinguished by adding +a <code>_lo</code> or <code>_hi</code> suffix to the name, as in <code>arg_lo+0(FP)</code> or <code>arg_hi+4(FP)</code>. +If a Go prototype does not name its result, the expected assembly name is <code>ret</code>. +</p> + +<p> +The <code>SP</code> pseudo-register is a virtual stack pointer +used to refer to frame-local variables and the arguments being +prepared for function calls. +It points to the highest address within the local stack frame, so references should use negative offsets +in the range [−framesize, 0): +<code>x-8(SP)</code>, <code>y-4(SP)</code>, and so on. +</p> + +<p> +On architectures with a hardware register named <code>SP</code>, +the name prefix distinguishes +references to the virtual stack pointer from references to the architectural +<code>SP</code> register. +That is, <code>x-8(SP)</code> and <code>-8(SP)</code> +are different memory locations: +the first refers to the virtual stack pointer pseudo-register, +while the second refers to the +hardware's <code>SP</code> register. +</p> + +<p> +On machines where <code>SP</code> and <code>PC</code> are +traditionally aliases for a physical, numbered register, +in the Go assembler the names <code>SP</code> and <code>PC</code> +are still treated specially; +for instance, references to <code>SP</code> require a symbol, +much like <code>FP</code>. +To access the actual hardware register use the true <code>R</code> name. +For example, on the ARM architecture the hardware +<code>SP</code> and <code>PC</code> are accessible as +<code>R13</code> and <code>R15</code>. +</p> + +<p> +Branches and direct jumps are always written as offsets to the PC, or as +jumps to labels: +</p> + +<pre> +label: + MOVW $0, R1 + JMP label +</pre> + +<p> +Each label is visible only within the function in which it is defined. +It is therefore permitted for multiple functions in a file to define +and use the same label names. +Direct jumps and call instructions can target text symbols, +such as <code>name(SB)</code>, but not offsets from symbols, +such as <code>name+4(SB)</code>. +</p> + +<p> +Instructions, registers, and assembler directives are always in UPPER CASE to remind you +that assembly programming is a fraught endeavor. +(Exception: the <code>g</code> register renaming on ARM.) +</p> + +<p> +In Go object files and binaries, the full name of a symbol is the +package path followed by a period and the symbol name: +<code>fmt.Printf</code> or <code>math/rand.Int</code>. +Because the assembler's parser treats period and slash as punctuation, +those strings cannot be used directly as identifier names. +Instead, the assembler allows the middle dot character U+00B7 +and the division slash U+2215 in identifiers and rewrites them to +plain period and slash. +Within an assembler source file, the symbols above are written as +<code>fmt·Printf</code> and <code>math∕rand·Int</code>. +The assembly listings generated by the compilers when using the <code>-S</code> flag +show the period and slash directly instead of the Unicode replacements +required by the assemblers. +</p> + +<p> +Most hand-written assembly files do not include the full package path +in symbol names, because the linker inserts the package path of the current +object file at the beginning of any name starting with a period: +in an assembly source file within the math/rand package implementation, +the package's Int function can be referred to as <code>·Int</code>. +This convention avoids the need to hard-code a package's import path in its +own source code, making it easier to move the code from one location to another. +</p> + +<h3 id="directives">Directives</h3> + +<p> +The assembler uses various directives to bind text and data to symbol names. +For example, here is a simple complete function definition. The <code>TEXT</code> +directive declares the symbol <code>runtime·profileloop</code> and the instructions +that follow form the body of the function. +The last instruction in a <code>TEXT</code> block must be some sort of jump, usually a <code>RET</code> (pseudo-)instruction. +(If it's not, the linker will append a jump-to-itself instruction; there is no fallthrough in <code>TEXTs</code>.) +After the symbol, the arguments are flags (see below) +and the frame size, a constant (but see below): +</p> + +<pre> +TEXT runtime·profileloop(SB),NOSPLIT,$8 + MOVQ $runtime·profileloop1(SB), CX + MOVQ CX, 0(SP) + CALL runtime·externalthreadhandler(SB) + RET +</pre> + +<p> +In the general case, the frame size is followed by an argument size, separated by a minus sign. +(It's not a subtraction, just idiosyncratic syntax.) +The frame size <code>$24-8</code> states that the function has a 24-byte frame +and is called with 8 bytes of argument, which live on the caller's frame. +If <code>NOSPLIT</code> is not specified for the <code>TEXT</code>, +the argument size must be provided. +For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the +argument size is correct. +</p> + +<p> +Note that the symbol name uses a middle dot to separate the components and is specified as an offset from the +static base pseudo-register <code>SB</code>. +This function would be called from Go source for package <code>runtime</code> using the +simple name <code>profileloop</code>. +</p> + +<p> +Global data symbols are defined by a sequence of initializing +<code>DATA</code> directives followed by a <code>GLOBL</code> directive. +Each <code>DATA</code> directive initializes a section of the +corresponding memory. +The memory not explicitly initialized is zeroed. +The general form of the <code>DATA</code> directive is + +<pre> +DATA symbol+offset(SB)/width, value +</pre> + +<p> +which initializes the symbol memory at the given offset and width with the given value. +The <code>DATA</code> directives for a given symbol must be written with increasing offsets. +</p> + +<p> +The <code>GLOBL</code> directive declares a symbol to be global. +The arguments are optional flags and the size of the data being declared as a global, +which will have initial value all zeros unless a <code>DATA</code> directive +has initialized it. +The <code>GLOBL</code> directive must follow any corresponding <code>DATA</code> directives. +</p> + +<p> +For example, +</p> + +<pre> +DATA divtab<>+0x00(SB)/4, $0xf4f8fcff +DATA divtab<>+0x04(SB)/4, $0xe6eaedf0 +... +DATA divtab<>+0x3c(SB)/4, $0x81828384 +GLOBL divtab<>(SB), RODATA, $64 + +GLOBL runtime·tlsoffset(SB), NOPTR, $4 +</pre> + +<p> +declares and initializes <code>divtab<></code>, a read-only 64-byte table of 4-byte integer values, +and declares <code>runtime·tlsoffset</code>, a 4-byte, implicitly zeroed variable that +contains no pointers. +</p> + +<p> +There may be one or two arguments to the directives. +If there are two, the first is a bit mask of flags, +which can be written as numeric expressions, added or or-ed together, +or can be set symbolically for easier absorption by a human. +Their values, defined in the standard <code>#include</code> file <code>textflag.h</code>, are: +</p> + +<ul> +<li> +<code>NOPROF</code> = 1 +<br> +(For <code>TEXT</code> items.) +Don't profile the marked function. This flag is deprecated. +</li> +<li> +<code>DUPOK</code> = 2 +<br> +It is legal to have multiple instances of this symbol in a single binary. +The linker will choose one of the duplicates to use. +</li> +<li> +<code>NOSPLIT</code> = 4 +<br> +(For <code>TEXT</code> items.) +Don't insert the preamble to check if the stack must be split. +The frame for the routine, plus anything it calls, must fit in the +spare space remaining in the current stack segment. +Used to protect routines such as the stack splitting code itself. +</li> +<li> +<code>RODATA</code> = 8 +<br> +(For <code>DATA</code> and <code>GLOBL</code> items.) +Put this data in a read-only section. +</li> +<li> +<code>NOPTR</code> = 16 +<br> +(For <code>DATA</code> and <code>GLOBL</code> items.) +This data contains no pointers and therefore does not need to be +scanned by the garbage collector. +</li> +<li> +<code>WRAPPER</code> = 32 +<br> +(For <code>TEXT</code> items.) +This is a wrapper function and should not count as disabling <code>recover</code>. +</li> +<li> +<code>NEEDCTXT</code> = 64 +<br> +(For <code>TEXT</code> items.) +This function is a closure so it uses its incoming context register. +</li> +<li> +<code>LOCAL</code> = 128 +<br> +This symbol is local to the dynamic shared object. +</li> +<li> +<code>TLSBSS</code> = 256 +<br> +(For <code>DATA</code> and <code>GLOBL</code> items.) +Put this data in thread local storage. +</li> +<li> +<code>NOFRAME</code> = 512 +<br> +(For <code>TEXT</code> items.) +Do not insert instructions to allocate a stack frame and save/restore the return +address, even if this is not a leaf function. +Only valid on functions that declare a frame size of 0. +</li> +<li> +<code>TOPFRAME</code> = 2048 +<br> +(For <code>TEXT</code> items.) +Function is the outermost frame of the call stack. Traceback should stop at this function. +</li> +</ul> + +<h3 id="special-instructions">Special instructions</h3> + +<p> +The <code>PCALIGN</code> pseudo-instruction is used to indicate that the next instruction should be aligned +to a specified boundary by padding with no-op instructions. +</p> + +<p> +It is currently supported on arm64, amd64, ppc64, loong64 and riscv64. + +For example, the start of the <code>MOVD</code> instruction below is aligned to 32 bytes: +<pre> +PCALIGN $32 +MOVD $2, R0 +</pre> +</p> + +<h3 id="data-offsets">Interacting with Go types and constants</h3> + +<p> +If a package has any .s files, then <code>go build</code> will direct +the compiler to emit a special header called <code>go_asm.h</code>, +which the .s files can then <code>#include</code>. +The file contains symbolic <code>#define</code> constants for the +offsets of Go struct fields, the sizes of Go struct types, and most +Go <code>const</code> declarations defined in the current package. +Go assembly should avoid making assumptions about the layout of Go +types and instead use these constants. +This improves the readability of assembly code, and keeps it robust to +changes in data layout either in the Go type definitions or in the +layout rules used by the Go compiler. +</p> + +<p> +Constants are of the form <code>const_<i>name</i></code>. +For example, given the Go declaration <code>const bufSize = +1024</code>, assembly code can refer to the value of this constant +as <code>const_bufSize</code>. +</p> + +<p> +Field offsets are of the form <code><i>type</i>_<i>field</i></code>. +Struct sizes are of the form <code><i>type</i>__size</code>. +For example, consider the following Go definition: +</p> + +<pre> +type reader struct { + buf [bufSize]byte + r int +} +</pre> + +<p> +Assembly can refer to the size of this struct +as <code>reader__size</code> and the offsets of the two fields +as <code>reader_buf</code> and <code>reader_r</code>. +Hence, if register <code>R1</code> contains a pointer to +a <code>reader</code>, assembly can reference the <code>r</code> field +as <code>reader_r(R1)</code>. +</p> + +<p> +If any of these <code>#define</code> names are ambiguous (for example, +a struct with a <code>_size</code> field), <code>#include +"go_asm.h"</code> will fail with a "redefinition of macro" error. +</p> + +<h3 id="runtime">Runtime Coordination</h3> + +<p> +For garbage collection to run correctly, the runtime must know the +location of pointers in all global data and in most stack frames. +The Go compiler emits this information when compiling Go source files, +but assembly programs must define it explicitly. +</p> + +<p> +A data symbol marked with the <code>NOPTR</code> flag (see above) +is treated as containing no pointers to runtime-allocated data. +A data symbol with the <code>RODATA</code> flag +is allocated in read-only memory and is therefore treated +as implicitly marked <code>NOPTR</code>. +A data symbol with a total size smaller than a pointer +is also treated as implicitly marked <code>NOPTR</code>. +It is not possible to define a symbol containing pointers in an assembly source file; +such a symbol must be defined in a Go source file instead. +Assembly source can still refer to the symbol by name +even without <code>DATA</code> and <code>GLOBL</code> directives. +A good general rule of thumb is to define all non-<code>RODATA</code> +symbols in Go instead of in assembly. +</p> + +<p> +Each function also needs annotations giving the location of +live pointers in its arguments, results, and local stack frame. +For an assembly function with no pointer results and +either no local stack frame or no function calls, +the only requirement is to define a Go prototype for the function +in a Go source file in the same package. The name of the assembly +function must not contain the package name component (for example, +function <code>Syscall</code> in package <code>syscall</code> should +use the name <code>·Syscall</code> instead of the equivalent name +<code>syscall·Syscall</code> in its <code>TEXT</code> directive). +For more complex situations, explicit annotation is needed. +These annotations use pseudo-instructions defined in the standard +<code>#include</code> file <code>funcdata.h</code>. +</p> + +<p> +If a function has no arguments and no results, +the pointer information can be omitted. +This is indicated by an argument size annotation of <code>$<i>n</i>-0</code> +on the <code>TEXT</code> instruction. +Otherwise, pointer information must be provided by +a Go prototype for the function in a Go source file, +even for assembly functions not called directly from Go. +(The prototype will also let <code>go</code> <code>vet</code> check the argument references.) +At the start of the function, the arguments are assumed +to be initialized but the results are assumed uninitialized. +If the results will hold live pointers during a call instruction, +the function should start by zeroing the results and then +executing the pseudo-instruction <code>GO_RESULTS_INITIALIZED</code>. +This instruction records that the results are now initialized +and should be scanned during stack movement and garbage collection. +It is typically easier to arrange that assembly functions do not +return pointers or do not contain call instructions; +no assembly functions in the standard library use +<code>GO_RESULTS_INITIALIZED</code>. +</p> + +<p> +If a function has no local stack frame, +the pointer information can be omitted. +This is indicated by a local frame size annotation of <code>$0-<i>n</i></code> +on the <code>TEXT</code> instruction. +The pointer information can also be omitted if the +function contains no call instructions. +Otherwise, the local stack frame must not contain pointers, +and the assembly must confirm this fact by executing the +pseudo-instruction <code>NO_LOCAL_POINTERS</code>. +Because stack resizing is implemented by moving the stack, +the stack pointer may change during any function call: +even pointers to stack data must not be kept in local variables. +</p> + +<p> +Assembly functions should always be given Go prototypes, +both to provide pointer information for the arguments and results +and to let <code>go</code> <code>vet</code> check that +the offsets being used to access them are correct. +</p> + +<h2 id="architectures">Architecture-specific details</h2> + +<p> +It is impractical to list all the instructions and other details for each machine. +To see what instructions are defined for a given machine, say ARM, +look in the source for the <code>obj</code> support library for +that architecture, located in the directory <code>src/cmd/internal/obj/arm</code>. +In that directory is a file <code>a.out.go</code>; it contains +a long list of constants starting with <code>A</code>, like this: +</p> + +<pre> +const ( + AAND = obj.ABaseARM + obj.A_ARCHSPECIFIC + iota + AEOR + ASUB + ARSB + AADD + ... +</pre> + +<p> +This is the list of instructions and their spellings as known to the assembler and linker for that architecture. +Each instruction begins with an initial capital <code>A</code> in this list, so <code>AAND</code> +represents the bitwise and instruction, +<code>AND</code> (without the leading <code>A</code>), +and is written in assembly source as <code>AND</code>. +The enumeration is mostly in alphabetical order. +(The architecture-independent <code>AXXX</code>, defined in the +<code>cmd/internal/obj</code> package, +represents an invalid instruction). +The sequence of the <code>A</code> names has nothing to do with the actual +encoding of the machine instructions. +The <code>cmd/internal/obj</code> package takes care of that detail. +</p> + +<p> +The instructions for both the 386 and AMD64 architectures are listed in +<code>cmd/internal/obj/x86/a.out.go</code>. +</p> + +<p> +The architectures share syntax for common addressing modes such as +<code>(R1)</code> (register indirect), +<code>4(R1)</code> (register indirect with offset), and +<code>$foo(SB)</code> (absolute address). +The assembler also supports some (not necessarily all) addressing modes +specific to each architecture. +The sections below list these. +</p> + +<p> +One detail evident in the examples from the previous sections is that data in the instructions flows from left to right: +<code>MOVQ</code> <code>$0,</code> <code>CX</code> clears <code>CX</code>. +This rule applies even on architectures where the conventional notation uses the opposite direction. +</p> + +<p> +Here follow some descriptions of key Go-specific details for the supported architectures. +</p> + +<h3 id="x86">32-bit Intel 386</h3> + +<p> +The runtime pointer to the <code>g</code> structure is maintained +through the value of an otherwise unused (as far as Go is concerned) register in the MMU. +In the runtime package, assembly code can include <code>go_tls.h</code>, which defines +an OS- and architecture-dependent macro <code>get_tls</code> for accessing this register. +The <code>get_tls</code> macro takes one argument, which is the register to load the +<code>g</code> pointer into. +</p> + +<p> +For example, the sequence to load <code>g</code> and <code>m</code> +using <code>CX</code> looks like this: +</p> + +<pre> +#include "go_tls.h" +#include "go_asm.h" +... +get_tls(CX) +MOVL g(CX), AX // Move g into AX. +MOVL g_m(AX), BX // Move g.m into BX. +</pre> + +<p> +The <code>get_tls</code> macro is also defined on <a href="#amd64">amd64</a>. +</p> + +<p> +Addressing modes: +</p> + +<ul> + +<li> +<code>(DI)(BX*2)</code>: The location at address <code>DI</code> plus <code>BX*2</code>. +</li> + +<li> +<code>64(DI)(BX*2)</code>: The location at address <code>DI</code> plus <code>BX*2</code> plus 64. +These modes accept only 1, 2, 4, and 8 as scale factors. +</li> + +</ul> + +<p> +When using the compiler and assembler's +<code>-dynlink</code> or <code>-shared</code> modes, +any load or store of a fixed memory location such as a global variable +must be assumed to overwrite <code>CX</code>. +Therefore, to be safe for use with these modes, +assembly sources should typically avoid CX except between memory references. +</p> + +<h3 id="amd64">64-bit Intel 386 (a.k.a. amd64)</h3> + +<p> +The two architectures behave largely the same at the assembler level. +Assembly code to access the <code>m</code> and <code>g</code> +pointers on the 64-bit version is the same as on the 32-bit 386, +except it uses <code>MOVQ</code> rather than <code>MOVL</code>: +</p> + +<pre> +get_tls(CX) +MOVQ g(CX), AX // Move g into AX. +MOVQ g_m(AX), BX // Move g.m into BX. +</pre> + +<p> +Register <code>BP</code> is callee-save. +The assembler automatically inserts <code>BP</code> save/restore when frame size is larger than zero. +Using <code>BP</code> as a general purpose register is allowed, +however it can interfere with sampling-based profiling. +</p> + +<h3 id="arm">ARM</h3> + +<p> +The registers <code>R10</code> and <code>R11</code> +are reserved by the compiler and linker. +</p> + +<p> +<code>R10</code> points to the <code>g</code> (goroutine) structure. +Within assembler source code, this pointer must be referred to as <code>g</code>; +the name <code>R10</code> is not recognized. +</p> + +<p> +To make it easier for people and compilers to write assembly, the ARM linker +allows general addressing forms and pseudo-operations like <code>DIV</code> or <code>MOD</code> +that may not be expressible using a single hardware instruction. +It implements these forms as multiple instructions, often using the <code>R11</code> register +to hold temporary values. +Hand-written assembly can use <code>R11</code>, but doing so requires +being sure that the linker is not also using it to implement any of the other +instructions in the function. +</p> + +<p> +When defining a <code>TEXT</code>, specifying frame size <code>$-4</code> +tells the linker that this is a leaf function that does not need to save <code>LR</code> on entry. +</p> + +<p> +The name <code>SP</code> always refers to the virtual stack pointer described earlier. +For the hardware register, use <code>R13</code>. +</p> + +<p> +Condition code syntax is to append a period and the one- or two-letter code to the instruction, +as in <code>MOVW.EQ</code>. +Multiple codes may be appended: <code>MOVM.IA.W</code>. +The order of the code modifiers is irrelevant. +</p> + +<p> +Addressing modes: +</p> + +<ul> + +<li> +<code>R0->16</code> +<br> +<code>R0>>16</code> +<br> +<code>R0<<16</code> +<br> +<code>R0@>16</code>: +For <code><<</code>, left shift <code>R0</code> by 16 bits. +The other codes are <code>-></code> (arithmetic right shift), +<code>>></code> (logical right shift), and +<code>@></code> (rotate right). +</li> + +<li> +<code>R0->R1</code> +<br> +<code>R0>>R1</code> +<br> +<code>R0<<R1</code> +<br> +<code>R0@>R1</code>: +For <code><<</code>, left shift <code>R0</code> by the count in <code>R1</code>. +The other codes are <code>-></code> (arithmetic right shift), +<code>>></code> (logical right shift), and +<code>@></code> (rotate right). + +</li> + +<li> +<code>[R0,g,R12-R15]</code>: For multi-register instructions, the set comprising +<code>R0</code>, <code>g</code>, and <code>R12</code> through <code>R15</code> inclusive. +</li> + +<li> +<code>(R5, R6)</code>: Destination register pair. +</li> + +</ul> + +<h3 id="arm64">ARM64</h3> + +<p> +<code>R18</code> is the "platform register", reserved on the Apple platform. +To prevent accidental misuse, the register is named <code>R18_PLATFORM</code>. +<code>R27</code> and <code>R28</code> are reserved by the compiler and linker. +<code>R29</code> is the frame pointer. +<code>R30</code> is the link register. +</p> + +<p> +Instruction modifiers are appended to the instruction following a period. +The only modifiers are <code>P</code> (postincrement) and <code>W</code> +(preincrement): +<code>MOVW.P</code>, <code>MOVW.W</code> +</p> + +<p> +Addressing modes: +</p> + +<ul> + +<li> +<code>R0->16</code> +<br> +<code>R0>>16</code> +<br> +<code>R0<<16</code> +<br> +<code>R0@>16</code>: +These are the same as on the 32-bit ARM. +</li> + +<li> +<code>$(8<<12)</code>: +Left shift the immediate value <code>8</code> by <code>12</code> bits. +</li> + +<li> +<code>8(R0)</code>: +Add the value of <code>R0</code> and <code>8</code>. +</li> + +<li> +<code>(R2)(R0)</code>: +The location at <code>R0</code> plus <code>R2</code>. +</li> + +<li> +<code>R0.UXTB</code> +<br> +<code>R0.UXTB<<imm</code>: +<code>UXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and zero-extend it to the size of <code>R0</code>. +<code>R0.UXTB<<imm</code>: left shift the result of <code>R0.UXTB</code> by <code>imm</code> bits. +The <code>imm</code> value can be 0, 1, 2, 3, or 4. +The other extensions include <code>UXTH</code> (16-bit), <code>UXTW</code> (32-bit), and <code>UXTX</code> (64-bit). +</li> + +<li> +<code>R0.SXTB</code> +<br> +<code>R0.SXTB<<imm</code>: +<code>SXTB</code>: extract an 8-bit value from the low-order bits of <code>R0</code> and sign-extend it to the size of <code>R0</code>. +<code>R0.SXTB<<imm</code>: left shift the result of <code>R0.SXTB</code> by <code>imm</code> bits. +The <code>imm</code> value can be 0, 1, 2, 3, or 4. +The other extensions include <code>SXTH</code> (16-bit), <code>SXTW</code> (32-bit), and <code>SXTX</code> (64-bit). +</li> + +<li> +<code>(R5, R6)</code>: Register pair for <code>LDAXP</code>/<code>LDP</code>/<code>LDXP</code>/<code>STLXP</code>/<code>STP</code>/<code>STP</code>. +</li> + +</ul> + +<p> +Reference: <a href="/pkg/cmd/internal/obj/arm64">Go ARM64 Assembly Instructions Reference Manual</a> +</p> + +<h3 id="ppc64">PPC64</h3> + +<p> +This assembler is used by GOARCH values ppc64 and ppc64le. +</p> + +<p> +Reference: <a href="/pkg/cmd/internal/obj/ppc64">Go PPC64 Assembly Instructions Reference Manual</a> +</p> + +<h3 id="s390x">IBM z/Architecture, a.k.a. s390x</h3> + +<p> +The registers <code>R10</code> and <code>R11</code> are reserved. +The assembler uses them to hold temporary values when assembling some instructions. +</p> + +<p> +<code>R13</code> points to the <code>g</code> (goroutine) structure. +This register must be referred to as <code>g</code>; the name <code>R13</code> is not recognized. +</p> + +<p> +<code>R15</code> points to the stack frame and should typically only be accessed using the +virtual registers <code>SP</code> and <code>FP</code>. +</p> + +<p> +Load- and store-multiple instructions operate on a range of registers. +The range of registers is specified by a start register and an end register. +For example, <code>LMG</code> <code>(R9),</code> <code>R5,</code> <code>R7</code> would load +<code>R5</code>, <code>R6</code> and <code>R7</code> with the 64-bit values at +<code>0(R9)</code>, <code>8(R9)</code> and <code>16(R9)</code> respectively. +</p> + +<p> +Storage-and-storage instructions such as <code>MVC</code> and <code>XC</code> are written +with the length as the first argument. +For example, <code>XC</code> <code>$8,</code> <code>(R9),</code> <code>(R9)</code> would clear +eight bytes at the address specified in <code>R9</code>. +</p> + +<p> +If a vector instruction takes a length or an index as an argument then it will be the +first argument. +For example, <code>VLEIF</code> <code>$1,</code> <code>$16,</code> <code>V2</code> will load +the value sixteen into index one of <code>V2</code>. +Care should be taken when using vector instructions to ensure that they are available at +runtime. +To use vector instructions a machine must have both the vector facility (bit 129 in the +facility list) and kernel support. +Without kernel support a vector instruction will have no effect (it will be equivalent +to a <code>NOP</code> instruction). +</p> + +<p> +Addressing modes: +</p> + +<ul> + +<li> +<code>(R5)(R6*1)</code>: The location at <code>R5</code> plus <code>R6</code>. +It is a scaled mode as on the x86, but the only scale allowed is <code>1</code>. +</li> + +</ul> + +<h3 id="mips">MIPS, MIPS64</h3> + +<p> +General purpose registers are named <code>R0</code> through <code>R31</code>, +floating point registers are <code>F0</code> through <code>F31</code>. +</p> + +<p> +<code>R30</code> is reserved to point to <code>g</code>. +<code>R23</code> is used as a temporary register. +</p> + +<p> +In a <code>TEXT</code> directive, the frame size <code>$-4</code> for MIPS or +<code>$-8</code> for MIPS64 instructs the linker not to save <code>LR</code>. +</p> + +<p> +<code>SP</code> refers to the virtual stack pointer. +For the hardware register, use <code>R29</code>. +</p> + +<p> +Addressing modes: +</p> + +<ul> + +<li> +<code>16(R1)</code>: The location at <code>R1</code> plus 16. +</li> + +<li> +<code>(R1)</code>: Alias for <code>0(R1)</code>. +</li> + +</ul> + +<p> +The value of <code>GOMIPS</code> environment variable (<code>hardfloat</code> or +<code>softfloat</code>) is made available to assembly code by predefining either +<code>GOMIPS_hardfloat</code> or <code>GOMIPS_softfloat</code>. +</p> + +<p> +The value of <code>GOMIPS64</code> environment variable (<code>hardfloat</code> or +<code>softfloat</code>) is made available to assembly code by predefining either +<code>GOMIPS64_hardfloat</code> or <code>GOMIPS64_softfloat</code>. +</p> + +<h3 id="unsupported_opcodes">Unsupported opcodes</h3> + +<p> +The assemblers are designed to support the compiler so not all hardware instructions +are defined for all architectures: if the compiler doesn't generate it, it might not be there. +If you need to use a missing instruction, there are two ways to proceed. +One is to update the assembler to support that instruction, which is straightforward +but only worthwhile if it's likely the instruction will be used again. +Instead, for simple one-off cases, it's possible to use the <code>BYTE</code> +and <code>WORD</code> directives +to lay down explicit data into the instruction stream within a <code>TEXT</code>. +Here's how the 386 runtime defines the 64-bit atomic load function. +</p> + +<pre> +// uint64 atomicload64(uint64 volatile* addr); +// so actually +// void atomicload64(uint64 *res, uint64 volatile *addr); +TEXT runtime·atomicload64(SB), NOSPLIT, $0-12 + MOVL ptr+0(FP), AX + TESTL $7, AX + JZ 2(PC) + MOVL 0, AX // crash with nil ptr deref + LEAL ret_lo+4(FP), BX + // MOVQ (%EAX), %MM0 + BYTE $0x0f; BYTE $0x6f; BYTE $0x00 + // MOVQ %MM0, 0(%EBX) + BYTE $0x0f; BYTE $0x7f; BYTE $0x03 + // EMMS + BYTE $0x0F; BYTE $0x77 + RET +</pre> diff --git a/doc/go1.17_spec.html b/doc/go1.17_spec.html new file mode 100644 index 0000000..c87d9af --- /dev/null +++ b/doc/go1.17_spec.html @@ -0,0 +1,6864 @@ +<!--{ + "Title": "The Go Programming Language Specification", + "Subtitle": "Version of Oct 15, 2021", + "Path": "/ref/spec" +}--> + +<h2 id="Introduction">Introduction</h2> + +<p> +This is the reference manual for the Go programming language as it was for +language version 1.17, in October 2021, before the introduction of generics. +It is provided for historical interest. +The current reference manual can be found <a href="/doc/go_spec.html">here</a>. +For more information and other documents, see <a href="/">go.dev</a>. +</p> + +<p> +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 +<i>packages</i>, whose properties allow efficient management of +dependencies. +</p> + +<p> +The grammar is compact and simple to parse, allowing for easy analysis +by automatic tools such as integrated development environments. +</p> + +<h2 id="Notation">Notation</h2> +<p> +The syntax is specified using Extended Backus-Naur Form (EBNF): +</p> + +<pre class="grammar"> +Production = production_name "=" [ Expression ] "." . +Expression = Alternative { "|" Alternative } . +Alternative = Term { Term } . +Term = production_name | token [ "…" token ] | Group | Option | Repetition . +Group = "(" Expression ")" . +Option = "[" Expression "]" . +Repetition = "{" Expression "}" . +</pre> + +<p> +Productions are expressions constructed from terms and the following +operators, in increasing precedence: +</p> +<pre class="grammar"> +| alternation +() grouping +[] option (0 or 1 times) +{} repetition (0 to n times) +</pre> + +<p> +Lower-case production names are used to identify lexical tokens. +Non-terminals are in CamelCase. Lexical tokens are enclosed in +double quotes <code>""</code> or back quotes <code>``</code>. +</p> + +<p> +The form <code>a … b</code> represents the set of characters from +<code>a</code> through <code>b</code> as alternatives. The horizontal +ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various +enumerations or code snippets that are not further specified. The character <code>…</code> +(as opposed to the three characters <code>...</code>) is not a token of the Go +language. +</p> + +<h2 id="Source_code_representation">Source code representation</h2> + +<p> +Source code is Unicode text encoded in +<a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. 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 unqualified term <i>character</i> to refer to a Unicode code point +in the source text. +</p> +<p> +Each code point is distinct; for instance, upper and lower case letters +are different characters. +</p> +<p> +Implementation restriction: For compatibility with other tools, a +compiler may disallow the NUL character (U+0000) in the source text. +</p> +<p> +Implementation restriction: For compatibility with other tools, a +compiler may ignore a UTF-8-encoded byte order mark +(U+FEFF) if it is the first Unicode code point in the source text. +A byte order mark may be disallowed anywhere else in the source. +</p> + +<h3 id="Characters">Characters</h3> + +<p> +The following terms are used to denote specific Unicode character classes: +</p> +<pre class="ebnf"> +newline = /* the Unicode code point U+000A */ . +unicode_char = /* an arbitrary Unicode code point except newline */ . +unicode_letter = /* a Unicode code point classified as "Letter" */ . +unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ . +</pre> + +<p> +In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>, +Section 4.5 "General Category" defines a set of character categories. +Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo +as Unicode letters, and those in the Number category Nd as Unicode digits. +</p> + +<h3 id="Letters_and_digits">Letters and digits</h3> + +<p> +The underscore character <code>_</code> (U+005F) is considered a letter. +</p> +<pre class="ebnf"> +letter = unicode_letter | "_" . +decimal_digit = "0" … "9" . +binary_digit = "0" | "1" . +octal_digit = "0" … "7" . +hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . +</pre> + +<h2 id="Lexical_elements">Lexical elements</h2> + +<h3 id="Comments">Comments</h3> + +<p> +Comments serve as program documentation. There are two forms: +</p> + +<ol> +<li> +<i>Line comments</i> start with the character sequence <code>//</code> +and stop at the end of the line. +</li> +<li> +<i>General comments</i> start with the character sequence <code>/*</code> +and stop with the first subsequent character sequence <code>*/</code>. +</li> +</ol> + +<p> +A comment cannot start inside a <a href="#Rune_literals">rune</a> or +<a href="#String_literals">string literal</a>, or inside a comment. +A general comment containing no newlines acts like a space. +Any other comment acts like a newline. +</p> + +<h3 id="Tokens">Tokens</h3> + +<p> +Tokens form the vocabulary of the Go language. +There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators +and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from +spaces (U+0020), horizontal tabs (U+0009), +carriage returns (U+000D), and newlines (U+000A), +is ignored except as it separates tokens +that would otherwise combine into a single token. Also, a newline or end of file +may trigger the insertion of a <a href="#Semicolons">semicolon</a>. +While breaking the input into tokens, +the next token is the longest sequence of characters that form a +valid token. +</p> + +<h3 id="Semicolons">Semicolons</h3> + +<p> +The formal grammar uses semicolons <code>";"</code> as terminators in +a number of productions. Go programs may omit most of these semicolons +using the following two rules: +</p> + +<ol> +<li> +When the input is broken into tokens, a semicolon is automatically inserted +into the token stream immediately after a line's final token if that token is +<ul> + <li>an + <a href="#Identifiers">identifier</a> + </li> + + <li>an + <a href="#Integer_literals">integer</a>, + <a href="#Floating-point_literals">floating-point</a>, + <a href="#Imaginary_literals">imaginary</a>, + <a href="#Rune_literals">rune</a>, or + <a href="#String_literals">string</a> literal + </li> + + <li>one of the <a href="#Keywords">keywords</a> + <code>break</code>, + <code>continue</code>, + <code>fallthrough</code>, or + <code>return</code> + </li> + + <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a> + <code>++</code>, + <code>--</code>, + <code>)</code>, + <code>]</code>, or + <code>}</code> + </li> +</ul> +</li> + +<li> +To allow complex statements to occupy a single line, a semicolon +may be omitted before a closing <code>")"</code> or <code>"}"</code>. +</li> +</ol> + +<p> +To reflect idiomatic use, code examples in this document elide semicolons +using these rules. +</p> + + +<h3 id="Identifiers">Identifiers</h3> + +<p> +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. +</p> +<pre class="ebnf"> +identifier = letter { letter | unicode_digit } . +</pre> +<pre> +a +_x9 +ThisVariableIsExported +αβ +</pre> + +<p> +Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. +</p> + + +<h3 id="Keywords">Keywords</h3> + +<p> +The following keywords are reserved and may not be used as identifiers. +</p> +<pre class="grammar"> +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 +</pre> + +<h3 id="Operators_and_punctuation">Operators and punctuation</h3> + +<p> +The following character sequences represent <a href="#Operators">operators</a> +(including <a href="#Assignments">assignment operators</a>) and punctuation: +</p> +<pre class="grammar"> ++ & += &= && == != ( ) +- | -= |= || < <= [ ] +* ^ *= ^= <- > >= { } +/ << /= <<= ++ = := , ; +% >> %= >>= -- ! ... . : + &^ &^= +</pre> + +<h3 id="Integer_literals">Integer literals</h3> + +<p> +An integer literal is a sequence of digits representing an +<a href="#Constants">integer constant</a>. +An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code> +for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal, +and <code>0x</code> or <code>0X</code> for hexadecimal. +A single <code>0</code> is considered a decimal zero. +In hexadecimal literals, letters <code>a</code> through <code>f</code> +and <code>A</code> through <code>F</code> represent values 10 through 15. +</p> + +<p> +For readability, an underscore character <code>_</code> may appear after +a base prefix or between successive digits; such underscores do not change +the literal's value. +</p> +<pre class="ebnf"> +int_lit = decimal_lit | binary_lit | octal_lit | hex_lit . +decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] . +binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits . +octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits . +hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits . + +decimal_digits = decimal_digit { [ "_" ] decimal_digit } . +binary_digits = binary_digit { [ "_" ] binary_digit } . +octal_digits = octal_digit { [ "_" ] octal_digit } . +hex_digits = hex_digit { [ "_" ] hex_digit } . +</pre> + +<pre> +42 +4_2 +0600 +0_600 +0o600 +0O600 // second character is capital letter 'O' +0xBadFace +0xBad_Face +0x_67_7a_2f_cc_40_c6 +170141183460469231731687303715884105727 +170_141183_460469_231731_687303_715884_105727 + +_42 // an identifier, not an integer literal +42_ // invalid: _ must separate successive digits +4__2 // invalid: only one _ at a time +0_xBadFace // invalid: _ must separate successive digits +</pre> + + +<h3 id="Floating-point_literals">Floating-point literals</h3> + +<p> +A floating-point literal is a decimal or hexadecimal representation of a +<a href="#Constants">floating-point constant</a>. +</p> + +<p> +A decimal floating-point literal consists of an integer part (decimal digits), +a decimal point, a fractional part (decimal digits), and an exponent part +(<code>e</code> or <code>E</code> followed by an optional sign and decimal digits). +One of the integer part or the fractional part may be elided; one of the decimal point +or the exponent part may be elided. +An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>. +</p> + +<p> +A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code> +prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits), +and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits). +One of the integer part or the fractional part may be elided; the radix point may be elided as well, +but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.) +An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>. +</p> + +<p> +For readability, an underscore character <code>_</code> may appear after +a base prefix or between successive digits; such underscores do not change +the literal value. +</p> + +<pre class="ebnf"> +float_lit = decimal_float_lit | hex_float_lit . + +decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] | + decimal_digits decimal_exponent | + "." decimal_digits [ decimal_exponent ] . +decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits . + +hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent . +hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] | + [ "_" ] hex_digits | + "." hex_digits . +hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits . +</pre> + +<pre> +0. +72.40 +072.40 // == 72.40 +2.71828 +1.e+0 +6.67428e-11 +1E6 +.25 +.12345E+5 +1_5. // == 15.0 +0.15e+0_2 // == 15.0 + +0x1p-2 // == 0.25 +0x2.p10 // == 2048.0 +0x1.Fp+0 // == 1.9375 +0X.8p-0 // == 0.5 +0X_1FFFP-16 // == 0.1249847412109375 +0x15e-2 // == 0x15e - 2 (integer subtraction) + +0x.p1 // invalid: mantissa has no digits +1p-2 // invalid: p exponent requires hexadecimal mantissa +0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent +1_.5 // invalid: _ must separate successive digits +1._5 // invalid: _ must separate successive digits +1.5_e1 // invalid: _ must separate successive digits +1.5e_1 // invalid: _ must separate successive digits +1.5e1_ // invalid: _ must separate successive digits +</pre> + + +<h3 id="Imaginary_literals">Imaginary literals</h3> + +<p> +An imaginary literal represents the imaginary part of a +<a href="#Constants">complex constant</a>. +It consists of an <a href="#Integer_literals">integer</a> or +<a href="#Floating-point_literals">floating-point</a> literal +followed by the lower-case letter <code>i</code>. +The value of an imaginary literal is the value of the respective +integer or floating-point literal multiplied by the imaginary unit <i>i</i>. +</p> + +<pre class="ebnf"> +imaginary_lit = (decimal_digits | int_lit | float_lit) "i" . +</pre> + +<p> +For backward compatibility, an imaginary literal's integer part consisting +entirely of decimal digits (and possibly underscores) is considered a decimal +integer, even if it starts with a leading <code>0</code>. +</p> + +<pre> +0i +0123i // == 123i for backward-compatibility +0o123i // == 0o123 * 1i == 83i +0xabci // == 0xabc * 1i == 2748i +0.i +2.71828i +1.e+0i +6.67428e-11i +1E6i +.25i +.12345E+5i +0x1p-2i // == 0x1p-2 * 1i == 0.25i +</pre> + + +<h3 id="Rune_literals">Rune literals</h3> + +<p> +A rune literal represents a <a href="#Constants">rune constant</a>, +an integer value identifying a Unicode code point. +A rune literal is expressed as one or more characters enclosed in single quotes, +as in <code>'x'</code> or <code>'\n'</code>. +Within the quotes, any character may appear except newline and unescaped single +quote. A single quoted character represents the Unicode value +of the character itself, +while multi-character sequences beginning with a backslash encode +values in various formats. +</p> + +<p> +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 <code>'a'</code> holds a single byte representing +a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while +<code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing +a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. +</p> + +<p> +Several backslash escapes allow arbitrary values to be encoded as +ASCII text. There are four ways to represent the integer value +as a numeric constant: <code>\x</code> followed by exactly two hexadecimal +digits; <code>\u</code> followed by exactly four hexadecimal digits; +<code>\U</code> followed by exactly eight hexadecimal digits, and a +plain backslash <code>\</code> 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. +</p> + +<p> +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 escapes <code>\u</code> and <code>\U</code> +represent Unicode code points so within them some values are illegal, +in particular those above <code>0x10FFFF</code> and surrogate halves. +</p> + +<p> +After a backslash, certain single-character escapes represent special values: +</p> + +<pre class="grammar"> +\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 rune literals) +\" U+0022 double quote (valid escape only within string literals) +</pre> + +<p> +All other sequences starting with a backslash are illegal inside rune literals. +</p> +<pre class="ebnf"> +rune_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" | `\` | "'" | `"` ) . +</pre> + +<pre> +'a' +'ä' +'本' +'\t' +'\000' +'\007' +'\377' +'\x07' +'\xff' +'\u12e4' +'\U00101234' +'\'' // rune literal containing single quote character +'aa' // illegal: too many characters +'\xa' // illegal: too few hexadecimal digits +'\0' // illegal: too few octal digits +'\uDFFF' // illegal: surrogate half +'\U00110000' // illegal: invalid Unicode code point +</pre> + + +<h3 id="String_literals">String literals</h3> + +<p> +A string literal represents a <a href="#Constants">string constant</a> +obtained from concatenating a sequence of characters. There are two forms: +raw string literals and interpreted string literals. +</p> + +<p> +Raw string literals are character sequences between back quotes, as in +<code>`foo`</code>. Within the quotes, any character may appear except +back quote. The value of a raw string literal is the +string composed of the uninterpreted (implicitly UTF-8-encoded) characters +between the quotes; +in particular, backslashes have no special meaning and the string may +contain newlines. +Carriage return characters ('\r') inside raw string literals +are discarded from the raw string value. +</p> + +<p> +Interpreted string literals are character sequences between double +quotes, as in <code>"bar"</code>. +Within the quotes, any character may appear except newline and unescaped double quote. +The text between the quotes forms the +value of the literal, with backslash escapes interpreted as they +are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and +<code>\"</code> is legal), with the same restrictions. +The three-digit octal (<code>\</code><i>nnn</i>) +and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual +<i>bytes</i> of the resulting string; all other escapes represent +the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>. +Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent +a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, +<code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent +the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character +U+00FF. +</p> + +<pre class="ebnf"> +string_lit = raw_string_lit | interpreted_string_lit . +raw_string_lit = "`" { unicode_char | newline } "`" . +interpreted_string_lit = `"` { unicode_value | byte_value } `"` . +</pre> + +<pre> +`abc` // same as "abc" +`\n +\n` // same as "\\n\n\\n" +"\n" +"\"" // same as `"` +"Hello, world!\n" +"日本語" +"\u65e5本\U00008a9e" +"\xff\u00FF" +"\uD800" // illegal: surrogate half +"\U00110000" // illegal: invalid Unicode code point +</pre> + +<p> +These examples all represent the same string: +</p> + +<pre> +"日本語" // 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 +</pre> + +<p> +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 rune literal (it is not a single code +point), and will appear as two code points if placed in a string +literal. +</p> + + +<h2 id="Constants">Constants</h2> + +<p>There are <i>boolean constants</i>, +<i>rune constants</i>, +<i>integer constants</i>, +<i>floating-point constants</i>, <i>complex constants</i>, +and <i>string constants</i>. Rune, integer, floating-point, +and complex constants are +collectively called <i>numeric constants</i>. +</p> + +<p> +A constant value is represented by a +<a href="#Rune_literals">rune</a>, +<a href="#Integer_literals">integer</a>, +<a href="#Floating-point_literals">floating-point</a>, +<a href="#Imaginary_literals">imaginary</a>, +or +<a href="#String_literals">string</a> literal, +an identifier denoting a constant, +a <a href="#Constant_expressions">constant expression</a>, +a <a href="#Conversions">conversion</a> with a result that is a constant, or +the result value of some built-in functions such as +<code>unsafe.Sizeof</code> applied to any value, +<code>cap</code> or <code>len</code> applied to +<a href="#Length_and_capacity">some expressions</a>, +<code>real</code> and <code>imag</code> applied to a complex constant +and <code>complex</code> applied to numeric constants. +The boolean truth values are represented by the predeclared constants +<code>true</code> and <code>false</code>. The predeclared identifier +<a href="#Iota">iota</a> denotes an integer constant. +</p> + +<p> +In general, complex constants are a form of +<a href="#Constant_expressions">constant expression</a> +and are discussed in that section. +</p> + +<p> +Numeric constants represent exact values of arbitrary precision and do not overflow. +Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, +and not-a-number values. +</p> + +<p> +Constants may be <a href="#Types">typed</a> or <i>untyped</i>. +Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, +and certain <a href="#Constant_expressions">constant expressions</a> +containing only untyped constant operands are untyped. +</p> + +<p> +A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> +or <a href="#Conversions">conversion</a>, or implicitly when used in a +<a href="#Variable_declarations">variable declaration</a> or an +<a href="#Assignments">assignment</a> or as an +operand in an <a href="#Expressions">expression</a>. +It is an error if the constant value +cannot be <a href="#Representability">represented</a> as a value of the respective type. +</p> + +<p> +An untyped constant has a <i>default type</i> which is the type to which the +constant is implicitly converted in contexts where a typed value is required, +for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> +such as <code>i := 0</code> where there is no explicit type. +The default type of an untyped constant is <code>bool</code>, <code>rune</code>, +<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> +respectively, depending on whether it is a boolean, rune, integer, floating-point, +complex, or string constant. +</p> + +<p> +Implementation restriction: Although numeric constants have arbitrary +precision in the language, a compiler may implement them using an +internal representation with limited precision. That said, every +implementation must: +</p> + +<ul> + <li>Represent integer constants with at least 256 bits.</li> + + <li>Represent floating-point constants, including the parts of + a complex constant, with a mantissa of at least 256 bits + and a signed binary exponent of at least 16 bits.</li> + + <li>Give an error if unable to represent an integer constant + precisely.</li> + + <li>Give an error if unable to represent a floating-point or + complex constant due to overflow.</li> + + <li>Round to the nearest representable constant if unable to + represent a floating-point or complex constant due to limits + on precision.</li> +</ul> + +<p> +These requirements apply both to literal constants and to the result +of evaluating <a href="#Constant_expressions">constant +expressions</a>. +</p> + + +<h2 id="Variables">Variables</h2> + +<p> +A variable is a storage location for holding a <i>value</i>. +The set of permissible values is determined by the +variable's <i><a href="#Types">type</a></i>. +</p> + +<p> +A <a href="#Variable_declarations">variable declaration</a> +or, for function parameters and results, the signature +of a <a href="#Function_declarations">function declaration</a> +or <a href="#Function_literals">function literal</a> reserves +storage for a named variable. + +Calling the built-in function <a href="#Allocation"><code>new</code></a> +or taking the address of a <a href="#Composite_literals">composite literal</a> +allocates storage for a variable at run time. +Such an anonymous variable is referred to via a (possibly implicit) +<a href="#Address_operators">pointer indirection</a>. +</p> + +<p> +<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, +and <a href="#Struct_types">struct</a> types have elements and fields that may +be <a href="#Address_operators">addressed</a> individually. Each such element +acts like a variable. +</p> + +<p> +The <i>static type</i> (or just <i>type</i>) of a variable is the +type given in its declaration, the type provided in the +<code>new</code> call or composite literal, or the type of +an element of a structured variable. +Variables of interface type also have a distinct <i>dynamic type</i>, +which is the concrete type of the value assigned to the variable at run time +(unless the value is the predeclared identifier <code>nil</code>, +which has no type). +The dynamic type may vary during execution but values stored in interface +variables are always <a href="#Assignability">assignable</a> +to the static type of the variable. +</p> + +<pre> +var x interface{} // x is nil and has static type interface{} +var v *T // v has value nil, static type *T +x = 42 // x has value 42 and dynamic type int +x = v // x has value (*T)(nil) and dynamic type *T +</pre> + +<p> +A variable's value is retrieved by referring to the variable in an +<a href="#Expressions">expression</a>; it is the most recent value +<a href="#Assignments">assigned</a> to the variable. +If a variable has not yet been assigned a value, its value is the +<a href="#The_zero_value">zero value</a> for its type. +</p> + + +<h2 id="Types">Types</h2> + +<p> +A type determines a set of values together with operations and methods specific +to those values. A type may be denoted by a <i>type name</i>, if it has one, +or specified using a <i>type literal</i>, which composes a type from existing types. +</p> + +<pre class="ebnf"> +Type = TypeName | TypeLit | "(" Type ")" . +TypeName = identifier | QualifiedIdent . +TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | + SliceType | MapType | ChannelType . +</pre> + +<p> +The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. +Others are introduced with <a href="#Type_declarations">type declarations</a>. +<i>Composite types</i>—array, struct, pointer, function, +interface, slice, map, and channel types—may be constructed using +type literals. +</p> + +<p> +Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> +is one of the predeclared boolean, numeric, or string types, or a type literal, +the corresponding underlying +type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type +is the underlying type of the type to which <code>T</code> refers in its +<a href="#Type_declarations">type declaration</a>. +</p> + +<pre> +type ( + A1 = string + A2 = A1 +) + +type ( + B1 string + B2 B1 + B3 []B1 + B4 B3 +) +</pre> + +<p> +The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, +and <code>B2</code> is <code>string</code>. +The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>. +</p> + +<h3 id="Method_sets">Method sets</h3> +<p> +A type has a (possibly empty) <i>method set</i> associated with it. +The method set of an <a href="#Interface_types">interface type</a> is its interface. +The method set of any other type <code>T</code> consists of all +<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. +The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code> +is the set of all methods declared with receiver <code>*T</code> or <code>T</code> +(that is, it also contains the method set of <code>T</code>). +Further rules apply to structs containing embedded fields, as described +in the section on <a href="#Struct_types">struct types</a>. +Any other type has an empty method set. +In a method set, each method must have a +<a href="#Uniqueness_of_identifiers">unique</a> +non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. +</p> + +<p> +The method set of a type determines the interfaces that the +type <a href="#Interface_types">implements</a> +and the methods that can be <a href="#Calls">called</a> +using a receiver of that type. +</p> + +<h3 id="Boolean_types">Boolean types</h3> + +<p> +A <i>boolean type</i> represents the set of Boolean truth values +denoted by the predeclared constants <code>true</code> +and <code>false</code>. The predeclared boolean type is <code>bool</code>; +it is a <a href="#Type_definitions">defined type</a>. +</p> + +<h3 id="Numeric_types">Numeric types</h3> + +<p> +A <i>numeric type</i> represents sets of integer or floating-point values. +The predeclared architecture-independent numeric types are: +</p> + +<pre class="grammar"> +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 IEEE-754 32-bit floating-point numbers +float64 the set of all IEEE-754 64-bit floating-point numbers + +complex64 the set of all complex numbers with float32 real and imaginary parts +complex128 the set of all complex numbers with float64 real and imaginary parts + +byte alias for uint8 +rune alias for int32 +</pre> + +<p> +The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using +<a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. +</p> + +<p> +There is also a set of predeclared numeric types with implementation-specific sizes: +</p> + +<pre class="grammar"> +uint either 32 or 64 bits +int same size as uint +uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value +</pre> + +<p> +To avoid portability issues all numeric types are <a href="#Type_definitions">defined +types</a> and thus distinct except +<code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and +<code>rune</code>, which is an alias for <code>int32</code>. +Explicit conversions +are required when different numeric types are mixed in an expression +or assignment. For instance, <code>int32</code> and <code>int</code> +are not the same type even though they may have the same size on a +particular architecture. +</p> + +<h3 id="String_types">String types</h3> + +<p> +A <i>string type</i> represents the set of string values. +A string value is a (possibly empty) sequence of bytes. +The number of bytes is called the length of the string and is never negative. +Strings are immutable: once created, +it is impossible to change the contents of a string. +The predeclared string type is <code>string</code>; +it is a <a href="#Type_definitions">defined type</a>. +</p> + +<p> +The length of a string <code>s</code> can be discovered using +the built-in function <a href="#Length_and_capacity"><code>len</code></a>. +The length is a compile-time constant if the string is a constant. +A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(s)-1</code>. +It is illegal to take the address of such an element; if +<code>s[i]</code> is the <code>i</code>'th byte of a +string, <code>&s[i]</code> is invalid. +</p> + + +<h3 id="Array_types">Array types</h3> + +<p> +An array is a numbered sequence of elements of a single +type, called the element type. +The number of elements is called the length of the array and is never negative. +</p> + +<pre class="ebnf"> +ArrayType = "[" ArrayLength "]" ElementType . +ArrayLength = Expression . +ElementType = Type . +</pre> + +<p> +The length is part of the array's type; it must evaluate to a +non-negative <a href="#Constants">constant</a> +<a href="#Representability">representable</a> by a value +of type <code>int</code>. +The length of array <code>a</code> can be discovered +using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. +The elements can be addressed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(a)-1</code>. +Array types are always one-dimensional but may be composed to form +multi-dimensional types. +</p> + +<pre> +[32]byte +[2*N] struct { x, y int32 } +[1000]*float64 +[3][5]int +[2][2][2]float64 // same as [2]([2]([2]float64)) +</pre> + +<h3 id="Slice_types">Slice types</h3> + +<p> +A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and +provides access to a numbered sequence of elements from that array. +A slice type denotes the set of all slices of arrays of its element type. +The number of elements is called the length of the slice and is never negative. +The value of an uninitialized slice is <code>nil</code>. +</p> + +<pre class="ebnf"> +SliceType = "[" "]" ElementType . +</pre> + +<p> +The length of a slice <code>s</code> can be discovered by the built-in function +<a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during +execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(s)-1</code>. The slice index of a +given element may be less than the index of the same element in the +underlying array. +</p> +<p> +A slice, once initialized, is always associated with an underlying +array that holds its elements. A slice therefore shares storage +with its array and with other slices of the same array; by contrast, +distinct arrays always represent distinct storage. +</p> +<p> +The array underlying a slice may extend past the end of the slice. +The <i>capacity</i> is a measure of that extent: it is the sum of +the length of the slice and the length of the array beyond the slice; +a slice of length up to that capacity can be created by +<a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice. +The capacity of a slice <code>a</code> can be discovered using the +built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>. +</p> + +<p> +A new, initialized slice value for a given element type <code>T</code> is +made using the built-in function +<a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes a slice type +and parameters specifying the length and optionally the capacity. +A slice created with <code>make</code> always allocates a new, hidden array +to which the returned slice value refers. That is, executing +</p> + +<pre> +make([]T, length, capacity) +</pre> + +<p> +produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> +it, so these two expressions are equivalent: +</p> + +<pre> +make([]int, 50, 100) +new([100]int)[0:50] +</pre> + +<p> +Like arrays, slices are always one-dimensional but may be composed to construct +higher-dimensional objects. +With arrays of arrays, the inner arrays are, by construction, always the same length; +however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. +Moreover, the inner slices must be initialized individually. +</p> + +<h3 id="Struct_types">Struct types</h3> + +<p> +A struct is a sequence of named elements, called fields, each of which has a +name and a type. Field names may be specified explicitly (IdentifierList) or +implicitly (EmbeddedField). +Within a struct, non-<a href="#Blank_identifier">blank</a> field names must +be <a href="#Uniqueness_of_identifiers">unique</a>. +</p> + +<pre class="ebnf"> +StructType = "struct" "{" { FieldDecl ";" } "}" . +FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . +EmbeddedField = [ "*" ] TypeName . +Tag = string_lit . +</pre> + +<pre> +// An empty struct. +struct {} + +// A struct with 6 fields. +struct { + x, y int + u float32 + _ float32 // padding + A *[]int + F func() +} +</pre> + +<p> +A field declared with a type but no explicit field name is called an <i>embedded field</i>. +An embedded field must be specified as +a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>, +and <code>T</code> itself may not be +a pointer type. The unqualified type name acts as the field name. +</p> + +<pre> +// A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4 +struct { + T1 // field name is T1 + *T2 // field name is T2 + P.T3 // field name is T3 + *P.T4 // field name is T4 + x, y int // field names are x and y +} +</pre> + +<p> +The following declaration is illegal because field names must be unique +in a struct type: +</p> + +<pre> +struct { + T // conflicts with embedded field *T and *P.T + *T // conflicts with embedded field T and *P.T + *P.T // conflicts with embedded field T and *T +} +</pre> + +<p> +A field or <a href="#Method_declarations">method</a> <code>f</code> of an +embedded field in a struct <code>x</code> is called <i>promoted</i> if +<code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes +that field or method <code>f</code>. +</p> + +<p> +Promoted fields act like ordinary fields +of a struct except that they cannot be used as field names in +<a href="#Composite_literals">composite literals</a> of the struct. +</p> + +<p> +Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a> +<code>T</code>, promoted methods are included in the method set of the struct as follows: +</p> +<ul> + <li> + If <code>S</code> contains an embedded field <code>T</code>, + the <a href="#Method_sets">method sets</a> of <code>S</code> + and <code>*S</code> both include promoted methods with receiver + <code>T</code>. The method set of <code>*S</code> also + includes promoted methods with receiver <code>*T</code>. + </li> + + <li> + If <code>S</code> contains an embedded field <code>*T</code>, + the method sets of <code>S</code> and <code>*S</code> both + include promoted methods with receiver <code>T</code> or + <code>*T</code>. + </li> +</ul> + +<p> +A field declaration may be followed by an optional string literal <i>tag</i>, +which becomes an attribute for all the fields in the corresponding +field declaration. An empty tag string is equivalent to an absent tag. +The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> +and take part in <a href="#Type_identity">type identity</a> for structs +but are otherwise ignored. +</p> + +<pre> +struct { + x, y float64 "" // an empty tag string is like an absent tag + name string "any string is permitted as a tag" + _ [4]byte "ceci n'est pas un champ de structure" +} + +// A struct corresponding to a TimeStamp protocol buffer. +// The tag strings define the protocol buffer field numbers; +// they follow the convention outlined by the reflect package. +struct { + microsec uint64 `protobuf:"1"` + serverIP6 uint64 `protobuf:"2"` +} +</pre> + +<h3 id="Pointer_types">Pointer types</h3> + +<p> +A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given +type, called the <i>base type</i> of the pointer. +The value of an uninitialized pointer is <code>nil</code>. +</p> + +<pre class="ebnf"> +PointerType = "*" BaseType . +BaseType = Type . +</pre> + +<pre> +*Point +*[4]int +</pre> + +<h3 id="Function_types">Function types</h3> + +<p> +A function type denotes the set of all functions with the same parameter +and result types. The value of an uninitialized variable of function type +is <code>nil</code>. +</p> + +<pre class="ebnf"> +FunctionType = "func" Signature . +Signature = Parameters [ Result ] . +Result = Parameters | Type . +Parameters = "(" [ ParameterList [ "," ] ] ")" . +ParameterList = ParameterDecl { "," ParameterDecl } . +ParameterDecl = [ IdentifierList ] [ "..." ] Type . +</pre> + +<p> +Within a list of parameters or results, the names (IdentifierList) +must either all be present or all be absent. If present, each name +stands for one item (parameter or result) of the specified type and +all non-<a href="#Blank_identifier">blank</a> names in the signature +must be <a href="#Uniqueness_of_identifiers">unique</a>. +If absent, each type stands for one item of that type. +Parameter and result +lists are always parenthesized except that if there is exactly +one unnamed result it may be written as an unparenthesized type. +</p> + +<p> +The final incoming parameter in a function signature may have +a type prefixed with <code>...</code>. +A function with such a parameter is called <i>variadic</i> and +may be invoked with zero or more arguments for that parameter. +</p> + +<pre> +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) +</pre> + + +<h3 id="Interface_types">Interface types</h3> + +<p> +An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>. +A variable of interface type can store a value of any type with a method set +that is any superset of the interface. Such a type is said to +<i>implement the interface</i>. +The value of an uninitialized variable of interface type is <code>nil</code>. +</p> + +<pre class="ebnf"> +InterfaceType = "interface" "{" { ( MethodSpec | InterfaceTypeName ) ";" } "}" . +MethodSpec = MethodName Signature . +MethodName = identifier . +InterfaceTypeName = TypeName . +</pre> + +<p> +An interface type may specify methods <i>explicitly</i> through method specifications, +or it may <i>embed</i> methods of other interfaces through interface type names. +</p> + +<pre> +// A simple File interface. +interface { + Read([]byte) (int, error) + Write([]byte) (int, error) + Close() error +} +</pre> + +<p> +The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a> +and not <a href="#Blank_identifier">blank</a>. +</p> + +<pre> +interface { + String() string + String() string // illegal: String not unique + _(x int) // illegal: method must have non-blank name +} +</pre> + +<p> +More than one type may implement an interface. +For instance, if two types <code>S1</code> and <code>S2</code> +have the method set +</p> + +<pre> +func (p T) Read(p []byte) (n int, err error) +func (p T) Write(p []byte) (n int, err error) +func (p T) Close() error +</pre> + +<p> +(where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) +then the <code>File</code> interface is implemented by both <code>S1</code> and +<code>S2</code>, regardless of what other methods +<code>S1</code> and <code>S2</code> may have or share. +</p> + +<p> +A type implements any interface comprising any subset of its methods +and may therefore implement several distinct interfaces. For +instance, all types implement the <i>empty interface</i>: +</p> + +<pre> +interface{} +</pre> + +<p> +Similarly, consider this interface specification, +which appears within a <a href="#Type_declarations">type declaration</a> +to define an interface called <code>Locker</code>: +</p> + +<pre> +type Locker interface { + Lock() + Unlock() +} +</pre> + +<p> +If <code>S1</code> and <code>S2</code> also implement +</p> + +<pre> +func (p T) Lock() { … } +func (p T) Unlock() { … } +</pre> + +<p> +they implement the <code>Locker</code> interface as well +as the <code>File</code> interface. +</p> + +<p> +An interface <code>T</code> may use a (possibly qualified) interface type +name <code>E</code> in place of a method specification. This is called +<i>embedding</i> interface <code>E</code> in <code>T</code>. +The <a href="#Method_sets">method set</a> of <code>T</code> is the <i>union</i> +of the method sets of <code>T</code>’s explicitly declared methods and of +<code>T</code>’s embedded interfaces. +</p> + +<pre> +type Reader interface { + Read(p []byte) (n int, err error) + Close() error +} + +type Writer interface { + Write(p []byte) (n int, err error) + Close() error +} + +// ReadWriter's methods are Read, Write, and Close. +type ReadWriter interface { + Reader // includes methods of Reader in ReadWriter's method set + Writer // includes methods of Writer in ReadWriter's method set +} +</pre> + +<p> +A <i>union</i> of method sets contains the (exported and non-exported) +methods of each method set exactly once, and methods with the +<a href="#Uniqueness_of_identifiers">same</a> names must +have <a href="#Type_identity">identical</a> signatures. +</p> + +<pre> +type ReadCloser interface { + Reader // includes methods of Reader in ReadCloser's method set + Close() // illegal: signatures of Reader.Close and Close are different +} +</pre> + +<p> +An interface type <code>T</code> may not embed itself +or any interface type that embeds <code>T</code>, recursively. +</p> + +<pre> +// illegal: Bad cannot embed itself +type Bad interface { + Bad +} + +// illegal: Bad1 cannot embed itself using Bad2 +type Bad1 interface { + Bad2 +} +type Bad2 interface { + Bad1 +} +</pre> + +<h3 id="Map_types">Map types</h3> + +<p> +A map is an unordered group of elements of one type, called the +element type, indexed by a set of unique <i>keys</i> of another type, +called the key type. +The value of an uninitialized map is <code>nil</code>. +</p> + +<pre class="ebnf"> +MapType = "map" "[" KeyType "]" ElementType . +KeyType = Type . +</pre> + +<p> +The <a href="#Comparison_operators">comparison operators</a> +<code>==</code> and <code>!=</code> must be fully defined +for operands of the key type; thus the key type must not be a function, map, or +slice. +If the key type is an interface type, these +comparison operators must be defined for the dynamic key values; +failure will cause a <a href="#Run_time_panics">run-time panic</a>. + +</p> + +<pre> +map[string]int +map[*T]struct{ x, y float64 } +map[string]interface{} +</pre> + +<p> +The number of map elements is called its length. +For a map <code>m</code>, it can be discovered using the +built-in function <a href="#Length_and_capacity"><code>len</code></a> +and may change during execution. Elements may be added during execution +using <a href="#Assignments">assignments</a> and retrieved with +<a href="#Index_expressions">index expressions</a>; they may be removed with the +<a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function. +</p> +<p> +A new, empty map value is made using the built-in +function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes the map type and an optional capacity hint as arguments: +</p> + +<pre> +make(map[string]int) +make(map[string]int, 100) +</pre> + +<p> +The initial capacity does not bound its size: +maps grow to accommodate the number of items +stored in them, with the exception of <code>nil</code> maps. +A <code>nil</code> map is equivalent to an empty map except that no elements +may be added. +</p> + +<h3 id="Channel_types">Channel types</h3> + +<p> +A channel provides a mechanism for +<a href="#Go_statements">concurrently executing functions</a> +to communicate by +<a href="#Send_statements">sending</a> and +<a href="#Receive_operator">receiving</a> +values of a specified element type. +The value of an uninitialized channel is <code>nil</code>. +</p> + +<pre class="ebnf"> +ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . +</pre> + +<p> +The optional <code><-</code> operator specifies the channel <i>direction</i>, +<i>send</i> or <i>receive</i>. If no direction is given, the channel is +<i>bidirectional</i>. +A channel may be constrained only to send or only to receive by +<a href="#Assignments">assignment</a> or +explicit <a href="#Conversions">conversion</a>. +</p> + +<pre> +chan T // can be used to send and receive values of type T +chan<- float64 // can only be used to send float64s +<-chan int // can only be used to receive ints +</pre> + +<p> +The <code><-</code> operator associates with the leftmost <code>chan</code> +possible: +</p> + +<pre> +chan<- chan int // same as chan<- (chan int) +chan<- <-chan int // same as chan<- (<-chan int) +<-chan <-chan int // same as <-chan (<-chan int) +chan (<-chan int) +</pre> + +<p> +A new, initialized channel +value can be made using the built-in function +<a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes the channel type and an optional <i>capacity</i> as arguments: +</p> + +<pre> +make(chan int, 100) +</pre> + +<p> +The capacity, in number of elements, sets the size of the buffer in the channel. +If the capacity is zero or absent, the channel is unbuffered and communication +succeeds only when both a sender and receiver are ready. Otherwise, the channel +is buffered and communication succeeds without blocking if the buffer +is not full (sends) or not empty (receives). +A <code>nil</code> channel is never ready for communication. +</p> + +<p> +A channel may be closed with the built-in function +<a href="#Close"><code>close</code></a>. +The multi-valued assignment form of the +<a href="#Receive_operator">receive operator</a> +reports whether a received value was sent before +the channel was closed. +</p> + +<p> +A single channel may be used in +<a href="#Send_statements">send statements</a>, +<a href="#Receive_operator">receive operations</a>, +and calls to the built-in functions +<a href="#Length_and_capacity"><code>cap</code></a> and +<a href="#Length_and_capacity"><code>len</code></a> +by any number of goroutines without further synchronization. +Channels act as first-in-first-out queues. +For example, if one goroutine sends values on a channel +and a second goroutine receives them, the values are +received in the order sent. +</p> + +<h2 id="Properties_of_types_and_values">Properties of types and values</h2> + +<h3 id="Type_identity">Type identity</h3> + +<p> +Two types are either <i>identical</i> or <i>different</i>. +</p> + +<p> +A <a href="#Type_definitions">defined type</a> is always different from any other type. +Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are +structurally equivalent; that is, they have the same literal structure and corresponding +components have identical types. In detail: +</p> + +<ul> + <li>Two array types are identical if they have identical element types and + the same array length.</li> + + <li>Two slice types are identical if they have identical element types.</li> + + <li>Two struct types are identical if they have the same sequence of fields, + and if corresponding fields have the same names, and identical types, + and identical tags. + <a href="#Exported_identifiers">Non-exported</a> field names from different + packages are always different.</li> + + <li>Two pointer types are identical if they have identical base types.</li> + + <li>Two function types are identical if they have the same number of parameters + and result values, corresponding parameter and result types are + identical, and either both functions are variadic or neither is. + Parameter and result names are not required to match.</li> + + <li>Two interface types are identical if they have the same set of methods + with the same names and identical function types. + <a href="#Exported_identifiers">Non-exported</a> method names from different + packages are always different. The order of the methods is irrelevant.</li> + + <li>Two map types are identical if they have identical key and element types.</li> + + <li>Two channel types are identical if they have identical element types and + the same direction.</li> +</ul> + +<p> +Given the declarations +</p> + +<pre> +type ( + A0 = []string + A1 = A0 + A2 = struct{ a, b int } + A3 = int + A4 = func(A3, float64) *A0 + A5 = func(x int, _ float64) *[]string +) + +type ( + B0 A0 + B1 []string + B2 struct{ a, b int } + B3 struct{ a, c int } + B4 func(int, float64) *B0 + B5 func(x int, y float64) *A1 +) + +type C0 = B0 +</pre> + +<p> +these types are identical: +</p> + +<pre> +A0, A1, and []string +A2 and struct{ a, b int } +A3 and int +A4, func(int, float64) *[]string, and A5 + +B0 and C0 +[]int and []int +struct{ a, b *T5 } and struct{ a, b *T5 } +func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5 +</pre> + +<p> +<code>B0</code> and <code>B1</code> are different because they are new types +created by distinct <a href="#Type_definitions">type definitions</a>; +<code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> +are different because <code>B0</code> is different from <code>[]string</code>. +</p> + + +<h3 id="Assignability">Assignability</h3> + +<p> +A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> +("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies: +</p> + +<ul> +<li> +<code>x</code>'s type is identical to <code>T</code>. +</li> +<li> +<code>x</code>'s type <code>V</code> and <code>T</code> have identical +<a href="#Types">underlying types</a> and at least one of <code>V</code> +or <code>T</code> is not a <a href="#Type_definitions">defined</a> type. +</li> +<li> +<code>T</code> is an interface type and +<code>x</code> <a href="#Interface_types">implements</a> <code>T</code>. +</li> +<li> +<code>x</code> is a bidirectional channel value, <code>T</code> is a channel type, +<code>x</code>'s type <code>V</code> and <code>T</code> have identical element types, +and at least one of <code>V</code> or <code>T</code> is not a defined type. +</li> +<li> +<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> +is a pointer, function, slice, map, channel, or interface type. +</li> +<li> +<code>x</code> is an untyped <a href="#Constants">constant</a> +<a href="#Representability">representable</a> +by a value of type <code>T</code>. +</li> +</ul> + + +<h3 id="Representability">Representability</h3> + +<p> +A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i> +by a value of type <code>T</code> if one of the following conditions applies: +</p> + +<ul> +<li> +<code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. +</li> + +<li> +<code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s +precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE +negative zero further simplified to an unsigned zero. Note that constant values never result +in an IEEE negative zero, NaN, or infinity. +</li> + +<li> +<code>T</code> is a complex type, and <code>x</code>'s +<a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> +are representable by values of <code>T</code>'s component type (<code>float32</code> or +<code>float64</code>). +</li> +</ul> + +<pre> +x T x is representable by a value of T because + +'a' byte 97 is in the set of byte values +97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers +"foo" string "foo" is in the set of string values +1024 int16 1024 is in the set of 16-bit integers +42.0 byte 42 is in the set of unsigned 8-bit integers +1e10 uint64 10000000000 is in the set of unsigned 64-bit integers +2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values +-1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 +0i int 0 is an integer value +(42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values +</pre> + +<pre> +x T x is not representable by a value of T because + +0 bool 0 is not in the set of boolean values +'a' string 'a' is a rune, it is not in the set of string values +1024 byte 1024 is not in the set of unsigned 8-bit integers +-1 uint16 -1 is not in the set of unsigned 16-bit integers +1.1 int 1.1 is not an integer value +42i float32 (0 + 42i) is not in the set of float32 values +1e1000 float64 1e1000 overflows to IEEE +Inf after rounding +</pre> + + +<h2 id="Blocks">Blocks</h2> + +<p> +A <i>block</i> is a possibly empty sequence of declarations and statements +within matching brace brackets. +</p> + +<pre class="ebnf"> +Block = "{" StatementList "}" . +StatementList = { Statement ";" } . +</pre> + +<p> +In addition to explicit blocks in the source code, there are implicit blocks: +</p> + +<ol> + <li>The <i>universe block</i> encompasses all Go source text.</li> + + <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all + Go source text for that package.</li> + + <li>Each file has a <i>file block</i> containing all Go source text + in that file.</li> + + <li>Each <a href="#If_statements">"if"</a>, + <a href="#For_statements">"for"</a>, and + <a href="#Switch_statements">"switch"</a> + statement is considered to be in its own implicit block.</li> + + <li>Each clause in a <a href="#Switch_statements">"switch"</a> + or <a href="#Select_statements">"select"</a> statement + acts as an implicit block.</li> +</ol> + +<p> +Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. +</p> + + +<h2 id="Declarations_and_scope">Declarations and scope</h2> + +<p> +A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a +<a href="#Constant_declarations">constant</a>, +<a href="#Type_declarations">type</a>, +<a href="#Variable_declarations">variable</a>, +<a href="#Function_declarations">function</a>, +<a href="#Labeled_statements">label</a>, or +<a href="#Import_declarations">package</a>. +Every identifier in a program must be declared. +No identifier may be declared twice in the same block, and +no identifier may be declared in both the file and package block. +</p> + +<p> +The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier +in a declaration, but it does not introduce a binding and thus is not declared. +In the package block, the identifier <code>init</code> may only be used for +<a href="#Package_initialization"><code>init</code> function</a> declarations, +and like the blank identifier it does not introduce a new binding. +</p> + +<pre class="ebnf"> +Declaration = ConstDecl | TypeDecl | VarDecl . +TopLevelDecl = Declaration | FunctionDecl | MethodDecl . +</pre> + +<p> +The <i>scope</i> of a declared identifier is the extent of source text in which +the identifier denotes the specified constant, type, variable, function, label, or package. +</p> + +<p> +Go is lexically scoped using <a href="#Blocks">blocks</a>: +</p> + +<ol> + <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li> + + <li>The scope of an identifier denoting a constant, type, variable, + or function (but not method) declared at top level (outside any + function) is the package block.</li> + + <li>The scope of the package name of an imported package is the file block + of the file containing the import declaration.</li> + + <li>The scope of an identifier denoting a method receiver, function parameter, + or result variable is the function body.</li> + + <li>The scope of a constant or variable identifier declared + inside a function begins at the end of the ConstSpec or VarSpec + (ShortVarDecl for short variable declarations) + and ends at the end of the innermost containing block.</li> + + <li>The scope of a type identifier declared inside a function + begins at the identifier in the TypeSpec + and ends at the end of the innermost containing block.</li> +</ol> + +<p> +An identifier declared in a block may be redeclared in an inner block. +While the identifier of the inner declaration is in scope, it denotes +the entity declared by the inner declaration. +</p> + +<p> +The <a href="#Package_clause">package clause</a> is not a declaration; the package name +does not appear in any scope. Its purpose is to identify the files belonging +to the same <a href="#Packages">package</a> and to specify the default package name for import +declarations. +</p> + + +<h3 id="Label_scopes">Label scopes</h3> + +<p> +Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are +used in the <a href="#Break_statements">"break"</a>, +<a href="#Continue_statements">"continue"</a>, and +<a href="#Goto_statements">"goto"</a> statements. +It is illegal to define a label that is never used. +In contrast to other identifiers, labels are not block scoped and do +not conflict with identifiers that are not labels. The scope of a label +is the body of the function in which it is declared and excludes +the body of any nested function. +</p> + + +<h3 id="Blank_identifier">Blank identifier</h3> + +<p> +The <i>blank identifier</i> is represented by the underscore character <code>_</code>. +It serves as an anonymous placeholder instead of a regular (non-blank) +identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, +as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>. +</p> + + +<h3 id="Predeclared_identifiers">Predeclared identifiers</h3> + +<p> +The following identifiers are implicitly declared in the +<a href="#Blocks">universe block</a>: +</p> +<pre class="grammar"> +Types: + bool byte complex64 complex128 error float32 float64 + int int8 int16 int32 int64 rune string + uint uint8 uint16 uint32 uint64 uintptr + +Constants: + true false iota + +Zero value: + nil + +Functions: + append cap close complex copy delete imag len + make new panic print println real recover +</pre> + + +<h3 id="Exported_identifiers">Exported identifiers</h3> + +<p> +An identifier may be <i>exported</i> to permit access to it from another package. +An identifier is exported if both: +</p> +<ol> + <li>the first character of the identifier's name is a Unicode upper case + letter (Unicode class "Lu"); and</li> + <li>the identifier is declared in the <a href="#Blocks">package block</a> + or it is a <a href="#Struct_types">field name</a> or + <a href="#MethodName">method name</a>.</li> +</ol> +<p> +All other identifiers are not exported. +</p> + + +<h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> + +<p> +Given a set of identifiers, an identifier is called <i>unique</i> if it is +<i>different</i> from every other in the set. +Two identifiers are different if they are spelled differently, or if they +appear in different <a href="#Packages">packages</a> and are not +<a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. +</p> + +<h3 id="Constant_declarations">Constant declarations</h3> + +<p> +A constant declaration binds a list of identifiers (the names of +the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. +The number of identifiers must be equal +to the number of expressions, and the <i>n</i>th identifier on +the left is bound to the value of the <i>n</i>th expression on the +right. +</p> + +<pre class="ebnf"> +ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . +ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . + +IdentifierList = identifier { "," identifier } . +ExpressionList = Expression { "," Expression } . +</pre> + +<p> +If the type is present, all constants take the type specified, and +the expressions must be <a href="#Assignability">assignable</a> to that type. +If the type is omitted, the constants take the +individual types of the corresponding expressions. +If the expression values are untyped <a href="#Constants">constants</a>, +the declared constants remain untyped and the constant identifiers +denote the constant values. For instance, if the expression is a +floating-point literal, the constant identifier denotes a floating-point +constant, even if the literal's fractional part is zero. +</p> + +<pre> +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 +</pre> + +<p> +Within a parenthesized <code>const</code> declaration list the +expression list may be omitted from any but the first ConstSpec. +Such an empty list is equivalent to the textual substitution of the +first preceding non-empty expression list and its type if any. +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 <a href="#Iota"><code>iota</code> constant generator</a> +this mechanism permits light-weight declaration of sequential values: +</p> + +<pre> +const ( + Sunday = iota + Monday + Tuesday + Wednesday + Thursday + Friday + Partyday + numberOfDays // this constant is not exported +) +</pre> + + +<h3 id="Iota">Iota</h3> + +<p> +Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier +<code>iota</code> represents successive untyped integer <a href="#Constants"> +constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> +in that constant declaration, starting at zero. +It can be used to construct a set of related constants: +</p> + +<pre> +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 +</pre> + +<p> +By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value: +</p> + +<pre> +const ( + bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) + bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) + _, _ // (iota == 2, unused) + bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) +) +</pre> + +<p> +This last example exploits the <a href="#Constant_declarations">implicit repetition</a> +of the last non-empty expression list. +</p> + + +<h3 id="Type_declarations">Type declarations</h3> + +<p> +A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>. +Type declarations come in two forms: alias declarations and type definitions. +</p> + +<pre class="ebnf"> +TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . +TypeSpec = AliasDecl | TypeDef . +</pre> + +<h4 id="Alias_declarations">Alias declarations</h4> + +<p> +An alias declaration binds an identifier to the given type. +</p> + +<pre class="ebnf"> +AliasDecl = identifier "=" Type . +</pre> + +<p> +Within the <a href="#Declarations_and_scope">scope</a> of +the identifier, it serves as an <i>alias</i> for the type. +</p> + +<pre> +type ( + nodeList = []*Node // nodeList and []*Node are identical types + Polar = polar // Polar and polar denote identical types +) +</pre> + + +<h4 id="Type_definitions">Type definitions</h4> + +<p> +A type definition creates a new, distinct type with the same +<a href="#Types">underlying type</a> and operations as the given type, +and binds an identifier to it. +</p> + +<pre class="ebnf"> +TypeDef = identifier Type . +</pre> + +<p> +The new type is called a <i>defined type</i>. +It is <a href="#Type_identity">different</a> from any other type, +including the type it is created from. +</p> + +<pre> +type ( + Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types + polar Point // polar and Point denote different types +) + +type TreeNode struct { + left, right *TreeNode + value *Comparable +} + +type Block interface { + BlockSize() int + Encrypt(src, dst []byte) + Decrypt(src, dst []byte) +} +</pre> + +<p> +A defined type may have <a href="#Method_declarations">methods</a> associated with it. +It does not inherit any methods bound to the given type, +but the <a href="#Method_sets">method set</a> +of an interface type or of elements of a composite type remains unchanged: +</p> + +<pre> +// A Mutex is a data type with two methods, Lock and Unlock. +type Mutex struct { /* Mutex fields */ } +func (m *Mutex) Lock() { /* Lock implementation */ } +func (m *Mutex) Unlock() { /* Unlock implementation */ } + +// NewMutex has the same composition as Mutex but its method set is empty. +type NewMutex Mutex + +// The method set of PtrMutex's underlying type *Mutex remains unchanged, +// but the method set of PtrMutex is empty. +type PtrMutex *Mutex + +// The method set of *PrintableMutex contains the methods +// Lock and Unlock bound to its embedded field Mutex. +type PrintableMutex struct { + Mutex +} + +// MyBlock is an interface type that has the same method set as Block. +type MyBlock Block +</pre> + +<p> +Type definitions may be used to define different boolean, numeric, +or string types and associate methods with them: +</p> + +<pre> +type TimeZone int + +const ( + EST TimeZone = -(5 + iota) + CST + MST + PST +) + +func (tz TimeZone) String() string { + return fmt.Sprintf("GMT%+dh", tz) +} +</pre> + + +<h3 id="Variable_declarations">Variable declarations</h3> + +<p> +A variable declaration creates one or more <a href="#Variables">variables</a>, +binds corresponding identifiers to them, and gives each a type and an initial value. +</p> + +<pre class="ebnf"> +VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . +VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . +</pre> + +<pre> +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" +</pre> + +<p> +If a list of expressions is given, the variables are initialized +with the expressions following the rules for <a href="#Assignments">assignments</a>. +Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. +</p> + +<p> +If a type is present, each variable is given that type. +Otherwise, each variable is given the type of the corresponding +initialization value in the assignment. +If that value is an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; +if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>. +The predeclared value <code>nil</code> cannot be used to initialize a variable +with no explicit type. +</p> + +<pre> +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 +</pre> + +<p> +Implementation restriction: A compiler may make it illegal to declare a variable +inside a <a href="#Function_declarations">function body</a> if the variable is +never used. +</p> + +<h3 id="Short_variable_declarations">Short variable declarations</h3> + +<p> +A <i>short variable declaration</i> uses the syntax: +</p> + +<pre class="ebnf"> +ShortVarDecl = IdentifierList ":=" ExpressionList . +</pre> + +<p> +It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a> +with initializer expressions but no types: +</p> + +<pre class="grammar"> +"var" IdentifierList = ExpressionList . +</pre> + +<pre> +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 +</pre> + +<p> +Unlike regular variable declarations, a short variable declaration may <i>redeclare</i> +variables provided they were originally declared earlier in the same block +(or the parameter lists if the block is the function body) with the same type, +and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. +As a consequence, redeclaration can only appear in a multi-variable short declaration. +Redeclaration does not introduce a new variable; it just assigns a new value to the original. +</p> + +<pre> +field1, offset := nextField(str, 0) +field2, offset := nextField(str, offset) // redeclares offset +a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere +</pre> + +<p> +Short variable declarations may appear only inside functions. +In some contexts such as the initializers for +<a href="#If_statements">"if"</a>, +<a href="#For_statements">"for"</a>, or +<a href="#Switch_statements">"switch"</a> statements, +they can be used to declare local temporary variables. +</p> + +<h3 id="Function_declarations">Function declarations</h3> + +<p> +A function declaration binds an identifier, the <i>function name</i>, +to a function. +</p> + +<pre class="ebnf"> +FunctionDecl = "func" FunctionName Signature [ FunctionBody ] . +FunctionName = identifier . +FunctionBody = Block . +</pre> + +<p> +If the function's <a href="#Function_types">signature</a> declares +result parameters, the function body's statement list must end in +a <a href="#Terminating_statements">terminating statement</a>. +</p> + +<pre> +func IndexRune(s string, r rune) int { + for i, c := range s { + if c == r { + return i + } + } + // invalid: missing return statement +} +</pre> + +<p> +A function declaration may omit the body. Such a declaration provides the +signature for a function implemented outside Go, such as an assembly routine. +</p> + +<pre> +func min(x int, y int) int { + if x < y { + return x + } + return y +} + +func flushICache(begin, end uintptr) // implemented externally +</pre> + +<h3 id="Method_declarations">Method declarations</h3> + +<p> +A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>. +A method declaration binds an identifier, the <i>method name</i>, to a method, +and associates the method with the receiver's <i>base type</i>. +</p> + +<pre class="ebnf"> +MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . +Receiver = Parameters . +</pre> + +<p> +The receiver is specified via an extra parameter section preceding the method +name. That parameter section must declare a single non-variadic parameter, the receiver. +Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a +pointer to a defined type <code>T</code>. <code>T</code> is called the receiver +<i>base type</i>. A receiver base type cannot be a pointer or interface type and +it must be defined in the same package as the method. +The method is said to be <i>bound</i> to its receiver base type and the method name +is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> +or <code>*T</code>. +</p> + +<p> +A non-<a href="#Blank_identifier">blank</a> receiver identifier must be +<a href="#Uniqueness_of_identifiers">unique</a> in the method signature. +If the receiver's value is not referenced inside the body of the method, +its identifier may be omitted in the declaration. The same applies in +general to parameters of functions and methods. +</p> + +<p> +For a base type, the non-blank names of methods bound to it must be unique. +If the base type is a <a href="#Struct_types">struct type</a>, +the non-blank method and field names must be distinct. +</p> + +<p> +Given defined type <code>Point</code>, the declarations +</p> + +<pre> +func (p *Point) Length() float64 { + return math.Sqrt(p.x * p.x + p.y * p.y) +} + +func (p *Point) Scale(factor float64) { + p.x *= factor + p.y *= factor +} +</pre> + +<p> +bind the methods <code>Length</code> and <code>Scale</code>, +with receiver type <code>*Point</code>, +to the base type <code>Point</code>. +</p> + +<p> +The type of a method is the type of a function with the receiver as first +argument. For instance, the method <code>Scale</code> has type +</p> + +<pre> +func(p *Point, factor float64) +</pre> + +<p> +However, a function declared this way is not a method. +</p> + + +<h2 id="Expressions">Expressions</h2> + +<p> +An expression specifies the computation of a value by applying +operators and functions to operands. +</p> + +<h3 id="Operands">Operands</h3> + +<p> +Operands denote the elementary values in an expression. An operand may be a +literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) +non-<a href="#Blank_identifier">blank</a> identifier denoting a +<a href="#Constant_declarations">constant</a>, +<a href="#Variable_declarations">variable</a>, or +<a href="#Function_declarations">function</a>, +or a parenthesized expression. +</p> + +<p> +The <a href="#Blank_identifier">blank identifier</a> may appear as an +operand only on the left-hand side of an <a href="#Assignments">assignment</a>. +</p> + +<pre class="ebnf"> +Operand = Literal | OperandName | "(" Expression ")" . +Literal = BasicLit | CompositeLit | FunctionLit . +BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . +OperandName = identifier | QualifiedIdent . +</pre> + +<h3 id="Qualified_identifiers">Qualified identifiers</h3> + +<p> +A qualified identifier is an identifier qualified with a package name prefix. +Both the package name and the identifier must not be +<a href="#Blank_identifier">blank</a>. +</p> + +<pre class="ebnf"> +QualifiedIdent = PackageName "." identifier . +</pre> + +<p> +A qualified identifier accesses an identifier in a different package, which +must be <a href="#Import_declarations">imported</a>. +The identifier must be <a href="#Exported_identifiers">exported</a> and +declared in the <a href="#Blocks">package block</a> of that package. +</p> + +<pre> +math.Sin // denotes the Sin function in package math +</pre> + +<h3 id="Composite_literals">Composite literals</h3> + +<p> +Composite literals construct values for structs, arrays, slices, and maps +and create a new value each time they are evaluated. +They consist of the type of the literal followed by a brace-bound list of elements. +Each element may optionally be preceded by a corresponding key. +</p> + +<pre class="ebnf"> +CompositeLit = LiteralType LiteralValue . +LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | + SliceType | MapType | TypeName . +LiteralValue = "{" [ ElementList [ "," ] ] "}" . +ElementList = KeyedElement { "," KeyedElement } . +KeyedElement = [ Key ":" ] Element . +Key = FieldName | Expression | LiteralValue . +FieldName = identifier . +Element = Expression | LiteralValue . +</pre> + +<p> +The LiteralType's underlying type must be a struct, array, slice, or map type +(the grammar enforces this constraint except when the type is given +as a TypeName). +The types of the elements and keys must be <a href="#Assignability">assignable</a> +to the respective field, element, and key types of the literal type; +there is no additional conversion. +The key is interpreted as a field name for struct literals, +an index for array and slice literals, and a key for map literals. +For map literals, all elements must have a key. It is an error +to specify multiple elements with the same field name or +constant key value. For non-constant map keys, see the section on +<a href="#Order_of_evaluation">evaluation order</a>. +</p> + +<p> +For struct literals the following rules apply: +</p> +<ul> + <li>A key must be a field name declared in the struct type. + </li> + <li>An element list that does not contain any keys must + list an element for each struct field in the + order in which the fields are declared. + </li> + <li>If any element has a key, every element must have a key. + </li> + <li>An element list that contains keys does not need to + have an element for each struct field. Omitted fields + get the zero value for that field. + </li> + <li>A literal may omit the element list; such a literal evaluates + to the zero value for its type. + </li> + <li>It is an error to specify an element for a non-exported + field of a struct belonging to a different package. + </li> +</ul> + +<p> +Given the declarations +</p> +<pre> +type Point3D struct { x, y, z float64 } +type Line struct { p, q Point3D } +</pre> + +<p> +one may write +</p> + +<pre> +origin := Point3D{} // zero value for Point3D +line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x +</pre> + +<p> +For array and slice literals the following rules apply: +</p> +<ul> + <li>Each element has an associated integer index marking + its position in the array. + </li> + <li>An element with a key uses the key as its index. The + key must be a non-negative constant + <a href="#Representability">representable</a> by + a value of type <code>int</code>; and if it is typed + it must be of integer type. + </li> + <li>An element without a key uses the previous element's index plus one. + If the first element has no key, its index is zero. + </li> +</ul> + +<p> +<a href="#Address_operators">Taking the address</a> of a composite literal +generates a pointer to a unique <a href="#Variables">variable</a> initialized +with the literal's value. +</p> + +<pre> +var pointer *Point3D = &Point3D{y: 1000} +</pre> + +<p> +Note that the <a href="#The_zero_value">zero value</a> for a slice or map +type is not the same as an initialized but empty value of the same type. +Consequently, taking the address of an empty slice or map composite literal +does not have the same effect as allocating a new slice or map value with +<a href="#Allocation">new</a>. +</p> + +<pre> +p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0 +p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0 +</pre> + +<p> +The length of an array literal is the length specified in the literal type. +If fewer elements than the length are provided in the literal, the missing +elements are set to the zero value for the array element type. +It is an error to provide elements with index values outside the index range +of the array. The notation <code>...</code> specifies an array length equal +to the maximum element index plus one. +</p> + +<pre> +buffer := [10]string{} // len(buffer) == 10 +intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 +days := [...]string{"Sat", "Sun"} // len(days) == 2 +</pre> + +<p> +A slice literal describes the entire underlying array literal. +Thus the length and capacity of a slice literal are the maximum +element index plus one. A slice literal has the form +</p> + +<pre> +[]T{x1, x2, … xn} +</pre> + +<p> +and is shorthand for a slice operation applied to an array: +</p> + +<pre> +tmp := [n]T{x1, x2, … xn} +tmp[0 : n] +</pre> + +<p> +Within a composite literal of array, slice, or map type <code>T</code>, +elements or map keys that are themselves composite literals may elide the respective +literal type if it is identical to the element or key type of <code>T</code>. +Similarly, elements or keys that are addresses of composite literals may elide +the <code>&T</code> when the element or key type is <code>*T</code>. +</p> + +<pre> +[...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} +[][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} +[][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} +map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}} +map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"} + +type PPoint *Point +[2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} +[2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})} +</pre> + +<p> +A parsing ambiguity arises when a composite literal using the +TypeName form of the LiteralType appears as an operand between the +<a href="#Keywords">keyword</a> and the opening brace of the block +of an "if", "for", or "switch" statement, and the composite literal +is not enclosed in parentheses, square brackets, or curly braces. +In this rare case, the opening brace of the literal is erroneously parsed +as the one introducing the block of statements. To resolve the ambiguity, +the composite literal must appear within parentheses. +</p> + +<pre> +if x == (T{a,b,c}[i]) { … } +if (x == T{a,b,c}[i]) { … } +</pre> + +<p> +Examples of valid array, slice, and map literals: +</p> + +<pre> +// list of prime numbers +primes := []int{2, 3, 5, 7, 9, 2147483647} + +// vowels[ch] is true if ch is a vowel +vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true} + +// the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} +filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} + +// frequencies in Hz for equal-tempered scale (A4 = 440Hz) +noteFrequency := map[string]float32{ + "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, + "G0": 24.50, "A0": 27.50, "B0": 30.87, +} +</pre> + + +<h3 id="Function_literals">Function literals</h3> + +<p> +A function literal represents an anonymous <a href="#Function_declarations">function</a>. +</p> + +<pre class="ebnf"> +FunctionLit = "func" Signature FunctionBody . +</pre> + +<pre> +func(a, b int, z float64) bool { return a*b < int(z) } +</pre> + +<p> +A function literal can be assigned to a variable or invoked directly. +</p> + +<pre> +f := func(x, y int) int { return x + y } +func(ch chan int) { ch <- ACK }(replyChan) +</pre> + +<p> +Function literals are <i>closures</i>: 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. +</p> + + +<h3 id="Primary_expressions">Primary expressions</h3> + +<p> +Primary expressions are the operands for unary and binary expressions. +</p> + +<pre class="ebnf"> +PrimaryExpr = + Operand | + Conversion | + MethodExpr | + PrimaryExpr Selector | + PrimaryExpr Index | + PrimaryExpr Slice | + PrimaryExpr TypeAssertion | + PrimaryExpr Arguments . + +Selector = "." identifier . +Index = "[" Expression "]" . +Slice = "[" [ Expression ] ":" [ Expression ] "]" | + "[" [ Expression ] ":" Expression ":" Expression "]" . +TypeAssertion = "." "(" Type ")" . +Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . +</pre> + + +<pre> +x +2 +(s + ".txt") +f(3.1415, true) +Point{1, 2} +m["foo"] +s[i : j + 1] +obj.color +f.p[i].x() +</pre> + + +<h3 id="Selectors">Selectors</h3> + +<p> +For a <a href="#Primary_expressions">primary expression</a> <code>x</code> +that is not a <a href="#Package_clause">package name</a>, the +<i>selector expression</i> +</p> + +<pre> +x.f +</pre> + +<p> +denotes the field or method <code>f</code> of the value <code>x</code> +(or sometimes <code>*x</code>; see below). +The identifier <code>f</code> is called the (field or method) <i>selector</i>; +it must not be the <a href="#Blank_identifier">blank identifier</a>. +The type of the selector expression is the type of <code>f</code>. +If <code>x</code> is a package name, see the section on +<a href="#Qualified_identifiers">qualified identifiers</a>. +</p> + +<p> +A selector <code>f</code> may denote a field or method <code>f</code> of +a type <code>T</code>, or it may refer +to a field or method <code>f</code> of a nested +<a href="#Struct_types">embedded field</a> of <code>T</code>. +The number of embedded fields traversed +to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. +The depth of a field or method <code>f</code> +declared in <code>T</code> is zero. +The depth of a field or method <code>f</code> declared in +an embedded field <code>A</code> in <code>T</code> is the +depth of <code>f</code> in <code>A</code> plus one. +</p> + +<p> +The following rules apply to selectors: +</p> + +<ol> +<li> +For a value <code>x</code> of type <code>T</code> or <code>*T</code> +where <code>T</code> is not a pointer or interface type, +<code>x.f</code> denotes the field or method at the shallowest depth +in <code>T</code> where there +is such an <code>f</code>. +If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> +with shallowest depth, the selector expression is illegal. +</li> + +<li> +For a value <code>x</code> of type <code>I</code> where <code>I</code> +is an interface type, <code>x.f</code> denotes the actual method with name +<code>f</code> of the dynamic value of <code>x</code>. +If there is no method with name <code>f</code> in the +<a href="#Method_sets">method set</a> of <code>I</code>, the selector +expression is illegal. +</li> + +<li> +As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> +pointer type and <code>(*x).f</code> is a valid selector expression denoting a field +(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. +</li> + +<li> +In all other cases, <code>x.f</code> is illegal. +</li> + +<li> +If <code>x</code> is of pointer type and has the value +<code>nil</code> and <code>x.f</code> denotes a struct field, +assigning to or evaluating <code>x.f</code> +causes a <a href="#Run_time_panics">run-time panic</a>. +</li> + +<li> +If <code>x</code> is of interface type and has the value +<code>nil</code>, <a href="#Calls">calling</a> or +<a href="#Method_values">evaluating</a> the method <code>x.f</code> +causes a <a href="#Run_time_panics">run-time panic</a>. +</li> +</ol> + +<p> +For example, given the declarations: +</p> + +<pre> +type T0 struct { + x int +} + +func (*T0) M0() + +type T1 struct { + y int +} + +func (T1) M1() + +type T2 struct { + z int + T1 + *T0 +} + +func (*T2) M2() + +type Q *T2 + +var t T2 // with t.T0 != nil +var p *T2 // with p != nil and (*p).T0 != nil +var q Q = p +</pre> + +<p> +one may write: +</p> + +<pre> +t.z // t.z +t.y // t.T1.y +t.x // (*t.T0).x + +p.z // (*p).z +p.y // (*p).T1.y +p.x // (*(*p).T0).x + +q.x // (*(*q).T0).x (*q).x is a valid field selector + +p.M0() // ((*p).T0).M0() M0 expects *T0 receiver +p.M1() // ((*p).T1).M1() M1 expects T1 receiver +p.M2() // p.M2() M2 expects *T2 receiver +t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls +</pre> + +<p> +but the following is invalid: +</p> + +<pre> +q.M0() // (*q).M0 is valid but not a field selector +</pre> + + +<h3 id="Method_expressions">Method expressions</h3> + +<p> +If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>T.M</code> is a function that is callable as a regular function +with the same arguments as <code>M</code> prefixed by an additional +argument that is the receiver of the method. +</p> + +<pre class="ebnf"> +MethodExpr = ReceiverType "." MethodName . +ReceiverType = Type . +</pre> + +<p> +Consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +</pre> + +<p> +The expression +</p> + +<pre> +T.Mv +</pre> + +<p> +yields a function equivalent to <code>Mv</code> but +with an explicit receiver as its first argument; it has signature +</p> + +<pre> +func(tv T, a int) int +</pre> + +<p> +That function may be called normally with an explicit receiver, so +these five invocations are equivalent: +</p> + +<pre> +t.Mv(7) +T.Mv(t, 7) +(T).Mv(t, 7) +f1 := T.Mv; f1(t, 7) +f2 := (T).Mv; f2(t, 7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +(*T).Mp +</pre> + +<p> +yields a function value representing <code>Mp</code> with signature +</p> + +<pre> +func(tp *T, f float32) float32 +</pre> + +<p> +For a method with a value receiver, one can derive a function +with an explicit pointer receiver, so +</p> + +<pre> +(*T).Mv +</pre> + +<p> +yields a function value representing <code>Mv</code> with signature +</p> + +<pre> +func(tv *T, a int) int +</pre> + +<p> +Such a function indirects through the receiver to create a value +to pass as the receiver to the underlying method; +the method does not overwrite the value whose address is passed in +the function call. +</p> + +<p> +The final case, a value-receiver function for a pointer-receiver method, +is illegal because pointer-receiver methods are not in the method set +of the value type. +</p> + +<p> +Function values derived from methods are called with function call syntax; +the receiver is provided as the first argument to the call. +That is, given <code>f := T.Mv</code>, <code>f</code> is invoked +as <code>f(t, 7)</code> not <code>t.f(7)</code>. +To construct a function that binds the receiver, use a +<a href="#Function_literals">function literal</a> or +<a href="#Method_values">method value</a>. +</p> + +<p> +It is legal to derive a function value from a method of an interface type. +The resulting function takes an explicit receiver of that interface type. +</p> + +<h3 id="Method_values">Method values</h3> + +<p> +If the expression <code>x</code> has static type <code>T</code> and +<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>x.M</code> is called a <i>method value</i>. +The method value <code>x.M</code> is a function value that is callable +with the same arguments as a method call of <code>x.M</code>. +The expression <code>x</code> is evaluated and saved during the evaluation of the +method value; the saved copy is then used as the receiver in any calls, +which may be executed later. +</p> + +<pre> +type S struct { *T } +type T int +func (t T) M() { print(t) } + +t := new(T) +s := S{T: t} +f := t.M // receiver *t is evaluated and stored in f +g := s.M // receiver *(s.T) is evaluated and stored in g +*t = 42 // does not affect stored receivers in f and g +</pre> + +<p> +The type <code>T</code> may be an interface or non-interface type. +</p> + +<p> +As in the discussion of <a href="#Method_expressions">method expressions</a> above, +consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +var pt *T +func makeT() T +</pre> + +<p> +The expression +</p> + +<pre> +t.Mv +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(int) int +</pre> + +<p> +These two invocations are equivalent: +</p> + +<pre> +t.Mv(7) +f := t.Mv; f(7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +pt.Mp +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(float32) float32 +</pre> + +<p> +As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver +using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. +</p> + +<p> +As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver +using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. +</p> + +<pre> +f := t.Mv; f(7) // like t.Mv(7) +f := pt.Mp; f(7) // like pt.Mp(7) +f := pt.Mv; f(7) // like (*pt).Mv(7) +f := t.Mp; f(7) // like (&t).Mp(7) +f := makeT().Mp // invalid: result of makeT() is not addressable +</pre> + +<p> +Although the examples above use non-interface types, it is also legal to create a method value +from a value of interface type. +</p> + +<pre> +var i interface { M(int) } = myVal +f := i.M; f(7) // like i.M(7) +</pre> + + +<h3 id="Index_expressions">Index expressions</h3> + +<p> +A primary expression of the form +</p> + +<pre> +a[x] +</pre> + +<p> +denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. +The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively. +The following rules apply: +</p> + +<p> +If <code>a</code> is not a map: +</p> +<ul> + <li>the index <code>x</code> must be of integer type or an untyped constant</li> + <li>a constant index must be non-negative and + <a href="#Representability">representable</a> by a value of type <code>int</code></li> + <li>a constant index that is untyped is given type <code>int</code></li> + <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>, + otherwise it is <i>out of range</i></li> +</ul> + +<p> +For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>: +</p> +<ul> + <li>a <a href="#Constants">constant</a> index must be in range</li> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the array element at index <code>x</code> and the type of + <code>a[x]</code> is the element type of <code>A</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type: +</p> +<ul> + <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: +</p> +<ul> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of + <code>a[x]</code> is the element type of <code>S</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#String_types">string type</a>: +</p> +<ul> + <li>a <a href="#Constants">constant</a> index must be in range + if the string <code>a</code> is also constant</li> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of + <code>a[x]</code> is <code>byte</code></li> + <li><code>a[x]</code> may not be assigned to</li> +</ul> + +<p> +For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>: +</p> +<ul> + <li><code>x</code>'s type must be + <a href="#Assignability">assignable</a> + to the key type of <code>M</code></li> + <li>if the map contains an entry with key <code>x</code>, + <code>a[x]</code> is the map element with key <code>x</code> + and the type of <code>a[x]</code> is the element type of <code>M</code></li> + <li>if the map is <code>nil</code> or does not contain such an entry, + <code>a[x]</code> is the <a href="#The_zero_value">zero value</a> + for the element type of <code>M</code></li> +</ul> + +<p> +Otherwise <code>a[x]</code> is illegal. +</p> + +<p> +An index expression on a map <code>a</code> of type <code>map[K]V</code> +used in an <a href="#Assignments">assignment</a> or initialization of the special form +</p> + +<pre> +v, ok = a[x] +v, ok := a[x] +var v, ok = a[x] +</pre> + +<p> +yields an additional untyped boolean value. The value of <code>ok</code> is +<code>true</code> if the key <code>x</code> is present in the map, and +<code>false</code> otherwise. +</p> + +<p> +Assigning to an element of a <code>nil</code> map causes a +<a href="#Run_time_panics">run-time panic</a>. +</p> + + +<h3 id="Slice_expressions">Slice expressions</h3> + +<p> +Slice expressions construct a substring or slice from a string, array, pointer +to array, or slice. There are two variants: a simple form that specifies a low +and high bound, and a full form that also specifies a bound on the capacity. +</p> + +<h4>Simple slice expressions</h4> + +<p> +For a string, array, pointer to array, or slice <code>a</code>, the primary expression +</p> + +<pre> +a[low : high] +</pre> + +<p> +constructs a substring or slice. The <i>indices</i> <code>low</code> and +<code>high</code> select which elements of operand <code>a</code> appear +in the result. The result has indices starting at 0 and length equal to +<code>high</code> - <code>low</code>. +After slicing the array <code>a</code> +</p> + +<pre> +a := [5]int{1, 2, 3, 4, 5} +s := a[1:4] +</pre> + +<p> +the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements +</p> + +<pre> +s[0] == 2 +s[1] == 3 +s[2] == 4 +</pre> + +<p> +For convenience, any of the indices may be omitted. A missing <code>low</code> +index defaults to zero; a missing <code>high</code> index defaults to the length of the +sliced operand: +</p> + +<pre> +a[2:] // same as a[2 : len(a)] +a[:3] // same as a[0 : 3] +a[:] // same as a[0 : len(a)] +</pre> + +<p> +If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for +<code>(*a)[low : high]</code>. +</p> + +<p> +For arrays or strings, the indices are <i>in range</i> if +<code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>, +otherwise they are <i>out of range</i>. +For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. +A <a href="#Constants">constant</a> index must be non-negative and +<a href="#Representability">representable</a> by a value of type +<code>int</code>; for arrays or constant strings, constant indices must also be in range. +If both indices are constant, they must satisfy <code>low <= high</code>. +If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<p> +Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, +the result of the slice operation is a non-constant value of the same type as the operand. +For untyped string operands the result is a non-constant value of type <code>string</code>. +If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> +and the result of the slice operation is a slice with the same element type as the array. +</p> + +<p> +If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result +is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying +array with the operand. +</p> + +<pre> +var a [10]int +s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5] +s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5] +s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element +</pre> + + +<h4>Full slice expressions</h4> + +<p> +For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression +</p> + +<pre> +a[low : high : max] +</pre> + +<p> +constructs a slice of the same type, and with the same length and elements as the simple slice +expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity +by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. +After slicing the array <code>a</code> +</p> + +<pre> +a := [5]int{1, 2, 3, 4, 5} +t := a[1:3:5] +</pre> + +<p> +the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements +</p> + +<pre> +t[0] == 2 +t[1] == 3 +</pre> + +<p> +As for simple slice expressions, if <code>a</code> is a pointer to an array, +<code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. +If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. +</p> + +<p> +The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, +otherwise they are <i>out of range</i>. +A <a href="#Constants">constant</a> index must be non-negative and +<a href="#Representability">representable</a> by a value of type +<code>int</code>; for arrays, constant indices must also be in range. +If multiple indices are constant, the constants that are present must be in range relative to each +other. +If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<h3 id="Type_assertions">Type assertions</h3> + +<p> +For an expression <code>x</code> of <a href="#Interface_types">interface type</a> +and a type <code>T</code>, the primary expression +</p> + +<pre> +x.(T) +</pre> + +<p> +asserts that <code>x</code> is not <code>nil</code> +and that the value stored in <code>x</code> is of type <code>T</code>. +The notation <code>x.(T)</code> is called a <i>type assertion</i>. +</p> +<p> +More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts +that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> +to the type <code>T</code>. +In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; +otherwise the type assertion is invalid since it is not possible for <code>x</code> +to store a value of type <code>T</code>. +If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type +of <code>x</code> implements the interface <code>T</code>. +</p> +<p> +If the type assertion holds, the value of the expression is the value +stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, +a <a href="#Run_time_panics">run-time panic</a> occurs. +In other words, even though the dynamic type of <code>x</code> +is known only at run time, the type of <code>x.(T)</code> is +known to be <code>T</code> in a correct program. +</p> + +<pre> +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 (missing method m) + r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader + … +} +</pre> + +<p> +A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form +</p> + +<pre> +v, ok = x.(T) +v, ok := x.(T) +var v, ok = x.(T) +var v, ok interface{} = x.(T) // dynamic types of v and ok are T and bool +</pre> + +<p> +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> +if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is +the <a href="#The_zero_value">zero value</a> for type <code>T</code>. +No <a href="#Run_time_panics">run-time panic</a> occurs in this case. +</p> + + +<h3 id="Calls">Calls</h3> + +<p> +Given an expression <code>f</code> of function type +<code>F</code>, +</p> + +<pre> +f(a1, a2, … an) +</pre> + +<p> +calls <code>f</code> with arguments <code>a1, a2, … an</code>. +Except for one special case, arguments must be single-valued expressions +<a href="#Assignability">assignable</a> to the parameter types of +<code>F</code> and are evaluated before the function is called. +The type of the expression is the result type +of <code>F</code>. +A method invocation is similar but the method itself +is specified as a selector upon a value of the receiver type for +the method. +</p> + +<pre> +math.Atan2(x, y) // function call +var pt *Point +pt.Scale(3.5) // method call with receiver pt +</pre> + +<p> +In a function call, the function value and arguments are evaluated in +<a href="#Order_of_evaluation">the usual order</a>. +After they are evaluated, the parameters of the call are passed by value to the function +and the called function begins execution. +The return parameters of the function are passed by value +back to the caller when the function returns. +</p> + +<p> +Calling a <code>nil</code> function value +causes a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<p> +As a special case, if the return values of a function or method +<code>g</code> are equal in number and individually +assignable to the parameters of another function or method +<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code> +will invoke <code>f</code> after binding the return values of +<code>g</code> to the parameters of <code>f</code> in order. The call +of <code>f</code> must contain no parameters other than the call of <code>g</code>, +and <code>g</code> must have at least one return value. +If <code>f</code> has a final <code>...</code> parameter, it is +assigned the return values of <code>g</code> that remain after +assignment of regular parameters. +</p> + +<pre> +func Split(s string, pos int) (string, string) { + return s[0:pos], s[pos:] +} + +func Join(s, t string) string { + return s + t +} + +if Join(Split(value, len(value)/2)) != value { + log.Panic("test fails") +} +</pre> + +<p> +A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> +of (the type of) <code>x</code> contains <code>m</code> and the +argument list can be assigned to the parameter list of <code>m</code>. +If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method +set contains <code>m</code>, <code>x.m()</code> is shorthand +for <code>(&x).m()</code>: +</p> + +<pre> +var p Point +p.Scale(3.5) +</pre> + +<p> +There is no distinct method type and there are no method literals. +</p> + +<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> + +<p> +If <code>f</code> is <a href="#Function_types">variadic</a> with a final +parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> +the type of <code>p</code> is equivalent to type <code>[]T</code>. +If <code>f</code> is invoked with no actual arguments for <code>p</code>, +the value passed to <code>p</code> is <code>nil</code>. +Otherwise, the value passed is a new slice +of type <code>[]T</code> with a new underlying array whose successive elements +are the actual arguments, which all must be <a href="#Assignability">assignable</a> +to <code>T</code>. The length and capacity of the slice is therefore +the number of arguments bound to <code>p</code> and may differ for each +call site. +</p> + +<p> +Given the function and calls +</p> +<pre> +func Greeting(prefix string, who ...string) +Greeting("nobody") +Greeting("hello:", "Joe", "Anna", "Eileen") +</pre> + +<p> +within <code>Greeting</code>, <code>who</code> will have the value +<code>nil</code> in the first call, and +<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. +</p> + +<p> +If the final argument is assignable to a slice type <code>[]T</code> and +is followed by <code>...</code>, it is passed unchanged as the value +for a <code>...T</code> parameter. In this case no new slice is created. +</p> + +<p> +Given the slice <code>s</code> and call +</p> + +<pre> +s := []string{"James", "Jasmine"} +Greeting("goodbye:", s...) +</pre> + +<p> +within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> +with the same underlying array. +</p> + + +<h3 id="Operators">Operators</h3> + +<p> +Operators combine operands into expressions. +</p> + +<pre class="ebnf"> +Expression = UnaryExpr | Expression binary_op Expression . +UnaryExpr = PrimaryExpr | unary_op UnaryExpr . + +binary_op = "||" | "&&" | rel_op | add_op | mul_op . +rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . +add_op = "+" | "-" | "|" | "^" . +mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . + +unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . +</pre> + +<p> +Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. +For other binary operators, the operand types must be <a href="#Type_identity">identical</a> +unless the operation involves shifts or untyped <a href="#Constants">constants</a>. +For operations involving constants only, see the section on +<a href="#Constant_expressions">constant expressions</a>. +</p> + +<p> +Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> +and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a> +to the type of the other operand. +</p> + +<p> +The right operand in a shift expression must have integer type +or be an untyped constant <a href="#Representability">representable</a> by a +value of type <code>uint</code>. +If the left operand of a non-constant shift expression is an untyped constant, +it is first implicitly converted to the type it would assume if the shift expression were +replaced by its left operand alone. +</p> + +<pre> +var a [1024]byte +var s uint = 33 + +// The results of the following examples are given for 64-bit ints. +var i = 1<<s // 1 has type int +var j int32 = 1<<s // 1 has type int32; j == 0 +var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 +var m int = 1.0<<s // 1.0 has type int; m == 1<<33 +var n = 1.0<<s == j // 1.0 has type int32; n == true +var o = 1<<s == 2<<s // 1 and 2 have type int; o == false +var p = 1<<s == 1<<33 // 1 has type int; p == true +var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift +var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift +var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift +var v float32 = 1<<s // illegal: 1 has type float32, cannot shift +var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression; w == 1<<33 +var x = a[1.0<<s] // panics: 1.0 has type int, but 1<<33 overflows array bounds +var b = make([]byte, 1.0<<s) // 1.0 has type int; len(b) == 1<<33 + +// The results of the following examples are given for 32-bit ints, +// which means the shifts will overflow. +var mm int = 1.0<<s // 1.0 has type int; mm == 0 +var oo = 1<<s == 2<<s // 1 and 2 have type int; oo == true +var pp = 1<<s == 1<<33 // illegal: 1 has type int, but 1<<33 overflows int +var xx = a[1.0<<s] // 1.0 has type int; xx == a[0] +var bb = make([]byte, 1.0<<s) // 1.0 has type int; len(bb) == 0 +</pre> + +<h4 id="Operator_precedence">Operator precedence</h4> +<p> +Unary operators have the highest precedence. +As the <code>++</code> and <code>--</code> operators form +statements, not expressions, they fall +outside the operator hierarchy. +As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. +</p> + +<p> +There are five precedence levels for binary operators. +Multiplication operators bind strongest, followed by addition +operators, comparison operators, <code>&&</code> (logical AND), +and finally <code>||</code> (logical OR): +</p> + +<pre class="grammar"> +Precedence Operator + 5 * / % << >> & &^ + 4 + - | ^ + 3 == != < <= > >= + 2 && + 1 || +</pre> + +<p> +Binary operators of the same precedence associate from left to right. +For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. +</p> + +<pre> ++x +23 + 3*x[i] +x <= f() +^a >> b +f() || g() +x == y+1 && <-chanInt > 0 +</pre> + + +<h3 id="Arithmetic_operators">Arithmetic operators</h3> +<p> +Arithmetic operators apply to numeric values and yield a result of the same +type as the first operand. The four standard arithmetic operators (<code>+</code>, +<code>-</code>, <code>*</code>, <code>/</code>) apply to integer, +floating-point, and complex types; <code>+</code> also applies to strings. +The bitwise logical and shift operators apply to integers only. +</p> + +<pre class="grammar"> ++ sum integers, floats, complex values, strings +- difference integers, floats, complex values +* product integers, floats, complex values +/ quotient integers, floats, complex values +% remainder integers + +& bitwise AND integers +| bitwise OR integers +^ bitwise XOR integers +&^ bit clear (AND NOT) integers + +<< left shift integer << integer >= 0 +>> right shift integer >> integer >= 0 +</pre> + + +<h4 id="Integer_operators">Integer operators</h4> + +<p> +For two integer values <code>x</code> and <code>y</code>, the integer quotient +<code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following +relationships: +</p> + +<pre> +x = q*y + r and |r| < |y| +</pre> + +<p> +with <code>x / y</code> truncated towards zero +(<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). +</p> + +<pre> + x y x / y x % y + 5 3 1 2 +-5 3 -1 -2 + 5 -3 -1 2 +-5 -3 1 -2 +</pre> + +<p> +The one exception to this rule is that if the dividend <code>x</code> is +the most negative value for the int type of <code>x</code>, the quotient +<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) +due to two's-complement <a href="#Integer_overflow">integer overflow</a>: +</p> + +<pre> + x, q +int8 -128 +int16 -32768 +int32 -2147483648 +int64 -9223372036854775808 +</pre> + +<p> +If the divisor is a <a href="#Constants">constant</a>, it must not be zero. +If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +If the dividend is non-negative and the divisor is a constant power of 2, +the division may be replaced by a right shift, and computing the remainder may +be replaced by a bitwise AND operation: +</p> + +<pre> + x x / 4 x % 4 x >> 2 x & 3 + 11 2 3 2 3 +-11 -2 -3 -3 1 +</pre> + +<p> +The shift operators shift the left operand by the shift count specified by the +right operand, which must be non-negative. If the shift count is negative at run time, +a <a href="#Run_time_panics">run-time panic</a> occurs. +The shift operators implement arithmetic shifts if the left operand is a signed +integer and logical shifts if it is an unsigned integer. +There is no upper limit on the shift count. Shifts behave +as if the left operand is shifted <code>n</code> times by 1 for a shift +count of <code>n</code>. +As a result, <code>x << 1</code> is the same as <code>x*2</code> +and <code>x >> 1</code> is the same as +<code>x/2</code> but truncated towards negative infinity. +</p> + +<p> +For integer operands, the unary operators +<code>+</code>, <code>-</code>, and <code>^</code> are defined as +follows: +</p> + +<pre class="grammar"> ++x is 0 + x +-x negation is 0 - x +^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x + and m = -1 for signed x +</pre> + + +<h4 id="Integer_overflow">Integer overflow</h4> + +<p> +For unsigned integer values, the operations <code>+</code>, +<code>-</code>, <code>*</code>, and <code><<</code> are +computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of +the <a href="#Numeric_types">unsigned integer</a>'s type. +Loosely speaking, these unsigned integer operations +discard high bits upon overflow, and programs may rely on "wrap around". +</p> +<p> +For signed integers, the operations <code>+</code>, +<code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally +overflow and the resulting value exists and is deterministically defined +by the signed integer representation, the operation, and its operands. +Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>. +A compiler may not optimize code under the assumption that overflow does +not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. +</p> + + +<h4 id="Floating_point_operators">Floating-point operators</h4> + +<p> +For floating-point and complex numbers, +<code>+x</code> is the same as <code>x</code>, +while <code>-x</code> is the negation of <code>x</code>. +The result of a floating-point or complex division by zero is not specified beyond the +IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> +occurs is implementation-specific. +</p> + +<p> +An implementation may combine multiple floating-point operations into a single +fused operation, possibly across statements, and produce a result that differs +from the value obtained by executing and rounding the instructions individually. +An explicit floating-point type <a href="#Conversions">conversion</a> rounds to +the precision of the target type, preventing fusion that would discard that rounding. +</p> + +<p> +For instance, some architectures provide a "fused multiply and add" (FMA) instruction +that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>. +These examples show when a Go implementation can use that instruction: +</p> + +<pre> +// FMA allowed for computing r, because x*y is not explicitly rounded: +r = x*y + z +r = z; r += x*y +t = x*y; r = t + z +*p = x*y; r = *p + z +r = x*y + float64(z) + +// FMA disallowed for computing r, because it would omit rounding of x*y: +r = float64(x*y) + z +r = z; r += float64(x*y) +t = float64(x*y); r = t + z +</pre> + +<h4 id="String_concatenation">String concatenation</h4> + +<p> +Strings can be concatenated using the <code>+</code> operator +or the <code>+=</code> assignment operator: +</p> + +<pre> +s := "hi" + string(c) +s += " and good bye" +</pre> + +<p> +String addition creates a new string by concatenating the operands. +</p> + + +<h3 id="Comparison_operators">Comparison operators</h3> + +<p> +Comparison operators compare two operands and yield an untyped boolean value. +</p> + +<pre class="grammar"> +== equal +!= not equal +< less +<= less or equal +> greater +>= greater or equal +</pre> + +<p> +In any comparison, the first operand +must be <a href="#Assignability">assignable</a> +to the type of the second operand, or vice versa. +</p> +<p> +The equality operators <code>==</code> and <code>!=</code> apply +to operands that are <i>comparable</i>. +The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> +apply to operands that are <i>ordered</i>. +These terms and the result of the comparisons are defined as follows: +</p> + +<ul> + <li> + Boolean values are comparable. + Two boolean values are equal if they are either both + <code>true</code> or both <code>false</code>. + </li> + + <li> + Integer values are comparable and ordered, in the usual way. + </li> + + <li> + Floating-point values are comparable and ordered, + as defined by the IEEE-754 standard. + </li> + + <li> + Complex values are comparable. + Two complex values <code>u</code> and <code>v</code> are + equal if both <code>real(u) == real(v)</code> and + <code>imag(u) == imag(v)</code>. + </li> + + <li> + String values are comparable and ordered, lexically byte-wise. + </li> + + <li> + Pointer values are comparable. + Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>. + Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal. + </li> + + <li> + Channel values are comparable. + Two channel values are equal if they were created by the same call to + <a href="#Making_slices_maps_and_channels"><code>make</code></a> + or if both have value <code>nil</code>. + </li> + + <li> + Interface values are comparable. + Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types + and equal dynamic values or if both have value <code>nil</code>. + </li> + + <li> + A value <code>x</code> of non-interface type <code>X</code> and + a value <code>t</code> of interface type <code>T</code> are comparable when values + of type <code>X</code> are comparable and + <code>X</code> implements <code>T</code>. + They are equal if <code>t</code>'s dynamic type is identical to <code>X</code> + and <code>t</code>'s dynamic value is equal to <code>x</code>. + </li> + + <li> + Struct values are comparable if all their fields are comparable. + Two struct values are equal if their corresponding + non-<a href="#Blank_identifier">blank</a> fields are equal. + </li> + + <li> + Array values are comparable if values of the array element type are comparable. + Two array values are equal if their corresponding elements are equal. + </li> +</ul> + +<p> +A comparison of two interface values with identical dynamic types +causes a <a href="#Run_time_panics">run-time panic</a> if values +of that type are not comparable. This behavior applies not only to direct interface +value comparisons but also when comparing arrays of interface values +or structs with interface-valued fields. +</p> + +<p> +Slice, map, and function values are not comparable. +However, as a special case, a slice, map, or function value may +be compared to the predeclared identifier <code>nil</code>. +Comparison of pointer, channel, and interface values to <code>nil</code> +is also allowed and follows from the general rules above. +</p> + +<pre> +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 +) +</pre> + +<h3 id="Logical_operators">Logical operators</h3> + +<p> +Logical operators apply to <a href="#Boolean_types">boolean</a> values +and yield a result of the same type as the operands. +The right operand is evaluated conditionally. +</p> + +<pre class="grammar"> +&& 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" +</pre> + + +<h3 id="Address_operators">Address operators</h3> + +<p> +For an operand <code>x</code> of type <code>T</code>, the address operation +<code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. +The operand must be <i>addressable</i>, +that is, either a variable, pointer indirection, or slice indexing +operation; or a field selector of an addressable struct operand; +or an array indexing operation of an addressable array. +As an exception to the addressability requirement, <code>x</code> may also be a +(possibly parenthesized) +<a href="#Composite_literals">composite literal</a>. +If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, +then the evaluation of <code>&x</code> does too. +</p> + +<p> +For an operand <code>x</code> of pointer type <code>*T</code>, the pointer +indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed +to by <code>x</code>. +If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> +will cause a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<pre> +&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 +</pre> + + +<h3 id="Receive_operator">Receive operator</h3> + +<p> +For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>, +the value of the receive operation <code><-ch</code> is the value received +from the channel <code>ch</code>. The channel direction must permit receive operations, +and the type of the receive operation is the element type of the channel. +The expression blocks until a value is available. +Receiving from a <code>nil</code> channel blocks forever. +A receive operation on a <a href="#Close">closed</a> channel can always proceed +immediately, yielding the element type's <a href="#The_zero_value">zero value</a> +after any previously sent values have been received. +</p> + +<pre> +v1 := <-ch +v2 = <-ch +f(<-ch) +<-strobe // wait until clock pulse and discard received value +</pre> + +<p> +A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form +</p> + +<pre> +x, ok = <-ch +x, ok := <-ch +var x, ok = <-ch +var x, ok T = <-ch +</pre> + +<p> +yields an additional untyped boolean result reporting whether the +communication succeeded. The value of <code>ok</code> is <code>true</code> +if the value received was delivered by a successful send operation to the +channel, or <code>false</code> if it is a zero value generated because the +channel is closed and empty. +</p> + + +<h3 id="Conversions">Conversions</h3> + +<p> +A conversion changes the <a href="#Types">type</a> of an expression +to the type specified by the conversion. +A conversion may appear literally in the source, or it may be <i>implied</i> +by the context in which an expression appears. +</p> + +<p> +An <i>explicit</i> conversion is an expression of the form <code>T(x)</code> +where <code>T</code> is a type and <code>x</code> is an expression +that can be converted to type <code>T</code>. +</p> + +<pre class="ebnf"> +Conversion = Type "(" Expression [ "," ] ")" . +</pre> + +<p> +If the type starts with the operator <code>*</code> or <code><-</code>, +or if the type starts with the keyword <code>func</code> +and has no result list, it must be parenthesized when +necessary to avoid ambiguity: +</p> + +<pre> +*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) +</pre> + +<p> +A <a href="#Constants">constant</a> value <code>x</code> can be converted to +type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a> +by a value of <code>T</code>. +As a special case, an integer constant <code>x</code> can be explicitly converted to a +<a href="#String_types">string type</a> using the +<a href="#Conversions_to_and_from_a_string_type">same rule</a> +as for non-constant <code>x</code>. +</p> + +<p> +Converting a constant yields a typed constant as result. +</p> + +<pre> +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 +</pre> + +<p> +A non-constant value <code>x</code> can be converted to type <code>T</code> +in any of these cases: +</p> + +<ul> + <li> + <code>x</code> is <a href="#Assignability">assignable</a> + to <code>T</code>. + </li> + <li> + ignoring struct tags (see below), + <code>x</code>'s type and <code>T</code> have <a href="#Type_identity">identical</a> + <a href="#Types">underlying types</a>. + </li> + <li> + ignoring struct tags (see below), + <code>x</code>'s type and <code>T</code> are pointer types + that are not <a href="#Type_definitions">defined types</a>, + and their pointer base types have identical underlying types. + </li> + <li> + <code>x</code>'s type and <code>T</code> are both integer or floating + point types. + </li> + <li> + <code>x</code>'s type and <code>T</code> are both complex types. + </li> + <li> + <code>x</code> is an integer or a slice of bytes or runes + and <code>T</code> is a string type. + </li> + <li> + <code>x</code> is a string and <code>T</code> is a slice of bytes or runes. + </li> + <li> + <code>x</code> is a slice, <code>T</code> is a pointer to an array, + and the slice and array types have <a href="#Type_identity">identical</a> element types. + </li> +</ul> + +<p> +<a href="#Struct_types">Struct tags</a> are ignored when comparing struct types +for identity for the purpose of conversion: +</p> + +<pre> +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 +</pre> + +<p> +Specific rules apply to (non-constant) conversions between numeric types or +to and from a string type. +These conversions may change the representation of <code>x</code> +and incur a run-time cost. +All other conversions only change the type but not the representation +of <code>x</code>. +</p> + +<p> +There is no linguistic mechanism to convert between pointers and integers. +The package <a href="#Package_unsafe"><code>unsafe</code></a> +implements this functionality under +restricted circumstances. +</p> + +<h4>Conversions between numeric types</h4> + +<p> +For the conversion of non-constant numeric values, the following rules apply: +</p> + +<ol> +<li> +When converting between integer types, if the value is a signed integer, it is +sign extended to implicit infinite precision; otherwise it is zero extended. +It is then truncated to fit in the result type's size. +For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>. +The conversion always yields a valid value; there is no indication of overflow. +</li> +<li> +When converting a floating-point number to an integer, the fraction is discarded +(truncation towards zero). +</li> +<li> +When converting an integer or floating-point number to a floating-point type, +or a complex number to another complex type, the result value is rounded +to the precision specified by the destination type. +For instance, the value of a variable <code>x</code> of type <code>float32</code> +may be stored using additional precision beyond that of an IEEE-754 32-bit number, +but float32(x) represents the result of rounding <code>x</code>'s value to +32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits +of precision, but <code>float32(x + 0.1)</code> does not. +</li> +</ol> + +<p> +In all non-constant conversions involving floating-point or complex values, +if the result type cannot represent the value the conversion +succeeds but the result value is implementation-dependent. +</p> + +<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4> + +<ol> +<li> +Converting a signed or unsigned integer value to a string type yields a +string containing the UTF-8 representation of the integer. Values outside +the range of valid Unicode code points are converted to <code>"\uFFFD"</code>. + +<pre> +string('a') // "a" +string(-1) // "\ufffd" == "\xef\xbf\xbd" +string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" +type MyString string +MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" +</pre> +</li> + +<li> +Converting a slice of bytes to a string type yields +a string whose successive bytes are the elements of the slice. + +<pre> +string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" +string([]byte{}) // "" +string([]byte(nil)) // "" + +type MyBytes []byte +string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" +</pre> +</li> + +<li> +Converting a slice of runes to a string type yields +a string that is the concatenation of the individual rune values +converted to strings. + +<pre> +string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" +string([]rune{}) // "" +string([]rune(nil)) // "" + +type MyRunes []rune +string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" +</pre> +</li> + +<li> +Converting a value of a string type to a slice of bytes type +yields a slice whose successive elements are the bytes of the string. + +<pre> +[]byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} +[]byte("") // []byte{} + +MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} +</pre> +</li> + +<li> +Converting a value of a string type to a slice of runes type +yields a slice containing the individual Unicode code points of the string. + +<pre> +[]rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4} +[]rune("") // []rune{} + +MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4} +</pre> +</li> +</ol> + +<h4 id="Conversions_from_slice_to_array_pointer">Conversions from slice to array pointer</h4> + +<p> +Converting a slice to an array pointer yields a pointer to the underlying array of the slice. +If the <a href="#Length_and_capacity">length</a> of the slice is less than the length of the array, +a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<pre> +s := make([]byte, 2, 4) +s0 := (*[0]byte)(s) // s0 != nil +s1 := (*[1]byte)(s[1:]) // &s1[0] == &s[1] +s2 := (*[2]byte)(s) // &s2[0] == &s[0] +s4 := (*[4]byte)(s) // panics: len([4]byte) > len(s) + +var t []string +t0 := (*[0]string)(t) // t0 == nil +t1 := (*[1]string)(t) // panics: len([1]string) > len(t) + +u := make([]byte, 0) +u0 := (*[0]byte)(u) // u0 != nil +</pre> + +<h3 id="Constant_expressions">Constant expressions</h3> + +<p> +Constant expressions may contain only <a href="#Constants">constant</a> +operands and are evaluated at compile time. +</p> + +<p> +Untyped boolean, numeric, and string constants may be used as operands +wherever it is legal to use an operand of boolean, numeric, or string type, +respectively. +</p> + +<p> +A constant <a href="#Comparison_operators">comparison</a> always yields +an untyped boolean constant. If the left operand of a constant +<a href="#Operators">shift expression</a> is an untyped constant, the +result is an integer constant; otherwise it is a constant of the same +type as the left operand, which must be of +<a href="#Numeric_types">integer type</a>. +</p> + +<p> +Any other operation on untyped constants results in an untyped constant of the +same kind; that is, a boolean, integer, floating-point, complex, or string +constant. +If the untyped operands of a binary operation (other than a shift) are of +different kinds, the result is of the operand's kind that appears later in this +list: integer, rune, floating-point, complex. +For example, an untyped integer constant divided by an +untyped complex constant yields an untyped complex constant. +</p> + +<pre> +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 Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division) +const d = 1 << 3.0 // d == 8 (untyped integer constant) +const e = 1.0 << 3 // e == 8 (untyped integer constant) +const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32) +const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) +const h = "foo" > "bar" // h == true (untyped boolean constant) +const j = true // j == true (untyped boolean constant) +const k = 'w' + 1 // k == 'x' (untyped rune constant) +const l = "hi" // l == "hi" (untyped string constant) +const m = string(k) // m == "x" (type string) +const Σ = 1 - 0.707i // (untyped complex constant) +const Δ = Σ + 2.0e-4 // (untyped complex constant) +const Φ = iota*1i - 1/1i // (untyped complex constant) +</pre> + +<p> +Applying the built-in function <code>complex</code> to untyped +integer, rune, or floating-point constants yields +an untyped complex constant. +</p> + +<pre> +const ic = complex(0, c) // ic == 3.75i (untyped complex constant) +const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) +</pre> + +<p> +Constant expressions are always evaluated exactly; intermediate values and the +constants themselves may require precision significantly larger than supported +by any predeclared type in the language. The following are legal declarations: +</p> + +<pre> +const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant) +const Four int8 = Huge >> 98 // Four == 4 (type int8) +</pre> + +<p> +The divisor of a constant division or remainder operation must not be zero: +</p> + +<pre> +3.14 / 0.0 // illegal: division by zero +</pre> + +<p> +The values of <i>typed</i> constants must always be accurately +<a href="#Representability">representable</a> by values +of the constant type. The following constant expressions are illegal: +</p> + +<pre> +uint(-1) // -1 cannot be represented as a uint +int(3.14) // 3.14 cannot be represented as an int +int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64 +Four * 300 // operand 300 cannot be represented as an int8 (type of Four) +Four * 100 // product 400 cannot be represented as an int8 (type of Four) +</pre> + +<p> +The mask used by the unary bitwise complement operator <code>^</code> matches +the rule for non-constants: the mask is all 1s for unsigned constants +and -1 for signed and untyped constants. +</p> + +<pre> +^1 // untyped integer constant, equal to -2 +uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8 +^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) +int8(^1) // same as int8(-2) +^int8(1) // same as -1 ^ int8(1) = -2 +</pre> + +<p> +Implementation restriction: A compiler may use rounding while +computing untyped floating-point or complex constant expressions; see +the implementation restriction in the section +on <a href="#Constants">constants</a>. This rounding may cause a +floating-point constant expression to be invalid in an integer +context, even if it would be integral when calculated using infinite +precision, and vice versa. +</p> + + +<h3 id="Order_of_evaluation">Order of evaluation</h3> + +<p> +At package level, <a href="#Package_initialization">initialization dependencies</a> +determine the evaluation order of individual initialization expressions in +<a href="#Variable_declarations">variable declarations</a>. +Otherwise, when evaluating the <a href="#Operands">operands</a> of an +expression, assignment, or +<a href="#Return_statements">return statement</a>, +all function calls, method calls, and +communication operations are evaluated in lexical left-to-right +order. +</p> + +<p> +For example, in the (function-local) assignment +</p> +<pre> +y[f()], ok = g(h(), i()+x[j()], <-c), k() +</pre> +<p> +the function calls and communication happen in the order +<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, +<code><-c</code>, <code>g()</code>, and <code>k()</code>. +However, the order of those events compared to the evaluation +and indexing of <code>x</code> and the evaluation +of <code>y</code> is not specified. +</p> + +<pre> +a := 1 +f := func() int { a++; return a } +x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified +m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified +n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified +</pre> + +<p> +At package level, initialization dependencies override the left-to-right rule +for individual initialization expressions, but not for operands within each +expression: +</p> + +<pre> +var a, b, c = f() + v(), g(), sqr(u()) + v() + +func f() int { return c } +func g() int { return a } +func sqr(x int) int { return x*x } + +// functions u and v are independent of all other variables and functions +</pre> + +<p> +The function calls happen in the order +<code>u()</code>, <code>sqr()</code>, <code>v()</code>, +<code>f()</code>, <code>v()</code>, and <code>g()</code>. +</p> + +<p> +Floating-point operations within a single expression are evaluated according to +the associativity of the operators. Explicit parentheses affect the evaluation +by overriding the default associativity. +In the expression <code>x + (y + z)</code> the addition <code>y + z</code> +is performed before adding <code>x</code>. +</p> + +<h2 id="Statements">Statements</h2> + +<p> +Statements control execution. +</p> + +<pre class="ebnf"> +Statement = + Declaration | LabeledStmt | SimpleStmt | + GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | + FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | + DeferStmt . + +SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . +</pre> + +<h3 id="Terminating_statements">Terminating statements</h3> + +<p> +A <i>terminating statement</i> interrupts the regular flow of control in +a <a href="#Blocks">block</a>. The following statements are terminating: +</p> + +<ol> +<li> + A <a href="#Return_statements">"return"</a> or + <a href="#Goto_statements">"goto"</a> statement. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + A call to the built-in function + <a href="#Handling_panics"><code>panic</code></a>. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + An <a href="#If_statements">"if" statement</a> in which: + <ul> + <li>the "else" branch is present, and</li> + <li>both branches are terminating statements.</li> + </ul> +</li> + +<li> + A <a href="#For_statements">"for" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "for" statement, and</li> + <li>the loop condition is absent, and</li> + <li>the "for" statement does not use a range clause.</li> + </ul> +</li> + +<li> + A <a href="#Switch_statements">"switch" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "switch" statement,</li> + <li>there is a default case, and</li> + <li>the statement lists in each case, including the default, end in a terminating + statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough" + statement</a>.</li> + </ul> +</li> + +<li> + A <a href="#Select_statements">"select" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "select" statement, and</li> + <li>the statement lists in each case, including the default if present, + end in a terminating statement.</li> + </ul> +</li> + +<li> + A <a href="#Labeled_statements">labeled statement</a> labeling + a terminating statement. +</li> +</ol> + +<p> +All other statements are not terminating. +</p> + +<p> +A <a href="#Blocks">statement list</a> ends in a terminating statement if the list +is not empty and its final non-empty statement is terminating. +</p> + + +<h3 id="Empty_statements">Empty statements</h3> + +<p> +The empty statement does nothing. +</p> + +<pre class="ebnf"> +EmptyStmt = . +</pre> + + +<h3 id="Labeled_statements">Labeled statements</h3> + +<p> +A labeled statement may be the target of a <code>goto</code>, +<code>break</code> or <code>continue</code> statement. +</p> + +<pre class="ebnf"> +LabeledStmt = Label ":" Statement . +Label = identifier . +</pre> + +<pre> +Error: log.Panic("error encountered") +</pre> + + +<h3 id="Expression_statements">Expression statements</h3> + +<p> +With the exception of specific built-in functions, +function and method <a href="#Calls">calls</a> and +<a href="#Receive_operator">receive operations</a> +can appear in statement context. Such statements may be parenthesized. +</p> + +<pre class="ebnf"> +ExpressionStmt = Expression . +</pre> + +<p> +The following built-in functions are not permitted in statement context: +</p> + +<pre> +append cap complex imag len make new real +unsafe.Add unsafe.Alignof unsafe.Offsetof unsafe.Sizeof unsafe.Slice +</pre> + +<pre> +h(x+y) +f.Close() +<-ch +(<-ch) +len("foo") // illegal if len is the built-in function +</pre> + + +<h3 id="Send_statements">Send statements</h3> + +<p> +A send statement sends a value on a channel. +The channel expression must be of <a href="#Channel_types">channel type</a>, +the channel direction must permit send operations, +and the type of the value to be sent must be <a href="#Assignability">assignable</a> +to the channel's element type. +</p> + +<pre class="ebnf"> +SendStmt = Channel "<-" Expression . +Channel = Expression . +</pre> + +<p> +Both the channel and the value expression are evaluated before communication +begins. Communication blocks until the send can proceed. +A send on an unbuffered channel can proceed if a receiver is ready. +A send on a buffered channel can proceed if there is room in the buffer. +A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>. +A send on a <code>nil</code> channel blocks forever. +</p> + +<pre> +ch <- 3 // send value 3 to channel ch +</pre> + + +<h3 id="IncDec_statements">IncDec statements</h3> + +<p> +The "++" and "--" statements increment or decrement their operands +by the untyped <a href="#Constants">constant</a> <code>1</code>. +As with an assignment, the operand must be <a href="#Address_operators">addressable</a> +or a map index expression. +</p> + +<pre class="ebnf"> +IncDecStmt = Expression ( "++" | "--" ) . +</pre> + +<p> +The following <a href="#Assignments">assignment statements</a> are semantically +equivalent: +</p> + +<pre class="grammar"> +IncDec statement Assignment +x++ x += 1 +x-- x -= 1 +</pre> + + +<h3 id="Assignments">Assignments</h3> + +<pre class="ebnf"> +Assignment = ExpressionList assign_op ExpressionList . + +assign_op = [ add_op | mul_op ] "=" . +</pre> + +<p> +Each left-hand side operand must be <a href="#Address_operators">addressable</a>, +a map index expression, or (for <code>=</code> assignments only) the +<a href="#Blank_identifier">blank identifier</a>. +Operands may be parenthesized. +</p> + +<pre> +x = 1 +*p = f() +a[i] = 23 +(k) = <-ch // same as: k = <-ch +</pre> + +<p> +An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code> +<code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a> +is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i> +<code>(y)</code> but evaluates <code>x</code> +only once. The <i>op</i><code>=</code> construct is a single token. +In assignment operations, both the left- and right-hand expression lists +must contain exactly one single-valued expression, and the left-hand +expression must not be the blank identifier. +</p> + +<pre> +a[i] <<= 2 +i &^= 1<<n +</pre> + +<p> +A tuple assignment assigns the individual elements of a multi-valued +operation to a list of variables. There are two forms. In the +first, the right hand operand is a single multi-valued expression +such as a function call, a <a href="#Channel_types">channel</a> or +<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. +The number of operands on the left +hand side must match the number of values. For instance, if +<code>f</code> is a function returning two values, +</p> + +<pre> +x, y = f() +</pre> + +<p> +assigns the first value to <code>x</code> and the second to <code>y</code>. +In the second form, the number of operands on the left must equal the number +of expressions on the right, each of which must be single-valued, and the +<i>n</i>th expression on the right is assigned to the <i>n</i>th +operand on the left: +</p> + +<pre> +one, two, three = '一', '二', '三' +</pre> + +<p> +The <a href="#Blank_identifier">blank identifier</a> provides a way to +ignore right-hand side values in an assignment: +</p> + +<pre> +_ = x // evaluate x but ignore it +x, _ = f() // evaluate f() but ignore second result value +</pre> + +<p> +The assignment proceeds in two phases. +First, the operands of <a href="#Index_expressions">index expressions</a> +and <a href="#Address_operators">pointer indirections</a> +(including implicit pointer indirections in <a href="#Selectors">selectors</a>) +on the left and the expressions on the right are all +<a href="#Order_of_evaluation">evaluated in the usual order</a>. +Second, the assignments are carried out in left-to-right order. +</p> + +<pre> +a, b = b, a // exchange a and b + +x := []int{1, 2, 3} +i := 0 +i, x[i] = 1, 2 // set i = 1, x[0] = 2 + +i = 0 +x[i], i = 2, 1 // set x[0] = 2, i = 1 + +x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end) + +x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5. + +type Point struct { x, y int } +var p *Point +x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7 + +i = 2 +x = []int{3, 5, 7} +for i, x[i] = range x { // set i, x[2] = 0, x[0] + break +} +// after this loop, i == 0 and x == []int{3, 5, 3} +</pre> + +<p> +In assignments, each value must be <a href="#Assignability">assignable</a> +to the type of the operand to which it is assigned, with the following special cases: +</p> + +<ol> +<li> + Any typed value may be assigned to the blank identifier. +</li> + +<li> + If an untyped constant + is assigned to a variable of interface type or the blank identifier, + the constant is first implicitly <a href="#Conversions">converted</a> to its + <a href="#Constants">default type</a>. +</li> + +<li> + If an untyped boolean value is assigned to a variable of interface type or + the blank identifier, it is first implicitly converted to type <code>bool</code>. +</li> +</ol> + +<h3 id="If_statements">If statements</h3> + +<p> +"If" statements specify the conditional execution of two branches +according to the value of a boolean expression. If the expression +evaluates to true, the "if" branch is executed, otherwise, if +present, the "else" branch is executed. +</p> + +<pre class="ebnf"> +IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] . +</pre> + +<pre> +if x > max { + x = max +} +</pre> + +<p> +The expression may be preceded by a simple statement, which +executes before the expression is evaluated. +</p> + +<pre> +if x := f(); x < y { + return x +} else if x > z { + return z +} else { + return y +} +</pre> + + +<h3 id="Switch_statements">Switch statements</h3> + +<p> +"Switch" statements provide multi-way execution. +An expression or type is compared to the "cases" +inside the "switch" to determine which branch +to execute. +</p> + +<pre class="ebnf"> +SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . +</pre> + +<p> +There are two forms: expression switches and type switches. +In an expression switch, the cases contain expressions that are compared +against the value of the switch expression. +In a type switch, the cases contain types that are compared against the +type of a specially annotated switch expression. +The switch expression is evaluated exactly once in a switch statement. +</p> + +<h4 id="Expression_switches">Expression switches</h4> + +<p> +In an expression switch, +the switch expression is evaluated and +the case expressions, which need not be constants, +are evaluated left-to-right and top-to-bottom; the first one that equals the +switch expression +triggers execution of the statements of the associated case; +the other cases are skipped. +If no case matches and there is a "default" case, +its statements are executed. +There can be at most one default case and it may appear anywhere in the +"switch" statement. +A missing switch expression is equivalent to the boolean value +<code>true</code>. +</p> + +<pre class="ebnf"> +ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . +ExprCaseClause = ExprSwitchCase ":" StatementList . +ExprSwitchCase = "case" ExpressionList | "default" . +</pre> + +<p> +If the switch expression evaluates to an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>. +The predeclared untyped value <code>nil</code> cannot be used as a switch expression. +The switch expression type must be <a href="#Comparison_operators">comparable</a>. +</p> + +<p> +If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a> +to the type of the switch expression. +For each (possibly converted) case expression <code>x</code> and the value <code>t</code> +of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>. +</p> + +<p> +In other words, the switch expression is treated as if it were used to declare and +initialize a temporary variable <code>t</code> without explicit type; it is that +value of <code>t</code> against which each case expression <code>x</code> is tested +for equality. +</p> + +<p> +In a case or default clause, the last non-empty statement +may be a (possibly <a href="#Labeled_statements">labeled</a>) +<a href="#Fallthrough_statements">"fallthrough" statement</a> to +indicate that control should flow from the end of this clause to +the first statement of the next clause. +Otherwise control flows to the end of the "switch" statement. +A "fallthrough" statement may appear as the last statement of all +but the last clause of an expression switch. +</p> + +<p> +The switch expression may be preceded by a simple statement, which +executes before the expression is evaluated. +</p> + +<pre> +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() +} +</pre> + +<p> +Implementation restriction: A compiler may disallow multiple case +expressions evaluating to the same constant. +For instance, the current compilers disallow duplicate integer, +floating point, or string constants in case expressions. +</p> + +<h4 id="Type_switches">Type switches</h4> + +<p> +A type switch compares types rather than values. It is otherwise similar +to an expression switch. It is marked by a special switch expression that +has the form of a <a href="#Type_assertions">type assertion</a> +using the keyword <code>type</code> rather than an actual type: +</p> + +<pre> +switch x.(type) { +// cases +} +</pre> + +<p> +Cases then match actual types <code>T</code> against the dynamic type of the +expression <code>x</code>. As with type assertions, <code>x</code> must be of +<a href="#Interface_types">interface type</a>, and each non-interface type +<code>T</code> listed in a case must implement the type of <code>x</code>. +The types listed in the cases of a type switch must all be +<a href="#Type_identity">different</a>. +</p> + +<pre class="ebnf"> +TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . +TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . +TypeCaseClause = TypeSwitchCase ":" StatementList . +TypeSwitchCase = "case" TypeList | "default" . +TypeList = Type { "," Type } . +</pre> + +<p> +The TypeSwitchGuard may include a +<a href="#Short_variable_declarations">short variable declaration</a>. +When that form is used, the variable is declared at the end of the +TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause. +In clauses with a case listing exactly one type, the variable +has that type; otherwise, the variable has the type of the expression +in the TypeSwitchGuard. +</p> + +<p> +Instead of a type, a case may use the predeclared identifier +<a href="#Predeclared_identifiers"><code>nil</code></a>; +that case is selected when the expression in the TypeSwitchGuard +is a <code>nil</code> interface value. +There may be at most one <code>nil</code> case. +</p> + +<p> +Given an expression <code>x</code> of type <code>interface{}</code>, +the following type switch: +</p> + +<pre> +switch i := x.(type) { +case nil: + printString("x is nil") // type of i is type of x (interface{}) +case int: + printInt(i) // type of i is int +case float64: + printFloat64(i) // type of i is float64 +case func(int) float64: + printFunction(i) // type of i is func(int) float64 +case bool, string: + printString("type is bool or string") // type of i is type of x (interface{}) +default: + printString("don't know the type") // type of i is type of x (interface{}) +} +</pre> + +<p> +could be rewritten: +</p> + +<pre> +v := x // x is evaluated exactly once +if v == nil { + i := v // type of i is type of x (interface{}) + printString("x is nil") +} else if i, isInt := v.(int); isInt { + printInt(i) // type of i is int +} else if i, isFloat64 := v.(float64); isFloat64 { + printFloat64(i) // type of i is float64 +} else if i, isFunc := v.(func(int) float64); isFunc { + printFunction(i) // type of i is func(int) float64 +} else { + _, isBool := v.(bool) + _, isString := v.(string) + if isBool || isString { + i := v // type of i is type of x (interface{}) + printString("type is bool or string") + } else { + i := v // type of i is type of x (interface{}) + printString("don't know the type") + } +} +</pre> + +<p> +The type switch guard may be preceded by a simple statement, which +executes before the guard is evaluated. +</p> + +<p> +The "fallthrough" statement is not permitted in a type switch. +</p> + +<h3 id="For_statements">For statements</h3> + +<p> +A "for" statement specifies repeated execution of a block. There are three forms: +The iteration may be controlled by a single condition, a "for" clause, or a "range" clause. +</p> + +<pre class="ebnf"> +ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . +Condition = Expression . +</pre> + +<h4 id="For_condition">For statements with single condition</h4> + +<p> +In its simplest form, a "for" statement specifies the repeated execution of +a block as long as a boolean condition evaluates to true. +The condition is evaluated before each iteration. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. +</p> + +<pre> +for a < b { + a *= 2 +} +</pre> + +<h4 id="For_clause">For statements with <code>for</code> clause</h4> + +<p> +A "for" statement with a ForClause is also controlled by its condition, but +additionally it may specify an <i>init</i> +and a <i>post</i> statement, such as an assignment, +an increment or decrement statement. The init statement may be a +<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. +Variables declared by the init statement are re-used in each iteration. +</p> + +<pre class="ebnf"> +ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . +InitStmt = SimpleStmt . +PostStmt = SimpleStmt . +</pre> + +<pre> +for i := 0; i < 10; i++ { + f(i) +} +</pre> + +<p> +If non-empty, the init statement is executed once before evaluating the +condition for the first iteration; +the post statement is executed after each execution of the block (and +only if the block was executed). +Any element of the ForClause may be empty but the +<a href="#Semicolons">semicolons</a> are +required unless there is only a condition. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. +</p> + +<pre> +for cond { S() } is the same as for ; cond ; { S() } +for { S() } is the same as for true { S() } +</pre> + +<h4 id="For_range">For statements with <code>range</code> clause</h4> + +<p> +A "for" statement with a "range" clause +iterates through all entries of an array, slice, string or map, +or values received on a channel. For each entry it assigns <i>iteration values</i> +to corresponding <i>iteration variables</i> if present and then executes the block. +</p> + +<pre class="ebnf"> +RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . +</pre> + +<p> +The expression on the right in the "range" clause is called the <i>range expression</i>, +which may be an array, pointer to an array, slice, string, map, or channel permitting +<a href="#Receive_operator">receive operations</a>. +As with an assignment, if present the operands on the left must be +<a href="#Address_operators">addressable</a> or map index expressions; they +denote the iteration variables. If the range expression is a channel, at most +one iteration variable is permitted, otherwise there may be up to two. +If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, +the range clause is equivalent to the same clause without that identifier. +</p> + +<p> +The range expression <code>x</code> is evaluated once before beginning the loop, +with one exception: if at most one iteration variable is present and +<code>len(x)</code> is <a href="#Length_and_capacity">constant</a>, +the range expression is not evaluated. +</p> + +<p> +Function calls on the left are evaluated once per iteration. +For each iteration, iteration values are produced as follows +if the respective iteration variables are present: +</p> + +<pre class="grammar"> +Range expression 1st value 2nd value + +array or slice a [n]E, *[n]E, or []E index i int a[i] E +string s string type index i int see below rune +map m map[K]V key k K m[k] V +channel c chan E, <-chan E element e E +</pre> + +<ol> +<li> +For an array, pointer to array, or slice value <code>a</code>, the index iteration +values are produced in increasing order, starting at element index 0. +If at most one iteration variable is present, the range loop produces +iteration values from 0 up to <code>len(a)-1</code> and does not index into the array +or slice itself. For a <code>nil</code> slice, the number of iterations is 0. +</li> + +<li> +For a string value, the "range" clause iterates over the Unicode code points +in the string starting at byte index 0. On successive iterations, the index value will be the +index of the first byte of successive UTF-8-encoded code points in the string, +and the second value, of type <code>rune</code>, will be the value of +the corresponding code point. If the iteration encounters an invalid +UTF-8 sequence, the second value will be <code>0xFFFD</code>, +the Unicode replacement character, and the next iteration will advance +a single byte in the string. +</li> + +<li> +The iteration order over maps is not specified +and is not guaranteed to be the same from one iteration to the next. +If a map entry that has not yet been reached is removed during iteration, +the corresponding iteration value will not be produced. If a map entry is +created during iteration, that entry may be produced during the iteration or +may be skipped. The choice may vary for each entry created and from one +iteration to the next. +If the map is <code>nil</code>, the number of iterations is 0. +</li> + +<li> +For channels, the iteration values produced are the successive values sent on +the channel until the channel is <a href="#Close">closed</a>. If the channel +is <code>nil</code>, the range expression blocks forever. +</li> +</ol> + +<p> +The iteration values are assigned to the respective +iteration variables as in an <a href="#Assignments">assignment statement</a>. +</p> + +<p> +The iteration variables may be declared by the "range" clause using a form of +<a href="#Short_variable_declarations">short variable declaration</a> +(<code>:=</code>). +In this case their types are set to the types of the respective iteration values +and their <a href="#Declarations_and_scope">scope</a> is the block of the "for" +statement; they are re-used in each iteration. +If the iteration variables are declared outside the "for" statement, +after execution their values will be those of the last iteration. +</p> + +<pre> +var testdata *struct { + a *[7]int +} +for i, _ := range testdata.a { + // testdata.a is never evaluated; len(testdata.a) is constant + // i ranges from 0 to 6 + f(i) +} + +var a [10]string +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{} // element type of m is assignable to val +m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6} +for key, val = range m { + h(key, val) +} +// key == last map key encountered in iteration +// val == map[key] + +var ch chan Work = producer() +for w := range ch { + doWork(w) +} + +// empty a channel +for range ch {} +</pre> + + +<h3 id="Go_statements">Go statements</h3> + +<p> +A "go" statement starts the execution of a function call +as an independent concurrent thread of control, or <i>goroutine</i>, +within the same address space. +</p> + +<pre class="ebnf"> +GoStmt = "go" Expression . +</pre> + +<p> +The expression must be a function or method call; it cannot be parenthesized. +Calls of built-in functions are restricted as for +<a href="#Expression_statements">expression statements</a>. +</p> + +<p> +The function value and parameters are +<a href="#Calls">evaluated as usual</a> +in the calling goroutine, but +unlike with a regular call, program execution does not wait +for the invoked function to complete. +Instead, the function begins executing independently +in a new goroutine. +When the function terminates, its goroutine also terminates. +If the function has any return values, they are discarded when the +function completes. +</p> + +<pre> +go Server() +go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c) +</pre> + + +<h3 id="Select_statements">Select statements</h3> + +<p> +A "select" statement chooses which of a set of possible +<a href="#Send_statements">send</a> or +<a href="#Receive_operator">receive</a> +operations will proceed. +It looks similar to a +<a href="#Switch_statements">"switch"</a> statement but with the +cases all referring to communication operations. +</p> + +<pre class="ebnf"> +SelectStmt = "select" "{" { CommClause } "}" . +CommClause = CommCase ":" StatementList . +CommCase = "case" ( SendStmt | RecvStmt ) | "default" . +RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr . +RecvExpr = Expression . +</pre> + +<p> +A case with a RecvStmt may assign the result of a RecvExpr to one or +two variables, which may be declared using a +<a href="#Short_variable_declarations">short variable declaration</a>. +The RecvExpr must be a (possibly parenthesized) receive operation. +There can be at most one default case and it may appear anywhere +in the list of cases. +</p> + +<p> +Execution of a "select" statement proceeds in several steps: +</p> + +<ol> +<li> +For all the cases in the statement, the channel operands of receive operations +and the channel and right-hand-side expressions of send statements are +evaluated exactly once, in source order, upon entering the "select" statement. +The result is a set of channels to receive from or send to, +and the corresponding values to send. +Any side effects in that evaluation will occur irrespective of which (if any) +communication operation is selected to proceed. +Expressions on the left-hand side of a RecvStmt with a short variable declaration +or assignment are not yet evaluated. +</li> + +<li> +If one or more of the communications can proceed, +a single one that can proceed is chosen via a uniform pseudo-random selection. +Otherwise, if there is a default case, that case is chosen. +If there is no default case, the "select" statement blocks until +at least one of the communications can proceed. +</li> + +<li> +Unless the selected case is the default case, the respective communication +operation is executed. +</li> + +<li> +If the selected case is a RecvStmt with a short variable declaration or +an assignment, the left-hand side expressions are evaluated and the +received value (or values) are assigned. +</li> + +<li> +The statement list of the selected case is executed. +</li> +</ol> + +<p> +Since communication on <code>nil</code> channels can never proceed, +a select with only <code>nil</code> channels and no default case blocks forever. +</p> + +<pre> +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 +</pre> + + +<h3 id="Return_statements">Return statements</h3> + +<p> +A "return" statement in a function <code>F</code> terminates the execution +of <code>F</code>, and optionally provides one or more result values. +Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> +are executed before <code>F</code> returns to its caller. +</p> + +<pre class="ebnf"> +ReturnStmt = "return" [ ExpressionList ] . +</pre> + +<p> +In a function without a result type, a "return" statement must not +specify any result values. +</p> +<pre> +func noResult() { + return +} +</pre> + +<p> +There are three ways to return values from a function with a result +type: +</p> + +<ol> + <li>The return value or values may be explicitly listed + in the "return" statement. Each expression must be single-valued + and <a href="#Assignability">assignable</a> + to the corresponding element of the function's result type. +<pre> +func simpleF() int { + return 2 +} + +func complexF1() (re float64, im float64) { + return -7.0, -4.0 +} +</pre> + </li> + <li>The expression list in the "return" statement may be a single + call to a multi-valued function. The effect is as if each value + returned from that function were assigned to a temporary + variable with the type of the respective value, followed by a + "return" statement listing these variables, at which point the + rules of the previous case apply. +<pre> +func complexF2() (re float64, im float64) { + return complexF1() +} +</pre> + </li> + <li>The expression list may be empty if the function's result + type specifies names for its <a href="#Function_types">result parameters</a>. + The result parameters act as ordinary local variables + and the function may assign values to them as necessary. + The "return" statement returns the values of these variables. +<pre> +func complexF3() (re float64, im float64) { + re = 7.0 + im = 4.0 + return +} + +func (devnull) Write(p []byte) (n int, _ error) { + n = len(p) + return +} +</pre> + </li> +</ol> + +<p> +Regardless of how they are declared, all the result values are initialized to +the <a href="#The_zero_value">zero values</a> for their type upon entry to the +function. A "return" statement that specifies results sets the result parameters before +any deferred functions are executed. +</p> + +<p> +Implementation restriction: A compiler may disallow an empty expression list +in a "return" statement if a different entity (constant, type, or variable) +with the same name as a result parameter is in +<a href="#Declarations_and_scope">scope</a> at the place of the return. +</p> + +<pre> +func f(n int) (res int, err error) { + if _, err := f(n-1); err != nil { + return // invalid return statement: err is shadowed + } + return +} +</pre> + +<h3 id="Break_statements">Break statements</h3> + +<p> +A "break" statement terminates execution of the innermost +<a href="#For_statements">"for"</a>, +<a href="#Switch_statements">"switch"</a>, or +<a href="#Select_statements">"select"</a> statement +within the same function. +</p> + +<pre class="ebnf"> +BreakStmt = "break" [ Label ] . +</pre> + +<p> +If there is a label, it must be that of an enclosing +"for", "switch", or "select" statement, +and that is the one whose execution terminates. +</p> + +<pre> +OuterLoop: + for i = 0; i < n; i++ { + for j = 0; j < m; j++ { + switch a[i][j] { + case nil: + state = Error + break OuterLoop + case item: + state = Found + break OuterLoop + } + } + } +</pre> + +<h3 id="Continue_statements">Continue statements</h3> + +<p> +A "continue" statement begins the next iteration of the +innermost <a href="#For_statements">"for" loop</a> at its post statement. +The "for" loop must be within the same function. +</p> + +<pre class="ebnf"> +ContinueStmt = "continue" [ Label ] . +</pre> + +<p> +If there is a label, it must be that of an enclosing +"for" statement, and that is the one whose execution +advances. +</p> + +<pre> +RowLoop: + for y, row := range rows { + for x, data := range row { + if data == endOfRow { + continue RowLoop + } + row[x] = data + bias(x, y) + } + } +</pre> + +<h3 id="Goto_statements">Goto statements</h3> + +<p> +A "goto" statement transfers control to the statement with the corresponding label +within the same function. +</p> + +<pre class="ebnf"> +GotoStmt = "goto" Label . +</pre> + +<pre> +goto Error +</pre> + +<p> +Executing the "goto" statement must not cause any variables to come into +<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. +For instance, this example: +</p> + +<pre> + goto L // BAD + v := 3 +L: +</pre> + +<p> +is erroneous because the jump to label <code>L</code> skips +the creation of <code>v</code>. +</p> + +<p> +A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. +For instance, this example: +</p> + +<pre> +if n%2 == 1 { + goto L1 +} +for n > 0 { + f() + n-- +L1: + f() + n-- +} +</pre> + +<p> +is erroneous because the label <code>L1</code> is inside +the "for" statement's block but the <code>goto</code> is not. +</p> + +<h3 id="Fallthrough_statements">Fallthrough statements</h3> + +<p> +A "fallthrough" statement transfers control to the first statement of the +next case clause in an <a href="#Expression_switches">expression "switch" statement</a>. +It may be used only as the final non-empty statement in such a clause. +</p> + +<pre class="ebnf"> +FallthroughStmt = "fallthrough" . +</pre> + + +<h3 id="Defer_statements">Defer statements</h3> + +<p> +A "defer" statement invokes a function whose execution is deferred +to the moment the surrounding function returns, either because the +surrounding function executed a <a href="#Return_statements">return statement</a>, +reached the end of its <a href="#Function_declarations">function body</a>, +or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>. +</p> + +<pre class="ebnf"> +DeferStmt = "defer" Expression . +</pre> + +<p> +The expression must be a function or method call; it cannot be parenthesized. +Calls of built-in functions are restricted as for +<a href="#Expression_statements">expression statements</a>. +</p> + +<p> +Each time a "defer" statement +executes, the function value and parameters to the call are +<a href="#Calls">evaluated as usual</a> +and saved anew but the actual function is not invoked. +Instead, deferred functions are invoked immediately before +the surrounding function returns, in the reverse order +they were deferred. That is, if the surrounding function +returns through an explicit <a href="#Return_statements">return statement</a>, +deferred functions are executed <i>after</i> any result parameters are set +by that return statement but <i>before</i> the function returns to its caller. +If a deferred function value evaluates +to <code>nil</code>, execution <a href="#Handling_panics">panics</a> +when the function is invoked, not when the "defer" statement is executed. +</p> + +<p> +For instance, if the deferred function is +a <a href="#Function_literals">function literal</a> and the surrounding +function has <a href="#Function_types">named result parameters</a> that +are in scope within the literal, the deferred function may access and modify +the result parameters before they are returned. +If the deferred function has any return values, they are discarded when +the function completes. +(See also the section on <a href="#Handling_panics">handling panics</a>.) +</p> + +<pre> +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 +} +</pre> + +<h2 id="Built-in_functions">Built-in functions</h2> + +<p> +Built-in functions are +<a href="#Predeclared_identifiers">predeclared</a>. +They are called like any other function but some of them +accept a type instead of an expression as the first argument. +</p> + +<p> +The built-in functions do not have standard Go types, +so they can only appear in <a href="#Calls">call expressions</a>; +they cannot be used as function values. +</p> + +<h3 id="Close">Close</h3> + +<p> +For a channel <code>c</code>, the built-in function <code>close(c)</code> +records that no more values will be sent on the channel. +It is an error if <code>c</code> is a receive-only channel. +Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>. +Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>. +After calling <code>close</code>, and after any previously +sent values have been received, receive operations will return +the zero value for the channel's type without blocking. +The multi-valued <a href="#Receive_operator">receive operation</a> +returns a received value along with an indication of whether the channel is closed. +</p> + + +<h3 id="Length_and_capacity">Length and capacity</h3> + +<p> +The built-in functions <code>len</code> and <code>cap</code> take arguments +of various types and return a result of type <code>int</code>. +The implementation guarantees that the result always fits into an <code>int</code>. +</p> + +<pre class="grammar"> +Call Argument type Result + +len(s) string type string length in bytes + [n]T, *[n]T array length (== n) + []T slice length + map[K]T map length (number of defined keys) + chan T number of elements queued in channel buffer + +cap(s) [n]T, *[n]T array length (== n) + []T slice capacity + chan T channel buffer capacity +</pre> + +<p> +The capacity of a slice is the number of elements for which there is +space allocated in the underlying array. +At any time the following relationship holds: +</p> + +<pre> +0 <= len(s) <= cap(s) +</pre> + +<p> +The length of a <code>nil</code> slice, map or channel is 0. +The capacity of a <code>nil</code> slice or channel is 0. +</p> + +<p> +The expression <code>len(s)</code> is <a href="#Constants">constant</a> if +<code>s</code> is a string constant. The expressions <code>len(s)</code> and +<code>cap(s)</code> are constants if the type of <code>s</code> is an array +or pointer to an array and the expression <code>s</code> does not contain +<a href="#Receive_operator">channel receives</a> or (non-constant) +<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. +Otherwise, invocations of <code>len</code> and <code>cap</code> are not +constant and <code>s</code> is evaluated. +</p> + +<pre> +const ( + c1 = imag(2i) // imag(2i) = 2.0 is a constant + c2 = len([10]float64{2}) // [10]float64{2} contains no function calls + c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls + c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued + c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call +) +var z complex128 +</pre> + +<h3 id="Allocation">Allocation</h3> + +<p> +The built-in function <code>new</code> takes a type <code>T</code>, +allocates storage for a <a href="#Variables">variable</a> of that type +at run time, and returns a value of type <code>*T</code> +<a href="#Pointer_types">pointing</a> to it. +The variable is initialized as described in the section on +<a href="#The_zero_value">initial values</a>. +</p> + +<pre class="grammar"> +new(T) +</pre> + +<p> +For instance +</p> + +<pre> +type S struct { a int; b float64 } +new(S) +</pre> + +<p> +allocates storage for a variable of type <code>S</code>, +initializes it (<code>a=0</code>, <code>b=0.0</code>), +and returns a value of type <code>*S</code> containing the address +of the location. +</p> + +<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> + +<p> +The built-in function <code>make</code> takes a type <code>T</code>, +which must be a slice, map or channel type, +optionally followed by a type-specific list of expressions. +It returns a value of type <code>T</code> (not <code>*T</code>). +The memory is initialized as described in the section on +<a href="#The_zero_value">initial values</a>. +</p> + +<pre class="grammar"> +Call Type T Result + +make(T, n) slice slice of type T with length n and capacity n +make(T, n, m) slice slice of type T with length n and capacity m + +make(T) map map of type T +make(T, n) map map of type T with initial space for approximately n elements + +make(T) channel unbuffered channel of type T +make(T, n) channel buffered channel of type T, buffer size n +</pre> + + +<p> +Each of the size arguments <code>n</code> and <code>m</code> must be of integer type +or an untyped <a href="#Constants">constant</a>. +A constant size argument must be non-negative and <a href="#Representability">representable</a> +by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>. +If both <code>n</code> and <code>m</code> are provided and are constant, then +<code>n</code> must be no larger than <code>m</code>. +If <code>n</code> is negative or larger than <code>m</code> at run time, +a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<pre> +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 +</pre> + +<p> +Calling <code>make</code> with a map type and size hint <code>n</code> will +create a map with initial space to hold <code>n</code> map elements. +The precise behavior is implementation-dependent. +</p> + + +<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3> + +<p> +The built-in functions <code>append</code> and <code>copy</code> assist in +common slice operations. +For both functions, the result is independent of whether the memory referenced +by the arguments overlaps. +</p> + +<p> +The <a href="#Function_types">variadic</a> function <code>append</code> +appends zero or more values <code>x</code> +to <code>s</code> of type <code>S</code>, which must be a slice type, and +returns the resulting slice, also of type <code>S</code>. +The values <code>x</code> are passed to a parameter of type <code>...T</code> +where <code>T</code> is the <a href="#Slice_types">element type</a> of +<code>S</code> and the respective +<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply. +As a special case, <code>append</code> also accepts a first argument +assignable to type <code>[]byte</code> with a second argument of +string type followed by <code>...</code>. This form appends the +bytes of the string. +</p> + +<pre class="grammar"> +append(s S, x ...T) S // T is the element type of S +</pre> + +<p> +If the capacity of <code>s</code> is not large enough to fit the additional +values, <code>append</code> allocates a new, sufficiently large underlying +array that fits both the existing slice elements and the additional values. +Otherwise, <code>append</code> re-uses the underlying array. +</p> + +<pre> +s0 := []int{0, 0} +s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2} +s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7} +s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0} +s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0} + +var t []interface{} +t = append(t, 42, 3.1415, "foo") // t == []interface{}{42, 3.1415, "foo"} + +var b []byte +b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' } +</pre> + +<p> +The function <code>copy</code> copies slice elements from +a source <code>src</code> to a destination <code>dst</code> and returns the +number of elements copied. +Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be +<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>. +The number of elements copied is the minimum of +<code>len(src)</code> and <code>len(dst)</code>. +As a special case, <code>copy</code> also accepts a destination argument assignable +to type <code>[]byte</code> with a source argument of a string type. +This form copies the bytes from the string into the byte slice. +</p> + +<pre class="grammar"> +copy(dst, src []T) int +copy(dst []byte, src string) int +</pre> + +<p> +Examples: +</p> + +<pre> +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 == []int{0, 1, 2, 3, 4, 5} +n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5} +n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello") +</pre> + + +<h3 id="Deletion_of_map_elements">Deletion of map elements</h3> + +<p> +The built-in function <code>delete</code> removes the element with key +<code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The +type of <code>k</code> must be <a href="#Assignability">assignable</a> +to the key type of <code>m</code>. +</p> + +<pre class="grammar"> +delete(m, k) // remove element m[k] from map m +</pre> + +<p> +If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code> +does not exist, <code>delete</code> is a no-op. +</p> + + +<h3 id="Complex_numbers">Manipulating complex numbers</h3> + +<p> +Three functions assemble and disassemble complex numbers. +The built-in function <code>complex</code> constructs a complex +value from a floating-point real and imaginary part, while +<code>real</code> and <code>imag</code> +extract the real and imaginary parts of a complex value. +</p> + +<pre class="grammar"> +complex(realPart, imaginaryPart floatT) complexT +real(complexT) floatT +imag(complexT) floatT +</pre> + +<p> +The type of the arguments and return value correspond. +For <code>complex</code>, the two arguments must be of the same +floating-point type and the return type is the complex type +with the corresponding floating-point constituents: +<code>complex64</code> for <code>float32</code> arguments, and +<code>complex128</code> for <code>float64</code> arguments. +If one of the arguments evaluates to an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to the type of the other argument. +If both arguments evaluate to untyped constants, they must be non-complex +numbers or their imaginary parts must be zero, and the return value of +the function is an untyped complex constant. +</p> + +<p> +For <code>real</code> and <code>imag</code>, the argument must be +of complex type, and the return type is the corresponding floating-point +type: <code>float32</code> for a <code>complex64</code> argument, and +<code>float64</code> for a <code>complex128</code> argument. +If the argument evaluates to an untyped constant, it must be a number, +and the return value of the function is an untyped floating-point constant. +</p> + +<p> +The <code>real</code> and <code>imag</code> functions together form the inverse of +<code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>, +<code>z == Z(complex(real(z), imag(z)))</code>. +</p> + +<p> +If the operands of these functions are all constants, the return +value is a constant. +</p> + +<pre> +var a = complex(2, -2) // complex128 +const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i +x := float32(math.Cos(math.Pi/2)) // float32 +var c64 = complex(5, -x) // complex64 +var s int = complex(1, 0) // untyped complex constant 1 + 0i can be converted to int +_ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift +var rl = real(c64) // float32 +var im = imag(a) // float64 +const c = imag(b) // untyped constant -1.4 +_ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift +</pre> + +<h3 id="Handling_panics">Handling panics</h3> + +<p> Two built-in functions, <code>panic</code> and <code>recover</code>, +assist in reporting and handling <a href="#Run_time_panics">run-time panics</a> +and program-defined error conditions. +</p> + +<pre class="grammar"> +func panic(interface{}) +func recover() interface{} +</pre> + +<p> +While executing a function <code>F</code>, +an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a> +terminates the execution of <code>F</code>. +Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> +are then executed as usual. +Next, any deferred functions run by <code>F's</code> caller are run, +and so on up to any deferred by the top-level function in the executing goroutine. +At that point, the program is terminated and the error +condition is reported, including the value of the argument to <code>panic</code>. +This termination sequence is called <i>panicking</i>. +</p> + +<pre> +panic(42) +panic("unreachable") +panic(Error("cannot parse")) +</pre> + +<p> +The <code>recover</code> function allows a program to manage behavior +of a panicking goroutine. +Suppose a function <code>G</code> defers a function <code>D</code> that calls +<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code> +is executing. +When the running of deferred functions reaches <code>D</code>, +the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>. +If <code>D</code> returns normally, without starting a new +<code>panic</code>, the panicking sequence stops. In that case, +the state of functions called between <code>G</code> and the call to <code>panic</code> +is discarded, and normal execution resumes. +Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s +execution terminates by returning to its caller. +</p> + +<p> +The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds: +</p> +<ul> +<li> +<code>panic</code>'s argument was <code>nil</code>; +</li> +<li> +the goroutine is not panicking; +</li> +<li> +<code>recover</code> was not called directly by a deferred function. +</li> +</ul> + +<p> +The <code>protect</code> function in the example below invokes +the function argument <code>g</code> and protects callers from +run-time panics raised by <code>g</code>. +</p> + +<pre> +func protect(g func()) { + defer func() { + log.Println("done") // Println executes normally even if there is a panic + if x := recover(); x != nil { + log.Printf("run time panic: %v", x) + } + }() + log.Println("start") + g() +} +</pre> + + +<h3 id="Bootstrapping">Bootstrapping</h3> + +<p> +Current implementations provide several built-in functions useful during +bootstrapping. These functions are documented for completeness but are not +guaranteed to stay in the language. They do not return a result. +</p> + +<pre class="grammar"> +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 +</pre> + +<p> +Implementation restriction: <code>print</code> and <code>println</code> need not +accept arbitrary argument types, but printing of boolean, numeric, and string +<a href="#Types">types</a> must be supported. +</p> + +<h2 id="Packages">Packages</h2> + +<p> +Go programs are constructed by linking together <i>packages</i>. +A package in turn is constructed from one or more source files +that together declare constants, types, variables and functions +belonging to the package and which are accessible in all files +of the same package. Those elements may be +<a href="#Exported_identifiers">exported</a> and used in another package. +</p> + +<h3 id="Source_file_organization">Source file organization</h3> + +<p> +Each source file consists of a package clause defining the package +to which it belongs, followed by a possibly empty set of import +declarations that declare packages whose contents it wishes to use, +followed by a possibly empty set of declarations of functions, +types, variables, and constants. +</p> + +<pre class="ebnf"> +SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } . +</pre> + +<h3 id="Package_clause">Package clause</h3> + +<p> +A package clause begins each source file and defines the package +to which the file belongs. +</p> + +<pre class="ebnf"> +PackageClause = "package" PackageName . +PackageName = identifier . +</pre> + +<p> +The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>. +</p> + +<pre> +package math +</pre> + +<p> +A set of files sharing the same PackageName form the implementation of a package. +An implementation may require that all source files for a package inhabit the same directory. +</p> + +<h3 id="Import_declarations">Import declarations</h3> + +<p> +An import declaration states that the source file containing the declaration +depends on functionality of the <i>imported</i> package +(<a href="#Program_initialization_and_execution">§Program initialization and execution</a>) +and enables access to <a href="#Exported_identifiers">exported</a> identifiers +of that package. +The import names an identifier (PackageName) to be used for access and an ImportPath +that specifies the package to be imported. +</p> + +<pre class="ebnf"> +ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . +ImportSpec = [ "." | PackageName ] ImportPath . +ImportPath = string_lit . +</pre> + +<p> +The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a> +to access exported identifiers of the package within the importing source file. +It is declared in the <a href="#Blocks">file block</a>. +If the PackageName is omitted, it defaults to the identifier specified in the +<a href="#Package_clause">package clause</a> of the imported package. +If an explicit period (<code>.</code>) appears instead of a name, all the +package's exported identifiers declared in that package's +<a href="#Blocks">package block</a> will be declared in the importing source +file's file block and must be accessed without a qualifier. +</p> + +<p> +The interpretation of the ImportPath is implementation-dependent but +it is typically a substring of the full file name of the compiled +package and may be relative to a repository of installed packages. +</p> + +<p> +Implementation restriction: A compiler may restrict ImportPaths to +non-empty strings using only characters belonging to +<a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a> +L, M, N, P, and S general categories (the Graphic characters without +spaces) and may also exclude the characters +<code>!"#$%&'()*,:;<=>?[\]^`{|}</code> +and the Unicode replacement character U+FFFD. +</p> + +<p> +Assume we have compiled a package containing the package clause +<code>package math</code>, which exports function <code>Sin</code>, and +installed the compiled package in the file identified by +<code>"lib/math"</code>. +This table illustrates how <code>Sin</code> is accessed in files +that import the package after the +various types of import declaration. +</p> + +<pre class="grammar"> +Import declaration Local name of Sin + +import "lib/math" math.Sin +import m "lib/math" m.Sin +import . "lib/math" Sin +</pre> + +<p> +An import declaration declares a dependency relation between +the importing and imported package. +It is illegal for a package to import itself, directly or indirectly, +or to directly import a package without +referring to any of its exported identifiers. To import a package solely for +its side-effects (initialization), use the <a href="#Blank_identifier">blank</a> +identifier as explicit package name: +</p> + +<pre> +import _ "lib/math" +</pre> + + +<h3 id="An_example_package">An example package</h3> + +<p> +Here is a complete Go package that implements a concurrent prime sieve. +</p> + +<pre> +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() +} +</pre> + +<h2 id="Program_initialization_and_execution">Program initialization and execution</h2> + +<h3 id="The_zero_value">The zero value</h3> +<p> +When storage is allocated for a <a href="#Variables">variable</a>, +either through a declaration or a call of <code>new</code>, or when +a new value is created, either through a composite literal or a call +of <code>make</code>, +and no explicit initialization is provided, the variable or value is +given a default value. Each element of such a variable or value is +set to the <i>zero value</i> for its type: <code>false</code> for booleans, +<code>0</code> for numeric types, <code>""</code> +for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps. +This initialization is done recursively, so for instance each element of an +array of structs will have its fields zeroed if no value is specified. +</p> +<p> +These two simple declarations are equivalent: +</p> + +<pre> +var i int +var i int = 0 +</pre> + +<p> +After +</p> + +<pre> +type T struct { i int; f float64; next *T } +t := new(T) +</pre> + +<p> +the following holds: +</p> + +<pre> +t.i == 0 +t.f == 0.0 +t.next == nil +</pre> + +<p> +The same would also be true after +</p> + +<pre> +var t T +</pre> + +<h3 id="Package_initialization">Package initialization</h3> + +<p> +Within a package, package-level variable initialization proceeds stepwise, +with each step selecting the variable earliest in <i>declaration order</i> +which has no dependencies on uninitialized variables. +</p> + +<p> +More precisely, a package-level variable is considered <i>ready for +initialization</i> if it is not yet initialized and either has +no <a href="#Variable_declarations">initialization expression</a> or +its initialization expression has no <i>dependencies</i> on uninitialized variables. +Initialization proceeds by repeatedly initializing the next package-level +variable that is earliest in declaration order and ready for initialization, +until there are no variables ready for initialization. +</p> + +<p> +If any variables are still uninitialized when this +process ends, those variables are part of one or more initialization cycles, +and the program is not valid. +</p> + +<p> +Multiple variables on the left-hand side of a variable declaration initialized +by single (multi-valued) expression on the right-hand side are initialized +together: If any of the variables on the left-hand side is initialized, all +those variables are initialized in the same step. +</p> + +<pre> +var x = a +var a, b = f() // a and b are initialized together, before x is initialized +</pre> + +<p> +For the purpose of package initialization, <a href="#Blank_identifier">blank</a> +variables are treated like any other variables in declarations. +</p> + +<p> +The declaration order of variables declared in multiple files is determined +by the order in which the files are presented to the compiler: Variables +declared in the first file are declared before any of the variables declared +in the second file, and so on. +</p> + +<p> +Dependency analysis does not rely on the actual values of the +variables, only on lexical <i>references</i> to them in the source, +analyzed transitively. For instance, if a variable <code>x</code>'s +initialization expression refers to a function whose body refers to +variable <code>y</code> then <code>x</code> depends on <code>y</code>. +Specifically: +</p> + +<ul> +<li> +A reference to a variable or function is an identifier denoting that +variable or function. +</li> + +<li> +A reference to a method <code>m</code> is a +<a href="#Method_values">method value</a> or +<a href="#Method_expressions">method expression</a> of the form +<code>t.m</code>, where the (static) type of <code>t</code> is +not an interface type, and the method <code>m</code> is in the +<a href="#Method_sets">method set</a> of <code>t</code>. +It is immaterial whether the resulting function value +<code>t.m</code> is invoked. +</li> + +<li> +A variable, function, or method <code>x</code> depends on a variable +<code>y</code> if <code>x</code>'s initialization expression or body +(for functions and methods) contains a reference to <code>y</code> +or to a function or method that depends on <code>y</code>. +</li> +</ul> + +<p> +For example, given the declarations +</p> + +<pre> +var ( + a = c + b // == 9 + b = f() // == 4 + c = f() // == 5 + d = 3 // == 5 after initialization has finished +) + +func f() int { + d++ + return d +} +</pre> + +<p> +the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. +Note that the order of subexpressions in initialization expressions is irrelevant: +<code>a = c + b</code> and <code>a = b + c</code> result in the same initialization +order in this example. +</p> + +<p> +Dependency analysis is performed per package; only references referring +to variables, functions, and (non-interface) methods declared in the current +package are considered. If other, hidden, data dependencies exists between +variables, the initialization order between those variables is unspecified. +</p> + +<p> +For instance, given the declarations +</p> + +<pre> +var x = I(T{}).ab() // x has an undetected, hidden dependency on a and b +var _ = sideEffect() // unrelated to x, a, or b +var a = b +var b = 42 + +type I interface { ab() []int } +type T struct{} +func (T) ab() []int { return []int{a, b} } +</pre> + +<p> +the variable <code>a</code> will be initialized after <code>b</code> but +whether <code>x</code> is initialized before <code>b</code>, between +<code>b</code> and <code>a</code>, or after <code>a</code>, and +thus also the moment at which <code>sideEffect()</code> is called (before +or after <code>x</code> is initialized) is not specified. +</p> + +<p> +Variables may also be initialized using functions named <code>init</code> +declared in the package block, with no arguments and no result parameters. +</p> + +<pre> +func init() { … } +</pre> + +<p> +Multiple such functions may be defined per package, even within a single +source file. In the package block, the <code>init</code> identifier can +be used only to declare <code>init</code> functions, yet the identifier +itself is not <a href="#Declarations_and_scope">declared</a>. Thus +<code>init</code> functions cannot be referred to from anywhere +in a program. +</p> + +<p> +A package with no imports is initialized by assigning initial values +to all its package-level variables followed by calling all <code>init</code> +functions in the order they appear in the source, possibly in multiple files, +as presented to the compiler. +If a package has imports, the imported packages are initialized +before initializing the package itself. If multiple packages import +a package, the imported package will be initialized only once. +The importing of packages, by construction, guarantees that there +can be no cyclic initialization dependencies. +</p> + +<p> +Package initialization—variable initialization and the invocation of +<code>init</code> functions—happens in a single goroutine, +sequentially, one package at a time. +An <code>init</code> function may launch other goroutines, which can run +concurrently with the initialization code. However, initialization +always sequences +the <code>init</code> functions: it will not invoke the next one +until the previous one has returned. +</p> + +<p> +To ensure reproducible initialization behavior, build systems are encouraged +to present multiple files belonging to the same package in lexical file name +order to a compiler. +</p> + + +<h3 id="Program_execution">Program execution</h3> +<p> +A complete program is created by linking a single, unimported package +called the <i>main package</i> with all the packages it imports, transitively. +The main package must +have package name <code>main</code> and +declare a function <code>main</code> that takes no +arguments and returns no value. +</p> + +<pre> +func main() { … } +</pre> + +<p> +Program execution begins by initializing the main package and then +invoking the function <code>main</code>. +When that function invocation returns, the program exits. +It does not wait for other (non-<code>main</code>) goroutines to complete. +</p> + +<h2 id="Errors">Errors</h2> + +<p> +The predeclared type <code>error</code> is defined as +</p> + +<pre> +type error interface { + Error() string +} +</pre> + +<p> +It is the conventional interface for representing an error condition, +with the nil value representing no error. +For instance, a function to read data from a file might be defined: +</p> + +<pre> +func Read(f *File, b []byte) (n int, err error) +</pre> + +<h2 id="Run_time_panics">Run-time panics</h2> + +<p> +Execution errors such as attempting to index an array out +of bounds trigger a <i>run-time panic</i> equivalent to a call of +the built-in function <a href="#Handling_panics"><code>panic</code></a> +with a value of the implementation-defined interface type <code>runtime.Error</code>. +That type satisfies the predeclared interface type +<a href="#Errors"><code>error</code></a>. +The exact error values that +represent distinct run-time error conditions are unspecified. +</p> + +<pre> +package runtime + +type Error interface { + error + // and perhaps other methods +} +</pre> + +<h2 id="System_considerations">System considerations</h2> + +<h3 id="Package_unsafe">Package <code>unsafe</code></h3> + +<p> +The built-in package <code>unsafe</code>, known to the compiler +and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>, +provides facilities for low-level programming including operations +that violate the type system. A package using <code>unsafe</code> +must be vetted manually for type safety and may not be portable. +The package provides the following interface: +</p> + +<pre class="grammar"> +package unsafe + +type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type +type Pointer *ArbitraryType + +func Alignof(variable ArbitraryType) uintptr +func Offsetof(selector ArbitraryType) uintptr +func Sizeof(variable ArbitraryType) uintptr + +type IntegerType int // shorthand for an integer type; it is not a real type +func Add(ptr Pointer, len IntegerType) Pointer +func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType +</pre> + +<p> +A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> +value may not be <a href="#Address_operators">dereferenced</a>. +Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to +a type of underlying type <code>Pointer</code> and vice versa. +The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. +</p> + +<pre> +var f float64 +bits = *(*uint64)(unsafe.Pointer(&f)) + +type ptr unsafe.Pointer +bits = *(*uint64)(ptr(&f)) + +var p ptr = nil +</pre> + +<p> +The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code> +of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code> +as if <code>v</code> was declared via <code>var v = x</code>. +</p> +<p> +The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a> +<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code> +or <code>*s</code>, and returns the field offset in bytes relative to the struct's address. +If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable +without pointer indirections through fields of the struct. +For a struct <code>s</code> with field <code>f</code>: +</p> + +<pre> +uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f)) +</pre> + +<p> +Computer architectures may require memory addresses to be <i>aligned</i>; +that is, for addresses of a variable to be a multiple of a factor, +the variable's type's <i>alignment</i>. The function <code>Alignof</code> +takes an expression denoting a variable of any type and returns the +alignment of the (type of the) variable in bytes. For a variable +<code>x</code>: +</p> + +<pre> +uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0 +</pre> + +<p> +Calls to <code>Alignof</code>, <code>Offsetof</code>, and +<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>. +</p> + +<p> +The function <code>Add</code> adds <code>len</code> to <code>ptr</code> +and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code>. +The <code>len</code> argument must be of integer type or an untyped <a href="#Constants">constant</a>. +A constant <code>len</code> argument must be <a href="#Representability">representable</a> by a value of type <code>int</code>; +if it is an untyped constant it is given type <code>int</code>. +The rules for <a href="/pkg/unsafe#Pointer">valid uses</a> of <code>Pointer</code> still apply. +</p> + +<p> +The function <code>Slice</code> returns a slice whose underlying array starts at <code>ptr</code> +and whose length and capacity are <code>len</code>. +<code>Slice(ptr, len)</code> is equivalent to +</p> + +<pre> +(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:] +</pre> + +<p> +except that, as a special case, if <code>ptr</code> +is <code>nil</code> and <code>len</code> is zero, +<code>Slice</code> returns <code>nil</code>. +</p> + +<p> +The <code>len</code> argument must be of integer type or an untyped <a href="#Constants">constant</a>. +A constant <code>len</code> argument must be non-negative and <a href="#Representability">representable</a> by a value of type <code>int</code>; +if it is an untyped constant it is given type <code>int</code>. +At run time, if <code>len</code> is negative, +or if <code>ptr</code> is <code>nil</code> and <code>len</code> is not zero, +a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> + +<p> +For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed: +</p> + +<pre class="grammar"> +type size in bytes + +byte, uint8, int8 1 +uint16, int16 2 +uint32, int32, float32 4 +uint64, int64, float64, complex64 8 +complex128 16 +</pre> + +<p> +The following minimal alignment properties are guaranteed: +</p> +<ol> +<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1. +</li> + +<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of + all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1. +</li> + +<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as + the alignment of a variable of the array's element type. +</li> +</ol> + +<p> +A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory. +</p> diff --git a/doc/go_mem.html b/doc/go_mem.html new file mode 100644 index 0000000..026c117 --- /dev/null +++ b/doc/go_mem.html @@ -0,0 +1,977 @@ +<!--{ + "Title": "The Go Memory Model", + "Subtitle": "Version of June 6, 2022", + "Path": "/ref/mem" +}--> + +<style> +p.rule { + font-style: italic; +} +</style> + +<h2 id="introduction">Introduction</h2> + +<p> +The Go memory model specifies the conditions under which +reads of a variable in one goroutine can be guaranteed to +observe values produced by writes to the same variable in a different goroutine. +</p> + + +<h3 id="advice">Advice</h3> + +<p> +Programs that modify data being simultaneously accessed by multiple goroutines +must serialize such access. +</p> + +<p> +To serialize access, protect the data with channel operations or other synchronization primitives +such as those in the <a href="/pkg/sync/"><code>sync</code></a> +and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages. +</p> + +<p> +If you must read the rest of this document to understand the behavior of your program, +you are being too clever. +</p> + +<p> +Don't be clever. +</p> + +<h3 id="overview">Informal Overview</h3> + +<p> +Go approaches its memory model in much the same way as the rest of the language, +aiming to keep the semantics simple, understandable, and useful. +This section gives a general overview of the approach and should suffice for most programmers. +The memory model is specified more formally in the next section. +</p> + +<p> +A <em>data race</em> is defined as +a write to a memory location happening concurrently with another read or write to that same location, +unless all the accesses involved are atomic data accesses as provided by the <code>sync/atomic</code> package. +As noted already, programmers are strongly encouraged to use appropriate synchronization +to avoid data races. +In the absence of data races, Go programs behave as if all the goroutines +were multiplexed onto a single processor. +This property is sometimes referred to as DRF-SC: data-race-free programs +execute in a sequentially consistent manner. +</p> + +<p> +While programmers should write Go programs without data races, +there are limitations to what a Go implementation can do in response to a data race. +An implementation may always react to a data race by reporting the race and terminating the program. +Otherwise, each read of a single-word-sized or sub-word-sized memory location +must observe a value actually written to that location (perhaps by a concurrent executing goroutine) +and not yet overwritten. +These implementation constraints make Go more like Java or JavaScript, +in that most races have a limited number of outcomes, +and less like C and C++, where the meaning of any program with a race +is entirely undefined, and the compiler may do anything at all. +Go's approach aims to make errant programs more reliable and easier to debug, +while still insisting that races are errors and that tools can diagnose and report them. +</p> + +<h2 id="model">Memory Model</h2> + +<p> +The following formal definition of Go's memory model closely follows +the approach presented by Hans-J. Boehm and Sarita V. Adve in +“<a href="https://www.hpl.hp.com/techreports/2008/HPL-2008-56.pdf">Foundations of the C++ Concurrency Memory Model</a>”, +published in PLDI 2008. +The definition of data-race-free programs and the guarantee of sequential consistency +for race-free programs are equivalent to the ones in that work. +</p> + +<p> +The memory model describes the requirements on program executions, +which are made up of goroutine executions, +which in turn are made up of memory operations. +</p> + +<p> +A <i>memory operation</i> is modeled by four details: +</p> +<ul> +<li>its kind, indicating whether it is an ordinary data read, an ordinary data write, +or a <i>synchronizing operation</i> such as an atomic data access, +a mutex operation, or a channel operation, +<li>its location in the program, +<li>the memory location or variable being accessed, and +<li>the values read or written by the operation. +</ul> +<p> +Some memory operations are <i>read-like</i>, including read, atomic read, mutex lock, and channel receive. +Other memory operations are <i>write-like</i>, including write, atomic write, mutex unlock, channel send, and channel close. +Some, such as atomic compare-and-swap, are both read-like and write-like. +</p> + +<p> +A <i>goroutine execution</i> is modeled as a set of memory operations executed by a single goroutine. +</p> + +<p> +<b>Requirement 1</b>: +The memory operations in each goroutine must correspond to a correct sequential execution of that goroutine, +given the values read from and written to memory. +That execution must be consistent with the <i>sequenced before</i> relation, +defined as the partial order requirements set out by the <a href="/ref/spec">Go language specification</a> +for Go's control flow constructs as well as the <a href="/ref/spec#Order_of_evaluation">order of evaluation for expressions</a>. +</p> + +<p> +A Go <i>program execution</i> is modeled as a set of goroutine executions, +together with a mapping <i>W</i> that specifies the write-like operation that each read-like operation reads from. +(Multiple executions of the same program can have different program executions.) +</p> + +<p> +<b>Requirement 2</b>: +For a given program execution, the mapping <i>W</i>, when limited to synchronizing operations, +must be explainable by some implicit total order of the synchronizing operations +that is consistent with sequencing and the values read and written by those operations. +</p> + +<p> +The <i>synchronized before</i> relation is a partial order on synchronizing memory operations, +derived from <i>W</i>. +If a synchronizing read-like memory operation <i>r</i> +observes a synchronizing write-like memory operation <i>w</i> +(that is, if <i>W</i>(<i>r</i>) = <i>w</i>), +then <i>w</i> is synchronized before <i>r</i>. +Informally, the synchronized before relation is a subset of the implied total order +mentioned in the previous paragraph, +limited to the information that <i>W</i> directly observes. +</p> + +<p> +The <i>happens before</i> relation is defined as the transitive closure of the +union of the sequenced before and synchronized before relations. +</p> + +<p> +<b>Requirement 3</b>: +For an ordinary (non-synchronizing) data read <i>r</i> on a memory location <i>x</i>, +<i>W</i>(<i>r</i>) must be a write <i>w</i> that is <i>visible</i> to <i>r</i>, +where visible means that both of the following hold: +</p> + +<ol> +<li><i>w</i> happens before <i>r</i>. +<li><i>w</i> does not happen before any other write <i>w'</i> (to <i>x</i>) that happens before <i>r</i>. +</ol> + +<p> +A <i>read-write data race</i> on memory location <i>x</i> +consists of a read-like memory operation <i>r</i> on <i>x</i> +and a write-like memory operation <i>w</i> on <i>x</i>, +at least one of which is non-synchronizing, +which are unordered by happens before +(that is, neither <i>r</i> happens before <i>w</i> +nor <i>w</i> happens before <i>r</i>). +</p> + +<p> +A <i>write-write data race</i> on memory location <i>x</i> +consists of two write-like memory operations <i>w</i> and <i>w'</i> on <i>x</i>, +at least one of which is non-synchronizing, +which are unordered by happens before. +</p> + +<p> +Note that if there are no read-write or write-write data races on memory location <i>x</i>, +then any read <i>r</i> on <i>x</i> has only one possible <i>W</i>(<i>r</i>): +the single <i>w</i> that immediately precedes it in the happens before order. +</p> + +<p> +More generally, it can be shown that any Go program that is data-race-free, +meaning it has no program executions with read-write or write-write data races, +can only have outcomes explained by some sequentially consistent interleaving +of the goroutine executions. +(The proof is the same as Section 7 of Boehm and Adve's paper cited above.) +This property is called DRF-SC. +</p> + +<p> +The intent of the formal definition is to match +the DRF-SC guarantee provided to race-free programs +by other languages, including C, C++, Java, JavaScript, Rust, and Swift. +</p> + +<p> +Certain Go language operations such as goroutine creation and memory allocation +act as synchronization operations. +The effect of these operations on the synchronized-before partial order +is documented in the “Synchronization” section below. +Individual packages are responsible for providing similar documentation +for their own operations. +</p> + +<h2 id="restrictions">Implementation Restrictions for Programs Containing Data Races</h2> + +<p> +The preceding section gave a formal definition of data-race-free program execution. +This section informally describes the semantics that implementations must provide +for programs that do contain races. +</p> + +<p> +Any implementation can, upon detecting a data race, +report the race and halt execution of the program. +Implementations using ThreadSanitizer +(accessed with “<code>go</code> <code>build</code> <code>-race</code>”) +do exactly this. +</p> + +<p> +A read of an array, struct, or complex number +may by implemented as a read of each individual sub-value +(array element, struct field, or real/imaginary component), +in any order. +Similarly, a write of an array, struct, or complex number +may be implemented as a write of each individual sub-value, +in any order. +</p> + +<p> +A read <i>r</i> of a memory location <i>x</i> +holding a value +that is not larger than a machine word must observe +some write <i>w</i> such that <i>r</i> does not happen before <i>w</i> +and there is no write <i>w'</i> such that <i>w</i> happens before <i>w'</i> +and <i>w'</i> happens before <i>r</i>. +That is, each read must observe a value written by a preceding or concurrent write. +</p> + +<p> +Additionally, observation of acausal and “out of thin air” writes is disallowed. +</p> + +<p> +Reads of memory locations larger than a single machine word +are encouraged but not required to meet the same semantics +as word-sized memory locations, +observing a single allowed write <i>w</i>. +For performance reasons, +implementations may instead treat larger operations +as a set of individual machine-word-sized operations +in an unspecified order. +This means that races on multiword data structures +can lead to inconsistent values not corresponding to a single write. +When the values depend on the consistency +of internal (pointer, length) or (pointer, type) pairs, +as can be the case for interface values, maps, +slices, and strings in most Go implementations, +such races can in turn lead to arbitrary memory corruption. +</p> + +<p> +Examples of incorrect synchronization are given in the +“Incorrect synchronization” section below. +</p> + +<p> +Examples of the limitations on implementations are given in the +“Incorrect compilation” section below. +</p> + +<h2 id="synchronization">Synchronization</h2> + +<h3 id="init">Initialization</h3> + +<p> +Program initialization runs in a single goroutine, +but that goroutine may create other goroutines, +which run concurrently. +</p> + +<p class="rule"> +If a package <code>p</code> imports package <code>q</code>, the completion of +<code>q</code>'s <code>init</code> functions happens before the start of any of <code>p</code>'s. +</p> + +<p class="rule"> +The completion of all <code>init</code> functions is synchronized before +the start of the function <code>main.main</code>. +</p> + +<h3 id="go">Goroutine creation</h3> + +<p class="rule"> +The <code>go</code> statement that starts a new goroutine +is synchronized before the start of the goroutine's execution. +</p> + +<p> +For example, in this program: +</p> + +<pre> +var a string + +func f() { + print(a) +} + +func hello() { + a = "hello, world" + go f() +} +</pre> + +<p> +calling <code>hello</code> will print <code>"hello, world"</code> +at some point in the future (perhaps after <code>hello</code> has returned). +</p> + +<h3 id="goexit">Goroutine destruction</h3> + +<p> +The exit of a goroutine is not guaranteed to be synchronized before +any event in the program. +For example, in this program: +</p> + +<pre> +var a string + +func hello() { + go func() { a = "hello" }() + print(a) +} +</pre> + +<p> +the assignment to <code>a</code> is not followed by +any synchronization event, so it is not guaranteed to be +observed by any other goroutine. +In fact, an aggressive compiler might delete the entire <code>go</code> statement. +</p> + +<p> +If the effects of a goroutine must be observed by another goroutine, +use a synchronization mechanism such as a lock or channel +communication to establish a relative ordering. +</p> + +<h3 id="chan">Channel communication</h3> + +<p> +Channel communication is the main method of synchronization +between goroutines. Each send on a particular channel +is matched to a corresponding receive from that channel, +usually in a different goroutine. +</p> + +<p class="rule"> +A send on a channel is synchronized before the completion of the +corresponding receive from that channel. +</p> + +<p> +This program: +</p> + +<pre> +var c = make(chan int, 10) +var a string + +func f() { + a = "hello, world" + c <- 0 +} + +func main() { + go f() + <-c + print(a) +} +</pre> + +<p> +is guaranteed to print <code>"hello, world"</code>. The write to <code>a</code> +is sequenced before the send on <code>c</code>, which is synchronized before +the corresponding receive on <code>c</code> completes, which is sequenced before +the <code>print</code>. +</p> + +<p class="rule"> +The closing of a channel is synchronized before a receive that returns a zero value +because the channel is closed. +</p> + +<p> +In the previous example, replacing +<code>c <- 0</code> with <code>close(c)</code> +yields a program with the same guaranteed behavior. +</p> + +<p class="rule"> +A receive from an unbuffered channel is synchronized before the completion of +the corresponding send on that channel. +</p> + +<p> +This program (as above, but with the send and receive statements swapped and +using an unbuffered channel): +</p> + +<pre> +var c = make(chan int) +var a string + +func f() { + a = "hello, world" + <-c +} + +func main() { + go f() + c <- 0 + print(a) +} +</pre> + +<p> +is also guaranteed to print <code>"hello, world"</code>. The write to <code>a</code> +is sequenced before the receive on <code>c</code>, which is synchronized before +the corresponding send on <code>c</code> completes, which is sequenced +before the <code>print</code>. +</p> + +<p> +If the channel were buffered (e.g., <code>c = make(chan int, 1)</code>) +then the program would not be guaranteed to print +<code>"hello, world"</code>. (It might print the empty string, +crash, or do something else.) +</p> + +<p class="rule"> +The <i>k</i>th receive on a channel with capacity <i>C</i> is synchronized before the completion of the <i>k</i>+<i>C</i>th send from that channel completes. +</p> + +<p> +This rule generalizes the previous rule to buffered channels. +It allows a counting semaphore to be modeled by a buffered channel: +the number of items in the channel corresponds to the number of active uses, +the capacity of the channel corresponds to the maximum number of simultaneous uses, +sending an item acquires the semaphore, and receiving an item releases +the semaphore. +This is a common idiom for limiting concurrency. +</p> + +<p> +This program starts a goroutine for every entry in the work list, but the +goroutines coordinate using the <code>limit</code> channel to ensure +that at most three are running work functions at a time. +</p> + +<pre> +var limit = make(chan int, 3) + +func main() { + for _, w := range work { + go func(w func()) { + limit <- 1 + w() + <-limit + }(w) + } + select{} +} +</pre> + +<h3 id="locks">Locks</h3> + +<p> +The <code>sync</code> package implements two lock data types, +<code>sync.Mutex</code> and <code>sync.RWMutex</code>. +</p> + +<p class="rule"> +For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> < <i>m</i>, +call <i>n</i> of <code>l.Unlock()</code> is synchronized before call <i>m</i> of <code>l.Lock()</code> returns. +</p> + +<p> +This program: +</p> + +<pre> +var l sync.Mutex +var a string + +func f() { + a = "hello, world" + l.Unlock() +} + +func main() { + l.Lock() + go f() + l.Lock() + print(a) +} +</pre> + +<p> +is guaranteed to print <code>"hello, world"</code>. +The first call to <code>l.Unlock()</code> (in <code>f</code>) is synchronized +before the second call to <code>l.Lock()</code> (in <code>main</code>) returns, +which is sequenced before the <code>print</code>. +</p> + +<p class="rule"> +For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>, +there is an <i>n</i> such that the <i>n</i>th call to <code>l.Unlock</code> +is synchronized before the return from <code>l.RLock</code>, +and the matching call to <code>l.RUnlock</code> is synchronized before the return from call <i>n</i>+1 to <code>l.Lock</code>. +</p> + +<p class="rule"> +A successful call to <code>l.TryLock</code> (or <code>l.TryRLock</code>) +is equivalent to a call to <code>l.Lock</code> (or <code>l.RLock</code>). +An unsuccessful call has no synchronizing effect at all. +As far as the memory model is concerned, +<code>l.TryLock</code> (or <code>l.TryRLock</code>) +may be considered to be able to return false +even when the mutex <i>l</i> is unlocked. +</p> + +<h3 id="once">Once</h3> + +<p> +The <code>sync</code> package provides a safe mechanism for +initialization in the presence of multiple goroutines +through the use of the <code>Once</code> type. +Multiple threads can execute <code>once.Do(f)</code> for a particular <code>f</code>, +but only one will run <code>f()</code>, and the other calls block +until <code>f()</code> has returned. +</p> + +<p class="rule"> +The completion of a single call of <code>f()</code> from <code>once.Do(f)</code> +is synchronized before the return of any call of <code>once.Do(f)</code>. +</p> + +<p> +In this program: +</p> + +<pre> +var a string +var once sync.Once + +func setup() { + a = "hello, world" +} + +func doprint() { + once.Do(setup) + print(a) +} + +func twoprint() { + go doprint() + go doprint() +} +</pre> + +<p> +calling <code>twoprint</code> will call <code>setup</code> exactly +once. +The <code>setup</code> function will complete before either call +of <code>print</code>. +The result will be that <code>"hello, world"</code> will be printed +twice. +</p> + +<h3 id="atomic">Atomic Values</h3> + +<p> +The APIs in the <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> +package are collectively “atomic operations” +that can be used to synchronize the execution of different goroutines. +If the effect of an atomic operation <i>A</i> is observed by atomic operation <i>B</i>, +then <i>A</i> is synchronized before <i>B</i>. +All the atomic operations executed in a program behave as though executed +in some sequentially consistent order. +</p> + +<p> +The preceding definition has the same semantics as C++’s sequentially consistent atomics +and Java’s <code>volatile</code> variables. +</p> + +<h3 id="finalizer">Finalizers</h3> + +<p> +The <a href="/pkg/runtime/"><code>runtime</code></a> package provides +a <code>SetFinalizer</code> function that adds a finalizer to be called when +a particular object is no longer reachable by the program. +A call to <code>SetFinalizer(x, f)</code> is synchronized before the finalization call <code>f(x)</code>. +</p> + +<h3 id="more">Additional Mechanisms</h3> + +<p> +The <code>sync</code> package provides additional synchronization abstractions, +including <a href="/pkg/sync/#Cond">condition variables</a>, +<a href="/pkg/sync/#Map">lock-free maps</a>, +<a href="/pkg/sync/#Pool">allocation pools</a>, +and +<a href="/pkg/sync/#WaitGroup">wait groups</a>. +The documentation for each of these specifies the guarantees it +makes concerning synchronization. +</p> + +<p> +Other packages that provide synchronization abstractions +should document the guarantees they make too. +</p> + + +<h2 id="badsync">Incorrect synchronization</h2> + +<p> +Programs with races are incorrect and +can exhibit non-sequentially consistent executions. +In particular, note that a read <i>r</i> may observe the value written by any write <i>w</i> +that executes concurrently with <i>r</i>. +Even if this occurs, it does not imply that reads happening after <i>r</i> +will observe writes that happened before <i>w</i>. +</p> + +<p> +In this program: +</p> + +<pre> +var a, b int + +func f() { + a = 1 + b = 2 +} + +func g() { + print(b) + print(a) +} + +func main() { + go f() + g() +} +</pre> + +<p> +it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>. +</p> + +<p> +This fact invalidates a few common idioms. +</p> + +<p> +Double-checked locking is an attempt to avoid the overhead of synchronization. +For example, the <code>twoprint</code> program might be +incorrectly written as: +</p> + +<pre> +var a string +var done bool + +func setup() { + a = "hello, world" + done = true +} + +func doprint() { + if !done { + once.Do(setup) + } + print(a) +} + +func twoprint() { + go doprint() + go doprint() +} +</pre> + +<p> +but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code> +implies observing the write to <code>a</code>. This +version can (incorrectly) print an empty string +instead of <code>"hello, world"</code>. +</p> + +<p> +Another incorrect idiom is busy waiting for a value, as in: +</p> + +<pre> +var a string +var done bool + +func setup() { + a = "hello, world" + done = true +} + +func main() { + go setup() + for !done { + } + print(a) +} +</pre> + +<p> +As before, there is no guarantee that, in <code>main</code>, +observing the write to <code>done</code> +implies observing the write to <code>a</code>, so this program could +print an empty string too. +Worse, there is no guarantee that the write to <code>done</code> will ever +be observed by <code>main</code>, since there are no synchronization +events between the two threads. The loop in <code>main</code> is not +guaranteed to finish. +</p> + +<p> +There are subtler variants on this theme, such as this program. +</p> + +<pre> +type T struct { + msg string +} + +var g *T + +func setup() { + t := new(T) + t.msg = "hello, world" + g = t +} + +func main() { + go setup() + for g == nil { + } + print(g.msg) +} +</pre> + +<p> +Even if <code>main</code> observes <code>g != nil</code> and exits its loop, +there is no guarantee that it will observe the initialized +value for <code>g.msg</code>. +</p> + +<p> +In all these examples, the solution is the same: +use explicit synchronization. +</p> + +<h2 id="badcompiler">Incorrect compilation</h2> + +<p> +The Go memory model restricts compiler optimizations as much as it does Go programs. +Some compiler optimizations that would be valid in single-threaded programs are not valid in all Go programs. +In particular, a compiler must not introduce writes that do not exist in the original program, +it must not allow a single read to observe multiple values, +and it must not allow a single write to write multiple values. +</p> + +<p> +All the following examples assume that `*p` and `*q` refer to +memory locations accessible to multiple goroutines. +</p> + +<p> +Not introducing data races into race-free programs means not moving +writes out of conditional statements in which they appear. +For example, a compiler must not invert the conditional in this program: +</p> + +<pre> +*p = 1 +if cond { + *p = 2 +} +</pre> + +<p> +That is, the compiler must not rewrite the program into this one: +</p> + +<pre> +*p = 2 +if !cond { + *p = 1 +} +</pre> + +<p> +If <code>cond</code> is false and another goroutine is reading <code>*p</code>, +then in the original program, the other goroutine can only observe any prior value of <code>*p</code> and <code>1</code>. +In the rewritten program, the other goroutine can observe <code>2</code>, which was previously impossible. +</p> + +<p> +Not introducing data races also means not assuming that loops terminate. +For example, a compiler must in general not move the accesses to <code>*p</code> or <code>*q</code> +ahead of the loop in this program: +</p> + +<pre> +n := 0 +for e := list; e != nil; e = e.next { + n++ +} +i := *p +*q = 1 +</pre> + +<p> +If <code>list</code> pointed to a cyclic list, +then the original program would never access <code>*p</code> or <code>*q</code>, +but the rewritten program would. +(Moving `*p` ahead would be safe if the compiler can prove `*p` will not panic; +moving `*q` ahead would also require the compiler proving that no other +goroutine can access `*q`.) +</p> + +<p> +Not introducing data races also means not assuming that called functions +always return or are free of synchronization operations. +For example, a compiler must not move the accesses to <code>*p</code> or <code>*q</code> +ahead of the function call in this program +(at least not without direct knowledge of the precise behavior of <code>f</code>): +</p> + +<pre> +f() +i := *p +*q = 1 +</pre> + +<p> +If the call never returned, then once again the original program +would never access <code>*p</code> or <code>*q</code>, but the rewritten program would. +And if the call contained synchronizing operations, then the original program +could establish happens before edges preceding the accesses +to <code>*p</code> and <code>*q</code>, but the rewritten program would not. +</p> + +<p> +Not allowing a single read to observe multiple values means +not reloading local variables from shared memory. +For example, a compiler must not discard <code>i</code> and reload it +a second time from <code>*p</code> in this program: +</p> + +<pre> +i := *p +if i < 0 || i >= len(funcs) { + panic("invalid function index") +} +... complex code ... +// compiler must NOT reload i = *p here +funcs[i]() +</pre> + +<p> +If the complex code needs many registers, a compiler for single-threaded programs +could discard <code>i</code> without saving a copy and then reload +<code>i = *p</code> just before +<code>funcs[i]()</code>. +A Go compiler must not, because the value of <code>*p</code> may have changed. +(Instead, the compiler could spill <code>i</code> to the stack.) +</p> + +<p> +Not allowing a single write to write multiple values also means not using +the memory where a local variable will be written as temporary storage before the write. +For example, a compiler must not use <code>*p</code> as temporary storage in this program: +</p> + +<pre> +*p = i + *p/2 +</pre> + +<p> +That is, it must not rewrite the program into this one: +</p> + +<pre> +*p /= 2 +*p += i +</pre> + +<p> +If <code>i</code> and <code>*p</code> start equal to 2, +the original code does <code>*p = 3</code>, +so a racing thread can read only 2 or 3 from <code>*p</code>. +The rewritten code does <code>*p = 1</code> and then <code>*p = 3</code>, +allowing a racing thread to read 1 as well. +</p> + +<p> +Note that all these optimizations are permitted in C/C++ compilers: +a Go compiler sharing a back end with a C/C++ compiler must take care +to disable optimizations that are invalid for Go. +</p> + +<p> +Note that the prohibition on introducing data races +does not apply if the compiler can prove that the races +do not affect correct execution on the target platform. +For example, on essentially all CPUs, it is valid to rewrite +</p> + +<pre> +n := 0 +for i := 0; i < m; i++ { + n += *shared +} +</pre> + +into: + +<pre> +n := 0 +local := *shared +for i := 0; i < m; i++ { + n += local +} +</pre> + +<p> +provided it can be proved that <code>*shared</code> will not fault on access, +because the potential added read will not affect any existing concurrent reads or writes. +On the other hand, the rewrite would not be valid in a source-to-source translator. +</p> + +<h2 id="conclusion">Conclusion</h2> + +<p> +Go programmers writing data-race-free programs can rely on +sequentially consistent execution of those programs, +just as in essentially all other modern programming languages. +</p> + +<p> +When it comes to programs with races, +both programmers and compilers should remember the advice: +don't be clever. +</p> diff --git a/doc/go_spec.html b/doc/go_spec.html new file mode 100644 index 0000000..7b9dd38 --- /dev/null +++ b/doc/go_spec.html @@ -0,0 +1,8754 @@ +<!--{ + "Title": "The Go Programming Language Specification", + "Subtitle": "Language version go1.22 (Feb 6, 2024)", + "Path": "/ref/spec" +}--> + +<h2 id="Introduction">Introduction</h2> + +<p> +This is the reference manual for the Go programming language. +The pre-Go1.18 version, without generics, can be found +<a href="/doc/go1.17_spec.html">here</a>. +For more information and other documents, see <a href="/">go.dev</a>. +</p> + +<p> +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 +<i>packages</i>, whose properties allow efficient management of +dependencies. +</p> + +<p> +The syntax is compact and simple to parse, allowing for easy analysis +by automatic tools such as integrated development environments. +</p> + +<h2 id="Notation">Notation</h2> +<p> +The syntax is specified using a +<a href="https://en.wikipedia.org/wiki/Wirth_syntax_notation">variant</a> +of Extended Backus-Naur Form (EBNF): +</p> + +<pre class="grammar"> +Syntax = { Production } . +Production = production_name "=" [ Expression ] "." . +Expression = Term { "|" Term } . +Term = Factor { Factor } . +Factor = production_name | token [ "…" token ] | Group | Option | Repetition . +Group = "(" Expression ")" . +Option = "[" Expression "]" . +Repetition = "{" Expression "}" . +</pre> + +<p> +Productions are expressions constructed from terms and the following +operators, in increasing precedence: +</p> +<pre class="grammar"> +| alternation +() grouping +[] option (0 or 1 times) +{} repetition (0 to n times) +</pre> + +<p> +Lowercase production names are used to identify lexical (terminal) tokens. +Non-terminals are in CamelCase. Lexical tokens are enclosed in +double quotes <code>""</code> or back quotes <code>``</code>. +</p> + +<p> +The form <code>a … b</code> represents the set of characters from +<code>a</code> through <code>b</code> as alternatives. The horizontal +ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various +enumerations or code snippets that are not further specified. The character <code>…</code> +(as opposed to the three characters <code>...</code>) is not a token of the Go +language. +</p> + +<p> +A link of the form [<a href="#Language_versions">Go 1.xx</a>] indicates that a described +language feature (or some aspect of it) was changed or added with language version 1.xx and +thus requires at minimum that language version to build. +For details, see the <a href="#Language_versions">linked section</a> +in the <a href="#Appendix">appendix</a>. +</p> + +<h2 id="Source_code_representation">Source code representation</h2> + +<p> +Source code is Unicode text encoded in +<a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. 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 unqualified term <i>character</i> to refer to a Unicode code point +in the source text. +</p> +<p> +Each code point is distinct; for instance, uppercase and lowercase letters +are different characters. +</p> +<p> +Implementation restriction: For compatibility with other tools, a +compiler may disallow the NUL character (U+0000) in the source text. +</p> +<p> +Implementation restriction: For compatibility with other tools, a +compiler may ignore a UTF-8-encoded byte order mark +(U+FEFF) if it is the first Unicode code point in the source text. +A byte order mark may be disallowed anywhere else in the source. +</p> + +<h3 id="Characters">Characters</h3> + +<p> +The following terms are used to denote specific Unicode character categories: +</p> +<pre class="ebnf"> +newline = /* the Unicode code point U+000A */ . +unicode_char = /* an arbitrary Unicode code point except newline */ . +unicode_letter = /* a Unicode code point categorized as "Letter" */ . +unicode_digit = /* a Unicode code point categorized as "Number, decimal digit" */ . +</pre> + +<p> +In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>, +Section 4.5 "General Category" defines a set of character categories. +Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo +as Unicode letters, and those in the Number category Nd as Unicode digits. +</p> + +<h3 id="Letters_and_digits">Letters and digits</h3> + +<p> +The underscore character <code>_</code> (U+005F) is considered a lowercase letter. +</p> +<pre class="ebnf"> +letter = unicode_letter | "_" . +decimal_digit = "0" … "9" . +binary_digit = "0" | "1" . +octal_digit = "0" … "7" . +hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . +</pre> + +<h2 id="Lexical_elements">Lexical elements</h2> + +<h3 id="Comments">Comments</h3> + +<p> +Comments serve as program documentation. There are two forms: +</p> + +<ol> +<li> +<i>Line comments</i> start with the character sequence <code>//</code> +and stop at the end of the line. +</li> +<li> +<i>General comments</i> start with the character sequence <code>/*</code> +and stop with the first subsequent character sequence <code>*/</code>. +</li> +</ol> + +<p> +A comment cannot start inside a <a href="#Rune_literals">rune</a> or +<a href="#String_literals">string literal</a>, or inside a comment. +A general comment containing no newlines acts like a space. +Any other comment acts like a newline. +</p> + +<h3 id="Tokens">Tokens</h3> + +<p> +Tokens form the vocabulary of the Go language. +There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators +and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from +spaces (U+0020), horizontal tabs (U+0009), +carriage returns (U+000D), and newlines (U+000A), +is ignored except as it separates tokens +that would otherwise combine into a single token. Also, a newline or end of file +may trigger the insertion of a <a href="#Semicolons">semicolon</a>. +While breaking the input into tokens, +the next token is the longest sequence of characters that form a +valid token. +</p> + +<h3 id="Semicolons">Semicolons</h3> + +<p> +The formal syntax uses semicolons <code>";"</code> as terminators in +a number of productions. Go programs may omit most of these semicolons +using the following two rules: +</p> + +<ol> +<li> +When the input is broken into tokens, a semicolon is automatically inserted +into the token stream immediately after a line's final token if that token is +<ul> + <li>an + <a href="#Identifiers">identifier</a> + </li> + + <li>an + <a href="#Integer_literals">integer</a>, + <a href="#Floating-point_literals">floating-point</a>, + <a href="#Imaginary_literals">imaginary</a>, + <a href="#Rune_literals">rune</a>, or + <a href="#String_literals">string</a> literal + </li> + + <li>one of the <a href="#Keywords">keywords</a> + <code>break</code>, + <code>continue</code>, + <code>fallthrough</code>, or + <code>return</code> + </li> + + <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a> + <code>++</code>, + <code>--</code>, + <code>)</code>, + <code>]</code>, or + <code>}</code> + </li> +</ul> +</li> + +<li> +To allow complex statements to occupy a single line, a semicolon +may be omitted before a closing <code>")"</code> or <code>"}"</code>. +</li> +</ol> + +<p> +To reflect idiomatic use, code examples in this document elide semicolons +using these rules. +</p> + + +<h3 id="Identifiers">Identifiers</h3> + +<p> +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. +</p> +<pre class="ebnf"> +identifier = letter { letter | unicode_digit } . +</pre> +<pre> +a +_x9 +ThisVariableIsExported +αβ +</pre> + +<p> +Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. +</p> + + +<h3 id="Keywords">Keywords</h3> + +<p> +The following keywords are reserved and may not be used as identifiers. +</p> +<pre class="grammar"> +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 +</pre> + +<h3 id="Operators_and_punctuation">Operators and punctuation</h3> + +<p> +The following character sequences represent <a href="#Operators">operators</a> +(including <a href="#Assignment_statements">assignment operators</a>) and punctuation +[<a href="#Go_1.18">Go 1.18</a>]: +</p> +<pre class="grammar"> ++ & += &= && == != ( ) +- | -= |= || < <= [ ] +* ^ *= ^= <- > >= { } +/ << /= <<= ++ = := , ; +% >> %= >>= -- ! ... . : + &^ &^= ~ +</pre> + +<h3 id="Integer_literals">Integer literals</h3> + +<p> +An integer literal is a sequence of digits representing an +<a href="#Constants">integer constant</a>. +An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code> +for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal, +and <code>0x</code> or <code>0X</code> for hexadecimal +[<a href="#Go_1.13">Go 1.13</a>]. +A single <code>0</code> is considered a decimal zero. +In hexadecimal literals, letters <code>a</code> through <code>f</code> +and <code>A</code> through <code>F</code> represent values 10 through 15. +</p> + +<p> +For readability, an underscore character <code>_</code> may appear after +a base prefix or between successive digits; such underscores do not change +the literal's value. +</p> +<pre class="ebnf"> +int_lit = decimal_lit | binary_lit | octal_lit | hex_lit . +decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] . +binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits . +octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits . +hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits . + +decimal_digits = decimal_digit { [ "_" ] decimal_digit } . +binary_digits = binary_digit { [ "_" ] binary_digit } . +octal_digits = octal_digit { [ "_" ] octal_digit } . +hex_digits = hex_digit { [ "_" ] hex_digit } . +</pre> + +<pre> +42 +4_2 +0600 +0_600 +0o600 +0O600 // second character is capital letter 'O' +0xBadFace +0xBad_Face +0x_67_7a_2f_cc_40_c6 +170141183460469231731687303715884105727 +170_141183_460469_231731_687303_715884_105727 + +_42 // an identifier, not an integer literal +42_ // invalid: _ must separate successive digits +4__2 // invalid: only one _ at a time +0_xBadFace // invalid: _ must separate successive digits +</pre> + + +<h3 id="Floating-point_literals">Floating-point literals</h3> + +<p> +A floating-point literal is a decimal or hexadecimal representation of a +<a href="#Constants">floating-point constant</a>. +</p> + +<p> +A decimal floating-point literal consists of an integer part (decimal digits), +a decimal point, a fractional part (decimal digits), and an exponent part +(<code>e</code> or <code>E</code> followed by an optional sign and decimal digits). +One of the integer part or the fractional part may be elided; one of the decimal point +or the exponent part may be elided. +An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>. +</p> + +<p> +A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code> +prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits), +and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits). +One of the integer part or the fractional part may be elided; the radix point may be elided as well, +but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.) +An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup> +[<a href="#Go_1.13">Go 1.13</a>]. +</p> + +<p> +For readability, an underscore character <code>_</code> may appear after +a base prefix or between successive digits; such underscores do not change +the literal value. +</p> + +<pre class="ebnf"> +float_lit = decimal_float_lit | hex_float_lit . + +decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] | + decimal_digits decimal_exponent | + "." decimal_digits [ decimal_exponent ] . +decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits . + +hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent . +hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] | + [ "_" ] hex_digits | + "." hex_digits . +hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits . +</pre> + +<pre> +0. +72.40 +072.40 // == 72.40 +2.71828 +1.e+0 +6.67428e-11 +1E6 +.25 +.12345E+5 +1_5. // == 15.0 +0.15e+0_2 // == 15.0 + +0x1p-2 // == 0.25 +0x2.p10 // == 2048.0 +0x1.Fp+0 // == 1.9375 +0X.8p-0 // == 0.5 +0X_1FFFP-16 // == 0.1249847412109375 +0x15e-2 // == 0x15e - 2 (integer subtraction) + +0x.p1 // invalid: mantissa has no digits +1p-2 // invalid: p exponent requires hexadecimal mantissa +0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent +1_.5 // invalid: _ must separate successive digits +1._5 // invalid: _ must separate successive digits +1.5_e1 // invalid: _ must separate successive digits +1.5e_1 // invalid: _ must separate successive digits +1.5e1_ // invalid: _ must separate successive digits +</pre> + + +<h3 id="Imaginary_literals">Imaginary literals</h3> + +<p> +An imaginary literal represents the imaginary part of a +<a href="#Constants">complex constant</a>. +It consists of an <a href="#Integer_literals">integer</a> or +<a href="#Floating-point_literals">floating-point</a> literal +followed by the lowercase letter <code>i</code>. +The value of an imaginary literal is the value of the respective +integer or floating-point literal multiplied by the imaginary unit <i>i</i> +[<a href="#Go_1.13">Go 1.13</a>] +</p> + +<pre class="ebnf"> +imaginary_lit = (decimal_digits | int_lit | float_lit) "i" . +</pre> + +<p> +For backward compatibility, an imaginary literal's integer part consisting +entirely of decimal digits (and possibly underscores) is considered a decimal +integer, even if it starts with a leading <code>0</code>. +</p> + +<pre> +0i +0123i // == 123i for backward-compatibility +0o123i // == 0o123 * 1i == 83i +0xabci // == 0xabc * 1i == 2748i +0.i +2.71828i +1.e+0i +6.67428e-11i +1E6i +.25i +.12345E+5i +0x1p-2i // == 0x1p-2 * 1i == 0.25i +</pre> + + +<h3 id="Rune_literals">Rune literals</h3> + +<p> +A rune literal represents a <a href="#Constants">rune constant</a>, +an integer value identifying a Unicode code point. +A rune literal is expressed as one or more characters enclosed in single quotes, +as in <code>'x'</code> or <code>'\n'</code>. +Within the quotes, any character may appear except newline and unescaped single +quote. A single quoted character represents the Unicode value +of the character itself, +while multi-character sequences beginning with a backslash encode +values in various formats. +</p> + +<p> +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 <code>'a'</code> holds a single byte representing +a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while +<code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing +a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. +</p> + +<p> +Several backslash escapes allow arbitrary values to be encoded as +ASCII text. There are four ways to represent the integer value +as a numeric constant: <code>\x</code> followed by exactly two hexadecimal +digits; <code>\u</code> followed by exactly four hexadecimal digits; +<code>\U</code> followed by exactly eight hexadecimal digits, and a +plain backslash <code>\</code> 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. +</p> + +<p> +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 escapes <code>\u</code> and <code>\U</code> +represent Unicode code points so within them some values are illegal, +in particular those above <code>0x10FFFF</code> and surrogate halves. +</p> + +<p> +After a backslash, certain single-character escapes represent special values: +</p> + +<pre class="grammar"> +\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 rune literals) +\" U+0022 double quote (valid escape only within string literals) +</pre> + +<p> +An unrecognized character following a backslash in a rune literal is illegal. +</p> + +<pre class="ebnf"> +rune_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" | `\` | "'" | `"` ) . +</pre> + +<pre> +'a' +'ä' +'本' +'\t' +'\000' +'\007' +'\377' +'\x07' +'\xff' +'\u12e4' +'\U00101234' +'\'' // rune literal containing single quote character +'aa' // illegal: too many characters +'\k' // illegal: k is not recognized after a backslash +'\xa' // illegal: too few hexadecimal digits +'\0' // illegal: too few octal digits +'\400' // illegal: octal value over 255 +'\uDFFF' // illegal: surrogate half +'\U00110000' // illegal: invalid Unicode code point +</pre> + + +<h3 id="String_literals">String literals</h3> + +<p> +A string literal represents a <a href="#Constants">string constant</a> +obtained from concatenating a sequence of characters. There are two forms: +raw string literals and interpreted string literals. +</p> + +<p> +Raw string literals are character sequences between back quotes, as in +<code>`foo`</code>. Within the quotes, any character may appear except +back quote. The value of a raw string literal is the +string composed of the uninterpreted (implicitly UTF-8-encoded) characters +between the quotes; +in particular, backslashes have no special meaning and the string may +contain newlines. +Carriage return characters ('\r') inside raw string literals +are discarded from the raw string value. +</p> + +<p> +Interpreted string literals are character sequences between double +quotes, as in <code>"bar"</code>. +Within the quotes, any character may appear except newline and unescaped double quote. +The text between the quotes forms the +value of the literal, with backslash escapes interpreted as they +are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and +<code>\"</code> is legal), with the same restrictions. +The three-digit octal (<code>\</code><i>nnn</i>) +and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual +<i>bytes</i> of the resulting string; all other escapes represent +the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>. +Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent +a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, +<code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent +the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character +U+00FF. +</p> + +<pre class="ebnf"> +string_lit = raw_string_lit | interpreted_string_lit . +raw_string_lit = "`" { unicode_char | newline } "`" . +interpreted_string_lit = `"` { unicode_value | byte_value } `"` . +</pre> + +<pre> +`abc` // same as "abc" +`\n +\n` // same as "\\n\n\\n" +"\n" +"\"" // same as `"` +"Hello, world!\n" +"日本語" +"\u65e5本\U00008a9e" +"\xff\u00FF" +"\uD800" // illegal: surrogate half +"\U00110000" // illegal: invalid Unicode code point +</pre> + +<p> +These examples all represent the same string: +</p> + +<pre> +"日本語" // 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 +</pre> + +<p> +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 rune literal (it is not a single code +point), and will appear as two code points if placed in a string +literal. +</p> + + +<h2 id="Constants">Constants</h2> + +<p>There are <i>boolean constants</i>, +<i>rune constants</i>, +<i>integer constants</i>, +<i>floating-point constants</i>, <i>complex constants</i>, +and <i>string constants</i>. Rune, integer, floating-point, +and complex constants are +collectively called <i>numeric constants</i>. +</p> + +<p> +A constant value is represented by a +<a href="#Rune_literals">rune</a>, +<a href="#Integer_literals">integer</a>, +<a href="#Floating-point_literals">floating-point</a>, +<a href="#Imaginary_literals">imaginary</a>, +or +<a href="#String_literals">string</a> literal, +an identifier denoting a constant, +a <a href="#Constant_expressions">constant expression</a>, +a <a href="#Conversions">conversion</a> with a result that is a constant, or +the result value of some built-in functions such as +<code>min</code> or <code>max</code> applied to constant arguments, +<code>unsafe.Sizeof</code> applied to <a href="#Package_unsafe">certain values</a>, +<code>cap</code> or <code>len</code> applied to +<a href="#Length_and_capacity">some expressions</a>, +<code>real</code> and <code>imag</code> applied to a complex constant +and <code>complex</code> applied to numeric constants. +The boolean truth values are represented by the predeclared constants +<code>true</code> and <code>false</code>. The predeclared identifier +<a href="#Iota">iota</a> denotes an integer constant. +</p> + +<p> +In general, complex constants are a form of +<a href="#Constant_expressions">constant expression</a> +and are discussed in that section. +</p> + +<p> +Numeric constants represent exact values of arbitrary precision and do not overflow. +Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, +and not-a-number values. +</p> + +<p> +Constants may be <a href="#Types">typed</a> or <i>untyped</i>. +Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, +and certain <a href="#Constant_expressions">constant expressions</a> +containing only untyped constant operands are untyped. +</p> + +<p> +A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> +or <a href="#Conversions">conversion</a>, or implicitly when used in a +<a href="#Variable_declarations">variable declaration</a> or an +<a href="#Assignment_statements">assignment statement</a> or as an +operand in an <a href="#Expressions">expression</a>. +It is an error if the constant value +cannot be <a href="#Representability">represented</a> as a value of the respective type. +If the type is a type parameter, the constant is converted into a non-constant +value of the type parameter. +</p> + +<p> +An untyped constant has a <i>default type</i> which is the type to which the +constant is implicitly converted in contexts where a typed value is required, +for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> +such as <code>i := 0</code> where there is no explicit type. +The default type of an untyped constant is <code>bool</code>, <code>rune</code>, +<code>int</code>, <code>float64</code>, <code>complex128</code>, or <code>string</code> +respectively, depending on whether it is a boolean, rune, integer, floating-point, +complex, or string constant. +</p> + +<p> +Implementation restriction: Although numeric constants have arbitrary +precision in the language, a compiler may implement them using an +internal representation with limited precision. That said, every +implementation must: +</p> + +<ul> + <li>Represent integer constants with at least 256 bits.</li> + + <li>Represent floating-point constants, including the parts of + a complex constant, with a mantissa of at least 256 bits + and a signed binary exponent of at least 16 bits.</li> + + <li>Give an error if unable to represent an integer constant + precisely.</li> + + <li>Give an error if unable to represent a floating-point or + complex constant due to overflow.</li> + + <li>Round to the nearest representable constant if unable to + represent a floating-point or complex constant due to limits + on precision.</li> +</ul> + +<p> +These requirements apply both to literal constants and to the result +of evaluating <a href="#Constant_expressions">constant +expressions</a>. +</p> + + +<h2 id="Variables">Variables</h2> + +<p> +A variable is a storage location for holding a <i>value</i>. +The set of permissible values is determined by the +variable's <i><a href="#Types">type</a></i>. +</p> + +<p> +A <a href="#Variable_declarations">variable declaration</a> +or, for function parameters and results, the signature +of a <a href="#Function_declarations">function declaration</a> +or <a href="#Function_literals">function literal</a> reserves +storage for a named variable. + +Calling the built-in function <a href="#Allocation"><code>new</code></a> +or taking the address of a <a href="#Composite_literals">composite literal</a> +allocates storage for a variable at run time. +Such an anonymous variable is referred to via a (possibly implicit) +<a href="#Address_operators">pointer indirection</a>. +</p> + +<p> +<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, +and <a href="#Struct_types">struct</a> types have elements and fields that may +be <a href="#Address_operators">addressed</a> individually. Each such element +acts like a variable. +</p> + +<p> +The <i>static type</i> (or just <i>type</i>) of a variable is the +type given in its declaration, the type provided in the +<code>new</code> call or composite literal, or the type of +an element of a structured variable. +Variables of interface type also have a distinct <i>dynamic type</i>, +which is the (non-interface) type of the value assigned to the variable at run time +(unless the value is the predeclared identifier <code>nil</code>, +which has no type). +The dynamic type may vary during execution but values stored in interface +variables are always <a href="#Assignability">assignable</a> +to the static type of the variable. +</p> + +<pre> +var x interface{} // x is nil and has static type interface{} +var v *T // v has value nil, static type *T +x = 42 // x has value 42 and dynamic type int +x = v // x has value (*T)(nil) and dynamic type *T +</pre> + +<p> +A variable's value is retrieved by referring to the variable in an +<a href="#Expressions">expression</a>; it is the most recent value +<a href="#Assignment_statements">assigned</a> to the variable. +If a variable has not yet been assigned a value, its value is the +<a href="#The_zero_value">zero value</a> for its type. +</p> + + +<h2 id="Types">Types</h2> + +<p> +A type determines a set of values together with operations and methods specific +to those values. A type may be denoted by a <i>type name</i>, if it has one, which must be +followed by <a href="#Instantiations">type arguments</a> if the type is generic. +A type may also be specified using a <i>type literal</i>, which composes a type +from existing types. +</p> + +<pre class="ebnf"> +Type = TypeName [ TypeArgs ] | TypeLit | "(" Type ")" . +TypeName = identifier | QualifiedIdent . +TypeArgs = "[" TypeList [ "," ] "]" . +TypeList = Type { "," Type } . +TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | + SliceType | MapType | ChannelType . +</pre> + +<p> +The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. +Others are introduced with <a href="#Type_declarations">type declarations</a> +or <a href="#Type_parameter_declarations">type parameter lists</a>. +<i>Composite types</i>—array, struct, pointer, function, +interface, slice, map, and channel types—may be constructed using +type literals. +</p> + +<p> +Predeclared types, defined types, and type parameters are called <i>named types</i>. +An alias denotes a named type if the type given in the alias declaration is a named type. +</p> + +<h3 id="Boolean_types">Boolean types</h3> + +<p> +A <i>boolean type</i> represents the set of Boolean truth values +denoted by the predeclared constants <code>true</code> +and <code>false</code>. The predeclared boolean type is <code>bool</code>; +it is a <a href="#Type_definitions">defined type</a>. +</p> + +<h3 id="Numeric_types">Numeric types</h3> + +<p> +An <i>integer</i>, <i>floating-point</i>, or <i>complex</i> type +represents the set of integer, floating-point, or complex values, respectively. +They are collectively called <i>numeric types</i>. +The predeclared architecture-independent numeric types are: +</p> + +<pre class="grammar"> +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 IEEE-754 32-bit floating-point numbers +float64 the set of all IEEE-754 64-bit floating-point numbers + +complex64 the set of all complex numbers with float32 real and imaginary parts +complex128 the set of all complex numbers with float64 real and imaginary parts + +byte alias for uint8 +rune alias for int32 +</pre> + +<p> +The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using +<a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. +</p> + +<p> +There is also a set of predeclared integer types with implementation-specific sizes: +</p> + +<pre class="grammar"> +uint either 32 or 64 bits +int same size as uint +uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value +</pre> + +<p> +To avoid portability issues all numeric types are <a href="#Type_definitions">defined +types</a> and thus distinct except +<code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and +<code>rune</code>, which is an alias for <code>int32</code>. +Explicit conversions +are required when different numeric types are mixed in an expression +or assignment. For instance, <code>int32</code> and <code>int</code> +are not the same type even though they may have the same size on a +particular architecture. +</p> + +<h3 id="String_types">String types</h3> + +<p> +A <i>string type</i> represents the set of string values. +A string value is a (possibly empty) sequence of bytes. +The number of bytes is called the length of the string and is never negative. +Strings are immutable: once created, +it is impossible to change the contents of a string. +The predeclared string type is <code>string</code>; +it is a <a href="#Type_definitions">defined type</a>. +</p> + +<p> +The length of a string <code>s</code> can be discovered using +the built-in function <a href="#Length_and_capacity"><code>len</code></a>. +The length is a compile-time constant if the string is a constant. +A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(s)-1</code>. +It is illegal to take the address of such an element; if +<code>s[i]</code> is the <code>i</code>'th byte of a +string, <code>&s[i]</code> is invalid. +</p> + + +<h3 id="Array_types">Array types</h3> + +<p> +An array is a numbered sequence of elements of a single +type, called the element type. +The number of elements is called the length of the array and is never negative. +</p> + +<pre class="ebnf"> +ArrayType = "[" ArrayLength "]" ElementType . +ArrayLength = Expression . +ElementType = Type . +</pre> + +<p> +The length is part of the array's type; it must evaluate to a +non-negative <a href="#Constants">constant</a> +<a href="#Representability">representable</a> by a value +of type <code>int</code>. +The length of array <code>a</code> can be discovered +using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. +The elements can be addressed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(a)-1</code>. +Array types are always one-dimensional but may be composed to form +multi-dimensional types. +</p> + +<pre> +[32]byte +[2*N] struct { x, y int32 } +[1000]*float64 +[3][5]int +[2][2][2]float64 // same as [2]([2]([2]float64)) +</pre> + +<p> +An array type <code>T</code> may not have an element of type <code>T</code>, +or of a type containing <code>T</code> as a component, directly or indirectly, +if those containing types are only array or struct types. +</p> + +<pre> +// invalid array types +type ( + T1 [10]T1 // element type of T1 is T1 + T2 [10]struct{ f T2 } // T2 contains T2 as component of a struct + T3 [10]T4 // T3 contains T3 as component of a struct in T4 + T4 struct{ f T3 } // T4 contains T4 as component of array T3 in a struct +) + +// valid array types +type ( + T5 [10]*T5 // T5 contains T5 as component of a pointer + T6 [10]func() T6 // T6 contains T6 as component of a function type + T7 [10]struct{ f []T7 } // T7 contains T7 as component of a slice in a struct +) +</pre> + +<h3 id="Slice_types">Slice types</h3> + +<p> +A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and +provides access to a numbered sequence of elements from that array. +A slice type denotes the set of all slices of arrays of its element type. +The number of elements is called the length of the slice and is never negative. +The value of an uninitialized slice is <code>nil</code>. +</p> + +<pre class="ebnf"> +SliceType = "[" "]" ElementType . +</pre> + +<p> +The length of a slice <code>s</code> can be discovered by the built-in function +<a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during +execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> +0 through <code>len(s)-1</code>. The slice index of a +given element may be less than the index of the same element in the +underlying array. +</p> +<p> +A slice, once initialized, is always associated with an underlying +array that holds its elements. A slice therefore shares storage +with its array and with other slices of the same array; by contrast, +distinct arrays always represent distinct storage. +</p> +<p> +The array underlying a slice may extend past the end of the slice. +The <i>capacity</i> is a measure of that extent: it is the sum of +the length of the slice and the length of the array beyond the slice; +a slice of length up to that capacity can be created by +<a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice. +The capacity of a slice <code>a</code> can be discovered using the +built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>. +</p> + +<p> +A new, initialized slice value for a given element type <code>T</code> may be +made using the built-in function +<a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes a slice type +and parameters specifying the length and optionally the capacity. +A slice created with <code>make</code> always allocates a new, hidden array +to which the returned slice value refers. That is, executing +</p> + +<pre> +make([]T, length, capacity) +</pre> + +<p> +produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> +it, so these two expressions are equivalent: +</p> + +<pre> +make([]int, 50, 100) +new([100]int)[0:50] +</pre> + +<p> +Like arrays, slices are always one-dimensional but may be composed to construct +higher-dimensional objects. +With arrays of arrays, the inner arrays are, by construction, always the same length; +however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. +Moreover, the inner slices must be initialized individually. +</p> + +<h3 id="Struct_types">Struct types</h3> + +<p> +A struct is a sequence of named elements, called fields, each of which has a +name and a type. Field names may be specified explicitly (IdentifierList) or +implicitly (EmbeddedField). +Within a struct, non-<a href="#Blank_identifier">blank</a> field names must +be <a href="#Uniqueness_of_identifiers">unique</a>. +</p> + +<pre class="ebnf"> +StructType = "struct" "{" { FieldDecl ";" } "}" . +FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . +EmbeddedField = [ "*" ] TypeName [ TypeArgs ] . +Tag = string_lit . +</pre> + +<pre> +// An empty struct. +struct {} + +// A struct with 6 fields. +struct { + x, y int + u float32 + _ float32 // padding + A *[]int + F func() +} +</pre> + +<p> +A field declared with a type but no explicit field name is called an <i>embedded field</i>. +An embedded field must be specified as +a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>, +and <code>T</code> itself may not be +a pointer type. The unqualified type name acts as the field name. +</p> + +<pre> +// A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4 +struct { + T1 // field name is T1 + *T2 // field name is T2 + P.T3 // field name is T3 + *P.T4 // field name is T4 + x, y int // field names are x and y +} +</pre> + +<p> +The following declaration is illegal because field names must be unique +in a struct type: +</p> + +<pre> +struct { + T // conflicts with embedded field *T and *P.T + *T // conflicts with embedded field T and *P.T + *P.T // conflicts with embedded field T and *T +} +</pre> + +<p> +A field or <a href="#Method_declarations">method</a> <code>f</code> of an +embedded field in a struct <code>x</code> is called <i>promoted</i> if +<code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes +that field or method <code>f</code>. +</p> + +<p> +Promoted fields act like ordinary fields +of a struct except that they cannot be used as field names in +<a href="#Composite_literals">composite literals</a> of the struct. +</p> + +<p> +Given a struct type <code>S</code> and a <a href="#Types">named type</a> +<code>T</code>, promoted methods are included in the method set of the struct as follows: +</p> +<ul> + <li> + If <code>S</code> contains an embedded field <code>T</code>, + the <a href="#Method_sets">method sets</a> of <code>S</code> + and <code>*S</code> both include promoted methods with receiver + <code>T</code>. The method set of <code>*S</code> also + includes promoted methods with receiver <code>*T</code>. + </li> + + <li> + If <code>S</code> contains an embedded field <code>*T</code>, + the method sets of <code>S</code> and <code>*S</code> both + include promoted methods with receiver <code>T</code> or + <code>*T</code>. + </li> +</ul> + +<p> +A field declaration may be followed by an optional string literal <i>tag</i>, +which becomes an attribute for all the fields in the corresponding +field declaration. An empty tag string is equivalent to an absent tag. +The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> +and take part in <a href="#Type_identity">type identity</a> for structs +but are otherwise ignored. +</p> + +<pre> +struct { + x, y float64 "" // an empty tag string is like an absent tag + name string "any string is permitted as a tag" + _ [4]byte "ceci n'est pas un champ de structure" +} + +// A struct corresponding to a TimeStamp protocol buffer. +// The tag strings define the protocol buffer field numbers; +// they follow the convention outlined by the reflect package. +struct { + microsec uint64 `protobuf:"1"` + serverIP6 uint64 `protobuf:"2"` +} +</pre> + +<p> +A struct type <code>T</code> may not contain a field of type <code>T</code>, +or of a type containing <code>T</code> as a component, directly or indirectly, +if those containing types are only array or struct types. +</p> + +<pre> +// invalid struct types +type ( + T1 struct{ T1 } // T1 contains a field of T1 + T2 struct{ f [10]T2 } // T2 contains T2 as component of an array + T3 struct{ T4 } // T3 contains T3 as component of an array in struct T4 + T4 struct{ f [10]T3 } // T4 contains T4 as component of struct T3 in an array +) + +// valid struct types +type ( + T5 struct{ f *T5 } // T5 contains T5 as component of a pointer + T6 struct{ f func() T6 } // T6 contains T6 as component of a function type + T7 struct{ f [10][]T7 } // T7 contains T7 as component of a slice in an array +) +</pre> + +<h3 id="Pointer_types">Pointer types</h3> + +<p> +A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given +type, called the <i>base type</i> of the pointer. +The value of an uninitialized pointer is <code>nil</code>. +</p> + +<pre class="ebnf"> +PointerType = "*" BaseType . +BaseType = Type . +</pre> + +<pre> +*Point +*[4]int +</pre> + +<h3 id="Function_types">Function types</h3> + +<p> +A function type denotes the set of all functions with the same parameter +and result types. The value of an uninitialized variable of function type +is <code>nil</code>. +</p> + +<pre class="ebnf"> +FunctionType = "func" Signature . +Signature = Parameters [ Result ] . +Result = Parameters | Type . +Parameters = "(" [ ParameterList [ "," ] ] ")" . +ParameterList = ParameterDecl { "," ParameterDecl } . +ParameterDecl = [ IdentifierList ] [ "..." ] Type . +</pre> + +<p> +Within a list of parameters or results, the names (IdentifierList) +must either all be present or all be absent. If present, each name +stands for one item (parameter or result) of the specified type and +all non-<a href="#Blank_identifier">blank</a> names in the signature +must be <a href="#Uniqueness_of_identifiers">unique</a>. +If absent, each type stands for one item of that type. +Parameter and result +lists are always parenthesized except that if there is exactly +one unnamed result it may be written as an unparenthesized type. +</p> + +<p> +The final incoming parameter in a function signature may have +a type prefixed with <code>...</code>. +A function with such a parameter is called <i>variadic</i> and +may be invoked with zero or more arguments for that parameter. +</p> + +<pre> +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) +</pre> + +<h3 id="Interface_types">Interface types</h3> + +<p> +An interface type defines a <i>type set</i>. +A variable of interface type can store a value of any type that is in the type +set of the interface. Such a type is said to +<a href="#Implementing_an_interface">implement the interface</a>. +The value of an uninitialized variable of interface type is <code>nil</code>. +</p> + +<pre class="ebnf"> +InterfaceType = "interface" "{" { InterfaceElem ";" } "}" . +InterfaceElem = MethodElem | TypeElem . +MethodElem = MethodName Signature . +MethodName = identifier . +TypeElem = TypeTerm { "|" TypeTerm } . +TypeTerm = Type | UnderlyingType . +UnderlyingType = "~" Type . +</pre> + +<p> +An interface type is specified by a list of <i>interface elements</i>. +An interface element is either a <i>method</i> or a <i>type element</i>, +where a type element is a union of one or more <i>type terms</i>. +A type term is either a single type or a single underlying type. +</p> + +<h4 id="Basic_interfaces">Basic interfaces</h4> + +<p> +In its most basic form an interface specifies a (possibly empty) list of methods. +The type set defined by such an interface is the set of types which implement all of +those methods, and the corresponding <a href="#Method_sets">method set</a> consists +exactly of the methods specified by the interface. +Interfaces whose type sets can be defined entirely by a list of methods are called +<i>basic interfaces.</i> +</p> + +<pre> +// A simple File interface. +interface { + Read([]byte) (int, error) + Write([]byte) (int, error) + Close() error +} +</pre> + +<p> +The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a> +and not <a href="#Blank_identifier">blank</a>. +</p> + +<pre> +interface { + String() string + String() string // illegal: String not unique + _(x int) // illegal: method must have non-blank name +} +</pre> + +<p> +More than one type may implement an interface. +For instance, if two types <code>S1</code> and <code>S2</code> +have the method set +</p> + +<pre> +func (p T) Read(p []byte) (n int, err error) +func (p T) Write(p []byte) (n int, err error) +func (p T) Close() error +</pre> + +<p> +(where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) +then the <code>File</code> interface is implemented by both <code>S1</code> and +<code>S2</code>, regardless of what other methods +<code>S1</code> and <code>S2</code> may have or share. +</p> + +<p> +Every type that is a member of the type set of an interface implements that interface. +Any given type may implement several distinct interfaces. +For instance, all types implement the <i>empty interface</i> which stands for the set +of all (non-interface) types: +</p> + +<pre> +interface{} +</pre> + +<p> +For convenience, the predeclared type <code>any</code> is an alias for the empty interface. +[<a href="#Go_1.18">Go 1.18</a>] +</p> + +<p> +Similarly, consider this interface specification, +which appears within a <a href="#Type_declarations">type declaration</a> +to define an interface called <code>Locker</code>: +</p> + +<pre> +type Locker interface { + Lock() + Unlock() +} +</pre> + +<p> +If <code>S1</code> and <code>S2</code> also implement +</p> + +<pre> +func (p T) Lock() { … } +func (p T) Unlock() { … } +</pre> + +<p> +they implement the <code>Locker</code> interface as well +as the <code>File</code> interface. +</p> + +<h4 id="Embedded_interfaces">Embedded interfaces</h4> + +<p> +In a slightly more general form +an interface <code>T</code> may use a (possibly qualified) interface type +name <code>E</code> as an interface element. This is called +<i>embedding</i> interface <code>E</code> in <code>T</code> +[<a href="#Go_1.14">Go 1.14</a>]. +The type set of <code>T</code> is the <i>intersection</i> of the type sets +defined by <code>T</code>'s explicitly declared methods and the type sets +of <code>T</code>’s embedded interfaces. +In other words, the type set of <code>T</code> is the set of all types that implement all the +explicitly declared methods of <code>T</code> and also all the methods of +<code>E</code> +[<a href="#Go_1.18">Go 1.18</a>]. +</p> + +<pre> +type Reader interface { + Read(p []byte) (n int, err error) + Close() error +} + +type Writer interface { + Write(p []byte) (n int, err error) + Close() error +} + +// ReadWriter's methods are Read, Write, and Close. +type ReadWriter interface { + Reader // includes methods of Reader in ReadWriter's method set + Writer // includes methods of Writer in ReadWriter's method set +} +</pre> + +<p> +When embedding interfaces, methods with the +<a href="#Uniqueness_of_identifiers">same</a> names must +have <a href="#Type_identity">identical</a> signatures. +</p> + +<pre> +type ReadCloser interface { + Reader // includes methods of Reader in ReadCloser's method set + Close() // illegal: signatures of Reader.Close and Close are different +} +</pre> + +<h4 id="General_interfaces">General interfaces</h4> + +<p> +In their most general form, an interface element may also be an arbitrary type term +<code>T</code>, or a term of the form <code>~T</code> specifying the underlying type <code>T</code>, +or a union of terms <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code> +[<a href="#Go_1.18">Go 1.18</a>]. +Together with method specifications, these elements enable the precise +definition of an interface's type set as follows: +</p> + +<ul> + <li>The type set of the empty interface is the set of all non-interface types. + </li> + + <li>The type set of a non-empty interface is the intersection of the type sets + of its interface elements. + </li> + + <li>The type set of a method specification is the set of all non-interface types + whose method sets include that method. + </li> + + <li>The type set of a non-interface type term is the set consisting + of just that type. + </li> + + <li>The type set of a term of the form <code>~T</code> + is the set of all types whose underlying type is <code>T</code>. + </li> + + <li>The type set of a <i>union</i> of terms + <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code> + is the union of the type sets of the terms. + </li> +</ul> + +<p> +The quantification "the set of all non-interface types" refers not just to all (non-interface) +types declared in the program at hand, but all possible types in all possible programs, and +hence is infinite. +Similarly, given the set of all non-interface types that implement a particular method, the +intersection of the method sets of those types will contain exactly that method, even if all +types in the program at hand always pair that method with another method. +</p> + +<p> +By construction, an interface's type set never contains an interface type. +</p> + +<pre> +// 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 +} +</pre> + +<p> +In a term of the form <code>~T</code>, the underlying type of <code>T</code> +must be itself, and <code>T</code> cannot be an interface. +</p> + +<pre> +type MyInt int + +interface { + ~[]byte // the underlying type of []byte is itself + ~MyInt // illegal: the underlying type of MyInt is not MyInt + ~error // illegal: error is an interface +} +</pre> + +<p> +Union elements denote unions of type sets: +</p> + +<pre> +// The Float interface represents all floating-point types +// (including any named types whose underlying types are +// either float32 or float64). +type Float interface { + ~float32 | ~float64 +} +</pre> + +<p> +The type <code>T</code> in a term of the form <code>T</code> or <code>~T</code> cannot +be a <a href="#Type_parameter_declarations">type parameter</a>, and the type sets of all +non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty). +Given a type parameter <code>P</code>: +</p> + +<pre> +interface { + P // illegal: P is a type parameter + int | ~P // illegal: P is a type parameter + ~int | MyInt // illegal: the type sets for ~int and MyInt are not disjoint (~int includes MyInt) + float32 | Float // overlapping type sets but Float is an interface +} +</pre> + +<p> +Implementation restriction: +A union (with more than one term) cannot contain the +<a href="#Predeclared_identifiers">predeclared identifier</a> <code>comparable</code> +or interfaces that specify methods, or embed <code>comparable</code> or interfaces +that specify methods. +</p> + +<p> +Interfaces that are not <a href="#Basic_interfaces">basic</a> may only be used as type +constraints, or as elements of other interfaces used as constraints. +They cannot be the types of values or variables, or components of other, +non-interface types. +</p> + +<pre> +var x Float // illegal: Float is not a basic interface + +var x interface{} = Float(nil) // illegal + +type Floatish struct { + f Float // illegal +} +</pre> + +<p> +An interface type <code>T</code> may not embed a type element +that is, contains, or embeds <code>T</code>, directly or indirectly. +</p> + +<pre> +// illegal: Bad may not embed itself +type Bad interface { + Bad +} + +// illegal: Bad1 may not embed itself using Bad2 +type Bad1 interface { + Bad2 +} +type Bad2 interface { + Bad1 +} + +// illegal: Bad3 may not embed a union containing Bad3 +type Bad3 interface { + ~int | ~string | Bad3 +} + +// illegal: Bad4 may not embed an array containing Bad4 as element type +type Bad4 interface { + [10]Bad4 +} +</pre> + +<h4 id="Implementing_an_interface">Implementing an interface</h4> + +<p> +A type <code>T</code> implements an interface <code>I</code> if +</p> + +<ul> +<li> + <code>T</code> is not an interface and is an element of the type set of <code>I</code>; or +</li> +<li> + <code>T</code> is an interface and the type set of <code>T</code> is a subset of the + type set of <code>I</code>. +</li> +</ul> + +<p> +A value of type <code>T</code> implements an interface if <code>T</code> +implements the interface. +</p> + +<h3 id="Map_types">Map types</h3> + +<p> +A map is an unordered group of elements of one type, called the +element type, indexed by a set of unique <i>keys</i> of another type, +called the key type. +The value of an uninitialized map is <code>nil</code>. +</p> + +<pre class="ebnf"> +MapType = "map" "[" KeyType "]" ElementType . +KeyType = Type . +</pre> + +<p> +The <a href="#Comparison_operators">comparison operators</a> +<code>==</code> and <code>!=</code> must be fully defined +for operands of the key type; thus the key type must not be a function, map, or +slice. +If the key type is an interface type, these +comparison operators must be defined for the dynamic key values; +failure will cause a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<pre> +map[string]int +map[*T]struct{ x, y float64 } +map[string]interface{} +</pre> + +<p> +The number of map elements is called its length. +For a map <code>m</code>, it can be discovered using the +built-in function <a href="#Length_and_capacity"><code>len</code></a> +and may change during execution. Elements may be added during execution +using <a href="#Assignment_statements">assignments</a> and retrieved with +<a href="#Index_expressions">index expressions</a>; they may be removed with the +<a href="#Deletion_of_map_elements"><code>delete</code></a> and +<a href="#Clear"><code>clear</code></a> built-in function. +</p> + +<p> +A new, empty map value is made using the built-in +function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes the map type and an optional capacity hint as arguments: +</p> + +<pre> +make(map[string]int) +make(map[string]int, 100) +</pre> + +<p> +The initial capacity does not bound its size: +maps grow to accommodate the number of items +stored in them, with the exception of <code>nil</code> maps. +A <code>nil</code> map is equivalent to an empty map except that no elements +may be added. + +<h3 id="Channel_types">Channel types</h3> + +<p> +A channel provides a mechanism for +<a href="#Go_statements">concurrently executing functions</a> +to communicate by +<a href="#Send_statements">sending</a> and +<a href="#Receive_operator">receiving</a> +values of a specified element type. +The value of an uninitialized channel is <code>nil</code>. +</p> + +<pre class="ebnf"> +ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . +</pre> + +<p> +The optional <code><-</code> operator specifies the channel <i>direction</i>, +<i>send</i> or <i>receive</i>. If a direction is given, the channel is <i>directional</i>, +otherwise it is <i>bidirectional</i>. +A channel may be constrained only to send or only to receive by +<a href="#Assignment_statements">assignment</a> or +explicit <a href="#Conversions">conversion</a>. +</p> + +<pre> +chan T // can be used to send and receive values of type T +chan<- float64 // can only be used to send float64s +<-chan int // can only be used to receive ints +</pre> + +<p> +The <code><-</code> operator associates with the leftmost <code>chan</code> +possible: +</p> + +<pre> +chan<- chan int // same as chan<- (chan int) +chan<- <-chan int // same as chan<- (<-chan int) +<-chan <-chan int // same as <-chan (<-chan int) +chan (<-chan int) +</pre> + +<p> +A new, initialized channel +value can be made using the built-in function +<a href="#Making_slices_maps_and_channels"><code>make</code></a>, +which takes the channel type and an optional <i>capacity</i> as arguments: +</p> + +<pre> +make(chan int, 100) +</pre> + +<p> +The capacity, in number of elements, sets the size of the buffer in the channel. +If the capacity is zero or absent, the channel is unbuffered and communication +succeeds only when both a sender and receiver are ready. Otherwise, the channel +is buffered and communication succeeds without blocking if the buffer +is not full (sends) or not empty (receives). +A <code>nil</code> channel is never ready for communication. +</p> + +<p> +A channel may be closed with the built-in function +<a href="#Close"><code>close</code></a>. +The multi-valued assignment form of the +<a href="#Receive_operator">receive operator</a> +reports whether a received value was sent before +the channel was closed. +</p> + +<p> +A single channel may be used in +<a href="#Send_statements">send statements</a>, +<a href="#Receive_operator">receive operations</a>, +and calls to the built-in functions +<a href="#Length_and_capacity"><code>cap</code></a> and +<a href="#Length_and_capacity"><code>len</code></a> +by any number of goroutines without further synchronization. +Channels act as first-in-first-out queues. +For example, if one goroutine sends values on a channel +and a second goroutine receives them, the values are +received in the order sent. +</p> + +<h2 id="Properties_of_types_and_values">Properties of types and values</h2> + +<h3 id="Underlying_types">Underlying types</h3> + +<p> +Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> +is one of the predeclared boolean, numeric, or string types, or a type literal, +the corresponding underlying type is <code>T</code> itself. +Otherwise, <code>T</code>'s underlying type is the underlying type of the +type to which <code>T</code> refers in its declaration. +For a type parameter that is the underlying type of its +<a href="#Type_constraints">type constraint</a>, which is always an interface. +</p> + +<pre> +type ( + A1 = string + A2 = A1 +) + +type ( + B1 string + B2 B1 + B3 []B1 + B4 B3 +) + +func f[P any](x P) { … } +</pre> + +<p> +The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, +and <code>B2</code> is <code>string</code>. +The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>. +The underlying type of <code>P</code> is <code>interface{}</code>. +</p> + +<h3 id="Core_types">Core types</h3> + +<p> +Each non-interface type <code>T</code> has a <i>core type</i>, which is the same as the +<a href="#Underlying_types">underlying type</a> of <code>T</code>. +</p> + +<p> +An interface <code>T</code> has a core type if one of the following +conditions is satisfied: +</p> + +<ol> +<li> +There is a single type <code>U</code> which is the <a href="#Underlying_types">underlying type</a> +of all types in the <a href="#Interface_types">type set</a> of <code>T</code>; or +</li> +<li> +the type set of <code>T</code> contains only <a href="#Channel_types">channel types</a> +with identical element type <code>E</code>, and all directional channels have the same +direction. +</li> +</ol> + +<p> +No other interfaces have a core type. +</p> + +<p> +The core type of an interface is, depending on the condition that is satisfied, either: +</p> + +<ol> +<li> +the type <code>U</code>; or +</li> +<li> +the type <code>chan E</code> if <code>T</code> contains only bidirectional +channels, or the type <code>chan<- E</code> or <code><-chan E</code> +depending on the direction of the directional channels present. +</li> +</ol> + +<p> +By definition, a core type is never a <a href="#Type_definitions">defined type</a>, +<a href="#Type_parameter_declarations">type parameter</a>, or +<a href="#Interface_types">interface type</a>. +</p> + +<p> +Examples of interfaces with core types: +</p> + +<pre> +type Celsius float32 +type Kelvin float32 + +interface{ int } // int +interface{ Celsius|Kelvin } // float32 +interface{ ~chan int } // chan int +interface{ ~chan int|~chan<- int } // chan<- int +interface{ ~[]*data; String() string } // []*data +</pre> + +<p> +Examples of interfaces without core types: +</p> + +<pre> +interface{} // no single underlying type +interface{ Celsius|float64 } // no single underlying type +interface{ chan int | chan<- string } // channels have different element types +interface{ <-chan int | chan<- int } // directional channels have different directions +</pre> + +<p> +Some operations (<a href="#Slice_expressions">slice expressions</a>, +<a href="#Appending_and_copying_slices"><code>append</code> and <code>copy</code></a>) +rely on a slightly more loose form of core types which accept byte slices and strings. +Specifically, if there are exactly two types, <code>[]byte</code> and <code>string</code>, +which are the underlying types of all types in the type set of interface <code>T</code>, +the core type of <code>T</code> is called <code>bytestring</code>. +</p> + +<p> +Examples of interfaces with <code>bytestring</code> core types: +</p> + +<pre> +interface{ int } // int (same as ordinary core type) +interface{ []byte | string } // bytestring +interface{ ~[]byte | myString } // bytestring +</pre> + +<p> +Note that <code>bytestring</code> is not a real type; it cannot be used to declare +variables or compose other types. It exists solely to describe the behavior of some +operations that read from a sequence of bytes, which may be a byte slice or a string. +</p> + +<h3 id="Type_identity">Type identity</h3> + +<p> +Two types are either <i>identical</i> or <i>different</i>. +</p> + +<p> +A <a href="#Types">named type</a> is always different from any other type. +Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are +structurally equivalent; that is, they have the same literal structure and corresponding +components have identical types. In detail: +</p> + +<ul> + <li>Two array types are identical if they have identical element types and + the same array length.</li> + + <li>Two slice types are identical if they have identical element types.</li> + + <li>Two struct types are identical if they have the same sequence of fields, + and if corresponding fields have the same names, and identical types, + and identical tags. + <a href="#Exported_identifiers">Non-exported</a> field names from different + packages are always different.</li> + + <li>Two pointer types are identical if they have identical base types.</li> + + <li>Two function types are identical if they have the same number of parameters + and result values, corresponding parameter and result types are + identical, and either both functions are variadic or neither is. + Parameter and result names are not required to match.</li> + + <li>Two interface types are identical if they define the same type set. + </li> + + <li>Two map types are identical if they have identical key and element types.</li> + + <li>Two channel types are identical if they have identical element types and + the same direction.</li> + + <li>Two <a href="#Instantiations">instantiated</a> types are identical if + their defined types and all type arguments are identical. + </li> +</ul> + +<p> +Given the declarations +</p> + +<pre> +type ( + A0 = []string + A1 = A0 + A2 = struct{ a, b int } + A3 = int + A4 = func(A3, float64) *A0 + A5 = func(x int, _ float64) *[]string + + B0 A0 + B1 []string + B2 struct{ a, b int } + B3 struct{ a, c int } + B4 func(int, float64) *B0 + B5 func(x int, y float64) *A1 + + C0 = B0 + D0[P1, P2 any] struct{ x P1; y P2 } + E0 = D0[int, string] +) +</pre> + +<p> +these types are identical: +</p> + +<pre> +A0, A1, and []string +A2 and struct{ a, b int } +A3 and int +A4, func(int, float64) *[]string, and A5 + +B0 and C0 +D0[int, string] and E0 +[]int and []int +struct{ a, b *B5 } and struct{ a, b *B5 } +func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5 +</pre> + +<p> +<code>B0</code> and <code>B1</code> are different because they are new types +created by distinct <a href="#Type_definitions">type definitions</a>; +<code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> +are different because <code>B0</code> is different from <code>[]string</code>; +and <code>P1</code> and <code>P2</code> are different because they are different +type parameters. +<code>D0[int, string]</code> and <code>struct{ x int; y string }</code> are +different because the former is an <a href="#Instantiations">instantiated</a> +defined type while the latter is a type literal +(but they are still <a href="#Assignability">assignable</a>). +</p> + +<h3 id="Assignability">Assignability</h3> + +<p> +A value <code>x</code> of type <code>V</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> +("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies: +</p> + +<ul> +<li> +<code>V</code> and <code>T</code> are identical. +</li> +<li> +<code>V</code> and <code>T</code> have identical +<a href="#Underlying_types">underlying types</a> +but are not type parameters and at least one of <code>V</code> +or <code>T</code> is not a <a href="#Types">named type</a>. +</li> +<li> +<code>V</code> and <code>T</code> are channel types with +identical element types, <code>V</code> is a bidirectional channel, +and at least one of <code>V</code> or <code>T</code> is not a <a href="#Types">named type</a>. +</li> +<li> +<code>T</code> is an interface type, but not a type parameter, and +<code>x</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>. +</li> +<li> +<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> +is a pointer, function, slice, map, channel, or interface type, +but not a type parameter. +</li> +<li> +<code>x</code> is an untyped <a href="#Constants">constant</a> +<a href="#Representability">representable</a> +by a value of type <code>T</code>. +</li> +</ul> + +<p> +Additionally, if <code>x</code>'s type <code>V</code> or <code>T</code> are type parameters, <code>x</code> +is assignable to a variable of type <code>T</code> if one of the following conditions applies: +</p> + +<ul> +<li> +<code>x</code> is the predeclared identifier <code>nil</code>, <code>T</code> is +a type parameter, and <code>x</code> is assignable to each type in +<code>T</code>'s type set. +</li> +<li> +<code>V</code> is not a <a href="#Types">named type</a>, <code>T</code> is +a type parameter, and <code>x</code> is assignable to each type in +<code>T</code>'s type set. +</li> +<li> +<code>V</code> is a type parameter and <code>T</code> is not a named type, +and values of each type in <code>V</code>'s type set are assignable +to <code>T</code>. +</li> +</ul> + +<h3 id="Representability">Representability</h3> + +<p> +A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i> +by a value of type <code>T</code>, +where <code>T</code> is not a <a href="#Type_parameter_declarations">type parameter</a>, +if one of the following conditions applies: +</p> + +<ul> +<li> +<code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. +</li> + +<li> +<code>T</code> is a <a href="#Numeric_types">floating-point type</a> and <code>x</code> can be rounded to <code>T</code>'s +precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE +negative zero further simplified to an unsigned zero. Note that constant values never result +in an IEEE negative zero, NaN, or infinity. +</li> + +<li> +<code>T</code> is a complex type, and <code>x</code>'s +<a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> +are representable by values of <code>T</code>'s component type (<code>float32</code> or +<code>float64</code>). +</li> +</ul> + +<p> +If <code>T</code> is a type parameter, +<code>x</code> is representable by a value of type <code>T</code> if <code>x</code> is representable +by a value of each type in <code>T</code>'s type set. +</p> + +<pre> +x T x is representable by a value of T because + +'a' byte 97 is in the set of byte values +97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers +"foo" string "foo" is in the set of string values +1024 int16 1024 is in the set of 16-bit integers +42.0 byte 42 is in the set of unsigned 8-bit integers +1e10 uint64 10000000000 is in the set of unsigned 64-bit integers +2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values +-1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 +0i int 0 is an integer value +(42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values +</pre> + +<pre> +x T x is not representable by a value of T because + +0 bool 0 is not in the set of boolean values +'a' string 'a' is a rune, it is not in the set of string values +1024 byte 1024 is not in the set of unsigned 8-bit integers +-1 uint16 -1 is not in the set of unsigned 16-bit integers +1.1 int 1.1 is not an integer value +42i float32 (0 + 42i) is not in the set of float32 values +1e1000 float64 1e1000 overflows to IEEE +Inf after rounding +</pre> + +<h3 id="Method_sets">Method sets</h3> + +<p> +The <i>method set</i> of a type determines the methods that can be +<a href="#Calls">called</a> on an <a href="#Operands">operand</a> of that type. +Every type has a (possibly empty) method set associated with it: +</p> + +<ul> +<li>The method set of a <a href="#Type_definitions">defined type</a> <code>T</code> consists of all +<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. +</li> + +<li> +The method set of a pointer to a defined type <code>T</code> +(where <code>T</code> is neither a pointer nor an interface) +is the set of all methods declared with receiver <code>*T</code> or <code>T</code>. +</li> + +<li>The method set of an <a href="#Interface_types">interface type</a> is the intersection +of the method sets of each type in the interface's <a href="#Interface_types">type set</a> +(the resulting method set is usually just the set of declared methods in the interface). +</li> +</ul> + +<p> +Further rules apply to structs (and pointer to structs) containing embedded fields, +as described in the section on <a href="#Struct_types">struct types</a>. +Any other type has an empty method set. +</p> + +<p> +In a method set, each method must have a +<a href="#Uniqueness_of_identifiers">unique</a> +non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. +</p> + +<h2 id="Blocks">Blocks</h2> + +<p> +A <i>block</i> is a possibly empty sequence of declarations and statements +within matching brace brackets. +</p> + +<pre class="ebnf"> +Block = "{" StatementList "}" . +StatementList = { Statement ";" } . +</pre> + +<p> +In addition to explicit blocks in the source code, there are implicit blocks: +</p> + +<ol> + <li>The <i>universe block</i> encompasses all Go source text.</li> + + <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all + Go source text for that package.</li> + + <li>Each file has a <i>file block</i> containing all Go source text + in that file.</li> + + <li>Each <a href="#If_statements">"if"</a>, + <a href="#For_statements">"for"</a>, and + <a href="#Switch_statements">"switch"</a> + statement is considered to be in its own implicit block.</li> + + <li>Each clause in a <a href="#Switch_statements">"switch"</a> + or <a href="#Select_statements">"select"</a> statement + acts as an implicit block.</li> +</ol> + +<p> +Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. +</p> + + +<h2 id="Declarations_and_scope">Declarations and scope</h2> + +<p> +A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a +<a href="#Constant_declarations">constant</a>, +<a href="#Type_declarations">type</a>, +<a href="#Type_parameter_declarations">type parameter</a>, +<a href="#Variable_declarations">variable</a>, +<a href="#Function_declarations">function</a>, +<a href="#Labeled_statements">label</a>, or +<a href="#Import_declarations">package</a>. +Every identifier in a program must be declared. +No identifier may be declared twice in the same block, and +no identifier may be declared in both the file and package block. +</p> + +<p> +The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier +in a declaration, but it does not introduce a binding and thus is not declared. +In the package block, the identifier <code>init</code> may only be used for +<a href="#Package_initialization"><code>init</code> function</a> declarations, +and like the blank identifier it does not introduce a new binding. +</p> + +<pre class="ebnf"> +Declaration = ConstDecl | TypeDecl | VarDecl . +TopLevelDecl = Declaration | FunctionDecl | MethodDecl . +</pre> + +<p> +The <i>scope</i> of a declared identifier is the extent of source text in which +the identifier denotes the specified constant, type, variable, function, label, or package. +</p> + +<p> +Go is lexically scoped using <a href="#Blocks">blocks</a>: +</p> + +<ol> + <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li> + + <li>The scope of an identifier denoting a constant, type, variable, + or function (but not method) declared at top level (outside any + function) is the package block.</li> + + <li>The scope of the package name of an imported package is the file block + of the file containing the import declaration.</li> + + <li>The scope of an identifier denoting a method receiver, function parameter, + or result variable is the function body.</li> + + <li>The scope of an identifier denoting a type parameter of a function + or declared by a method receiver begins after the name of the function + and ends at the end of the function body.</li> + + <li>The scope of an identifier denoting a type parameter of a type + begins after the name of the type and ends at the end + of the TypeSpec.</li> + + <li>The scope of a constant or variable identifier declared + inside a function begins at the end of the ConstSpec or VarSpec + (ShortVarDecl for short variable declarations) + and ends at the end of the innermost containing block.</li> + + <li>The scope of a type identifier declared inside a function + begins at the identifier in the TypeSpec + and ends at the end of the innermost containing block.</li> +</ol> + +<p> +An identifier declared in a block may be redeclared in an inner block. +While the identifier of the inner declaration is in scope, it denotes +the entity declared by the inner declaration. +</p> + +<p> +The <a href="#Package_clause">package clause</a> is not a declaration; the package name +does not appear in any scope. Its purpose is to identify the files belonging +to the same <a href="#Packages">package</a> and to specify the default package name for import +declarations. +</p> + + +<h3 id="Label_scopes">Label scopes</h3> + +<p> +Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are +used in the <a href="#Break_statements">"break"</a>, +<a href="#Continue_statements">"continue"</a>, and +<a href="#Goto_statements">"goto"</a> statements. +It is illegal to define a label that is never used. +In contrast to other identifiers, labels are not block scoped and do +not conflict with identifiers that are not labels. The scope of a label +is the body of the function in which it is declared and excludes +the body of any nested function. +</p> + + +<h3 id="Blank_identifier">Blank identifier</h3> + +<p> +The <i>blank identifier</i> is represented by the underscore character <code>_</code>. +It serves as an anonymous placeholder instead of a regular (non-blank) +identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, +as an <a href="#Operands">operand</a>, and in <a href="#Assignment_statements">assignment statements</a>. +</p> + + +<h3 id="Predeclared_identifiers">Predeclared identifiers</h3> + +<p> +The following identifiers are implicitly declared in the +<a href="#Blocks">universe block</a> +[<a href="#Go_1.18">Go 1.18</a>] +[<a href="#Go_1.21">Go 1.21</a>]: +</p> +<pre class="grammar"> +Types: + any bool byte comparable + complex64 complex128 error float32 float64 + int int8 int16 int32 int64 rune string + uint uint8 uint16 uint32 uint64 uintptr + +Constants: + true false iota + +Zero value: + nil + +Functions: + append cap clear close complex copy delete imag len + make max min new panic print println real recover +</pre> + +<h3 id="Exported_identifiers">Exported identifiers</h3> + +<p> +An identifier may be <i>exported</i> to permit access to it from another package. +An identifier is exported if both: +</p> +<ol> + <li>the first character of the identifier's name is a Unicode uppercase + letter (Unicode character category Lu); and</li> + <li>the identifier is declared in the <a href="#Blocks">package block</a> + or it is a <a href="#Struct_types">field name</a> or + <a href="#MethodName">method name</a>.</li> +</ol> +<p> +All other identifiers are not exported. +</p> + +<h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> + +<p> +Given a set of identifiers, an identifier is called <i>unique</i> if it is +<i>different</i> from every other in the set. +Two identifiers are different if they are spelled differently, or if they +appear in different <a href="#Packages">packages</a> and are not +<a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. +</p> + +<h3 id="Constant_declarations">Constant declarations</h3> + +<p> +A constant declaration binds a list of identifiers (the names of +the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. +The number of identifiers must be equal +to the number of expressions, and the <i>n</i>th identifier on +the left is bound to the value of the <i>n</i>th expression on the +right. +</p> + +<pre class="ebnf"> +ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . +ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . + +IdentifierList = identifier { "," identifier } . +ExpressionList = Expression { "," Expression } . +</pre> + +<p> +If the type is present, all constants take the type specified, and +the expressions must be <a href="#Assignability">assignable</a> to that type, +which must not be a type parameter. +If the type is omitted, the constants take the +individual types of the corresponding expressions. +If the expression values are untyped <a href="#Constants">constants</a>, +the declared constants remain untyped and the constant identifiers +denote the constant values. For instance, if the expression is a +floating-point literal, the constant identifier denotes a floating-point +constant, even if the literal's fractional part is zero. +</p> + +<pre> +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 +</pre> + +<p> +Within a parenthesized <code>const</code> declaration list the +expression list may be omitted from any but the first ConstSpec. +Such an empty list is equivalent to the textual substitution of the +first preceding non-empty expression list and its type if any. +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 <a href="#Iota"><code>iota</code> constant generator</a> +this mechanism permits light-weight declaration of sequential values: +</p> + +<pre> +const ( + Sunday = iota + Monday + Tuesday + Wednesday + Thursday + Friday + Partyday + numberOfDays // this constant is not exported +) +</pre> + + +<h3 id="Iota">Iota</h3> + +<p> +Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier +<code>iota</code> represents successive untyped integer <a href="#Constants"> +constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> +in that constant declaration, starting at zero. +It can be used to construct a set of related constants: +</p> + +<pre> +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 +</pre> + +<p> +By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value: +</p> + +<pre> +const ( + bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) + bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) + _, _ // (iota == 2, unused) + bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) +) +</pre> + +<p> +This last example exploits the <a href="#Constant_declarations">implicit repetition</a> +of the last non-empty expression list. +</p> + + +<h3 id="Type_declarations">Type declarations</h3> + +<p> +A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>. +Type declarations come in two forms: alias declarations and type definitions. +</p> + +<pre class="ebnf"> +TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . +TypeSpec = AliasDecl | TypeDef . +</pre> + +<h4 id="Alias_declarations">Alias declarations</h4> + +<p> +An alias declaration binds an identifier to the given type +[<a href="#Go_1.9">Go 1.9</a>]. +</p> + +<pre class="ebnf"> +AliasDecl = identifier "=" Type . +</pre> + +<p> +Within the <a href="#Declarations_and_scope">scope</a> of +the identifier, it serves as an <i>alias</i> for the type. +</p> + +<pre> +type ( + nodeList = []*Node // nodeList and []*Node are identical types + Polar = polar // Polar and polar denote identical types +) +</pre> + + +<h4 id="Type_definitions">Type definitions</h4> + +<p> +A type definition creates a new, distinct type with the same +<a href="#Underlying_types">underlying type</a> and operations as the given type +and binds an identifier, the <i>type name</i>, to it. +</p> + +<pre class="ebnf"> +TypeDef = identifier [ TypeParameters ] Type . +</pre> + +<p> +The new type is called a <i>defined type</i>. +It is <a href="#Type_identity">different</a> from any other type, +including the type it is created from. +</p> + +<pre> +type ( + Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types + polar Point // polar and Point denote different types +) + +type TreeNode struct { + left, right *TreeNode + value any +} + +type Block interface { + BlockSize() int + Encrypt(src, dst []byte) + Decrypt(src, dst []byte) +} +</pre> + +<p> +A defined type may have <a href="#Method_declarations">methods</a> associated with it. +It does not inherit any methods bound to the given type, +but the <a href="#Method_sets">method set</a> +of an interface type or of elements of a composite type remains unchanged: +</p> + +<pre> +// A Mutex is a data type with two methods, Lock and Unlock. +type Mutex struct { /* Mutex fields */ } +func (m *Mutex) Lock() { /* Lock implementation */ } +func (m *Mutex) Unlock() { /* Unlock implementation */ } + +// NewMutex has the same composition as Mutex but its method set is empty. +type NewMutex Mutex + +// The method set of PtrMutex's underlying type *Mutex remains unchanged, +// but the method set of PtrMutex is empty. +type PtrMutex *Mutex + +// The method set of *PrintableMutex contains the methods +// Lock and Unlock bound to its embedded field Mutex. +type PrintableMutex struct { + Mutex +} + +// MyBlock is an interface type that has the same method set as Block. +type MyBlock Block +</pre> + +<p> +Type definitions may be used to define different boolean, numeric, +or string types and associate methods with them: +</p> + +<pre> +type TimeZone int + +const ( + EST TimeZone = -(5 + iota) + CST + MST + PST +) + +func (tz TimeZone) String() string { + return fmt.Sprintf("GMT%+dh", tz) +} +</pre> + +<p> +If the type definition specifies <a href="#Type_parameter_declarations">type parameters</a>, +the type name denotes a <i>generic type</i>. +Generic types must be <a href="#Instantiations">instantiated</a> when they +are used. +</p> + +<pre> +type List[T any] struct { + next *List[T] + value T +} +</pre> + +<p> +In a type definition the given type cannot be a type parameter. +</p> + +<pre> +type T[P any] P // illegal: P is a type parameter + +func f[T any]() { + type L T // illegal: T is a type parameter declared by the enclosing function +} +</pre> + +<p> +A generic type may also have <a href="#Method_declarations">methods</a> associated with it. +In this case, the method receivers must declare the same number of type parameters as +present in the generic type definition. +</p> + +<pre> +// The method Len returns the number of elements in the linked list l. +func (l *List[T]) Len() int { … } +</pre> + +<h3 id="Type_parameter_declarations">Type parameter declarations</h3> + +<p> +A type parameter list declares the <i>type parameters</i> of a generic function or type declaration. +The type parameter list looks like an ordinary <a href="#Function_types">function parameter list</a> +except that the type parameter names must all be present and the list is enclosed +in square brackets rather than parentheses +[<a href="#Go_1.18">Go 1.18</a>]. +</p> + +<pre class="ebnf"> +TypeParameters = "[" TypeParamList [ "," ] "]" . +TypeParamList = TypeParamDecl { "," TypeParamDecl } . +TypeParamDecl = IdentifierList TypeConstraint . +</pre> + +<p> +All non-blank names in the list must be unique. +Each name declares a type parameter, which is a new and different <a href="#Types">named type</a> +that acts as a placeholder for an (as of yet) unknown type in the declaration. +The type parameter is replaced with a <i>type argument</i> upon +<a href="#Instantiations">instantiation</a> of the generic function or type. +</p> + +<pre> +[P any] +[S interface{ ~[]byte|string }] +[S ~[]E, E any] +[P Constraint[int]] +[_ any] +</pre> + +<p> +Just as each ordinary function parameter has a parameter type, each type parameter +has a corresponding (meta-)type which is called its +<a href="#Type_constraints"><i>type constraint</i></a>. +</p> + +<p> +A parsing ambiguity arises when the type parameter list for a generic type +declares a single type parameter <code>P</code> with a constraint <code>C</code> +such that the text <code>P C</code> forms a valid expression: +</p> + +<pre> +type T[P *C] … +type T[P (C)] … +type T[P *C|Q] … +… +</pre> + +<p> +In these rare cases, the type parameter list is indistinguishable from an +expression and the type declaration is parsed as an array type declaration. +To resolve the ambiguity, embed the constraint in an +<a href="#Interface_types">interface</a> or use a trailing comma: +</p> + +<pre> +type T[P interface{*C}] … +type T[P *C,] … +</pre> + +<p> +Type parameters may also be declared by the receiver specification +of a <a href="#Method_declarations">method declaration</a> associated +with a generic type. +</p> + +<p> +Within a type parameter list of a generic type <code>T</code>, a type constraint +may not (directly, or indirectly through the type parameter list of another +generic type) refer to <code>T</code>. +</p> + +<pre> +type T1[P T1[P]] … // illegal: T1 refers to itself +type T2[P interface{ T2[int] }] … // illegal: T2 refers to itself +type T3[P interface{ m(T3[int])}] … // illegal: T3 refers to itself +type T4[P T5[P]] … // illegal: T4 refers to T5 and +type T5[P T4[P]] … // T5 refers to T4 + +type T6[P int] struct{ f *T6[P] } // ok: reference to T6 is not in type parameter list +</pre> + +<h4 id="Type_constraints">Type constraints</h4> + +<p> +A <i>type constraint</i> is an <a href="#Interface_types">interface</a> that defines the +set of permissible type arguments for the respective type parameter and controls the +operations supported by values of that type parameter +[<a href="#Go_1.18">Go 1.18</a>]. +</p> + +<pre class="ebnf"> +TypeConstraint = TypeElem . +</pre> + +<p> +If the constraint is an interface literal of the form <code>interface{E}</code> where +<code>E</code> is an embedded <a href="#Interface_types">type element</a> (not a method), in a type parameter list +the enclosing <code>interface{ … }</code> may be omitted for convenience: +</p> + +<pre> +[T []P] // = [T interface{[]P}] +[T ~int] // = [T interface{~int}] +[T int|string] // = [T interface{int|string}] +type Constraint ~int // illegal: ~int is not in a type parameter list +</pre> + +<!-- +We should be able to simplify the rules for comparable or delegate some of them +elsewhere since we have a section that clearly defines how interfaces implement +other interfaces based on their type sets. But this should get us going for now. +--> + +<p> +The <a href="#Predeclared_identifiers">predeclared</a> +<a href="#Interface_types">interface type</a> <code>comparable</code> +denotes the set of all non-interface types that are +<a href="#Comparison_operators">strictly comparable</a> +[<a href="#Go_1.18">Go 1.18</a>]. +</p> + +<p> +Even though interfaces that are not type parameters are <a href="#Comparison_operators">comparable</a>, +they are not strictly comparable and therefore they do not implement <code>comparable</code>. +However, they <a href="#Satisfying_a_type_constraint">satisfy</a> <code>comparable</code>. +</p> + +<pre> +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) +</pre> + +<p> +The <code>comparable</code> interface and interfaces that (directly or indirectly) embed +<code>comparable</code> may only be used as type constraints. They cannot be the types of +values or variables, or components of other, non-interface types. +</p> + +<h4 id="Satisfying_a_type_constraint">Satisfying a type constraint</h4> + +<p> +A type argument <code>T</code><i> satisfies</i> a type constraint <code>C</code> +if <code>T</code> is an element of the type set defined by <code>C</code>; i.e., +if <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>. +As an exception, a <a href="#Comparison_operators">strictly comparable</a> +type constraint may also be satisfied by a <a href="#Comparison_operators">comparable</a> +(not necessarily strictly comparable) type argument +[<a href="#Go_1.20">Go 1.20</a>]. +More precisely: +</p> + +<p> +A type T <i>satisfies</i> a constraint <code>C</code> if +</p> + +<ul> +<li> + <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>; or +</li> +<li> + <code>C</code> can be written in the form <code>interface{ comparable; E }</code>, + where <code>E</code> is a <a href="#Basic_interfaces">basic interface</a> and + <code>T</code> is <a href="#Comparison_operators">comparable</a> and implements <code>E</code>. +</li> +</ul> + +<pre> +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() } +</pre> + +<p> +Because of the exception in the constraint satisfaction rule, comparing operands of type parameter type +may panic at run-time (even though comparable type parameters are always strictly comparable). +</p> + +<h3 id="Variable_declarations">Variable declarations</h3> + +<p> +A variable declaration creates one or more <a href="#Variables">variables</a>, +binds corresponding identifiers to them, and gives each a type and an initial value. +</p> + +<pre class="ebnf"> +VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . +VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . +</pre> + +<pre> +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" +</pre> + +<p> +If a list of expressions is given, the variables are initialized +with the expressions following the rules for <a href="#Assignment_statements">assignment statements</a>. +Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. +</p> + +<p> +If a type is present, each variable is given that type. +Otherwise, each variable is given the type of the corresponding +initialization value in the assignment. +If that value is an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; +if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>. +The predeclared value <code>nil</code> cannot be used to initialize a variable +with no explicit type. +</p> + +<pre> +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 +</pre> + +<p> +Implementation restriction: A compiler may make it illegal to declare a variable +inside a <a href="#Function_declarations">function body</a> if the variable is +never used. +</p> + +<h3 id="Short_variable_declarations">Short variable declarations</h3> + +<p> +A <i>short variable declaration</i> uses the syntax: +</p> + +<pre class="ebnf"> +ShortVarDecl = IdentifierList ":=" ExpressionList . +</pre> + +<p> +It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a> +with initializer expressions but no types: +</p> + +<pre class="grammar"> +"var" IdentifierList "=" ExpressionList . +</pre> + +<pre> +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 +</pre> + +<p> +Unlike regular variable declarations, a short variable declaration may <i>redeclare</i> +variables provided they were originally declared earlier in the same block +(or the parameter lists if the block is the function body) with the same type, +and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. +As a consequence, redeclaration can only appear in a multi-variable short declaration. +Redeclaration does not introduce a new variable; it just assigns a new value to the original. +The non-blank variable names on the left side of <code>:=</code> +must be <a href="#Uniqueness_of_identifiers">unique</a>. +</p> + +<pre> +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 := +</pre> + +<p> +Short variable declarations may appear only inside functions. +In some contexts such as the initializers for +<a href="#If_statements">"if"</a>, +<a href="#For_statements">"for"</a>, or +<a href="#Switch_statements">"switch"</a> statements, +they can be used to declare local temporary variables. +</p> + +<h3 id="Function_declarations">Function declarations</h3> + +<!-- + Given the importance of functions, this section has always + been woefully underdeveloped. Would be nice to expand this + a bit. +--> + +<p> +A function declaration binds an identifier, the <i>function name</i>, +to a function. +</p> + +<pre class="ebnf"> +FunctionDecl = "func" FunctionName [ TypeParameters ] Signature [ FunctionBody ] . +FunctionName = identifier . +FunctionBody = Block . +</pre> + +<p> +If the function's <a href="#Function_types">signature</a> declares +result parameters, the function body's statement list must end in +a <a href="#Terminating_statements">terminating statement</a>. +</p> + +<pre> +func IndexRune(s string, r rune) int { + for i, c := range s { + if c == r { + return i + } + } + // invalid: missing return statement +} +</pre> + +<p> +If the function declaration specifies <a href="#Type_parameter_declarations">type parameters</a>, +the function name denotes a <i>generic function</i>. +A generic function must be <a href="#Instantiations">instantiated</a> before it can be +called or used as a value. +</p> + +<pre> +func min[T ~int|~float64](x, y T) T { + if x < y { + return x + } + return y +} +</pre> + +<p> +A function declaration without type parameters may omit the body. +Such a declaration provides the signature for a function implemented outside Go, +such as an assembly routine. +</p> + +<pre> +func flushICache(begin, end uintptr) // implemented externally +</pre> + +<h3 id="Method_declarations">Method declarations</h3> + +<p> +A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>. +A method declaration binds an identifier, the <i>method name</i>, to a method, +and associates the method with the receiver's <i>base type</i>. +</p> + +<pre class="ebnf"> +MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . +Receiver = Parameters . +</pre> + +<p> +The receiver is specified via an extra parameter section preceding the method +name. That parameter section must declare a single non-variadic parameter, the receiver. +Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a +pointer to a defined type <code>T</code>, possibly followed by a list of type parameter +names <code>[P1, P2, …]</code> enclosed in square brackets. +<code>T</code> is called the receiver <i>base type</i>. A receiver base type cannot be +a pointer or interface type and it must be defined in the same package as the method. +The method is said to be <i>bound</i> to its receiver base type and the method name +is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> +or <code>*T</code>. +</p> + +<p> +A non-<a href="#Blank_identifier">blank</a> receiver identifier must be +<a href="#Uniqueness_of_identifiers">unique</a> in the method signature. +If the receiver's value is not referenced inside the body of the method, +its identifier may be omitted in the declaration. The same applies in +general to parameters of functions and methods. +</p> + +<p> +For a base type, the non-blank names of methods bound to it must be unique. +If the base type is a <a href="#Struct_types">struct type</a>, +the non-blank method and field names must be distinct. +</p> + +<p> +Given defined type <code>Point</code> the declarations +</p> + +<pre> +func (p *Point) Length() float64 { + return math.Sqrt(p.x * p.x + p.y * p.y) +} + +func (p *Point) Scale(factor float64) { + p.x *= factor + p.y *= factor +} +</pre> + +<p> +bind the methods <code>Length</code> and <code>Scale</code>, +with receiver type <code>*Point</code>, +to the base type <code>Point</code>. +</p> + +<p> +If the receiver base type is a <a href="#Type_declarations">generic type</a>, the +receiver specification must declare corresponding type parameters for the method +to use. This makes the receiver type parameters available to the method. +Syntactically, this type parameter declaration looks like an +<a href="#Instantiations">instantiation</a> of the receiver base type: the type +arguments must be identifiers denoting the type parameters being declared, one +for each type parameter of the receiver base type. +The type parameter names do not need to match their corresponding parameter names in the +receiver base type definition, and all non-blank parameter names must be unique in the +receiver parameter section and the method signature. +The receiver type parameter constraints are implied by the receiver base type definition: +corresponding type parameters have corresponding constraints. +</p> + +<pre> +type Pair[A, B any] struct { + a A + b B +} + +func (p Pair[A, B]) Swap() Pair[B, A] { … } // receiver declares A, B +func (p Pair[First, _]) First() First { … } // receiver declares First, corresponds to A in Pair +</pre> + +<h2 id="Expressions">Expressions</h2> + +<p> +An expression specifies the computation of a value by applying +operators and functions to operands. +</p> + +<h3 id="Operands">Operands</h3> + +<p> +Operands denote the elementary values in an expression. An operand may be a +literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) +non-<a href="#Blank_identifier">blank</a> identifier denoting a +<a href="#Constant_declarations">constant</a>, +<a href="#Variable_declarations">variable</a>, or +<a href="#Function_declarations">function</a>, +or a parenthesized expression. +</p> + +<pre class="ebnf"> +Operand = Literal | OperandName [ TypeArgs ] | "(" Expression ")" . +Literal = BasicLit | CompositeLit | FunctionLit . +BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . +OperandName = identifier | QualifiedIdent . +</pre> + +<p> +An operand name denoting a <a href="#Function_declarations">generic function</a> +may be followed by a list of <a href="#Instantiations">type arguments</a>; the +resulting operand is an <a href="#Instantiations">instantiated</a> function. +</p> + +<p> +The <a href="#Blank_identifier">blank identifier</a> may appear as an +operand only on the left-hand side of an <a href="#Assignment_statements">assignment statement</a>. +</p> + +<p> +Implementation restriction: A compiler need not report an error if an operand's +type is a <a href="#Type_parameter_declarations">type parameter</a> with an empty +<a href="#Interface_types">type set</a>. Functions with such type parameters +cannot be <a href="#Instantiations">instantiated</a>; any attempt will lead +to an error at the instantiation site. +</p> + +<h3 id="Qualified_identifiers">Qualified identifiers</h3> + +<p> +A <i>qualified identifier</i> is an identifier qualified with a package name prefix. +Both the package name and the identifier must not be +<a href="#Blank_identifier">blank</a>. +</p> + +<pre class="ebnf"> +QualifiedIdent = PackageName "." identifier . +</pre> + +<p> +A qualified identifier accesses an identifier in a different package, which +must be <a href="#Import_declarations">imported</a>. +The identifier must be <a href="#Exported_identifiers">exported</a> and +declared in the <a href="#Blocks">package block</a> of that package. +</p> + +<pre> +math.Sin // denotes the Sin function in package math +</pre> + +<h3 id="Composite_literals">Composite literals</h3> + +<p> +Composite literals construct new composite values each time they are evaluated. +They consist of the type of the literal followed by a brace-bound list of elements. +Each element may optionally be preceded by a corresponding key. +</p> + +<pre class="ebnf"> +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 . +</pre> + +<p> +The LiteralType's <a href="#Core_types">core type</a> <code>T</code> +must be a struct, array, slice, or map type +(the syntax enforces this constraint except when the type is given +as a TypeName). +The types of the elements and keys must be <a href="#Assignability">assignable</a> +to the respective field, element, and key types of type <code>T</code>; +there is no additional conversion. +The key is interpreted as a field name for struct literals, +an index for array and slice literals, and a key for map literals. +For map literals, all elements must have a key. It is an error +to specify multiple elements with the same field name or +constant key value. For non-constant map keys, see the section on +<a href="#Order_of_evaluation">evaluation order</a>. +</p> + +<p> +For struct literals the following rules apply: +</p> +<ul> + <li>A key must be a field name declared in the struct type. + </li> + <li>An element list that does not contain any keys must + list an element for each struct field in the + order in which the fields are declared. + </li> + <li>If any element has a key, every element must have a key. + </li> + <li>An element list that contains keys does not need to + have an element for each struct field. Omitted fields + get the zero value for that field. + </li> + <li>A literal may omit the element list; such a literal evaluates + to the zero value for its type. + </li> + <li>It is an error to specify an element for a non-exported + field of a struct belonging to a different package. + </li> +</ul> + +<p> +Given the declarations +</p> +<pre> +type Point3D struct { x, y, z float64 } +type Line struct { p, q Point3D } +</pre> + +<p> +one may write +</p> + +<pre> +origin := Point3D{} // zero value for Point3D +line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x +</pre> + +<p> +For array and slice literals the following rules apply: +</p> +<ul> + <li>Each element has an associated integer index marking + its position in the array. + </li> + <li>An element with a key uses the key as its index. The + key must be a non-negative constant + <a href="#Representability">representable</a> by + a value of type <code>int</code>; and if it is typed + it must be of <a href="#Numeric_types">integer type</a>. + </li> + <li>An element without a key uses the previous element's index plus one. + If the first element has no key, its index is zero. + </li> +</ul> + +<p> +<a href="#Address_operators">Taking the address</a> of a composite literal +generates a pointer to a unique <a href="#Variables">variable</a> initialized +with the literal's value. +</p> + +<pre> +var pointer *Point3D = &Point3D{y: 1000} +</pre> + +<p> +Note that the <a href="#The_zero_value">zero value</a> for a slice or map +type is not the same as an initialized but empty value of the same type. +Consequently, taking the address of an empty slice or map composite literal +does not have the same effect as allocating a new slice or map value with +<a href="#Allocation">new</a>. +</p> + +<pre> +p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0 +p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0 +</pre> + +<p> +The length of an array literal is the length specified in the literal type. +If fewer elements than the length are provided in the literal, the missing +elements are set to the zero value for the array element type. +It is an error to provide elements with index values outside the index range +of the array. The notation <code>...</code> specifies an array length equal +to the maximum element index plus one. +</p> + +<pre> +buffer := [10]string{} // len(buffer) == 10 +intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 +days := [...]string{"Sat", "Sun"} // len(days) == 2 +</pre> + +<p> +A slice literal describes the entire underlying array literal. +Thus the length and capacity of a slice literal are the maximum +element index plus one. A slice literal has the form +</p> + +<pre> +[]T{x1, x2, … xn} +</pre> + +<p> +and is shorthand for a slice operation applied to an array: +</p> + +<pre> +tmp := [n]T{x1, x2, … xn} +tmp[0 : n] +</pre> + +<p> +Within a composite literal of array, slice, or map type <code>T</code>, +elements or map keys that are themselves composite literals may elide the respective +literal type if it is identical to the element or key type of <code>T</code>. +Similarly, elements or keys that are addresses of composite literals may elide +the <code>&T</code> when the element or key type is <code>*T</code>. +</p> + +<pre> +[...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} +[][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} +[][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} +map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}} +map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"} + +type PPoint *Point +[2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} +[2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})} +</pre> + +<p> +A parsing ambiguity arises when a composite literal using the +TypeName form of the LiteralType appears as an operand between the +<a href="#Keywords">keyword</a> and the opening brace of the block +of an "if", "for", or "switch" statement, and the composite literal +is not enclosed in parentheses, square brackets, or curly braces. +In this rare case, the opening brace of the literal is erroneously parsed +as the one introducing the block of statements. To resolve the ambiguity, +the composite literal must appear within parentheses. +</p> + +<pre> +if x == (T{a,b,c}[i]) { … } +if (x == T{a,b,c}[i]) { … } +</pre> + +<p> +Examples of valid array, slice, and map literals: +</p> + +<pre> +// list of prime numbers +primes := []int{2, 3, 5, 7, 9, 2147483647} + +// vowels[ch] is true if ch is a vowel +vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true} + +// the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} +filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} + +// frequencies in Hz for equal-tempered scale (A4 = 440Hz) +noteFrequency := map[string]float32{ + "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, + "G0": 24.50, "A0": 27.50, "B0": 30.87, +} +</pre> + + +<h3 id="Function_literals">Function literals</h3> + +<p> +A function literal represents an anonymous <a href="#Function_declarations">function</a>. +Function literals cannot declare type parameters. +</p> + +<pre class="ebnf"> +FunctionLit = "func" Signature FunctionBody . +</pre> + +<pre> +func(a, b int, z float64) bool { return a*b < int(z) } +</pre> + +<p> +A function literal can be assigned to a variable or invoked directly. +</p> + +<pre> +f := func(x, y int) int { return x + y } +func(ch chan int) { ch <- ACK }(replyChan) +</pre> + +<p> +Function literals are <i>closures</i>: 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. +</p> + + +<h3 id="Primary_expressions">Primary expressions</h3> + +<p> +Primary expressions are the operands for unary and binary expressions. +</p> + +<pre class="ebnf"> +PrimaryExpr = + Operand | + Conversion | + MethodExpr | + PrimaryExpr Selector | + PrimaryExpr Index | + PrimaryExpr Slice | + PrimaryExpr TypeAssertion | + PrimaryExpr Arguments . + +Selector = "." identifier . +Index = "[" Expression [ "," ] "]" . +Slice = "[" [ Expression ] ":" [ Expression ] "]" | + "[" [ Expression ] ":" Expression ":" Expression "]" . +TypeAssertion = "." "(" Type ")" . +Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . +</pre> + + +<pre> +x +2 +(s + ".txt") +f(3.1415, true) +Point{1, 2} +m["foo"] +s[i : j + 1] +obj.color +f.p[i].x() +</pre> + + +<h3 id="Selectors">Selectors</h3> + +<p> +For a <a href="#Primary_expressions">primary expression</a> <code>x</code> +that is not a <a href="#Package_clause">package name</a>, the +<i>selector expression</i> +</p> + +<pre> +x.f +</pre> + +<p> +denotes the field or method <code>f</code> of the value <code>x</code> +(or sometimes <code>*x</code>; see below). +The identifier <code>f</code> is called the (field or method) <i>selector</i>; +it must not be the <a href="#Blank_identifier">blank identifier</a>. +The type of the selector expression is the type of <code>f</code>. +If <code>x</code> is a package name, see the section on +<a href="#Qualified_identifiers">qualified identifiers</a>. +</p> + +<p> +A selector <code>f</code> may denote a field or method <code>f</code> of +a type <code>T</code>, or it may refer +to a field or method <code>f</code> of a nested +<a href="#Struct_types">embedded field</a> of <code>T</code>. +The number of embedded fields traversed +to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. +The depth of a field or method <code>f</code> +declared in <code>T</code> is zero. +The depth of a field or method <code>f</code> declared in +an embedded field <code>A</code> in <code>T</code> is the +depth of <code>f</code> in <code>A</code> plus one. +</p> + +<p> +The following rules apply to selectors: +</p> + +<ol> +<li> +For a value <code>x</code> of type <code>T</code> or <code>*T</code> +where <code>T</code> is not a pointer or interface type, +<code>x.f</code> denotes the field or method at the shallowest depth +in <code>T</code> where there is such an <code>f</code>. +If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> +with shallowest depth, the selector expression is illegal. +</li> + +<li> +For a value <code>x</code> of type <code>I</code> where <code>I</code> +is an interface type, <code>x.f</code> denotes the actual method with name +<code>f</code> of the dynamic value of <code>x</code>. +If there is no method with name <code>f</code> in the +<a href="#Method_sets">method set</a> of <code>I</code>, the selector +expression is illegal. +</li> + +<li> +As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> +pointer type and <code>(*x).f</code> is a valid selector expression denoting a field +(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. +</li> + +<li> +In all other cases, <code>x.f</code> is illegal. +</li> + +<li> +If <code>x</code> is of pointer type and has the value +<code>nil</code> and <code>x.f</code> denotes a struct field, +assigning to or evaluating <code>x.f</code> +causes a <a href="#Run_time_panics">run-time panic</a>. +</li> + +<li> +If <code>x</code> is of interface type and has the value +<code>nil</code>, <a href="#Calls">calling</a> or +<a href="#Method_values">evaluating</a> the method <code>x.f</code> +causes a <a href="#Run_time_panics">run-time panic</a>. +</li> +</ol> + +<p> +For example, given the declarations: +</p> + +<pre> +type T0 struct { + x int +} + +func (*T0) M0() + +type T1 struct { + y int +} + +func (T1) M1() + +type T2 struct { + z int + T1 + *T0 +} + +func (*T2) M2() + +type Q *T2 + +var t T2 // with t.T0 != nil +var p *T2 // with p != nil and (*p).T0 != nil +var q Q = p +</pre> + +<p> +one may write: +</p> + +<pre> +t.z // t.z +t.y // t.T1.y +t.x // (*t.T0).x + +p.z // (*p).z +p.y // (*p).T1.y +p.x // (*(*p).T0).x + +q.x // (*(*q).T0).x (*q).x is a valid field selector + +p.M0() // ((*p).T0).M0() M0 expects *T0 receiver +p.M1() // ((*p).T1).M1() M1 expects T1 receiver +p.M2() // p.M2() M2 expects *T2 receiver +t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls +</pre> + +<p> +but the following is invalid: +</p> + +<pre> +q.M0() // (*q).M0 is valid but not a field selector +</pre> + + +<h3 id="Method_expressions">Method expressions</h3> + +<p> +If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>T.M</code> is a function that is callable as a regular function +with the same arguments as <code>M</code> prefixed by an additional +argument that is the receiver of the method. +</p> + +<pre class="ebnf"> +MethodExpr = ReceiverType "." MethodName . +ReceiverType = Type . +</pre> + +<p> +Consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +</pre> + +<p> +The expression +</p> + +<pre> +T.Mv +</pre> + +<p> +yields a function equivalent to <code>Mv</code> but +with an explicit receiver as its first argument; it has signature +</p> + +<pre> +func(tv T, a int) int +</pre> + +<p> +That function may be called normally with an explicit receiver, so +these five invocations are equivalent: +</p> + +<pre> +t.Mv(7) +T.Mv(t, 7) +(T).Mv(t, 7) +f1 := T.Mv; f1(t, 7) +f2 := (T).Mv; f2(t, 7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +(*T).Mp +</pre> + +<p> +yields a function value representing <code>Mp</code> with signature +</p> + +<pre> +func(tp *T, f float32) float32 +</pre> + +<p> +For a method with a value receiver, one can derive a function +with an explicit pointer receiver, so +</p> + +<pre> +(*T).Mv +</pre> + +<p> +yields a function value representing <code>Mv</code> with signature +</p> + +<pre> +func(tv *T, a int) int +</pre> + +<p> +Such a function indirects through the receiver to create a value +to pass as the receiver to the underlying method; +the method does not overwrite the value whose address is passed in +the function call. +</p> + +<p> +The final case, a value-receiver function for a pointer-receiver method, +is illegal because pointer-receiver methods are not in the method set +of the value type. +</p> + +<p> +Function values derived from methods are called with function call syntax; +the receiver is provided as the first argument to the call. +That is, given <code>f := T.Mv</code>, <code>f</code> is invoked +as <code>f(t, 7)</code> not <code>t.f(7)</code>. +To construct a function that binds the receiver, use a +<a href="#Function_literals">function literal</a> or +<a href="#Method_values">method value</a>. +</p> + +<p> +It is legal to derive a function value from a method of an interface type. +The resulting function takes an explicit receiver of that interface type. +</p> + +<h3 id="Method_values">Method values</h3> + +<p> +If the expression <code>x</code> has static type <code>T</code> and +<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, +<code>x.M</code> is called a <i>method value</i>. +The method value <code>x.M</code> is a function value that is callable +with the same arguments as a method call of <code>x.M</code>. +The expression <code>x</code> is evaluated and saved during the evaluation of the +method value; the saved copy is then used as the receiver in any calls, +which may be executed later. +</p> + +<pre> +type S struct { *T } +type T int +func (t T) M() { print(t) } + +t := new(T) +s := S{T: t} +f := t.M // receiver *t is evaluated and stored in f +g := s.M // receiver *(s.T) is evaluated and stored in g +*t = 42 // does not affect stored receivers in f and g +</pre> + +<p> +The type <code>T</code> may be an interface or non-interface type. +</p> + +<p> +As in the discussion of <a href="#Method_expressions">method expressions</a> above, +consider a struct type <code>T</code> with two methods, +<code>Mv</code>, whose receiver is of type <code>T</code>, and +<code>Mp</code>, whose receiver is of type <code>*T</code>. +</p> + +<pre> +type T struct { + a int +} +func (tv T) Mv(a int) int { return 0 } // value receiver +func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver + +var t T +var pt *T +func makeT() T +</pre> + +<p> +The expression +</p> + +<pre> +t.Mv +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(int) int +</pre> + +<p> +These two invocations are equivalent: +</p> + +<pre> +t.Mv(7) +f := t.Mv; f(7) +</pre> + +<p> +Similarly, the expression +</p> + +<pre> +pt.Mp +</pre> + +<p> +yields a function value of type +</p> + +<pre> +func(float32) float32 +</pre> + +<p> +As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver +using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. +</p> + +<p> +As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver +using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. +</p> + +<pre> +f := t.Mv; f(7) // like t.Mv(7) +f := pt.Mp; f(7) // like pt.Mp(7) +f := pt.Mv; f(7) // like (*pt).Mv(7) +f := t.Mp; f(7) // like (&t).Mp(7) +f := makeT().Mp // invalid: result of makeT() is not addressable +</pre> + +<p> +Although the examples above use non-interface types, it is also legal to create a method value +from a value of interface type. +</p> + +<pre> +var i interface { M(int) } = myVal +f := i.M; f(7) // like i.M(7) +</pre> + + +<h3 id="Index_expressions">Index expressions</h3> + +<p> +A primary expression of the form +</p> + +<pre> +a[x] +</pre> + +<p> +denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. +The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively. +The following rules apply: +</p> + +<p> +If <code>a</code> is neither a map nor a type parameter: +</p> +<ul> + <li>the index <code>x</code> must be an untyped constant or its + <a href="#Core_types">core type</a> must be an <a href="#Numeric_types">integer</a></li> + <li>a constant index must be non-negative and + <a href="#Representability">representable</a> by a value of type <code>int</code></li> + <li>a constant index that is untyped is given type <code>int</code></li> + <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>, + otherwise it is <i>out of range</i></li> +</ul> + +<p> +For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>: +</p> +<ul> + <li>a <a href="#Constants">constant</a> index must be in range</li> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the array element at index <code>x</code> and the type of + <code>a[x]</code> is the element type of <code>A</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type: +</p> +<ul> + <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: +</p> +<ul> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of + <code>a[x]</code> is the element type of <code>S</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#String_types">string type</a>: +</p> +<ul> + <li>a <a href="#Constants">constant</a> index must be in range + if the string <code>a</code> is also constant</li> + <li>if <code>x</code> is out of range at run time, + a <a href="#Run_time_panics">run-time panic</a> occurs</li> + <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of + <code>a[x]</code> is <code>byte</code></li> + <li><code>a[x]</code> may not be assigned to</li> +</ul> + +<p> +For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>: +</p> +<ul> + <li><code>x</code>'s type must be + <a href="#Assignability">assignable</a> + to the key type of <code>M</code></li> + <li>if the map contains an entry with key <code>x</code>, + <code>a[x]</code> is the map element with key <code>x</code> + and the type of <code>a[x]</code> is the element type of <code>M</code></li> + <li>if the map is <code>nil</code> or does not contain such an entry, + <code>a[x]</code> is the <a href="#The_zero_value">zero value</a> + for the element type of <code>M</code></li> +</ul> + +<p> +For <code>a</code> of <a href="#Type_parameter_declarations">type parameter type</a> <code>P</code>: +</p> +<ul> + <li>The index expression <code>a[x]</code> must be valid for values + of all types in <code>P</code>'s type set.</li> + <li>The element types of all types in <code>P</code>'s type set must be identical. + In this context, the element type of a string type is <code>byte</code>.</li> + <li>If there is a map type in the type set of <code>P</code>, + all types in that type set must be map types, and the respective key types + must be all identical.</li> + <li><code>a[x]</code> is the array, slice, or string element at index <code>x</code>, + or the map element with key <code>x</code> of the type argument + that <code>P</code> is instantiated with, and the type of <code>a[x]</code> is + the type of the (identical) element types.</li> + <li><code>a[x]</code> may not be assigned to if <code>P</code>'s type set + includes string types.</li> +</ul> + +<p> +Otherwise <code>a[x]</code> is illegal. +</p> + +<p> +An index expression on a map <code>a</code> of type <code>map[K]V</code> +used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form +</p> + +<pre> +v, ok = a[x] +v, ok := a[x] +var v, ok = a[x] +</pre> + +<p> +yields an additional untyped boolean value. The value of <code>ok</code> is +<code>true</code> if the key <code>x</code> is present in the map, and +<code>false</code> otherwise. +</p> + +<p> +Assigning to an element of a <code>nil</code> map causes a +<a href="#Run_time_panics">run-time panic</a>. +</p> + + +<h3 id="Slice_expressions">Slice expressions</h3> + +<p> +Slice expressions construct a substring or slice from a string, array, pointer +to array, or slice. There are two variants: a simple form that specifies a low +and high bound, and a full form that also specifies a bound on the capacity. +</p> + +<h4>Simple slice expressions</h4> + +<p> +The primary expression +</p> + +<pre> +a[low : high] +</pre> + +<p> +constructs a substring or slice. The <a href="#Core_types">core type</a> of +<code>a</code> must be a string, array, pointer to array, slice, or a +<a href="#Core_types"><code>bytestring</code></a>. +The <i>indices</i> <code>low</code> and +<code>high</code> select which elements of operand <code>a</code> appear +in the result. The result has indices starting at 0 and length equal to +<code>high</code> - <code>low</code>. +After slicing the array <code>a</code> +</p> + +<pre> +a := [5]int{1, 2, 3, 4, 5} +s := a[1:4] +</pre> + +<p> +the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements +</p> + +<pre> +s[0] == 2 +s[1] == 3 +s[2] == 4 +</pre> + +<p> +For convenience, any of the indices may be omitted. A missing <code>low</code> +index defaults to zero; a missing <code>high</code> index defaults to the length of the +sliced operand: +</p> + +<pre> +a[2:] // same as a[2 : len(a)] +a[:3] // same as a[0 : 3] +a[:] // same as a[0 : len(a)] +</pre> + +<p> +If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for +<code>(*a)[low : high]</code>. +</p> + +<p> +For arrays or strings, the indices are <i>in range</i> if +<code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>, +otherwise they are <i>out of range</i>. +For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. +A <a href="#Constants">constant</a> index must be non-negative and +<a href="#Representability">representable</a> by a value of type +<code>int</code>; for arrays or constant strings, constant indices must also be in range. +If both indices are constant, they must satisfy <code>low <= high</code>. +If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<p> +Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, +the result of the slice operation is a non-constant value of the same type as the operand. +For untyped string operands the result is a non-constant value of type <code>string</code>. +If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> +and the result of the slice operation is a slice with the same element type as the array. +</p> + +<p> +If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result +is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying +array with the operand. +</p> + +<pre> +var a [10]int +s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5] +s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5] +s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element + +var s []int +s3 := s[:0] // s3 == nil +</pre> + + +<h4>Full slice expressions</h4> + +<p> +The primary expression +</p> + +<pre> +a[low : high : max] +</pre> + +<p> +constructs a slice of the same type, and with the same length and elements as the simple slice +expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity +by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. +The <a href="#Core_types">core type</a> of <code>a</code> must be an array, pointer to array, +or slice (but not a string). +After slicing the array <code>a</code> +</p> + +<pre> +a := [5]int{1, 2, 3, 4, 5} +t := a[1:3:5] +</pre> + +<p> +the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements +</p> + +<pre> +t[0] == 2 +t[1] == 3 +</pre> + +<p> +As for simple slice expressions, if <code>a</code> is a pointer to an array, +<code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. +If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. +</p> + +<p> +The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, +otherwise they are <i>out of range</i>. +A <a href="#Constants">constant</a> index must be non-negative and +<a href="#Representability">representable</a> by a value of type +<code>int</code>; for arrays, constant indices must also be in range. +If multiple indices are constant, the constants that are present must be in range relative to each +other. +If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<h3 id="Type_assertions">Type assertions</h3> + +<p> +For an expression <code>x</code> of <a href="#Interface_types">interface type</a>, +but not a <a href="#Type_parameter_declarations">type parameter</a>, and a type <code>T</code>, +the primary expression +</p> + +<pre> +x.(T) +</pre> + +<p> +asserts that <code>x</code> is not <code>nil</code> +and that the value stored in <code>x</code> is of type <code>T</code>. +The notation <code>x.(T)</code> is called a <i>type assertion</i>. +</p> +<p> +More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts +that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> +to the type <code>T</code>. +In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; +otherwise the type assertion is invalid since it is not possible for <code>x</code> +to store a value of type <code>T</code>. +If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type +of <code>x</code> <a href="#Implementing_an_interface">implements</a> the interface <code>T</code>. +</p> +<p> +If the type assertion holds, the value of the expression is the value +stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, +a <a href="#Run_time_panics">run-time panic</a> occurs. +In other words, even though the dynamic type of <code>x</code> +is known only at run time, the type of <code>x.(T)</code> is +known to be <code>T</code> in a correct program. +</p> + +<pre> +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 (missing method m) + r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader + … +} +</pre> + +<p> +A type assertion used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form +</p> + +<pre> +v, ok = x.(T) +v, ok := x.(T) +var v, ok = x.(T) +var v, ok interface{} = x.(T) // dynamic types of v and ok are T and bool +</pre> + +<p> +yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> +if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is +the <a href="#The_zero_value">zero value</a> for type <code>T</code>. +No <a href="#Run_time_panics">run-time panic</a> occurs in this case. +</p> + + +<h3 id="Calls">Calls</h3> + +<p> +Given an expression <code>f</code> with a <a href="#Core_types">core type</a> +<code>F</code> of <a href="#Function_types">function type</a>, +</p> + +<pre> +f(a1, a2, … an) +</pre> + +<p> +calls <code>f</code> with arguments <code>a1, a2, … an</code>. +Except for one special case, arguments must be single-valued expressions +<a href="#Assignability">assignable</a> to the parameter types of +<code>F</code> and are evaluated before the function is called. +The type of the expression is the result type +of <code>F</code>. +A method invocation is similar but the method itself +is specified as a selector upon a value of the receiver type for +the method. +</p> + +<pre> +math.Atan2(x, y) // function call +var pt *Point +pt.Scale(3.5) // method call with receiver pt +</pre> + +<p> +If <code>f</code> denotes a generic function, it must be +<a href="#Instantiations">instantiated</a> before it can be called +or used as a function value. +</p> + +<p> +In a function call, the function value and arguments are evaluated in +<a href="#Order_of_evaluation">the usual order</a>. +After they are evaluated, the parameters of the call are passed by value to the function +and the called function begins execution. +The return parameters of the function are passed by value +back to the caller when the function returns. +</p> + +<p> +Calling a <code>nil</code> function value +causes a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<p> +As a special case, if the return values of a function or method +<code>g</code> are equal in number and individually +assignable to the parameters of another function or method +<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code> +will invoke <code>f</code> after binding the return values of +<code>g</code> to the parameters of <code>f</code> in order. The call +of <code>f</code> must contain no parameters other than the call of <code>g</code>, +and <code>g</code> must have at least one return value. +If <code>f</code> has a final <code>...</code> parameter, it is +assigned the return values of <code>g</code> that remain after +assignment of regular parameters. +</p> + +<pre> +func Split(s string, pos int) (string, string) { + return s[0:pos], s[pos:] +} + +func Join(s, t string) string { + return s + t +} + +if Join(Split(value, len(value)/2)) != value { + log.Panic("test fails") +} +</pre> + +<p> +A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> +of (the type of) <code>x</code> contains <code>m</code> and the +argument list can be assigned to the parameter list of <code>m</code>. +If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method +set contains <code>m</code>, <code>x.m()</code> is shorthand +for <code>(&x).m()</code>: +</p> + +<pre> +var p Point +p.Scale(3.5) +</pre> + +<p> +There is no distinct method type and there are no method literals. +</p> + +<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> + +<p> +If <code>f</code> is <a href="#Function_types">variadic</a> with a final +parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> +the type of <code>p</code> is equivalent to type <code>[]T</code>. +If <code>f</code> is invoked with no actual arguments for <code>p</code>, +the value passed to <code>p</code> is <code>nil</code>. +Otherwise, the value passed is a new slice +of type <code>[]T</code> with a new underlying array whose successive elements +are the actual arguments, which all must be <a href="#Assignability">assignable</a> +to <code>T</code>. The length and capacity of the slice is therefore +the number of arguments bound to <code>p</code> and may differ for each +call site. +</p> + +<p> +Given the function and calls +</p> +<pre> +func Greeting(prefix string, who ...string) +Greeting("nobody") +Greeting("hello:", "Joe", "Anna", "Eileen") +</pre> + +<p> +within <code>Greeting</code>, <code>who</code> will have the value +<code>nil</code> in the first call, and +<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. +</p> + +<p> +If the final argument is assignable to a slice type <code>[]T</code> and +is followed by <code>...</code>, it is passed unchanged as the value +for a <code>...T</code> parameter. In this case no new slice is created. +</p> + +<p> +Given the slice <code>s</code> and call +</p> + +<pre> +s := []string{"James", "Jasmine"} +Greeting("goodbye:", s...) +</pre> + +<p> +within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> +with the same underlying array. +</p> + +<h3 id="Instantiations">Instantiations</h3> + +<p> +A generic function or type is <i>instantiated</i> by substituting <i>type arguments</i> +for the type parameters [<a href="#Go_1.18">Go 1.18</a>]. +Instantiation proceeds in two steps: +</p> + +<ol> +<li> +Each type argument is substituted for its corresponding type parameter in the generic +declaration. +This substitution happens across the entire function or type declaration, +including the type parameter list itself and any types in that list. +</li> + +<li> +After substitution, each type argument must <a href="#Satisfying_a_type_constraint">satisfy</a> +the <a href="#Type_parameter_declarations">constraint</a> (instantiated, if necessary) +of the corresponding type parameter. Otherwise instantiation fails. +</li> +</ol> + +<p> +Instantiating a type results in a new non-generic <a href="#Types">named type</a>; +instantiating a function produces a new non-generic function. +</p> + +<pre> +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 +</pre> + +<p> +When using a generic function, type arguments may be provided explicitly, +or they may be partially or completely <a href="#Type_inference">inferred</a> +from the context in which the function is used. +Provided that they can be inferred, type argument lists may be omitted entirely if the function is: +</p> + +<ul> +<li> + <a href="#Calls">called</a> with ordinary arguments, +</li> +<li> + <a href="#Assignment_statements">assigned</a> to a variable with a known type +</li> +<li> + <a href="#Calls">passed as an argument</a> to another function, or +</li> +<li> + <a href="#Return_statements">returned as a result</a>. +</li> +</ul> + +<p> +In all other cases, a (possibly partial) type argument list must be present. +If a type argument list is absent or partial, all missing type arguments +must be inferrable from the context in which the function is used. +</p> + +<pre> +// sum returns the sum (concatenation, for strings) of its arguments. +func sum[T ~int | ~float64 | ~string](x... T) T { … } + +x := sum // illegal: the type of x is unknown +intSum := sum[int] // intSum has type func(x... int) int +a := intSum(2, 3) // a has value 5 of type int +b := sum[float64](2.0, 3) // b has value 5.0 of type float64 +c := sum(b, -1) // c has value 4.0 of type float64 + +type sumFunc func(x... string) string +var f sumFunc = sum // same as var f sumFunc = sum[string] +f = sum // same as f = sum[string] +</pre> + +<p> +A partial type argument list cannot be empty; at least the first argument must be present. +The list is a prefix of the full list of type arguments, leaving the remaining arguments +to be inferred. Loosely speaking, type arguments may be omitted from "right to left". +</p> + +<pre> +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 +</pre> + +<p> +For a generic type, all type arguments must always be provided explicitly. +</p> + +<h3 id="Type_inference">Type inference</h3> + +<p> +A use of a generic function may omit some or all type arguments if they can be +<i>inferred</i> from the context within which the function is used, including +the constraints of the function's type parameters. +Type inference succeeds if it can infer the missing type arguments +and <a href="#Instantiations">instantiation</a> succeeds with the +inferred type arguments. +Otherwise, type inference fails and the program is invalid. +</p> + +<p> +Type inference uses the type relationships between pairs of types for inference: +For instance, a function argument must be <a href="#Assignability">assignable</a> +to its respective function parameter; this establishes a relationship between the +type of the argument and the type of the parameter. +If either of these two types contains type parameters, type inference looks for the +type arguments to substitute the type parameters with such that the assignability +relationship is satisfied. +Similarly, type inference uses the fact that a type argument must +<a href="#Satisfying_a_type_constraint">satisfy</a> the constraint of its respective +type parameter. +</p> + +<p> +Each such pair of matched types corresponds to a <i>type equation</i> containing +one or multiple type parameters, from one or possibly multiple generic functions. +Inferring the missing type arguments means solving the resulting set of type +equations for the respective type parameters. +</p> + +<p> +For example, given +</p> + +<pre> +// dedup returns a copy of the argument slice with any duplicate entries removed. +func dedup[S ~[]E, E comparable](S) S { … } + +type Slice []int +var s Slice +s = dedup(s) // same as s = dedup[Slice, int](s) +</pre> + +<p> +the variable <code>s</code> of type <code>Slice</code> must be assignable to +the function parameter type <code>S</code> for the program to be valid. +To reduce complexity, type inference ignores the directionality of assignments, +so the type relationship between <code>Slice</code> and <code>S</code> can be +expressed via the (symmetric) type equation <code>Slice ≡<sub>A</sub> S</code> +(or <code>S ≡<sub>A</sub> Slice</code> for that matter), +where the <code><sub>A</sub></code> in <code>≡<sub>A</sub></code> +indicates that the LHS and RHS types must match per assignability rules +(see the section on <a href="#Type_unification">type unification</a> for +details). +Similarly, the type parameter <code>S</code> must satisfy its constraint +<code>~[]E</code>. This can be expressed as <code>S ≡<sub>C</sub> ~[]E</code> +where <code>X ≡<sub>C</sub> Y</code> stands for +"<code>X</code> satisfies constraint <code>Y</code>". +These observations lead to a set of two equations +</p> + +<pre> + Slice ≡<sub>A</sub> S (1) + S ≡<sub>C</sub> ~[]E (2) +</pre> + +<p> +which now can be solved for the type parameters <code>S</code> and <code>E</code>. +From (1) a compiler can infer that the type argument for <code>S</code> is <code>Slice</code>. +Similarly, because the underlying type of <code>Slice</code> is <code>[]int</code> +and <code>[]int</code> must match <code>[]E</code> of the constraint, +a compiler can infer that <code>E</code> must be <code>int</code>. +Thus, for these two equations, type inference infers +</p> + +<pre> + S ➞ Slice + E ➞ int +</pre> + +<p> +Given a set of type equations, the type parameters to solve for are +the type parameters of the functions that need to be instantiated +and for which no explicit type arguments is provided. +These type parameters are called <i>bound</i> type parameters. +For instance, in the <code>dedup</code> example above, the type parameters +<code>S</code> and <code>E</code> are bound to <code>dedup</code>. +An argument to a generic function call may be a generic function itself. +The type parameters of that function are included in the set of bound +type parameters. +The types of function arguments may contain type parameters from other +functions (such as a generic function enclosing a function call). +Those type parameters may also appear in type equations but they are +not bound in that context. +Type equations are always solved for the bound type parameters only. +</p> + +<p> +Type inference supports calls of generic functions and assignments +of generic functions to (explicitly function-typed) variables. +This includes passing generic functions as arguments to other +(possibly also generic) functions, and returning generic functions +as results. +Type inference operates on a set of equations specific to each of +these cases. +The equations are as follows (type argument lists are omitted for clarity): +</p> + +<ul> +<li> + <p> + For a function call <code>f(a<sub>0</sub>, a<sub>1</sub>, …)</code> where + <code>f</code> or a function argument <code>a<sub>i</sub></code> is + a generic function: + <br> + Each pair <code>(a<sub>i</sub>, p<sub>i</sub>)</code> of corresponding + function arguments and parameters where <code>a<sub>i</sub></code> is not an + <a href="#Constants">untyped constant</a> yields an equation + <code>typeof(p<sub>i</sub>) ≡<sub>A</sub> typeof(a<sub>i</sub>)</code>. + <br> + If <code>a<sub>i</sub></code> is an untyped constant <code>c<sub>j</sub></code>, + and <code>typeof(p<sub>i</sub>)</code> is a bound type parameter <code>P<sub>k</sub></code>, + the pair <code>(c<sub>j</sub>, P<sub>k</sub>)</code> is collected separately from + the type equations. + </p> +</li> +<li> + <p> + For an assignment <code>v = f</code> of a generic function <code>f</code> to a + (non-generic) variable <code>v</code> of function type: + <br> + <code>typeof(v) ≡<sub>A</sub> typeof(f)</code>. + </p> +</li> +<li> + <p> + For a return statement <code>return …, f, … </code> where <code>f</code> is a + generic function returned as a result to a (non-generic) result variable + <code>r</code> of function type: + <br> + <code>typeof(r) ≡<sub>A</sub> typeof(f)</code>. + </p> +</li> +</ul> + +<p> +Additionally, each type parameter <code>P<sub>k</sub></code> and corresponding type constraint +<code>C<sub>k</sub></code> yields the type equation +<code>P<sub>k</sub> ≡<sub>C</sub> C<sub>k</sub></code>. +</p> + +<p> +Type inference gives precedence to type information obtained from typed operands +before considering untyped constants. +Therefore, inference proceeds in two phases: +</p> + +<ol> +<li> + <p> + The type equations are solved for the bound + type parameters using <a href="#Type_unification">type unification</a>. + If unification fails, type inference fails. + </p> +</li> +<li> + <p> + For each bound type parameter <code>P<sub>k</sub></code> for which no type argument + has been inferred yet and for which one or more pairs + <code>(c<sub>j</sub>, P<sub>k</sub>)</code> with that same type parameter + were collected, determine the <a href="#Constant_expressions">constant kind</a> + of the constants <code>c<sub>j</sub></code> in all those pairs the same way as for + <a href="#Constant_expressions">constant expressions</a>. + The type argument for <code>P<sub>k</sub></code> is the + <a href="#Constants">default type</a> for the determined constant kind. + If a constant kind cannot be determined due to conflicting constant kinds, + type inference fails. + </p> +</li> +</ol> + +<p> +If not all type arguments have been found after these two phases, type inference fails. +</p> + +<p> +If the two phases are successful, type inference determined a type argument for each +bound type parameter: +</p> + +<pre> + P<sub>k</sub> ➞ A<sub>k</sub> +</pre> + +<p> +A type argument <code>A<sub>k</sub></code> may be a composite type, +containing other bound type parameters <code>P<sub>k</sub></code> as element types +(or even be just another bound type parameter). +In a process of repeated simplification, the bound type parameters in each type +argument are substituted with the respective type arguments for those type +parameters until each type argument is free of bound type parameters. +</p> + +<p> +If type arguments contain cyclic references to themselves +through bound type parameters, simplification and thus type +inference fails. +Otherwise, type inference succeeds. +</p> + +<h4 id="Type_unification">Type unification</h4> + +<p> +Type inference solves type equations through <i>type unification</i>. +Type unification recursively compares the LHS and RHS types of an +equation, where either or both types may be or contain bound type parameters, +and looks for type arguments for those type parameters such that the LHS +and RHS match (become identical or assignment-compatible, depending on +context). +To that effect, type inference maintains a map of bound type parameters +to inferred type arguments; this map is consulted and updated during type unification. +Initially, the bound type parameters are known but the map is empty. +During type unification, if a new type argument <code>A</code> is inferred, +the respective mapping <code>P ➞ A</code> from type parameter to argument +is added to the map. +Conversely, when comparing types, a known type argument +(a type argument for which a map entry already exists) +takes the place of its corresponding type parameter. +As type inference progresses, the map is populated more and more +until all equations have been considered, or until unification fails. +Type inference succeeds if no unification step fails and the map has +an entry for each type parameter. +</p> + +<p> +For example, given the type equation with the bound type parameter +<code>P</code> +</p> + +<pre> + [10]struct{ elem P, list []P } ≡<sub>A</sub> [10]struct{ elem string; list []string } +</pre> + +<p> +type inference starts with an empty map. +Unification first compares the top-level structure of the LHS and RHS +types. +Both are arrays of the same length; they unify if the element types unify. +Both element types are structs; they unify if they have +the same number of fields with the same names and if the +field types unify. +The type argument for <code>P</code> is not known yet (there is no map entry), +so unifying <code>P</code> with <code>string</code> adds +the mapping <code>P ➞ string</code> to the map. +Unifying the types of the <code>list</code> field requires +unifying <code>[]P</code> and <code>[]string</code> and +thus <code>P</code> and <code>string</code>. +Since the type argument for <code>P</code> is known at this point +(there is a map entry for <code>P</code>), its type argument +<code>string</code> takes the place of <code>P</code>. +And since <code>string</code> is identical to <code>string</code>, +this unification step succeeds as well. +Unification of the LHS and RHS of the equation is now finished. +Type inference succeeds because there is only one type equation, +no unification step failed, and the map is fully populated. +</p> + +<p> +Unification uses a combination of <i>exact</i> and <i>loose</i> +unification depending on whether two types have to be +<a href="#Type_identity">identical</a>, +<a href="#Assignability">assignment-compatible</a>, or +only structurally equal. +The respective <a href="#Type_unification_rules">type unification rules</a> +are spelled out in detail in the <a href="#Appendix">Appendix</a>. +</p> + +<p> +For an equation of the form <code>X ≡<sub>A</sub> Y</code>, +where <code>X</code> and <code>Y</code> are types involved +in an assignment (including parameter passing and return statements), +the top-level type structures may unify loosely but element types +must unify exactly, matching the rules for assignments. +</p> + +<p> +For an equation of the form <code>P ≡<sub>C</sub> C</code>, +where <code>P</code> is a type parameter and <code>C</code> +its corresponding constraint, the unification rules are bit +more complicated: +</p> + +<ul> +<li> + If <code>C</code> has a <a href="#Core_types">core type</a> + <code>core(C)</code> + and <code>P</code> has a known type argument <code>A</code>, + <code>core(C)</code> and <code>A</code> must unify loosely. + If <code>P</code> does not have a known type argument + and <code>C</code> contains exactly one type term <code>T</code> + that is not an underlying (tilde) type, unification adds the + mapping <code>P ➞ T</code> to the map. +</li> +<li> + If <code>C</code> does not have a core type + and <code>P</code> has a known type argument <code>A</code>, + <code>A</code> must have all methods of <code>C</code>, if any, + and corresponding method types must unify exactly. +</li> +</ul> + +<p> +When solving type equations from type constraints, +solving one equation may infer additional type arguments, +which in turn may enable solving other equations that depend +on those type arguments. +Type inference repeats type unification as long as new type +arguments are inferred. +</p> + +<h3 id="Operators">Operators</h3> + +<p> +Operators combine operands into expressions. +</p> + +<pre class="ebnf"> +Expression = UnaryExpr | Expression binary_op Expression . +UnaryExpr = PrimaryExpr | unary_op UnaryExpr . + +binary_op = "||" | "&&" | rel_op | add_op | mul_op . +rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . +add_op = "+" | "-" | "|" | "^" . +mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . + +unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . +</pre> + +<p> +Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. +For other binary operators, the operand types must be <a href="#Type_identity">identical</a> +unless the operation involves shifts or untyped <a href="#Constants">constants</a>. +For operations involving constants only, see the section on +<a href="#Constant_expressions">constant expressions</a>. +</p> + +<p> +Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> +and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a> +to the type of the other operand. +</p> + +<p> +The right operand in a shift expression must have <a href="#Numeric_types">integer type</a> +[<a href="#Go_1.13">Go 1.13</a>] +or be an untyped constant <a href="#Representability">representable</a> by a +value of type <code>uint</code>. +If the left operand of a non-constant shift expression is an untyped constant, +it is first implicitly converted to the type it would assume if the shift expression were +replaced by its left operand alone. +</p> + +<pre> +var a [1024]byte +var s uint = 33 + +// The results of the following examples are given for 64-bit ints. +var i = 1<<s // 1 has type int +var j int32 = 1<<s // 1 has type int32; j == 0 +var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 +var m int = 1.0<<s // 1.0 has type int; m == 1<<33 +var n = 1.0<<s == j // 1.0 has type int32; n == true +var o = 1<<s == 2<<s // 1 and 2 have type int; o == false +var p = 1<<s == 1<<33 // 1 has type int; p == true +var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift +var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift +var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift +var v1 float32 = 1<<s // illegal: 1 has type float32, cannot shift +var v2 = string(1<<s) // illegal: 1 is converted to a string, cannot shift +var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression; w == 1<<33 +var x = a[1.0<<s] // panics: 1.0 has type int, but 1<<33 overflows array bounds +var b = make([]byte, 1.0<<s) // 1.0 has type int; len(b) == 1<<33 + +// The results of the following examples are given for 32-bit ints, +// which means the shifts will overflow. +var mm int = 1.0<<s // 1.0 has type int; mm == 0 +var oo = 1<<s == 2<<s // 1 and 2 have type int; oo == true +var pp = 1<<s == 1<<33 // illegal: 1 has type int, but 1<<33 overflows int +var xx = a[1.0<<s] // 1.0 has type int; xx == a[0] +var bb = make([]byte, 1.0<<s) // 1.0 has type int; len(bb) == 0 +</pre> + +<h4 id="Operator_precedence">Operator precedence</h4> +<p> +Unary operators have the highest precedence. +As the <code>++</code> and <code>--</code> operators form +statements, not expressions, they fall +outside the operator hierarchy. +As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. +</p> +<p> +There are five precedence levels for binary operators. +Multiplication operators bind strongest, followed by addition +operators, comparison operators, <code>&&</code> (logical AND), +and finally <code>||</code> (logical OR): +</p> + +<pre class="grammar"> +Precedence Operator + 5 * / % << >> & &^ + 4 + - | ^ + 3 == != < <= > >= + 2 && + 1 || +</pre> + +<p> +Binary operators of the same precedence associate from left to right. +For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. +</p> + +<pre> ++x // x +42 + a - b // (42 + a) - b +23 + 3*x[i] // 23 + (3 * x[i]) +x <= f() // x <= f() +^a >> b // (^a) >> b +f() || g() // f() || g() +x == y+1 && <-chanInt > 0 // (x == (y+1)) && ((<-chanInt) > 0) +</pre> + + +<h3 id="Arithmetic_operators">Arithmetic operators</h3> +<p> +Arithmetic operators apply to numeric values and yield a result of the same +type as the first operand. The four standard arithmetic operators (<code>+</code>, +<code>-</code>, <code>*</code>, <code>/</code>) apply to +<a href="#Numeric_types">integer</a>, <a href="#Numeric_types">floating-point</a>, and +<a href="#Numeric_types">complex</a> types; <code>+</code> also applies to <a href="#String_types">strings</a>. +The bitwise logical and shift operators apply to integers only. +</p> + +<pre class="grammar"> ++ sum integers, floats, complex values, strings +- difference integers, floats, complex values +* product integers, floats, complex values +/ quotient integers, floats, complex values +% remainder integers + +& bitwise AND integers +| bitwise OR integers +^ bitwise XOR integers +&^ bit clear (AND NOT) integers + +<< left shift integer << integer >= 0 +>> right shift integer >> integer >= 0 +</pre> + +<p> +If the operand type is a <a href="#Type_parameter_declarations">type parameter</a>, +the operator must apply to each type in that type set. +The operands are represented as values of the type argument that the type parameter +is <a href="#Instantiations">instantiated</a> with, and the operation is computed +with the precision of that type argument. For example, given the function: +</p> + +<pre> +func dotProduct[F ~float32|~float64](v1, v2 []F) F { + var s F + for i, x := range v1 { + y := v2[i] + s += x * y + } + return s +} +</pre> + +<p> +the product <code>x * y</code> and the addition <code>s += x * y</code> +are computed with <code>float32</code> or <code>float64</code> precision, +respectively, depending on the type argument for <code>F</code>. +</p> + +<h4 id="Integer_operators">Integer operators</h4> + +<p> +For two integer values <code>x</code> and <code>y</code>, the integer quotient +<code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following +relationships: +</p> + +<pre> +x = q*y + r and |r| < |y| +</pre> + +<p> +with <code>x / y</code> truncated towards zero +(<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). +</p> + +<pre> + x y x / y x % y + 5 3 1 2 +-5 3 -1 -2 + 5 -3 -1 2 +-5 -3 1 -2 +</pre> + +<p> +The one exception to this rule is that if the dividend <code>x</code> is +the most negative value for the int type of <code>x</code>, the quotient +<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) +due to two's-complement <a href="#Integer_overflow">integer overflow</a>: +</p> + +<pre> + x, q +int8 -128 +int16 -32768 +int32 -2147483648 +int64 -9223372036854775808 +</pre> + +<p> +If the divisor is a <a href="#Constants">constant</a>, it must not be zero. +If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. +If the dividend is non-negative and the divisor is a constant power of 2, +the division may be replaced by a right shift, and computing the remainder may +be replaced by a bitwise AND operation: +</p> + +<pre> + x x / 4 x % 4 x >> 2 x & 3 + 11 2 3 2 3 +-11 -2 -3 -3 1 +</pre> + +<p> +The shift operators shift the left operand by the shift count specified by the +right operand, which must be non-negative. If the shift count is negative at run time, +a <a href="#Run_time_panics">run-time panic</a> occurs. +The shift operators implement arithmetic shifts if the left operand is a signed +integer and logical shifts if it is an unsigned integer. +There is no upper limit on the shift count. Shifts behave +as if the left operand is shifted <code>n</code> times by 1 for a shift +count of <code>n</code>. +As a result, <code>x << 1</code> is the same as <code>x*2</code> +and <code>x >> 1</code> is the same as +<code>x/2</code> but truncated towards negative infinity. +</p> + +<p> +For integer operands, the unary operators +<code>+</code>, <code>-</code>, and <code>^</code> are defined as +follows: +</p> + +<pre class="grammar"> ++x is 0 + x +-x negation is 0 - x +^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x + and m = -1 for signed x +</pre> + + +<h4 id="Integer_overflow">Integer overflow</h4> + +<p> +For <a href="#Numeric_types">unsigned integer</a> values, the operations <code>+</code>, +<code>-</code>, <code>*</code>, and <code><<</code> are +computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of +the unsigned integer's type. +Loosely speaking, these unsigned integer operations +discard high bits upon overflow, and programs may rely on "wrap around". +</p> + +<p> +For signed integers, the operations <code>+</code>, +<code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally +overflow and the resulting value exists and is deterministically defined +by the signed integer representation, the operation, and its operands. +Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>. +A compiler may not optimize code under the assumption that overflow does +not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. +</p> + +<h4 id="Floating_point_operators">Floating-point operators</h4> + +<p> +For floating-point and complex numbers, +<code>+x</code> is the same as <code>x</code>, +while <code>-x</code> is the negation of <code>x</code>. +The result of a floating-point or complex division by zero is not specified beyond the +IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> +occurs is implementation-specific. +</p> + +<p> +An implementation may combine multiple floating-point operations into a single +fused operation, possibly across statements, and produce a result that differs +from the value obtained by executing and rounding the instructions individually. +An explicit <a href="#Numeric_types">floating-point type</a> <a href="#Conversions">conversion</a> rounds to +the precision of the target type, preventing fusion that would discard that rounding. +</p> + +<p> +For instance, some architectures provide a "fused multiply and add" (FMA) instruction +that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>. +These examples show when a Go implementation can use that instruction: +</p> + +<pre> +// FMA allowed for computing r, because x*y is not explicitly rounded: +r = x*y + z +r = z; r += x*y +t = x*y; r = t + z +*p = x*y; r = *p + z +r = x*y + float64(z) + +// FMA disallowed for computing r, because it would omit rounding of x*y: +r = float64(x*y) + z +r = z; r += float64(x*y) +t = float64(x*y); r = t + z +</pre> + +<h4 id="String_concatenation">String concatenation</h4> + +<p> +Strings can be concatenated using the <code>+</code> operator +or the <code>+=</code> assignment operator: +</p> + +<pre> +s := "hi" + string(c) +s += " and good bye" +</pre> + +<p> +String addition creates a new string by concatenating the operands. +</p> + +<h3 id="Comparison_operators">Comparison operators</h3> + +<p> +Comparison operators compare two operands and yield an untyped boolean value. +</p> + +<pre class="grammar"> +== equal +!= not equal +< less +<= less or equal +> greater +>= greater or equal +</pre> + +<p> +In any comparison, the first operand +must be <a href="#Assignability">assignable</a> +to the type of the second operand, or vice versa. +</p> +<p> +The equality operators <code>==</code> and <code>!=</code> apply +to operands of <i>comparable</i> types. +The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> +apply to operands of <i>ordered</i> types. +These terms and the result of the comparisons are defined as follows: +</p> + +<ul> + <li> + Boolean types are comparable. + Two boolean values are equal if they are either both + <code>true</code> or both <code>false</code>. + </li> + + <li> + Integer types are comparable and ordered. + Two integer values are compared in the usual way. + </li> + + <li> + Floating-point types are comparable and ordered. + Two floating-point values are compared as defined by the IEEE-754 standard. + </li> + + <li> + Complex types are comparable. + Two complex values <code>u</code> and <code>v</code> are + equal if both <code>real(u) == real(v)</code> and + <code>imag(u) == imag(v)</code>. + </li> + + <li> + String types are comparable and ordered. + Two string values are compared lexically byte-wise. + </li> + + <li> + Pointer types are comparable. + Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>. + Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal. + </li> + + <li> + Channel types are comparable. + Two channel values are equal if they were created by the same call to + <a href="#Making_slices_maps_and_channels"><code>make</code></a> + or if both have value <code>nil</code>. + </li> + + <li> + Interface types that are not type parameters are comparable. + Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types + and equal dynamic values or if both have value <code>nil</code>. + </li> + + <li> + A value <code>x</code> of non-interface type <code>X</code> and + a value <code>t</code> of interface type <code>T</code> can be compared + if type <code>X</code> is comparable and + <code>X</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>. + They are equal if <code>t</code>'s dynamic type is identical to <code>X</code> + and <code>t</code>'s dynamic value is equal to <code>x</code>. + </li> + + <li> + Struct types are comparable if all their field types are comparable. + Two struct values are equal if their corresponding + non-<a href="#Blank_identifier">blank</a> field values are equal. + The fields are compared in source order, and comparison stops as + soon as two field values differ (or all fields have been compared). + </li> + + <li> + Array types are comparable if their array element types are comparable. + Two array values are equal if their corresponding element values are equal. + The elements are compared in ascending index order, and comparison stops + as soon as two element values differ (or all elements have been compared). + </li> + + <li> + Type parameters are comparable if they are strictly comparable (see below). + </li> +</ul> + +<p> +A comparison of two interface values with identical dynamic types +causes a <a href="#Run_time_panics">run-time panic</a> if that type +is not comparable. This behavior applies not only to direct interface +value comparisons but also when comparing arrays of interface values +or structs with interface-valued fields. +</p> + +<p> +Slice, map, and function types are not comparable. +However, as a special case, a slice, map, or function value may +be compared to the predeclared identifier <code>nil</code>. +Comparison of pointer, channel, and interface values to <code>nil</code> +is also allowed and follows from the general rules above. +</p> + +<pre> +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 +) +</pre> + +<p> +A type is <i>strictly comparable</i> if it is comparable and not an interface +type nor composed of interface types. +Specifically: +</p> + +<ul> + <li> + Boolean, numeric, string, pointer, and channel types are strictly comparable. + </li> + + <li> + Struct types are strictly comparable if all their field types are strictly comparable. + </li> + + <li> + Array types are strictly comparable if their array element types are strictly comparable. + </li> + + <li> + Type parameters are strictly comparable if all types in their type set are strictly comparable. + </li> +</ul> + +<h3 id="Logical_operators">Logical operators</h3> + +<p> +Logical operators apply to <a href="#Boolean_types">boolean</a> values +and yield a result of the same type as the operands. +The left operand is evaluated, and then the right if the condition requires it. +</p> + +<pre class="grammar"> +&& 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" +</pre> + + +<h3 id="Address_operators">Address operators</h3> + +<p> +For an operand <code>x</code> of type <code>T</code>, the address operation +<code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. +The operand must be <i>addressable</i>, +that is, either a variable, pointer indirection, or slice indexing +operation; or a field selector of an addressable struct operand; +or an array indexing operation of an addressable array. +As an exception to the addressability requirement, <code>x</code> may also be a +(possibly parenthesized) +<a href="#Composite_literals">composite literal</a>. +If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, +then the evaluation of <code>&x</code> does too. +</p> + +<p> +For an operand <code>x</code> of pointer type <code>*T</code>, the pointer +indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed +to by <code>x</code>. +If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> +will cause a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<pre> +&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 +</pre> + + +<h3 id="Receive_operator">Receive operator</h3> + +<p> +For an operand <code>ch</code> whose <a href="#Core_types">core type</a> is a +<a href="#Channel_types">channel</a>, +the value of the receive operation <code><-ch</code> is the value received +from the channel <code>ch</code>. The channel direction must permit receive operations, +and the type of the receive operation is the element type of the channel. +The expression blocks until a value is available. +Receiving from a <code>nil</code> channel blocks forever. +A receive operation on a <a href="#Close">closed</a> channel can always proceed +immediately, yielding the element type's <a href="#The_zero_value">zero value</a> +after any previously sent values have been received. +</p> + +<pre> +v1 := <-ch +v2 = <-ch +f(<-ch) +<-strobe // wait until clock pulse and discard received value +</pre> + +<p> +A receive expression used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form +</p> + +<pre> +x, ok = <-ch +x, ok := <-ch +var x, ok = <-ch +var x, ok T = <-ch +</pre> + +<p> +yields an additional untyped boolean result reporting whether the +communication succeeded. The value of <code>ok</code> is <code>true</code> +if the value received was delivered by a successful send operation to the +channel, or <code>false</code> if it is a zero value generated because the +channel is closed and empty. +</p> + + +<h3 id="Conversions">Conversions</h3> + +<p> +A conversion changes the <a href="#Types">type</a> of an expression +to the type specified by the conversion. +A conversion may appear literally in the source, or it may be <i>implied</i> +by the context in which an expression appears. +</p> + +<p> +An <i>explicit</i> conversion is an expression of the form <code>T(x)</code> +where <code>T</code> is a type and <code>x</code> is an expression +that can be converted to type <code>T</code>. +</p> + +<pre class="ebnf"> +Conversion = Type "(" Expression [ "," ] ")" . +</pre> + +<p> +If the type starts with the operator <code>*</code> or <code><-</code>, +or if the type starts with the keyword <code>func</code> +and has no result list, it must be parenthesized when +necessary to avoid ambiguity: +</p> + +<pre> +*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) +</pre> + +<p> +A <a href="#Constants">constant</a> value <code>x</code> can be converted to +type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a> +by a value of <code>T</code>. +As a special case, an integer constant <code>x</code> can be explicitly converted to a +<a href="#String_types">string type</a> using the +<a href="#Conversions_to_and_from_a_string_type">same rule</a> +as for non-constant <code>x</code>. +</p> + +<p> +Converting a constant to a type that is not a <a href="#Type_parameter_declarations">type parameter</a> +yields a typed constant. +</p> + +<pre> +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 +</pre> + +<p> +Converting a constant to a type parameter yields a <i>non-constant</i> value of that type, +with the value represented as a value of the type argument that the type parameter +is <a href="#Instantiations">instantiated</a> with. +For example, given the function: +</p> + +<pre> +func f[P ~float32|~float64]() { + … P(1.1) … +} +</pre> + +<p> +the conversion <code>P(1.1)</code> results in a non-constant value of type <code>P</code> +and the value <code>1.1</code> is represented as a <code>float32</code> or a <code>float64</code> +depending on the type argument for <code>f</code>. +Accordingly, if <code>f</code> is instantiated with a <code>float32</code> type, +the numeric value of the expression <code>P(1.1) + 1.2</code> will be computed +with the same precision as the corresponding non-constant <code>float32</code> +addition. +</p> + +<p> +A non-constant value <code>x</code> can be converted to type <code>T</code> +in any of these cases: +</p> + +<ul> + <li> + <code>x</code> is <a href="#Assignability">assignable</a> + to <code>T</code>. + </li> + <li> + ignoring struct tags (see below), + <code>x</code>'s type and <code>T</code> are not + <a href="#Type_parameter_declarations">type parameters</a> but have + <a href="#Type_identity">identical</a> <a href="#Underlying_types">underlying types</a>. + </li> + <li> + ignoring struct tags (see below), + <code>x</code>'s type and <code>T</code> are pointer types + that are not <a href="#Types">named types</a>, + and their pointer base types are not type parameters but + have identical underlying types. + </li> + <li> + <code>x</code>'s type and <code>T</code> are both integer or floating + point types. + </li> + <li> + <code>x</code>'s type and <code>T</code> are both complex types. + </li> + <li> + <code>x</code> is an integer or a slice of bytes or runes + and <code>T</code> is a string type. + </li> + <li> + <code>x</code> is a string and <code>T</code> is a slice of bytes or runes. + </li> + <li> + <code>x</code> is a slice, <code>T</code> is an array [<a href="#Go_1.20">Go 1.20</a>] + or a pointer to an array [<a href="#Go_1.17">Go 1.17</a>], + and the slice and array types have <a href="#Type_identity">identical</a> element types. + </li> +</ul> + +<p> +Additionally, if <code>T</code> or <code>x</code>'s type <code>V</code> are type +parameters, <code>x</code> +can also be converted to type <code>T</code> if one of the following conditions applies: +</p> + +<ul> +<li> +Both <code>V</code> and <code>T</code> are type parameters and a value of each +type in <code>V</code>'s type set can be converted to each type in <code>T</code>'s +type set. +</li> +<li> +Only <code>V</code> is a type parameter and a value of each +type in <code>V</code>'s type set can be converted to <code>T</code>. +</li> +<li> +Only <code>T</code> is a type parameter and <code>x</code> can be converted to each +type in <code>T</code>'s type set. +</li> +</ul> + +<p> +<a href="#Struct_types">Struct tags</a> are ignored when comparing struct types +for identity for the purpose of conversion: +</p> + +<pre> +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 +</pre> + +<p> +Specific rules apply to (non-constant) conversions between numeric types or +to and from a string type. +These conversions may change the representation of <code>x</code> +and incur a run-time cost. +All other conversions only change the type but not the representation +of <code>x</code>. +</p> + +<p> +There is no linguistic mechanism to convert between pointers and integers. +The package <a href="#Package_unsafe"><code>unsafe</code></a> +implements this functionality under restricted circumstances. +</p> + +<h4>Conversions between numeric types</h4> + +<p> +For the conversion of non-constant numeric values, the following rules apply: +</p> + +<ol> +<li> +When converting between <a href="#Numeric_types">integer types</a>, if the value is a signed integer, it is +sign extended to implicit infinite precision; otherwise it is zero extended. +It is then truncated to fit in the result type's size. +For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>. +The conversion always yields a valid value; there is no indication of overflow. +</li> +<li> +When converting a <a href="#Numeric_types">floating-point number</a> to an integer, the fraction is discarded +(truncation towards zero). +</li> +<li> +When converting an integer or floating-point number to a floating-point type, +or a <a href="#Numeric_types">complex number</a> to another complex type, the result value is rounded +to the precision specified by the destination type. +For instance, the value of a variable <code>x</code> of type <code>float32</code> +may be stored using additional precision beyond that of an IEEE-754 32-bit number, +but float32(x) represents the result of rounding <code>x</code>'s value to +32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits +of precision, but <code>float32(x + 0.1)</code> does not. +</li> +</ol> + +<p> +In all non-constant conversions involving floating-point or complex values, +if the result type cannot represent the value the conversion +succeeds but the result value is implementation-dependent. +</p> + +<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4> + +<ol> +<li> +Converting a slice of bytes to a string type yields +a string whose successive bytes are the elements of the slice. + +<pre> +string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" +string([]byte{}) // "" +string([]byte(nil)) // "" + +type bytes []byte +string(bytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" + +type myByte byte +string([]myByte{'w', 'o', 'r', 'l', 'd', '!'}) // "world!" +myString([]myByte{'\xf0', '\x9f', '\x8c', '\x8d'}) // "🌍" +</pre> +</li> + +<li> +Converting a slice of runes to a string type yields +a string that is the concatenation of the individual rune values +converted to strings. + +<pre> +string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" +string([]rune{}) // "" +string([]rune(nil)) // "" + +type runes []rune +string(runes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" + +type myRune rune +string([]myRune{0x266b, 0x266c}) // "\u266b\u266c" == "♫♬" +myString([]myRune{0x1f30e}) // "\U0001f30e" == "🌎" +</pre> +</li> + +<li> +Converting a value of a string type to a slice of bytes type +yields a non-nil slice whose successive elements are the bytes of the string. + +<pre> +[]byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} +[]byte("") // []byte{} + +bytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} + +[]myByte("world!") // []myByte{'w', 'o', 'r', 'l', 'd', '!'} +[]myByte(myString("🌏")) // []myByte{'\xf0', '\x9f', '\x8c', '\x8f'} +</pre> +</li> + +<li> +Converting a value of a string type to a slice of runes type +yields a slice containing the individual Unicode code points of the string. + +<pre> +[]rune(myString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4} +[]rune("") // []rune{} + +runes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4} + +[]myRune("♫♬") // []myRune{0x266b, 0x266c} +[]myRune(myString("🌐")) // []myRune{0x1f310} +</pre> +</li> + +<li> +Finally, for historical reasons, an integer value may be converted to a string type. +This form of conversion yields a string containing the (possibly multi-byte) UTF-8 +representation of the Unicode code point with the given integer value. +Values outside the range of valid Unicode code points are converted to <code>"\uFFFD"</code>. + +<pre> +string('a') // "a" +string(65) // "A" +string('\xf8') // "\u00f8" == "ø" == "\xc3\xb8" +string(-1) // "\ufffd" == "\xef\xbf\xbd" + +type myString string +myString('\u65e5') // "\u65e5" == "日" == "\xe6\x97\xa5" +</pre> + +Note: This form of conversion may eventually be removed from the language. +The <a href="/pkg/cmd/vet"><code>go vet</code></a> tool flags certain +integer-to-string conversions as potential errors. +Library functions such as +<a href="/pkg/unicode/utf8#AppendRune"><code>utf8.AppendRune</code></a> or +<a href="/pkg/unicode/utf8#EncodeRune"><code>utf8.EncodeRune</code></a> +should be used instead. +</li> +</ol> + +<h4 id="Conversions_from_slice_to_array_or_array_pointer">Conversions from slice to array or array pointer</h4> + +<p> +Converting a slice to an array yields an array containing the elements of the underlying array of the slice. +Similarly, converting a slice to an array pointer yields a pointer to the underlying array of the slice. +In both cases, if the <a href="#Length_and_capacity">length</a> of the slice is less than the length of the array, +a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<pre> +s := make([]byte, 2, 4) + +a0 := [0]byte(s) +a1 := [1]byte(s[1:]) // a1[0] == s[1] +a2 := [2]byte(s) // a2[0] == s[0] +a4 := [4]byte(s) // panics: len([4]byte) > len(s) + +s0 := (*[0]byte)(s) // s0 != nil +s1 := (*[1]byte)(s[1:]) // &s1[0] == &s[1] +s2 := (*[2]byte)(s) // &s2[0] == &s[0] +s4 := (*[4]byte)(s) // panics: len([4]byte) > len(s) + +var t []string +t0 := [0]string(t) // ok for nil slice t +t1 := (*[0]string)(t) // t1 == nil +t2 := (*[1]string)(t) // panics: len([1]string) > len(t) + +u := make([]byte, 0) +u0 := (*[0]byte)(u) // u0 != nil +</pre> + +<h3 id="Constant_expressions">Constant expressions</h3> + +<p> +Constant expressions may contain only <a href="#Constants">constant</a> +operands and are evaluated at compile time. +</p> + +<p> +Untyped boolean, numeric, and string constants may be used as operands +wherever it is legal to use an operand of boolean, numeric, or string type, +respectively. +</p> + +<p> +A constant <a href="#Comparison_operators">comparison</a> always yields +an untyped boolean constant. If the left operand of a constant +<a href="#Operators">shift expression</a> is an untyped constant, the +result is an integer constant; otherwise it is a constant of the same +type as the left operand, which must be of +<a href="#Numeric_types">integer type</a>. +</p> + +<p> +Any other operation on untyped constants results in an untyped constant of the +same kind; that is, a boolean, integer, floating-point, complex, or string +constant. +If the untyped operands of a binary operation (other than a shift) are of +different kinds, the result is of the operand's kind that appears later in this +list: integer, rune, floating-point, complex. +For example, an untyped integer constant divided by an +untyped complex constant yields an untyped complex constant. +</p> + +<pre> +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 Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division) +const d = 1 << 3.0 // d == 8 (untyped integer constant) +const e = 1.0 << 3 // e == 8 (untyped integer constant) +const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32) +const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) +const h = "foo" > "bar" // h == true (untyped boolean constant) +const j = true // j == true (untyped boolean constant) +const k = 'w' + 1 // k == 'x' (untyped rune constant) +const l = "hi" // l == "hi" (untyped string constant) +const m = string(k) // m == "x" (type string) +const Σ = 1 - 0.707i // (untyped complex constant) +const Δ = Σ + 2.0e-4 // (untyped complex constant) +const Φ = iota*1i - 1/1i // (untyped complex constant) +</pre> + +<p> +Applying the built-in function <code>complex</code> to untyped +integer, rune, or floating-point constants yields +an untyped complex constant. +</p> + +<pre> +const ic = complex(0, c) // ic == 3.75i (untyped complex constant) +const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) +</pre> + +<p> +Constant expressions are always evaluated exactly; intermediate values and the +constants themselves may require precision significantly larger than supported +by any predeclared type in the language. The following are legal declarations: +</p> + +<pre> +const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant) +const Four int8 = Huge >> 98 // Four == 4 (type int8) +</pre> + +<p> +The divisor of a constant division or remainder operation must not be zero: +</p> + +<pre> +3.14 / 0.0 // illegal: division by zero +</pre> + +<p> +The values of <i>typed</i> constants must always be accurately +<a href="#Representability">representable</a> by values +of the constant type. The following constant expressions are illegal: +</p> + +<pre> +uint(-1) // -1 cannot be represented as a uint +int(3.14) // 3.14 cannot be represented as an int +int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64 +Four * 300 // operand 300 cannot be represented as an int8 (type of Four) +Four * 100 // product 400 cannot be represented as an int8 (type of Four) +</pre> + +<p> +The mask used by the unary bitwise complement operator <code>^</code> matches +the rule for non-constants: the mask is all 1s for unsigned constants +and -1 for signed and untyped constants. +</p> + +<pre> +^1 // untyped integer constant, equal to -2 +uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8 +^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) +int8(^1) // same as int8(-2) +^int8(1) // same as -1 ^ int8(1) = -2 +</pre> + +<p> +Implementation restriction: A compiler may use rounding while +computing untyped floating-point or complex constant expressions; see +the implementation restriction in the section +on <a href="#Constants">constants</a>. This rounding may cause a +floating-point constant expression to be invalid in an integer +context, even if it would be integral when calculated using infinite +precision, and vice versa. +</p> + + +<h3 id="Order_of_evaluation">Order of evaluation</h3> + +<p> +At package level, <a href="#Package_initialization">initialization dependencies</a> +determine the evaluation order of individual initialization expressions in +<a href="#Variable_declarations">variable declarations</a>. +Otherwise, when evaluating the <a href="#Operands">operands</a> of an +expression, assignment, or +<a href="#Return_statements">return statement</a>, +all function calls, method calls, +<a href="#Receive operator">receive operations</a>, +and <a href="#Logical_operators">binary logical operations</a> +are evaluated in lexical left-to-right order. +</p> + +<p> +For example, in the (function-local) assignment +</p> +<pre> +y[f()], ok = g(z || h(), i()+x[j()], <-c), k() +</pre> +<p> +the function calls and communication happen in the order +<code>f()</code>, <code>h()</code> (if <code>z</code> +evaluates to false), <code>i()</code>, <code>j()</code>, +<code><-c</code>, <code>g()</code>, and <code>k()</code>. +However, the order of those events compared to the evaluation +and indexing of <code>x</code> and the evaluation +of <code>y</code> and <code>z</code> is not specified, +except as required lexically. For instance, <code>g</code> +cannot be called before its arguments are evaluated. +</p> + +<pre> +a := 1 +f := func() int { a++; return a } +x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified +m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified +n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified +</pre> + +<p> +At package level, initialization dependencies override the left-to-right rule +for individual initialization expressions, but not for operands within each +expression: +</p> + +<pre> +var a, b, c = f() + v(), g(), sqr(u()) + v() + +func f() int { return c } +func g() int { return a } +func sqr(x int) int { return x*x } + +// functions u and v are independent of all other variables and functions +</pre> + +<p> +The function calls happen in the order +<code>u()</code>, <code>sqr()</code>, <code>v()</code>, +<code>f()</code>, <code>v()</code>, and <code>g()</code>. +</p> + +<p> +Floating-point operations within a single expression are evaluated according to +the associativity of the operators. Explicit parentheses affect the evaluation +by overriding the default associativity. +In the expression <code>x + (y + z)</code> the addition <code>y + z</code> +is performed before adding <code>x</code>. +</p> + +<h2 id="Statements">Statements</h2> + +<p> +Statements control execution. +</p> + +<pre class="ebnf"> +Statement = + Declaration | LabeledStmt | SimpleStmt | + GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | + FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | + DeferStmt . + +SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . +</pre> + +<h3 id="Terminating_statements">Terminating statements</h3> + +<p> +A <i>terminating statement</i> interrupts the regular flow of control in +a <a href="#Blocks">block</a>. The following statements are terminating: +</p> + +<ol> +<li> + A <a href="#Return_statements">"return"</a> or + <a href="#Goto_statements">"goto"</a> statement. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + A call to the built-in function + <a href="#Handling_panics"><code>panic</code></a>. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement. + <!-- ul below only for regular layout --> + <ul> </ul> +</li> + +<li> + An <a href="#If_statements">"if" statement</a> in which: + <ul> + <li>the "else" branch is present, and</li> + <li>both branches are terminating statements.</li> + </ul> +</li> + +<li> + A <a href="#For_statements">"for" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "for" statement, and</li> + <li>the loop condition is absent, and</li> + <li>the "for" statement does not use a range clause.</li> + </ul> +</li> + +<li> + A <a href="#Switch_statements">"switch" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "switch" statement,</li> + <li>there is a default case, and</li> + <li>the statement lists in each case, including the default, end in a terminating + statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough" + statement</a>.</li> + </ul> +</li> + +<li> + A <a href="#Select_statements">"select" statement</a> in which: + <ul> + <li>there are no "break" statements referring to the "select" statement, and</li> + <li>the statement lists in each case, including the default if present, + end in a terminating statement.</li> + </ul> +</li> + +<li> + A <a href="#Labeled_statements">labeled statement</a> labeling + a terminating statement. +</li> +</ol> + +<p> +All other statements are not terminating. +</p> + +<p> +A <a href="#Blocks">statement list</a> ends in a terminating statement if the list +is not empty and its final non-empty statement is terminating. +</p> + + +<h3 id="Empty_statements">Empty statements</h3> + +<p> +The empty statement does nothing. +</p> + +<pre class="ebnf"> +EmptyStmt = . +</pre> + + +<h3 id="Labeled_statements">Labeled statements</h3> + +<p> +A labeled statement may be the target of a <code>goto</code>, +<code>break</code> or <code>continue</code> statement. +</p> + +<pre class="ebnf"> +LabeledStmt = Label ":" Statement . +Label = identifier . +</pre> + +<pre> +Error: log.Panic("error encountered") +</pre> + + +<h3 id="Expression_statements">Expression statements</h3> + +<p> +With the exception of specific built-in functions, +function and method <a href="#Calls">calls</a> and +<a href="#Receive_operator">receive operations</a> +can appear in statement context. Such statements may be parenthesized. +</p> + +<pre class="ebnf"> +ExpressionStmt = Expression . +</pre> + +<p> +The following built-in functions are not permitted in statement context: +</p> + +<pre> +append cap complex imag len make new real +unsafe.Add unsafe.Alignof unsafe.Offsetof unsafe.Sizeof unsafe.Slice unsafe.SliceData unsafe.String unsafe.StringData +</pre> + +<pre> +h(x+y) +f.Close() +<-ch +(<-ch) +len("foo") // illegal if len is the built-in function +</pre> + + +<h3 id="Send_statements">Send statements</h3> + +<p> +A send statement sends a value on a channel. +The channel expression's <a href="#Core_types">core type</a> +must be a <a href="#Channel_types">channel</a>, +the channel direction must permit send operations, +and the type of the value to be sent must be <a href="#Assignability">assignable</a> +to the channel's element type. +</p> + +<pre class="ebnf"> +SendStmt = Channel "<-" Expression . +Channel = Expression . +</pre> + +<p> +Both the channel and the value expression are evaluated before communication +begins. Communication blocks until the send can proceed. +A send on an unbuffered channel can proceed if a receiver is ready. +A send on a buffered channel can proceed if there is room in the buffer. +A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>. +A send on a <code>nil</code> channel blocks forever. +</p> + +<pre> +ch <- 3 // send value 3 to channel ch +</pre> + + +<h3 id="IncDec_statements">IncDec statements</h3> + +<p> +The "++" and "--" statements increment or decrement their operands +by the untyped <a href="#Constants">constant</a> <code>1</code>. +As with an assignment, the operand must be <a href="#Address_operators">addressable</a> +or a map index expression. +</p> + +<pre class="ebnf"> +IncDecStmt = Expression ( "++" | "--" ) . +</pre> + +<p> +The following <a href="#Assignment_statements">assignment statements</a> are semantically +equivalent: +</p> + +<pre class="grammar"> +IncDec statement Assignment +x++ x += 1 +x-- x -= 1 +</pre> + + +<h3 id="Assignment_statements">Assignment statements</h3> + +<p> +An <i>assignment</i> replaces the current value stored in a <a href="#Variables">variable</a> +with a new value specified by an <a href="#Expressions">expression</a>. +An assignment statement may assign a single value to a single variable, or multiple values to a +matching number of variables. +</p> + +<pre class="ebnf"> +Assignment = ExpressionList assign_op ExpressionList . + +assign_op = [ add_op | mul_op ] "=" . +</pre> + +<p> +Each left-hand side operand must be <a href="#Address_operators">addressable</a>, +a map index expression, or (for <code>=</code> assignments only) the +<a href="#Blank_identifier">blank identifier</a>. +Operands may be parenthesized. +</p> + +<pre> +x = 1 +*p = f() +a[i] = 23 +(k) = <-ch // same as: k = <-ch +</pre> + +<p> +An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code> +<code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a> +is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i> +<code>(y)</code> but evaluates <code>x</code> +only once. The <i>op</i><code>=</code> construct is a single token. +In assignment operations, both the left- and right-hand expression lists +must contain exactly one single-valued expression, and the left-hand +expression must not be the blank identifier. +</p> + +<pre> +a[i] <<= 2 +i &^= 1<<n +</pre> + +<p> +A tuple assignment assigns the individual elements of a multi-valued +operation to a list of variables. There are two forms. In the +first, the right hand operand is a single multi-valued expression +such as a function call, a <a href="#Channel_types">channel</a> or +<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. +The number of operands on the left +hand side must match the number of values. For instance, if +<code>f</code> is a function returning two values, +</p> + +<pre> +x, y = f() +</pre> + +<p> +assigns the first value to <code>x</code> and the second to <code>y</code>. +In the second form, the number of operands on the left must equal the number +of expressions on the right, each of which must be single-valued, and the +<i>n</i>th expression on the right is assigned to the <i>n</i>th +operand on the left: +</p> + +<pre> +one, two, three = '一', '二', '三' +</pre> + +<p> +The <a href="#Blank_identifier">blank identifier</a> provides a way to +ignore right-hand side values in an assignment: +</p> + +<pre> +_ = x // evaluate x but ignore it +x, _ = f() // evaluate f() but ignore second result value +</pre> + +<p> +The assignment proceeds in two phases. +First, the operands of <a href="#Index_expressions">index expressions</a> +and <a href="#Address_operators">pointer indirections</a> +(including implicit pointer indirections in <a href="#Selectors">selectors</a>) +on the left and the expressions on the right are all +<a href="#Order_of_evaluation">evaluated in the usual order</a>. +Second, the assignments are carried out in left-to-right order. +</p> + +<pre> +a, b = b, a // exchange a and b + +x := []int{1, 2, 3} +i := 0 +i, x[i] = 1, 2 // set i = 1, x[0] = 2 + +i = 0 +x[i], i = 2, 1 // set x[0] = 2, i = 1 + +x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end) + +x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5. + +type Point struct { x, y int } +var p *Point +x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7 + +i = 2 +x = []int{3, 5, 7} +for i, x[i] = range x { // set i, x[2] = 0, x[0] + break +} +// after this loop, i == 0 and x is []int{3, 5, 3} +</pre> + +<p> +In assignments, each value must be <a href="#Assignability">assignable</a> +to the type of the operand to which it is assigned, with the following special cases: +</p> + +<ol> +<li> + Any typed value may be assigned to the blank identifier. +</li> + +<li> + If an untyped constant + is assigned to a variable of interface type or the blank identifier, + the constant is first implicitly <a href="#Conversions">converted</a> to its + <a href="#Constants">default type</a>. +</li> + +<li> + If an untyped boolean value is assigned to a variable of interface type or + the blank identifier, it is first implicitly converted to type <code>bool</code>. +</li> +</ol> + +<h3 id="If_statements">If statements</h3> + +<p> +"If" statements specify the conditional execution of two branches +according to the value of a boolean expression. If the expression +evaluates to true, the "if" branch is executed, otherwise, if +present, the "else" branch is executed. +</p> + +<pre class="ebnf"> +IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] . +</pre> + +<pre> +if x > max { + x = max +} +</pre> + +<p> +The expression may be preceded by a simple statement, which +executes before the expression is evaluated. +</p> + +<pre> +if x := f(); x < y { + return x +} else if x > z { + return z +} else { + return y +} +</pre> + + +<h3 id="Switch_statements">Switch statements</h3> + +<p> +"Switch" statements provide multi-way execution. +An expression or type is compared to the "cases" +inside the "switch" to determine which branch +to execute. +</p> + +<pre class="ebnf"> +SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . +</pre> + +<p> +There are two forms: expression switches and type switches. +In an expression switch, the cases contain expressions that are compared +against the value of the switch expression. +In a type switch, the cases contain types that are compared against the +type of a specially annotated switch expression. +The switch expression is evaluated exactly once in a switch statement. +</p> + +<h4 id="Expression_switches">Expression switches</h4> + +<p> +In an expression switch, +the switch expression is evaluated and +the case expressions, which need not be constants, +are evaluated left-to-right and top-to-bottom; the first one that equals the +switch expression +triggers execution of the statements of the associated case; +the other cases are skipped. +If no case matches and there is a "default" case, +its statements are executed. +There can be at most one default case and it may appear anywhere in the +"switch" statement. +A missing switch expression is equivalent to the boolean value +<code>true</code>. +</p> + +<pre class="ebnf"> +ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . +ExprCaseClause = ExprSwitchCase ":" StatementList . +ExprSwitchCase = "case" ExpressionList | "default" . +</pre> + +<p> +If the switch expression evaluates to an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>. +The predeclared untyped value <code>nil</code> cannot be used as a switch expression. +The switch expression type must be <a href="#Comparison_operators">comparable</a>. +</p> + +<p> +If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a> +to the type of the switch expression. +For each (possibly converted) case expression <code>x</code> and the value <code>t</code> +of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>. +</p> + +<p> +In other words, the switch expression is treated as if it were used to declare and +initialize a temporary variable <code>t</code> without explicit type; it is that +value of <code>t</code> against which each case expression <code>x</code> is tested +for equality. +</p> + +<p> +In a case or default clause, the last non-empty statement +may be a (possibly <a href="#Labeled_statements">labeled</a>) +<a href="#Fallthrough_statements">"fallthrough" statement</a> to +indicate that control should flow from the end of this clause to +the first statement of the next clause. +Otherwise control flows to the end of the "switch" statement. +A "fallthrough" statement may appear as the last statement of all +but the last clause of an expression switch. +</p> + +<p> +The switch expression may be preceded by a simple statement, which +executes before the expression is evaluated. +</p> + +<pre> +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() +} +</pre> + +<p> +Implementation restriction: A compiler may disallow multiple case +expressions evaluating to the same constant. +For instance, the current compilers disallow duplicate integer, +floating point, or string constants in case expressions. +</p> + +<h4 id="Type_switches">Type switches</h4> + +<p> +A type switch compares types rather than values. It is otherwise similar +to an expression switch. It is marked by a special switch expression that +has the form of a <a href="#Type_assertions">type assertion</a> +using the keyword <code>type</code> rather than an actual type: +</p> + +<pre> +switch x.(type) { +// cases +} +</pre> + +<p> +Cases then match actual types <code>T</code> against the dynamic type of the +expression <code>x</code>. As with type assertions, <code>x</code> must be of +<a href="#Interface_types">interface type</a>, but not a +<a href="#Type_parameter_declarations">type parameter</a>, and each non-interface type +<code>T</code> listed in a case must implement the type of <code>x</code>. +The types listed in the cases of a type switch must all be +<a href="#Type_identity">different</a>. +</p> + +<pre class="ebnf"> +TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . +TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . +TypeCaseClause = TypeSwitchCase ":" StatementList . +TypeSwitchCase = "case" TypeList | "default" . +</pre> + +<p> +The TypeSwitchGuard may include a +<a href="#Short_variable_declarations">short variable declaration</a>. +When that form is used, the variable is declared at the end of the +TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause. +In clauses with a case listing exactly one type, the variable +has that type; otherwise, the variable has the type of the expression +in the TypeSwitchGuard. +</p> + +<p> +Instead of a type, a case may use the predeclared identifier +<a href="#Predeclared_identifiers"><code>nil</code></a>; +that case is selected when the expression in the TypeSwitchGuard +is a <code>nil</code> interface value. +There may be at most one <code>nil</code> case. +</p> + +<p> +Given an expression <code>x</code> of type <code>interface{}</code>, +the following type switch: +</p> + +<pre> +switch i := x.(type) { +case nil: + printString("x is nil") // type of i is type of x (interface{}) +case int: + printInt(i) // type of i is int +case float64: + printFloat64(i) // type of i is float64 +case func(int) float64: + printFunction(i) // type of i is func(int) float64 +case bool, string: + printString("type is bool or string") // type of i is type of x (interface{}) +default: + printString("don't know the type") // type of i is type of x (interface{}) +} +</pre> + +<p> +could be rewritten: +</p> + +<pre> +v := x // x is evaluated exactly once +if v == nil { + i := v // type of i is type of x (interface{}) + printString("x is nil") +} else if i, isInt := v.(int); isInt { + printInt(i) // type of i is int +} else if i, isFloat64 := v.(float64); isFloat64 { + printFloat64(i) // type of i is float64 +} else if i, isFunc := v.(func(int) float64); isFunc { + printFunction(i) // type of i is func(int) float64 +} else { + _, isBool := v.(bool) + _, isString := v.(string) + if isBool || isString { + i := v // type of i is type of x (interface{}) + printString("type is bool or string") + } else { + i := v // type of i is type of x (interface{}) + printString("don't know the type") + } +} +</pre> + +<p> +A <a href="#Type_parameter_declarations">type parameter</a> or a <a href="#Type_declarations">generic type</a> +may be used as a type in a case. If upon <a href="#Instantiations">instantiation</a> that type turns +out to duplicate another entry in the switch, the first matching case is chosen. +</p> + +<pre> +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 +</pre> + +<p> +The type switch guard may be preceded by a simple statement, which +executes before the guard is evaluated. +</p> + +<p> +The "fallthrough" statement is not permitted in a type switch. +</p> + +<h3 id="For_statements">For statements</h3> + +<p> +A "for" statement specifies repeated execution of a block. There are three forms: +The iteration may be controlled by a single condition, a "for" clause, or a "range" clause. +</p> + +<pre class="ebnf"> +ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . +Condition = Expression . +</pre> + +<h4 id="For_condition">For statements with single condition</h4> + +<p> +In its simplest form, a "for" statement specifies the repeated execution of +a block as long as a boolean condition evaluates to true. +The condition is evaluated before each iteration. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. +</p> + +<pre> +for a < b { + a *= 2 +} +</pre> + +<h4 id="For_clause">For statements with <code>for</code> clause</h4> + +<p> +A "for" statement with a ForClause is also controlled by its condition, but +additionally it may specify an <i>init</i> +and a <i>post</i> statement, such as an assignment, +an increment or decrement statement. The init statement may be a +<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. +</p> + +<pre class="ebnf"> +ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . +InitStmt = SimpleStmt . +PostStmt = SimpleStmt . +</pre> + +<pre> +for i := 0; i < 10; i++ { + f(i) +} +</pre> + +<p> +If non-empty, the init statement is executed once before evaluating the +condition for the first iteration; +the post statement is executed after each execution of the block (and +only if the block was executed). +Any element of the ForClause may be empty but the +<a href="#Semicolons">semicolons</a> are +required unless there is only a condition. +If the condition is absent, it is equivalent to the boolean value +<code>true</code>. +</p> + +<pre> +for cond { S() } is the same as for ; cond ; { S() } +for { S() } is the same as for true { S() } +</pre> + +<p> +Each iteration has its own separate declared variable (or variables) +[<a href="#Go_1.22">Go 1.22</a>]. +The variable used by the first iteration is declared by the init statement. +The variable used by each subsequent iteration is declared implicitly before +executing the post statement and initialized to the value of the previous +iteration's variable at that moment. +</p> + +<pre> +var prints []func() +for i := 0; i < 5; i++ { + prints = append(prints, func() { println(i) }) + i++ +} +for _, p := range prints { + p() +} +</pre> + +<p> +prints +</p> + +<pre> +1 +3 +5 +</pre> + +<p> +Prior to [<a href="#Go_1.22">Go 1.22</a>], iterations share one set of variables +instead of having their own separate variables. +In that case, the example above prints +</p> + +<pre> +6 +6 +6 +</pre> + +<h4 id="For_range">For statements with <code>range</code> clause</h4> + +<p> +A "for" statement with a "range" clause +iterates through all entries of an array, slice, string or map, values received on +a channel, or integer values from zero to an upper limit [<a href="#Go_1.22">Go 1.22</a>]. +For each entry it assigns <i>iteration values</i> +to corresponding <i>iteration variables</i> if present and then executes the block. +</p> + +<pre class="ebnf"> +RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . +</pre> + +<p> +The expression on the right in the "range" clause is called the <i>range expression</i>, +its <a href="#Core_types">core type</a> must be +an array, pointer to an array, slice, string, map, channel permitting +<a href="#Receive_operator">receive operations</a>, or an integer. +As with an assignment, if present the operands on the left must be +<a href="#Address_operators">addressable</a> or map index expressions; they +denote the iteration variables. If the range expression is a channel or integer, +at most one iteration variable is permitted, otherwise there may be up to two. +If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, +the range clause is equivalent to the same clause without that identifier. +</p> + +<p> +The range expression <code>x</code> is evaluated once before beginning the loop, +with one exception: if at most one iteration variable is present and +<code>len(x)</code> is <a href="#Length_and_capacity">constant</a>, +the range expression is not evaluated. +</p> + +<p> +Function calls on the left are evaluated once per iteration. +For each iteration, iteration values are produced as follows +if the respective iteration variables are present: +</p> + +<pre class="grammar"> +Range expression 1st value 2nd value + +array or slice a [n]E, *[n]E, or []E index i int a[i] E +string s string type index i int see below rune +map m map[K]V key k K m[k] V +channel c chan E, <-chan E element e E +integer n integer type value i see below +</pre> + +<ol> +<li> +For an array, pointer to array, or slice value <code>a</code>, the index iteration +values are produced in increasing order, starting at element index 0. +If at most one iteration variable is present, the range loop produces +iteration values from 0 up to <code>len(a)-1</code> and does not index into the array +or slice itself. For a <code>nil</code> slice, the number of iterations is 0. +</li> + +<li> +For a string value, the "range" clause iterates over the Unicode code points +in the string starting at byte index 0. On successive iterations, the index value will be the +index of the first byte of successive UTF-8-encoded code points in the string, +and the second value, of type <code>rune</code>, will be the value of +the corresponding code point. If the iteration encounters an invalid +UTF-8 sequence, the second value will be <code>0xFFFD</code>, +the Unicode replacement character, and the next iteration will advance +a single byte in the string. +</li> + +<li> +The iteration order over maps is not specified +and is not guaranteed to be the same from one iteration to the next. +If a map entry that has not yet been reached is removed during iteration, +the corresponding iteration value will not be produced. If a map entry is +created during iteration, that entry may be produced during the iteration or +may be skipped. The choice may vary for each entry created and from one +iteration to the next. +If the map is <code>nil</code>, the number of iterations is 0. +</li> + +<li> +For channels, the iteration values produced are the successive values sent on +the channel until the channel is <a href="#Close">closed</a>. If the channel +is <code>nil</code>, the range expression blocks forever. +</li> + +<li> +For an integer value <code>n</code>, the iteration values 0 through <code>n-1</code> +are produced in increasing order. +If <code>n</code> <= 0, the loop does not run any iterations. +</li> +</ol> + +<p> +The iteration variables may be declared by the "range" clause using a form of +<a href="#Short_variable_declarations">short variable declaration</a> +(<code>:=</code>). +In this case their <a href="#Declarations_and_scope">scope</a> is the block of the "for" statement +and each iteration has its own new variables [<a href="#Go_1.22">Go 1.22</a>] +(see also <a href="#For_clause">"for" statements with a ForClause</a>). +If the range expression is a (possibly untyped) integer expression <code>n</code>, +the variable has the same type as if it was +<a href="#Variable_declarations">declared</a> with initialization +expression <code>n</code>. +Otherwise, the variables have the types of their respective iteration values. +</p> + +<p> +If the iteration variables are not explicitly declared by the "range" clause, +they must be preexisting. +In this case, the iteration values are assigned to the respective variables +as in an <a href="#Assignment_statements">assignment statement</a>. +If the range expression is a (possibly untyped) integer expression <code>n</code>, +<code>n</code> too must be <a href="#Assignability">assignable</a> to the iteration variable; +if there is no iteration variable, <code>n</code> must be assignable to <code>int</code>. +</p> + +<pre> +var testdata *struct { + a *[7]int +} +for i, _ := range testdata.a { + // testdata.a is never evaluated; len(testdata.a) is constant + // i ranges from 0 to 6 + f(i) +} + +var a [10]string +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{} // element type of m is assignable to val +m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6} +for key, val = range m { + h(key, val) +} +// key == last map key encountered in iteration +// val == map[key] + +var ch chan Work = producer() +for w := range ch { + doWork(w) +} + +// empty a channel +for range ch {} + +// call f(0), f(1), ... f(9) +for i := range 10 { + // type of i is int (default type for untyped constant 10) + f(i) +} + +// invalid: 256 cannot be assigned to uint8 +var u uint8 +for u = range 256 { +} +</pre> + + +<h3 id="Go_statements">Go statements</h3> + +<p> +A "go" statement starts the execution of a function call +as an independent concurrent thread of control, or <i>goroutine</i>, +within the same address space. +</p> + +<pre class="ebnf"> +GoStmt = "go" Expression . +</pre> + +<p> +The expression must be a function or method call; it cannot be parenthesized. +Calls of built-in functions are restricted as for +<a href="#Expression_statements">expression statements</a>. +</p> + +<p> +The function value and parameters are +<a href="#Calls">evaluated as usual</a> +in the calling goroutine, but +unlike with a regular call, program execution does not wait +for the invoked function to complete. +Instead, the function begins executing independently +in a new goroutine. +When the function terminates, its goroutine also terminates. +If the function has any return values, they are discarded when the +function completes. +</p> + +<pre> +go Server() +go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c) +</pre> + + +<h3 id="Select_statements">Select statements</h3> + +<p> +A "select" statement chooses which of a set of possible +<a href="#Send_statements">send</a> or +<a href="#Receive_operator">receive</a> +operations will proceed. +It looks similar to a +<a href="#Switch_statements">"switch"</a> statement but with the +cases all referring to communication operations. +</p> + +<pre class="ebnf"> +SelectStmt = "select" "{" { CommClause } "}" . +CommClause = CommCase ":" StatementList . +CommCase = "case" ( SendStmt | RecvStmt ) | "default" . +RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr . +RecvExpr = Expression . +</pre> + +<p> +A case with a RecvStmt may assign the result of a RecvExpr to one or +two variables, which may be declared using a +<a href="#Short_variable_declarations">short variable declaration</a>. +The RecvExpr must be a (possibly parenthesized) receive operation. +There can be at most one default case and it may appear anywhere +in the list of cases. +</p> + +<p> +Execution of a "select" statement proceeds in several steps: +</p> + +<ol> +<li> +For all the cases in the statement, the channel operands of receive operations +and the channel and right-hand-side expressions of send statements are +evaluated exactly once, in source order, upon entering the "select" statement. +The result is a set of channels to receive from or send to, +and the corresponding values to send. +Any side effects in that evaluation will occur irrespective of which (if any) +communication operation is selected to proceed. +Expressions on the left-hand side of a RecvStmt with a short variable declaration +or assignment are not yet evaluated. +</li> + +<li> +If one or more of the communications can proceed, +a single one that can proceed is chosen via a uniform pseudo-random selection. +Otherwise, if there is a default case, that case is chosen. +If there is no default case, the "select" statement blocks until +at least one of the communications can proceed. +</li> + +<li> +Unless the selected case is the default case, the respective communication +operation is executed. +</li> + +<li> +If the selected case is a RecvStmt with a short variable declaration or +an assignment, the left-hand side expressions are evaluated and the +received value (or values) are assigned. +</li> + +<li> +The statement list of the selected case is executed. +</li> +</ol> + +<p> +Since communication on <code>nil</code> channels can never proceed, +a select with only <code>nil</code> channels and no default case blocks forever. +</p> + +<pre> +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 +</pre> + + +<h3 id="Return_statements">Return statements</h3> + +<p> +A "return" statement in a function <code>F</code> terminates the execution +of <code>F</code>, and optionally provides one or more result values. +Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> +are executed before <code>F</code> returns to its caller. +</p> + +<pre class="ebnf"> +ReturnStmt = "return" [ ExpressionList ] . +</pre> + +<p> +In a function without a result type, a "return" statement must not +specify any result values. +</p> +<pre> +func noResult() { + return +} +</pre> + +<p> +There are three ways to return values from a function with a result +type: +</p> + +<ol> + <li>The return value or values may be explicitly listed + in the "return" statement. Each expression must be single-valued + and <a href="#Assignability">assignable</a> + to the corresponding element of the function's result type. +<pre> +func simpleF() int { + return 2 +} + +func complexF1() (re float64, im float64) { + return -7.0, -4.0 +} +</pre> + </li> + <li>The expression list in the "return" statement may be a single + call to a multi-valued function. The effect is as if each value + returned from that function were assigned to a temporary + variable with the type of the respective value, followed by a + "return" statement listing these variables, at which point the + rules of the previous case apply. +<pre> +func complexF2() (re float64, im float64) { + return complexF1() +} +</pre> + </li> + <li>The expression list may be empty if the function's result + type specifies names for its <a href="#Function_types">result parameters</a>. + The result parameters act as ordinary local variables + and the function may assign values to them as necessary. + The "return" statement returns the values of these variables. +<pre> +func complexF3() (re float64, im float64) { + re = 7.0 + im = 4.0 + return +} + +func (devnull) Write(p []byte) (n int, _ error) { + n = len(p) + return +} +</pre> + </li> +</ol> + +<p> +Regardless of how they are declared, all the result values are initialized to +the <a href="#The_zero_value">zero values</a> for their type upon entry to the +function. A "return" statement that specifies results sets the result parameters before +any deferred functions are executed. +</p> + +<p> +Implementation restriction: A compiler may disallow an empty expression list +in a "return" statement if a different entity (constant, type, or variable) +with the same name as a result parameter is in +<a href="#Declarations_and_scope">scope</a> at the place of the return. +</p> + +<pre> +func f(n int) (res int, err error) { + if _, err := f(n-1); err != nil { + return // invalid return statement: err is shadowed + } + return +} +</pre> + +<h3 id="Break_statements">Break statements</h3> + +<p> +A "break" statement terminates execution of the innermost +<a href="#For_statements">"for"</a>, +<a href="#Switch_statements">"switch"</a>, or +<a href="#Select_statements">"select"</a> statement +within the same function. +</p> + +<pre class="ebnf"> +BreakStmt = "break" [ Label ] . +</pre> + +<p> +If there is a label, it must be that of an enclosing +"for", "switch", or "select" statement, +and that is the one whose execution terminates. +</p> + +<pre> +OuterLoop: + for i = 0; i < n; i++ { + for j = 0; j < m; j++ { + switch a[i][j] { + case nil: + state = Error + break OuterLoop + case item: + state = Found + break OuterLoop + } + } + } +</pre> + +<h3 id="Continue_statements">Continue statements</h3> + +<p> +A "continue" statement begins the next iteration of the +innermost enclosing <a href="#For_statements">"for" loop</a> +by advancing control to the end of the loop block. +The "for" loop must be within the same function. +</p> + +<pre class="ebnf"> +ContinueStmt = "continue" [ Label ] . +</pre> + +<p> +If there is a label, it must be that of an enclosing +"for" statement, and that is the one whose execution +advances. +</p> + +<pre> +RowLoop: + for y, row := range rows { + for x, data := range row { + if data == endOfRow { + continue RowLoop + } + row[x] = data + bias(x, y) + } + } +</pre> + +<h3 id="Goto_statements">Goto statements</h3> + +<p> +A "goto" statement transfers control to the statement with the corresponding label +within the same function. +</p> + +<pre class="ebnf"> +GotoStmt = "goto" Label . +</pre> + +<pre> +goto Error +</pre> + +<p> +Executing the "goto" statement must not cause any variables to come into +<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. +For instance, this example: +</p> + +<pre> + goto L // BAD + v := 3 +L: +</pre> + +<p> +is erroneous because the jump to label <code>L</code> skips +the creation of <code>v</code>. +</p> + +<p> +A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. +For instance, this example: +</p> + +<pre> +if n%2 == 1 { + goto L1 +} +for n > 0 { + f() + n-- +L1: + f() + n-- +} +</pre> + +<p> +is erroneous because the label <code>L1</code> is inside +the "for" statement's block but the <code>goto</code> is not. +</p> + +<h3 id="Fallthrough_statements">Fallthrough statements</h3> + +<p> +A "fallthrough" statement transfers control to the first statement of the +next case clause in an <a href="#Expression_switches">expression "switch" statement</a>. +It may be used only as the final non-empty statement in such a clause. +</p> + +<pre class="ebnf"> +FallthroughStmt = "fallthrough" . +</pre> + + +<h3 id="Defer_statements">Defer statements</h3> + +<p> +A "defer" statement invokes a function whose execution is deferred +to the moment the surrounding function returns, either because the +surrounding function executed a <a href="#Return_statements">return statement</a>, +reached the end of its <a href="#Function_declarations">function body</a>, +or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>. +</p> + +<pre class="ebnf"> +DeferStmt = "defer" Expression . +</pre> + +<p> +The expression must be a function or method call; it cannot be parenthesized. +Calls of built-in functions are restricted as for +<a href="#Expression_statements">expression statements</a>. +</p> + +<p> +Each time a "defer" statement +executes, the function value and parameters to the call are +<a href="#Calls">evaluated as usual</a> +and saved anew but the actual function is not invoked. +Instead, deferred functions are invoked immediately before +the surrounding function returns, in the reverse order +they were deferred. That is, if the surrounding function +returns through an explicit <a href="#Return_statements">return statement</a>, +deferred functions are executed <i>after</i> any result parameters are set +by that return statement but <i>before</i> the function returns to its caller. +If a deferred function value evaluates +to <code>nil</code>, execution <a href="#Handling_panics">panics</a> +when the function is invoked, not when the "defer" statement is executed. +</p> + +<p> +For instance, if the deferred function is +a <a href="#Function_literals">function literal</a> and the surrounding +function has <a href="#Function_types">named result parameters</a> that +are in scope within the literal, the deferred function may access and modify +the result parameters before they are returned. +If the deferred function has any return values, they are discarded when +the function completes. +(See also the section on <a href="#Handling_panics">handling panics</a>.) +</p> + +<pre> +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 +} +</pre> + +<h2 id="Built-in_functions">Built-in functions</h2> + +<p> +Built-in functions are +<a href="#Predeclared_identifiers">predeclared</a>. +They are called like any other function but some of them +accept a type instead of an expression as the first argument. +</p> + +<p> +The built-in functions do not have standard Go types, +so they can only appear in <a href="#Calls">call expressions</a>; +they cannot be used as function values. +</p> + + +<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3> + +<p> +The built-in functions <code>append</code> and <code>copy</code> assist in +common slice operations. +For both functions, the result is independent of whether the memory referenced +by the arguments overlaps. +</p> + +<p> +The <a href="#Function_types">variadic</a> function <code>append</code> +appends zero or more values <code>x</code> to a slice <code>s</code> +and returns the resulting slice of the same type as <code>s</code>. +The <a href="#Core_types">core type</a> of <code>s</code> must be a slice +of type <code>[]E</code>. +The values <code>x</code> are passed to a parameter of type <code>...E</code> +and the respective <a href="#Passing_arguments_to_..._parameters">parameter +passing rules</a> apply. +As a special case, if the core type of <code>s</code> is <code>[]byte</code>, +<code>append</code> also accepts a second argument with core type +<a href="#Core_types"><code>bytestring</code></a> followed by <code>...</code>. +This form appends the bytes of the byte slice or string. +</p> + +<pre class="grammar"> +append(s S, x ...E) S // core type of S is []E +</pre> + +<p> +If the capacity of <code>s</code> is not large enough to fit the additional +values, <code>append</code> <a href="#Allocation">allocates</a> a new, sufficiently large underlying +array that fits both the existing slice elements and the additional values. +Otherwise, <code>append</code> re-uses the underlying array. +</p> + +<pre> +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' } +</pre> + +<p> +The function <code>copy</code> copies slice elements from +a source <code>src</code> to a destination <code>dst</code> and returns the +number of elements copied. +The <a href="#Core_types">core types</a> of both arguments must be slices +with <a href="#Type_identity">identical</a> element type. +The number of elements copied is the minimum of +<code>len(src)</code> and <code>len(dst)</code>. +As a special case, if the destination's core type is <code>[]byte</code>, +<code>copy</code> also accepts a source argument with core type +</a> <a href="#Core_types"><code>bytestring</code></a>. +This form copies the bytes from the byte slice or string into the byte slice. +</p> + +<pre class="grammar"> +copy(dst, src []T) int +copy(dst []byte, src string) int +</pre> + +<p> +Examples: +</p> + +<pre> +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") +</pre> + + +<h3 id="Clear">Clear</h3> + +<p> +The built-in function <code>clear</code> takes an argument of <a href="#Map_types">map</a>, +<a href="#Slice_types">slice</a>, or <a href="#Type_parameter_declarations">type parameter</a> type, +and deletes or zeroes out all elements +[<a href="#Go_1.21">Go 1.21</a>]. +</p> + +<pre class="grammar"> +Call Argument type Result + +clear(m) map[K]T deletes all entries, resulting in an + empty map (len(m) == 0) + +clear(s) []T sets all elements up to the length of + <code>s</code> to the zero value of T + +clear(t) type parameter see below +</pre> + +<p> +If the type of the argument to <code>clear</code> is a +<a href="#Type_parameter_declarations">type parameter</a>, +all types in its type set must be maps or slices, and <code>clear</code> +performs the operation corresponding to the actual type argument. +</p> + +<p> +If the map or slice is <code>nil</code>, <code>clear</code> is a no-op. +</p> + + +<h3 id="Close">Close</h3> + +<p> +For an argument <code>ch</code> with a <a href="#Core_types">core type</a> +that is a <a href="#Channel_types">channel</a>, the built-in function <code>close</code> +records that no more values will be sent on the channel. +It is an error if <code>ch</code> is a receive-only channel. +Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>. +Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>. +After calling <code>close</code>, and after any previously +sent values have been received, receive operations will return +the zero value for the channel's type without blocking. +The multi-valued <a href="#Receive_operator">receive operation</a> +returns a received value along with an indication of whether the channel is closed. +</p> + + +<h3 id="Complex_numbers">Manipulating complex numbers</h3> + +<p> +Three functions assemble and disassemble complex numbers. +The built-in function <code>complex</code> constructs a complex +value from a floating-point real and imaginary part, while +<code>real</code> and <code>imag</code> +extract the real and imaginary parts of a complex value. +</p> + +<pre class="grammar"> +complex(realPart, imaginaryPart floatT) complexT +real(complexT) floatT +imag(complexT) floatT +</pre> + +<p> +The type of the arguments and return value correspond. +For <code>complex</code>, the two arguments must be of the same +<a href="#Numeric_types">floating-point type</a> and the return type is the +<a href="#Numeric_types">complex type</a> +with the corresponding floating-point constituents: +<code>complex64</code> for <code>float32</code> arguments, and +<code>complex128</code> for <code>float64</code> arguments. +If one of the arguments evaluates to an untyped constant, it is first implicitly +<a href="#Conversions">converted</a> to the type of the other argument. +If both arguments evaluate to untyped constants, they must be non-complex +numbers or their imaginary parts must be zero, and the return value of +the function is an untyped complex constant. +</p> + +<p> +For <code>real</code> and <code>imag</code>, the argument must be +of complex type, and the return type is the corresponding floating-point +type: <code>float32</code> for a <code>complex64</code> argument, and +<code>float64</code> for a <code>complex128</code> argument. +If the argument evaluates to an untyped constant, it must be a number, +and the return value of the function is an untyped floating-point constant. +</p> + +<p> +The <code>real</code> and <code>imag</code> functions together form the inverse of +<code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>, +<code>z == Z(complex(real(z), imag(z)))</code>. +</p> + +<p> +If the operands of these functions are all constants, the return +value is a constant. +</p> + +<pre> +var a = complex(2, -2) // complex128 +const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i +x := float32(math.Cos(math.Pi/2)) // float32 +var c64 = complex(5, -x) // complex64 +var s int = complex(1, 0) // untyped complex constant 1 + 0i can be converted to int +_ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift +var rl = real(c64) // float32 +var im = imag(a) // float64 +const c = imag(b) // untyped constant -1.4 +_ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift +</pre> + +<p> +Arguments of type parameter type are not permitted. +</p> + + +<h3 id="Deletion_of_map_elements">Deletion of map elements</h3> + +<p> +The built-in function <code>delete</code> removes the element with key +<code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The +value <code>k</code> must be <a href="#Assignability">assignable</a> +to the key type of <code>m</code>. +</p> + +<pre class="grammar"> +delete(m, k) // remove element m[k] from map m +</pre> + +<p> +If the type of <code>m</code> is a <a href="#Type_parameter_declarations">type parameter</a>, +all types in that type set must be maps, and they must all have identical key types. +</p> + +<p> +If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code> +does not exist, <code>delete</code> is a no-op. +</p> + + +<h3 id="Length_and_capacity">Length and capacity</h3> + +<p> +The built-in functions <code>len</code> and <code>cap</code> take arguments +of various types and return a result of type <code>int</code>. +The implementation guarantees that the result always fits into an <code>int</code>. +</p> + +<pre class="grammar"> +Call Argument type Result + +len(s) string type string length in bytes + [n]T, *[n]T array length (== n) + []T slice length + map[K]T map length (number of defined keys) + chan T number of elements queued in channel buffer + type parameter see below + +cap(s) [n]T, *[n]T array length (== n) + []T slice capacity + chan T channel buffer capacity + type parameter see below +</pre> + +<p> +If the argument type is a <a href="#Type_parameter_declarations">type parameter</a> <code>P</code>, +the call <code>len(e)</code> (or <code>cap(e)</code> respectively) must be valid for +each type in <code>P</code>'s type set. +The result is the length (or capacity, respectively) of the argument whose type +corresponds to the type argument with which <code>P</code> was +<a href="#Instantiations">instantiated</a>. +</p> + +<p> +The capacity of a slice is the number of elements for which there is +space allocated in the underlying array. +At any time the following relationship holds: +</p> + +<pre> +0 <= len(s) <= cap(s) +</pre> + +<p> +The length of a <code>nil</code> slice, map or channel is 0. +The capacity of a <code>nil</code> slice or channel is 0. +</p> + +<p> +The expression <code>len(s)</code> is <a href="#Constants">constant</a> if +<code>s</code> is a string constant. The expressions <code>len(s)</code> and +<code>cap(s)</code> are constants if the type of <code>s</code> is an array +or pointer to an array and the expression <code>s</code> does not contain +<a href="#Receive_operator">channel receives</a> or (non-constant) +<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. +Otherwise, invocations of <code>len</code> and <code>cap</code> are not +constant and <code>s</code> is evaluated. +</p> + +<pre> +const ( + c1 = imag(2i) // imag(2i) = 2.0 is a constant + c2 = len([10]float64{2}) // [10]float64{2} contains no function calls + c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls + c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued + c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call +) +var z complex128 +</pre> + + +<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> + +<p> +The built-in function <code>make</code> takes a type <code>T</code>, +optionally followed by a type-specific list of expressions. +The <a href="#Core_types">core type</a> of <code>T</code> must +be a slice, map or channel. +It returns a value of type <code>T</code> (not <code>*T</code>). +The memory is initialized as described in the section on +<a href="#The_zero_value">initial values</a>. +</p> + +<pre class="grammar"> +Call Core type Result + +make(T, n) slice slice of type T with length n and capacity n +make(T, n, m) slice slice of type T with length n and capacity m + +make(T) map map of type T +make(T, n) map map of type T with initial space for approximately n elements + +make(T) channel unbuffered channel of type T +make(T, n) channel buffered channel of type T, buffer size n +</pre> + +<p> +Each of the size arguments <code>n</code> and <code>m</code> must be of <a href="#Numeric_types">integer type</a>, +have a <a href="#Interface_types">type set</a> containing only integer types, +or be an untyped <a href="#Constants">constant</a>. +A constant size argument must be non-negative and <a href="#Representability">representable</a> +by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>. +If both <code>n</code> and <code>m</code> are provided and are constant, then +<code>n</code> must be no larger than <code>m</code>. +For slices and channels, if <code>n</code> is negative or larger than <code>m</code> at run time, +a <a href="#Run_time_panics">run-time panic</a> occurs. +</p> + +<pre> +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 +</pre> + +<p> +Calling <code>make</code> with a map type and size hint <code>n</code> will +create a map with initial space to hold <code>n</code> map elements. +The precise behavior is implementation-dependent. +</p> + + +<h3 id="Min_and_max">Min and max</h3> + +<p> +The built-in functions <code>min</code> and <code>max</code> compute the +smallest—or largest, respectively—value of a fixed number of +arguments of <a href="#Comparison_operators">ordered types</a>. +There must be at least one argument +[<a href="#Go_1.21">Go 1.21</a>]. +</p> + +<p> +The same type rules as for <a href="#Operators">operators</a> apply: +for <a href="#Comparison_operators">ordered</a> arguments <code>x</code> and +<code>y</code>, <code>min(x, y)</code> is valid if <code>x + y</code> is valid, +and the type of <code>min(x, y)</code> is the type of <code>x + y</code> +(and similarly for <code>max</code>). +If all arguments are constant, the result is constant. +</p> + +<pre> +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) +</pre> + +<p> +For numeric arguments, assuming all NaNs are equal, <code>min</code> and <code>max</code> are +commutative and associative: +</p> + +<pre> +min(x, y) == min(y, x) +min(x, y, z) == min(min(x, y), z) == min(x, min(y, z)) +</pre> + +<p> +For floating-point arguments negative zero, NaN, and infinity the following rules apply: +</p> + +<pre> + x y min(x, y) max(x, y) + + -0.0 0.0 -0.0 0.0 // negative zero is smaller than (non-negative) zero + -Inf y -Inf y // negative infinity is smaller than any other number + +Inf y y +Inf // positive infinity is larger than any other number + NaN y NaN NaN // if any argument is a NaN, the result is a NaN +</pre> + +<p> +For string arguments the result for <code>min</code> is the first argument +with the smallest (or for <code>max</code>, largest) value, +compared lexically byte-wise: +</p> + +<pre> +min(x, y) == if x <= y then x else y +min(x, y, z) == min(min(x, y), z) +</pre> + +<h3 id="Allocation">Allocation</h3> + +<p> +The built-in function <code>new</code> takes a type <code>T</code>, +allocates storage for a <a href="#Variables">variable</a> of that type +at run time, and returns a value of type <code>*T</code> +<a href="#Pointer_types">pointing</a> to it. +The variable is initialized as described in the section on +<a href="#The_zero_value">initial values</a>. +</p> + +<pre class="grammar"> +new(T) +</pre> + +<p> +For instance +</p> + +<pre> +type S struct { a int; b float64 } +new(S) +</pre> + +<p> +allocates storage for a variable of type <code>S</code>, +initializes it (<code>a=0</code>, <code>b=0.0</code>), +and returns a value of type <code>*S</code> containing the address +of the location. +</p> + + +<h3 id="Handling_panics">Handling panics</h3> + +<p> Two built-in functions, <code>panic</code> and <code>recover</code>, +assist in reporting and handling <a href="#Run_time_panics">run-time panics</a> +and program-defined error conditions. +</p> + +<pre class="grammar"> +func panic(interface{}) +func recover() interface{} +</pre> + +<p> +While executing a function <code>F</code>, +an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a> +terminates the execution of <code>F</code>. +Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> +are then executed as usual. +Next, any deferred functions run by <code>F</code>'s caller are run, +and so on up to any deferred by the top-level function in the executing goroutine. +At that point, the program is terminated and the error +condition is reported, including the value of the argument to <code>panic</code>. +This termination sequence is called <i>panicking</i>. +</p> + +<pre> +panic(42) +panic("unreachable") +panic(Error("cannot parse")) +</pre> + +<p> +The <code>recover</code> function allows a program to manage behavior +of a panicking goroutine. +Suppose a function <code>G</code> defers a function <code>D</code> that calls +<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code> +is executing. +When the running of deferred functions reaches <code>D</code>, +the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>. +If <code>D</code> returns normally, without starting a new +<code>panic</code>, the panicking sequence stops. In that case, +the state of functions called between <code>G</code> and the call to <code>panic</code> +is discarded, and normal execution resumes. +Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s +execution terminates by returning to its caller. +</p> + +<p> +The return value of <code>recover</code> is <code>nil</code> when the +goroutine is not panicking or <code>recover</code> was not called directly by a deferred function. +Conversely, if a goroutine is panicking and <code>recover</code> was called directly by a deferred function, +the return value of <code>recover</code> is guaranteed not to be <code>nil</code>. +To ensure this, calling <code>panic</code> with a <code>nil</code> interface value (or an untyped <code>nil</code>) +causes a <a href="#Run_time_panics">run-time panic</a>. +</p> + +<p> +The <code>protect</code> function in the example below invokes +the function argument <code>g</code> and protects callers from +run-time panics raised by <code>g</code>. +</p> + +<pre> +func protect(g func()) { + defer func() { + log.Println("done") // Println executes normally even if there is a panic + if x := recover(); x != nil { + log.Printf("run time panic: %v", x) + } + }() + log.Println("start") + g() +} +</pre> + + +<h3 id="Bootstrapping">Bootstrapping</h3> + +<p> +Current implementations provide several built-in functions useful during +bootstrapping. These functions are documented for completeness but are not +guaranteed to stay in the language. They do not return a result. +</p> + +<pre class="grammar"> +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 +</pre> + +<p> +Implementation restriction: <code>print</code> and <code>println</code> need not +accept arbitrary argument types, but printing of boolean, numeric, and string +<a href="#Types">types</a> must be supported. +</p> + + +<h2 id="Packages">Packages</h2> + +<p> +Go programs are constructed by linking together <i>packages</i>. +A package in turn is constructed from one or more source files +that together declare constants, types, variables and functions +belonging to the package and which are accessible in all files +of the same package. Those elements may be +<a href="#Exported_identifiers">exported</a> and used in another package. +</p> + +<h3 id="Source_file_organization">Source file organization</h3> + +<p> +Each source file consists of a package clause defining the package +to which it belongs, followed by a possibly empty set of import +declarations that declare packages whose contents it wishes to use, +followed by a possibly empty set of declarations of functions, +types, variables, and constants. +</p> + +<pre class="ebnf"> +SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } . +</pre> + +<h3 id="Package_clause">Package clause</h3> + +<p> +A package clause begins each source file and defines the package +to which the file belongs. +</p> + +<pre class="ebnf"> +PackageClause = "package" PackageName . +PackageName = identifier . +</pre> + +<p> +The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>. +</p> + +<pre> +package math +</pre> + +<p> +A set of files sharing the same PackageName form the implementation of a package. +An implementation may require that all source files for a package inhabit the same directory. +</p> + +<h3 id="Import_declarations">Import declarations</h3> + +<p> +An import declaration states that the source file containing the declaration +depends on functionality of the <i>imported</i> package +(<a href="#Program_initialization_and_execution">§Program initialization and execution</a>) +and enables access to <a href="#Exported_identifiers">exported</a> identifiers +of that package. +The import names an identifier (PackageName) to be used for access and an ImportPath +that specifies the package to be imported. +</p> + +<pre class="ebnf"> +ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . +ImportSpec = [ "." | PackageName ] ImportPath . +ImportPath = string_lit . +</pre> + +<p> +The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a> +to access exported identifiers of the package within the importing source file. +It is declared in the <a href="#Blocks">file block</a>. +If the PackageName is omitted, it defaults to the identifier specified in the +<a href="#Package_clause">package clause</a> of the imported package. +If an explicit period (<code>.</code>) appears instead of a name, all the +package's exported identifiers declared in that package's +<a href="#Blocks">package block</a> will be declared in the importing source +file's file block and must be accessed without a qualifier. +</p> + +<p> +The interpretation of the ImportPath is implementation-dependent but +it is typically a substring of the full file name of the compiled +package and may be relative to a repository of installed packages. +</p> + +<p> +Implementation restriction: A compiler may restrict ImportPaths to +non-empty strings using only characters belonging to +<a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a> +L, M, N, P, and S general categories (the Graphic characters without +spaces) and may also exclude the characters +<code>!"#$%&'()*,:;<=>?[\]^`{|}</code> +and the Unicode replacement character U+FFFD. +</p> + +<p> +Consider a compiled a package containing the package clause +<code>package math</code>, which exports function <code>Sin</code>, and +installed the compiled package in the file identified by +<code>"lib/math"</code>. +This table illustrates how <code>Sin</code> is accessed in files +that import the package after the +various types of import declaration. +</p> + +<pre class="grammar"> +Import declaration Local name of Sin + +import "lib/math" math.Sin +import m "lib/math" m.Sin +import . "lib/math" Sin +</pre> + +<p> +An import declaration declares a dependency relation between +the importing and imported package. +It is illegal for a package to import itself, directly or indirectly, +or to directly import a package without +referring to any of its exported identifiers. To import a package solely for +its side-effects (initialization), use the <a href="#Blank_identifier">blank</a> +identifier as explicit package name: +</p> + +<pre> +import _ "lib/math" +</pre> + + +<h3 id="An_example_package">An example package</h3> + +<p> +Here is a complete Go package that implements a concurrent prime sieve. +</p> + +<pre> +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() +} +</pre> + +<h2 id="Program_initialization_and_execution">Program initialization and execution</h2> + +<h3 id="The_zero_value">The zero value</h3> +<p> +When storage is allocated for a <a href="#Variables">variable</a>, +either through a declaration or a call of <code>new</code>, or when +a new value is created, either through a composite literal or a call +of <code>make</code>, +and no explicit initialization is provided, the variable or value is +given a default value. Each element of such a variable or value is +set to the <i>zero value</i> for its type: <code>false</code> for booleans, +<code>0</code> for numeric types, <code>""</code> +for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps. +This initialization is done recursively, so for instance each element of an +array of structs will have its fields zeroed if no value is specified. +</p> +<p> +These two simple declarations are equivalent: +</p> + +<pre> +var i int +var i int = 0 +</pre> + +<p> +After +</p> + +<pre> +type T struct { i int; f float64; next *T } +t := new(T) +</pre> + +<p> +the following holds: +</p> + +<pre> +t.i == 0 +t.f == 0.0 +t.next == nil +</pre> + +<p> +The same would also be true after +</p> + +<pre> +var t T +</pre> + +<h3 id="Package_initialization">Package initialization</h3> + +<p> +Within a package, package-level variable initialization proceeds stepwise, +with each step selecting the variable earliest in <i>declaration order</i> +which has no dependencies on uninitialized variables. +</p> + +<p> +More precisely, a package-level variable is considered <i>ready for +initialization</i> if it is not yet initialized and either has +no <a href="#Variable_declarations">initialization expression</a> or +its initialization expression has no <i>dependencies</i> on uninitialized variables. +Initialization proceeds by repeatedly initializing the next package-level +variable that is earliest in declaration order and ready for initialization, +until there are no variables ready for initialization. +</p> + +<p> +If any variables are still uninitialized when this +process ends, those variables are part of one or more initialization cycles, +and the program is not valid. +</p> + +<p> +Multiple variables on the left-hand side of a variable declaration initialized +by single (multi-valued) expression on the right-hand side are initialized +together: If any of the variables on the left-hand side is initialized, all +those variables are initialized in the same step. +</p> + +<pre> +var x = a +var a, b = f() // a and b are initialized together, before x is initialized +</pre> + +<p> +For the purpose of package initialization, <a href="#Blank_identifier">blank</a> +variables are treated like any other variables in declarations. +</p> + +<p> +The declaration order of variables declared in multiple files is determined +by the order in which the files are presented to the compiler: Variables +declared in the first file are declared before any of the variables declared +in the second file, and so on. +To ensure reproducible initialization behavior, build systems are encouraged +to present multiple files belonging to the same package in lexical file name +order to a compiler. +</p> + +<p> +Dependency analysis does not rely on the actual values of the +variables, only on lexical <i>references</i> to them in the source, +analyzed transitively. For instance, if a variable <code>x</code>'s +initialization expression refers to a function whose body refers to +variable <code>y</code> then <code>x</code> depends on <code>y</code>. +Specifically: +</p> + +<ul> +<li> +A reference to a variable or function is an identifier denoting that +variable or function. +</li> + +<li> +A reference to a method <code>m</code> is a +<a href="#Method_values">method value</a> or +<a href="#Method_expressions">method expression</a> of the form +<code>t.m</code>, where the (static) type of <code>t</code> is +not an interface type, and the method <code>m</code> is in the +<a href="#Method_sets">method set</a> of <code>t</code>. +It is immaterial whether the resulting function value +<code>t.m</code> is invoked. +</li> + +<li> +A variable, function, or method <code>x</code> depends on a variable +<code>y</code> if <code>x</code>'s initialization expression or body +(for functions and methods) contains a reference to <code>y</code> +or to a function or method that depends on <code>y</code>. +</li> +</ul> + +<p> +For example, given the declarations +</p> + +<pre> +var ( + a = c + b // == 9 + b = f() // == 4 + c = f() // == 5 + d = 3 // == 5 after initialization has finished +) + +func f() int { + d++ + return d +} +</pre> + +<p> +the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. +Note that the order of subexpressions in initialization expressions is irrelevant: +<code>a = c + b</code> and <code>a = b + c</code> result in the same initialization +order in this example. +</p> + +<p> +Dependency analysis is performed per package; only references referring +to variables, functions, and (non-interface) methods declared in the current +package are considered. If other, hidden, data dependencies exists between +variables, the initialization order between those variables is unspecified. +</p> + +<p> +For instance, given the declarations +</p> + +<pre> +var x = I(T{}).ab() // x has an undetected, hidden dependency on a and b +var _ = sideEffect() // unrelated to x, a, or b +var a = b +var b = 42 + +type I interface { ab() []int } +type T struct{} +func (T) ab() []int { return []int{a, b} } +</pre> + +<p> +the variable <code>a</code> will be initialized after <code>b</code> but +whether <code>x</code> is initialized before <code>b</code>, between +<code>b</code> and <code>a</code>, or after <code>a</code>, and +thus also the moment at which <code>sideEffect()</code> is called (before +or after <code>x</code> is initialized) is not specified. +</p> + +<p> +Variables may also be initialized using functions named <code>init</code> +declared in the package block, with no arguments and no result parameters. +</p> + +<pre> +func init() { … } +</pre> + +<p> +Multiple such functions may be defined per package, even within a single +source file. In the package block, the <code>init</code> identifier can +be used only to declare <code>init</code> functions, yet the identifier +itself is not <a href="#Declarations_and_scope">declared</a>. Thus +<code>init</code> functions cannot be referred to from anywhere +in a program. +</p> + +<p> +The entire package is initialized by assigning initial values +to all its package-level variables followed by calling +all <code>init</code> functions in the order they appear +in the source, possibly in multiple files, as presented +to the compiler. +</p> + +<h3 id="Program_initialization">Program initialization</h3> + +<p> +The packages of a complete program are initialized stepwise, one package at a time. +If a package has imports, the imported packages are initialized +before initializing the package itself. If multiple packages import +a package, the imported package will be initialized only once. +The importing of packages, by construction, guarantees that there +can be no cyclic initialization dependencies. +More precisely: +</p> + +<p> +Given the list of all packages, sorted by import path, in each step the first +uninitialized package in the list for which all imported packages (if any) are +already initialized is <a href="#Package_initialization">initialized</a>. +This step is repeated until all packages are initialized. +</p> + +<p> +Package initialization—variable initialization and the invocation of +<code>init</code> functions—happens in a single goroutine, +sequentially, one package at a time. +An <code>init</code> function may launch other goroutines, which can run +concurrently with the initialization code. However, initialization +always sequences +the <code>init</code> functions: it will not invoke the next one +until the previous one has returned. +</p> + +<h3 id="Program_execution">Program execution</h3> +<p> +A complete program is created by linking a single, unimported package +called the <i>main package</i> with all the packages it imports, transitively. +The main package must +have package name <code>main</code> and +declare a function <code>main</code> that takes no +arguments and returns no value. +</p> + +<pre> +func main() { … } +</pre> + +<p> +Program execution begins by <a href="#Program_initialization">initializing the program</a> +and then invoking the function <code>main</code> in package <code>main</code>. +When that function invocation returns, the program exits. +It does not wait for other (non-<code>main</code>) goroutines to complete. +</p> + +<h2 id="Errors">Errors</h2> + +<p> +The predeclared type <code>error</code> is defined as +</p> + +<pre> +type error interface { + Error() string +} +</pre> + +<p> +It is the conventional interface for representing an error condition, +with the nil value representing no error. +For instance, a function to read data from a file might be defined: +</p> + +<pre> +func Read(f *File, b []byte) (n int, err error) +</pre> + +<h2 id="Run_time_panics">Run-time panics</h2> + +<p> +Execution errors such as attempting to index an array out +of bounds trigger a <i>run-time panic</i> equivalent to a call of +the built-in function <a href="#Handling_panics"><code>panic</code></a> +with a value of the implementation-defined interface type <code>runtime.Error</code>. +That type satisfies the predeclared interface type +<a href="#Errors"><code>error</code></a>. +The exact error values that +represent distinct run-time error conditions are unspecified. +</p> + +<pre> +package runtime + +type Error interface { + error + // and perhaps other methods +} +</pre> + +<h2 id="System_considerations">System considerations</h2> + +<h3 id="Package_unsafe">Package <code>unsafe</code></h3> + +<p> +The built-in package <code>unsafe</code>, known to the compiler +and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>, +provides facilities for low-level programming including operations +that violate the type system. A package using <code>unsafe</code> +must be vetted manually for type safety and may not be portable. +The package provides the following interface: +</p> + +<pre class="grammar"> +package unsafe + +type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type +type Pointer *ArbitraryType + +func Alignof(variable ArbitraryType) uintptr +func Offsetof(selector ArbitraryType) uintptr +func Sizeof(variable ArbitraryType) uintptr + +type IntegerType int // shorthand for an integer type; it is not a real type +func Add(ptr Pointer, len IntegerType) Pointer +func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType +func SliceData(slice []ArbitraryType) *ArbitraryType +func String(ptr *byte, len IntegerType) string +func StringData(str string) *byte +</pre> + +<!-- +These conversions also apply to type parameters with suitable core types. +Determine if we can simply use core type instead of underlying type here, +of if the general conversion rules take care of this. +--> + +<p> +A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> +value may not be <a href="#Address_operators">dereferenced</a>. +Any pointer or value of <a href="#Core_types">core type</a> <code>uintptr</code> can be +<a href="#Conversions">converted</a> to a type of core type <code>Pointer</code> and vice versa. +The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. +</p> + +<pre> +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 +</pre> + +<p> +The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code> +of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code> +as if <code>v</code> was declared via <code>var v = x</code>. +</p> +<p> +The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a> +<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code> +or <code>*s</code>, and returns the field offset in bytes relative to the struct's address. +If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable +without pointer indirections through fields of the struct. +For a struct <code>s</code> with field <code>f</code>: +</p> + +<pre> +uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f)) +</pre> + +<p> +Computer architectures may require memory addresses to be <i>aligned</i>; +that is, for addresses of a variable to be a multiple of a factor, +the variable's type's <i>alignment</i>. The function <code>Alignof</code> +takes an expression denoting a variable of any type and returns the +alignment of the (type of the) variable in bytes. For a variable +<code>x</code>: +</p> + +<pre> +uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0 +</pre> + +<p> +A (variable of) type <code>T</code> has <i>variable size</i> if <code>T</code> +is a <a href="#Type_parameter_declarations">type parameter</a>, or if it is an +array or struct type containing elements +or fields of variable size. Otherwise the size is <i>constant</i>. +Calls to <code>Alignof</code>, <code>Offsetof</code>, and <code>Sizeof</code> +are compile-time <a href="#Constant_expressions">constant expressions</a> of +type <code>uintptr</code> if their arguments (or the struct <code>s</code> in +the selector expression <code>s.f</code> for <code>Offsetof</code>) are types +of constant size. +</p> + +<p> +The function <code>Add</code> adds <code>len</code> to <code>ptr</code> +and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code> +[<a href="#Go_1.17">Go 1.17</a>]. +The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>. +A constant <code>len</code> argument must be <a href="#Representability">representable</a> by a value of type <code>int</code>; +if it is an untyped constant it is given type <code>int</code>. +The rules for <a href="/pkg/unsafe#Pointer">valid uses</a> of <code>Pointer</code> still apply. +</p> + +<p> +The function <code>Slice</code> returns a slice whose underlying array starts at <code>ptr</code> +and whose length and capacity are <code>len</code>. +<code>Slice(ptr, len)</code> is equivalent to +</p> + +<pre> +(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:] +</pre> + +<p> +except that, as a special case, if <code>ptr</code> +is <code>nil</code> and <code>len</code> is zero, +<code>Slice</code> returns <code>nil</code> +[<a href="#Go_1.17">Go 1.17</a>]. +</p> + +<p> +The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>. +A constant <code>len</code> argument must be non-negative and <a href="#Representability">representable</a> by a value of type <code>int</code>; +if it is an untyped constant it is given type <code>int</code>. +At run time, if <code>len</code> is negative, +or if <code>ptr</code> is <code>nil</code> and <code>len</code> is not zero, +a <a href="#Run_time_panics">run-time panic</a> occurs +[<a href="#Go_1.17">Go 1.17</a>]. +</p> + +<p> +The function <code>SliceData</code> returns a pointer to the underlying array of the <code>slice</code> argument. +If the slice's capacity <code>cap(slice)</code> is not zero, that pointer is <code>&slice[:1][0]</code>. +If <code>slice</code> is <code>nil</code>, the result is <code>nil</code>. +Otherwise it is a non-<code>nil</code> pointer to an unspecified memory address +[<a href="#Go_1.20">Go 1.20</a>]. +</p> + +<p> +The function <code>String</code> returns a <code>string</code> value whose underlying bytes start at +<code>ptr</code> and whose length is <code>len</code>. +The same requirements apply to the <code>ptr</code> and <code>len</code> argument as in the function +<code>Slice</code>. If <code>len</code> is zero, the result is the empty string <code>""</code>. +Since Go strings are immutable, the bytes passed to <code>String</code> must not be modified afterwards. +[<a href="#Go_1.20">Go 1.20</a>] +</p> + +<p> +The function <code>StringData</code> returns a pointer to the underlying bytes of the <code>str</code> argument. +For an empty string the return value is unspecified, and may be <code>nil</code>. +Since Go strings are immutable, the bytes returned by <code>StringData</code> must not be modified +[<a href="#Go_1.20">Go 1.20</a>]. +</p> + +<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> + +<p> +For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed: +</p> + +<pre class="grammar"> +type size in bytes + +byte, uint8, int8 1 +uint16, int16 2 +uint32, int32, float32 4 +uint64, int64, float64, complex64 8 +complex128 16 +</pre> + +<p> +The following minimal alignment properties are guaranteed: +</p> +<ol> +<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1. +</li> + +<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of + all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1. +</li> + +<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as + the alignment of a variable of the array's element type. +</li> +</ol> + +<p> +A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory. +</p> + +<h2 id="Appendix">Appendix</h2> + +<h3 id="Language_versions">Language versions</h3> + +<p> +The <a href="/doc/go1compat">Go 1 compatibility guarantee</a> ensures that +programs written to the Go 1 specification will continue to compile and run +correctly, unchanged, over the lifetime of that specification. +More generally, as adjustments are made and features added to the language, +the compatibility guarantee ensures that a Go program that works with a +specific Go language version will continue to work with any subsequent version. +</p> + +<p> +For instance, the ability to use the prefix <code>0b</code> for binary +integer literals was introduced with Go 1.13, indicated +by [<a href="#Go_1.13">Go 1.13</a>] in the section on +<a href="#Integer_literals">integer literals</a>. +Source code containing an integer literal such as <code>0b1011</code> +will be rejected if the implied or required language version used by +the compiler is older than Go 1.13. +</p> + +<p> +The following table describes the minimum language version required for +features introduced after Go 1. +</p> + +<h4 id="Go_1.9">Go 1.9</h4> +<ul> +<li> +An <a href="#Alias_declarations">alias declaration</a> may be used to declare an alias name for a type. +</li> +</ul> + +<h4 id="Go_1.13">Go 1.13</h4> +<ul> +<li> +<a href="#Integer_literals">Integer literals</a> may use the prefixes <code>0b</code>, <code>0B</code>, <code>0o</code>, +and <code>0O</code> for binary, and octal literals, respectively. +</li> +<li> +Hexadecimal <a href="#Floating-point_literals">floating-point literals</a> may be written using the prefixes +<code>0x</code> and <code>0X</code>. +</li> +<li> +The <a href="#Imaginary_literals">imaginary suffix</a> <code>i</code> may be used with any (binary, decimal, hexadecimal) +integer or floating-point literal, not just decimal literals. +</li> +<li> +The digits of any number literal may be <a href="#Integer_literals">separated</a> (grouped) +using underscores <code>_</code>. +</li> +<li> +The shift count in a <a href="#Operators">shift operation</a> may be a signed integer type. +</li> +</ul> + +<h4 id="Go_1.14">Go 1.14</h4> +<ul> +<li> +Emdedding a method more than once through different <a href="#Embedded_interfaces">embedded interfaces</a> +is not an error. +</li> +</ul> + +<h4 id="Go_1.17">Go 1.17</h4> +<ul> +<li> +A slice may be <a href="#Conversions">converted</a> to an array pointer if the slice and array element +types match, and the array is not longer than the slice. +</li> +<li> +The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions +<code>Add</code> and <code>Slice</code>. +</li> +</ul> + +<h4 id="Go_1.18">Go 1.18</h4> +<p> +The 1.18 release adds polymorphic functions and types ("generics") to the language. +Specifically: +</p> +<ul> +<li> +The set of <a href="#Operators_and_punctuation">operators and punctuation</a> includes the new token <code>~</code>. +</li> +<li> +Function and type declarations may declare <a href="#Type_parameter_declarations">type parameters</a>. +</li> +<li> +Interface types may <a href="#General_interfaces">embed arbitrary types</a> (not just type names of interfaces) +as well as union and <code>~T</code> type elements. +</li> +<li> +The set of <a href="#Predeclared_identifiers">predeclared</a> types includes the new types +<code>any</code> and <code>comparable</code>. +</li> +</ul> + +<h4 id="Go_1.20">Go 1.20</h4> +<ul> +<li> +A slice may be <a href="#Conversions">converted</a> to an array if the slice and array element +types match and the array is not longer than the slice. +</li> +<li> +The built-in <a href="#Package_unsafe">package <code>unsafe</code></a> includes the new functions +<code>SliceData</code>, <code>String</code>, and <code>StringData</code>. +</li> +<li> +<a href="#Comparison_operators">Comparable types</a> (such as ordinary interfaces) may satisfy +<code>comparable</code> constraints, even if the type arguments are not strictly comparable. +</li> +</ul> + +<h4 id="Go_1.21">Go 1.21</h4> +<ul> +<li> +The set of <a href="#Predeclared_identifiers">predeclared</a> functions includes the new functions +<code>min</code>, <code>max</code>, and <code>clear</code>. +</li> +<li> +<a href="#Type_inference">Type inference</a> uses the types of interface methods for inference. +It also infers type arguments for generic functions assigned to variables or +passed as arguments to other (possibly generic) functions. +</li> +</ul> + +<h4 id="Go_1.22">Go 1.22</h4> +<ul> +<li> +In a <a href="#For_statements">"for" statement</a>, each iteration has its own set of iteration +variables rather than sharing the same variables in each iteration. +</li> +<li> +A "for" statement with <a href="#For_range">"range" clause</a> may iterate over +integer values from zero to an upper limit. +</li> +</ul> + +<h3 id="Type_unification_rules">Type unification rules</h3> + +<p> +The type unification rules describe if and how two types unify. +The precise details are relevant for Go implementations, +affect the specifics of error messages (such as whether +a compiler reports a type inference or other error), +and may explain why type inference fails in unusual code situations. +But by and large these rules can be ignored when writing Go code: +type inference is designed to mostly "work as expected", +and the unification rules are fine-tuned accordingly. +</p> + +<p> +Type unification is controlled by a <i>matching mode</i>, which may +be <i>exact</i> or <i>loose</i>. +As unification recursively descends a composite type structure, +the matching mode used for elements of the type, the <i>element matching mode</i>, +remains the same as the matching mode except when two types are unified for +<a href="#Assignability">assignability</a> (<code>≡<sub>A</sub></code>): +in this case, the matching mode is <i>loose</i> at the top level but +then changes to <i>exact</i> for element types, reflecting the fact +that types don't have to be identical to be assignable. +</p> + +<p> +Two types that are not bound type parameters unify exactly if any of +following conditions is true: +</p> + +<ul> +<li> + Both types are <a href="#Type_identity">identical</a>. +</li> +<li> + Both types have identical structure and their element types + unify exactly. +</li> +<li> + Exactly one type is an <a href="#Type_inference">unbound</a> + type parameter with a <a href="#Core_types">core type</a>, + and that core type unifies with the other type per the + unification rules for <code>≡<sub>A</sub></code> + (loose unification at the top level and exact unification + for element types). +</li> +</ul> + +<p> +If both types are bound type parameters, they unify per the given +matching modes if: +</p> + +<ul> +<li> + Both type parameters are identical. +</li> +<li> + At most one of the type parameters has a known type argument. + In this case, the type parameters are <i>joined</i>: + they both stand for the same type argument. + If neither type parameter has a known type argument yet, + a future type argument inferred for one the type parameters + is simultaneously inferred for both of them. +</li> +<li> + Both type parameters have a known type argument + and the type arguments unify per the given matching modes. +</li> +</ul> + +<p> +A single bound type parameter <code>P</code> and another type <code>T</code> unify +per the given matching modes if: +</p> + +<ul> +<li> + <code>P</code> doesn't have a known type argument. + In this case, <code>T</code> is inferred as the type argument for <code>P</code>. +</li> +<li> + <code>P</code> does have a known type argument <code>A</code>, + <code>A</code> and <code>T</code> unify per the given matching modes, + and one of the following conditions is true: + <ul> + <li> + Both <code>A</code> and <code>T</code> are interface types: + In this case, if both <code>A</code> and <code>T</code> are + also <a href="#Type_definitions">defined</a> types, + they must be <a href="#Type_identity">identical</a>. + Otherwise, if neither of them is a defined type, they must + have the same number of methods + (unification of <code>A</code> and <code>T</code> already + established that the methods match). + </li> + <li> + Neither <code>A</code> nor <code>T</code> are interface types: + In this case, if <code>T</code> is a defined type, <code>T</code> + replaces <code>A</code> as the inferred type argument for <code>P</code>. + </li> + </ul> +</li> +</ul> + +<p> +Finally, two types that are not bound type parameters unify loosely +(and per the element matching mode) if: +</p> + +<ul> +<li> + Both types unify exactly. +</li> +<li> + One type is a <a href="#Type_definitions">defined type</a>, + the other type is a type literal, but not an interface, + and their underlying types unify per the element matching mode. +</li> +<li> + Both types are interfaces (but not type parameters) with + identical <a href="#Interface_types">type terms</a>, + both or neither embed the predeclared type + <a href="#Predeclared_identifiers">comparable</a>, + corresponding method types unify exactly, + and the method set of one of the interfaces is a subset of + the method set of the other interface. +</li> +<li> + Only one type is an interface (but not a type parameter), + corresponding methods of the two types unify per the element matching mode, + and the method set of the interface is a subset of + the method set of the other type. +</li> +<li> + Both types have the same structure and their element types + unify per the element matching mode. +</li> +</ul> diff --git a/doc/godebug.md b/doc/godebug.md new file mode 100644 index 0000000..a7619c9 --- /dev/null +++ b/doc/godebug.md @@ -0,0 +1,273 @@ +--- +title: "Go, Backwards Compatibility, and GODEBUG" +layout: article +--- + +<!-- +This document is kept in the Go repo, not x/website, +because it documents the full list of known GODEBUG settings, +which are tied to a specific release. +--> + +## Introduction {#intro} + +Go's emphasis on backwards compatibility is one of its key strengths. +There are, however, times when we cannot maintain complete compatibility. +If code depends on buggy (including insecure) behavior, +then fixing the bug will break that code. +New features can also have similar impacts: +enabling the HTTP/2 use by the HTTP client broke programs +connecting to servers with buggy HTTP/2 implementations. +These kinds of changes are unavoidable and +[permitted by the Go 1 compatibility rules](/doc/go1compat). +Even so, Go provides a mechanism called GODEBUG to +reduce the impact such changes have on Go developers +using newer toolchains to compile old code. + +A GODEBUG setting is a `key=value` pair +that controls the execution of certain parts of a Go program. +The environment variable `GODEBUG` +can hold a comma-separated list of these settings. +For example, if a Go program is running in an environment that contains + + GODEBUG=http2client=0,http2server=0 + +then that Go program will disable the use of HTTP/2 by default in both +the HTTP client and the HTTP server. +It is also possible to set the default `GODEBUG` for a given program +(discussed below). + +When preparing any change that is permitted by Go 1 compatibility +but may nonetheless break some existing programs, +we first engineer the change to keep as many existing programs working as possible. +For the remaining programs, +we define a new GODEBUG setting that +allows individual programs to opt back in to the old behavior. +A GODEBUG setting may not be added if doing so is infeasible, +but that should be extremely rare. + +GODEBUG settings added for compatibility will be maintained +for a minimum of two years (four Go releases). +Some, such as `http2client` and `http2server`, +will be maintained much longer, even indefinitely. + +When possible, each GODEBUG setting has an associated +[runtime/metrics](/pkg/runtime/metrics/) counter +named `/godebug/non-default-behavior/<name>:events` +that counts the number of times a particular program's +behavior has changed based on a non-default value +for that setting. +For example, when `GODEBUG=http2client=0` is set, +`/godebug/non-default-behavior/http2client:events` +counts the number of HTTP transports that the program +has configured without HTTP/2 support. + +## Default GODEBUG Values {#default} + +When a GODEBUG setting is not listed in the environment variable, +its value is derived from three sources: +the defaults for the Go toolchain used to build the program, +amended to match the Go version listed in `go.mod`, +and then overridden by explicit `//go:debug` lines in the program. + +The [GODEBUG History](#history) gives the exact defaults for each Go toolchain version. +For example, Go 1.21 introduces the `panicnil` setting, +controlling whether `panic(nil)` is allowed; +it defaults to `panicnil=0`, making `panic(nil)` a run-time error. +Using `panicnil=1` restores the behavior of Go 1.20 and earlier. + +When compiling a work module or workspace that declares +an older Go version, the Go toolchain amends its defaults +to match that older Go version as closely as possible. +For example, when a Go 1.21 toolchain compiles a program, +if the work module's `go.mod` or the workspace's `go.work` +says `go` `1.20`, then the program defaults to `panicnil=1`, +matching Go 1.20 instead of Go 1.21. + +Because this method of setting GODEBUG defaults was introduced only in Go 1.21, +programs listing versions of Go earlier than Go 1.20 are configured to match Go 1.20, +not the older version. + +To override these defaults, a main package's source files +can include one or more `//go:debug` directives at the top of the file +(preceding the `package` statement). +Continuing the `panicnil` example, if the module or workspace is updated +to say `go` `1.21`, the program can opt back into the old `panic(nil)` +behavior by including this directive: + + //go:debug panicnil=1 + +Starting in Go 1.21, the Go toolchain treats a `//go:debug` directive +with an unrecognized GODEBUG setting as an invalid program. +Programs with more than one `//go:debug` line for a given setting +are also treated as invalid. +(Older toolchains ignore `//go:debug` directives entirely.) + +The defaults that will be compiled into a main package +are reported by the command: + +{{raw ` + go list -f '{{.DefaultGODEBUG}}' my/main/package +`}} + +Only differences from the base Go toolchain defaults are reported. + +When testing a package, `//go:debug` lines in the `*_test.go` +files are treated as directives for the test's main package. +In any other context, `//go:debug` lines are ignored by the toolchain; +`go` `vet` reports such lines as misplaced. + +## GODEBUG History {#history} + +This section documents the GODEBUG settings introduced and removed in each major Go release +for compatibility reasons. +Packages or programs may define additional settings for internal debugging purposes; +for example, +see the [runtime documentation](/pkg/runtime#hdr-Environment_Variables) +and the [go command documentation](/cmd/go#hdr-Build_and_test_caching). + +### Go 1.22 + +Go 1.22 adds a configurable limit to control the maximum acceptable RSA key size +that can be used in TLS handshakes, controlled by the [`tlsmaxrsasize` setting](/pkg/crypto/tls#Conn.Handshake). +The default is tlsmaxrsasize=8192, limiting RSA to 8192-bit keys. To avoid +denial of service attacks, this setting and default was backported to Go +1.19.13, Go 1.20.8, and Go 1.21.1. + +Go 1.22 made it an error for a request or response read by a net/http +client or server to have an empty Content-Length header. +This behavior is controlled by the `httplaxcontentlength` setting. + +Go 1.22 changed the behavior of ServeMux to accept extended +patterns and unescape both patterns and request paths by segment. +This behavior can be controlled by the +[`httpmuxgo121` setting](/pkg/net/http/#ServeMux). + +Go 1.22 added the [Alias type](/pkg/go/types#Alias) to [go/types](/pkg/go/types) +for the explicit representation of [type aliases](/ref/spec#Type_declarations). +Whether the type checker produces `Alias` types or not is controlled by the +[`gotypesalias` setting](/pkg/go/types#Alias). +For Go 1.22 it defaults to `gotypesalias=0`. +For Go 1.23, `gotypealias=1` will become the default. +This setting will be removed in a future release, Go 1.24 at the earliest. + +Go 1.22 changed the default minimum TLS version supported by both servers +and clients to TLS 1.2. The default can be reverted to TLS 1.0 using the +[`tls10server` setting](/pkg/crypto/tls/#Config). + +Go 1.22 changed the default TLS cipher suites used by clients and servers when +not explicitly configured, removing the cipher suites which used RSA based key +exchange. The default can be revert using the [`tlsrsakex` setting](/pkg/crypto/tls/#Config). + +Go 1.22 disabled +[`ConnectionState.ExportKeyingMaterial`](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial) +when the connection supports neither TLS 1.3 nor Extended Master Secret +(implemented in Go 1.21). It can be reenabled with the [`tlsunsafeekm` +setting](/pkg/crypto/tls/#ConnectionState.ExportKeyingMaterial). + +Go 1.22 changed how the runtime interacts with transparent huge pages on Linux. +In particular, a common default Linux kernel configuration can result in +significant memory overheads, and Go 1.22 no longer works around this default. +To work around this issue without adjusting kernel settings, transparent huge +pages can be disabled for Go memory with the +[`disablethp` setting](/pkg/runtime#hdr-Environment_Variable). +This behavior was backported to Go 1.21.1, but the setting is only available +starting with Go 1.21.6. +This setting may be removed in a future release, and users impacted by this issue +should adjust their Linux configuration according to the recommendations in the +[GC guide](/doc/gc-guide#Linux_transparent_huge_pages), or switch to a Linux +distribution that disables transparent huge pages altogether. + +Go 1.22 added contention on runtime-internal locks to the [`mutex` +profile](/pkg/runtime/pprof#Profile). Contention on these locks is always +reported at `runtime._LostContendedRuntimeLock`. Complete stack traces of +runtime locks can be enabled with the [`runtimecontentionstacks` +setting](/pkg/runtime#hdr-Environment_Variable). These stack traces have +non-standard semantics, see setting documentation for details. + +Go 1.22 added a new [`crypto/x509.Certificate`](/pkg/crypto/x509/#Certificate) +field, [`Policies`](/pkg/crypto/x509/#Certificate.Policies), which supports +certificate policy OIDs with components larger than 31 bits. By default this +field is only used during parsing, when it is populated with policy OIDs, but +not used during marshaling. It can be used to marshal these larger OIDs, instead +of the existing PolicyIdentifiers field, by using the +[`x509usepolicies` setting.](/pkg/crypto/x509/#CreateCertificate). + + +### Go 1.21 + +Go 1.21 made it a run-time error to call `panic` with a nil interface value, +controlled by the [`panicnil` setting](/pkg/builtin/#panic). + +Go 1.21 made it an error for html/template actions to appear inside of an ECMAScript 6 +template literal, controlled by the +[`jstmpllitinterp` setting](/pkg/html/template#hdr-Security_Model). +This behavior was backported to Go 1.19.8+ and Go 1.20.3+. + +Go 1.21 introduced a limit on the maximum number of MIME headers and multipart +forms, controlled by the +[`multipartmaxheaders` and `multipartmaxparts` settings](/pkg/mime/multipart#hdr-Limits) +respectively. +This behavior was backported to Go 1.19.8+ and Go 1.20.3+. + +Go 1.21 adds the support of Multipath TCP but it is only used if the application +explicitly asked for it. This behavior can be controlled by the +[`multipathtcp` setting](/pkg/net#Dialer.SetMultipathTCP). + +There is no plan to remove any of these settings. + +### Go 1.20 + +Go 1.20 introduced support for rejecting insecure paths in tar and zip archives, +controlled by the [`tarinsecurepath` setting](/pkg/archive/tar/#Reader.Next) +and the [`zipinsecurepath` setting](/pkg/archive/zip/#NewReader). +These default to `tarinsecurepath=1` and `zipinsecurepath=1`, +preserving the behavior of earlier versions of Go. +A future version of Go may change the defaults to +`tarinsecurepath=0` and `zipinsecurepath=0`. + +Go 1.20 introduced automatic seeding of the +[`math/rand`](/pkg/math/rand) global random number generator, +controlled by the [`randautoseed` setting](/pkg/math/rand/#Seed). + +Go 1.20 introduced the concept of fallback roots for use during certificate verification, +controlled by the [`x509usefallbackroots` setting](/pkg/crypto/x509/#SetFallbackRoots). + +Go 1.20 removed the preinstalled `.a` files for the standard library +from the Go distribution. +Installations now build and cache the standard library like +packages in other modules. +The [`installgoroot` setting](/cmd/go#hdr-Compile_and_install_packages_and_dependencies) +restores the installation and use of preinstalled `.a` files. + +There is no plan to remove any of these settings. + +### Go 1.19 + +Go 1.19 made it an error for path lookups to resolve to binaries in the current directory, +controlled by the [`execerrdot` setting](/pkg/os/exec#hdr-Executables_in_the_current_directory). +There is no plan to remove this setting. + +### Go 1.18 + +Go 1.18 removed support for SHA1 in most X.509 certificates, +controlled by the [`x509sha1` setting](/pkg/crypto/x509#InsecureAlgorithmError). +This setting will be removed in a future release, Go 1.22 at the earliest. + +### Go 1.10 + +Go 1.10 changed how build caching worked and added test caching, along +with the [`gocacheverify`, `gocachehash`, and `gocachetest` settings](/cmd/go/#hdr-Build_and_test_caching). +There is no plan to remove these settings. + +### Go 1.6 + +Go 1.6 introduced transparent support for HTTP/2, +controlled by the [`http2client`, `http2server`, and `http2debug` settings](/pkg/net/http/#hdr-HTTP_2). +There is no plan to remove these settings. + +### Go 1.5 + +Go 1.5 introduced a pure Go DNS resolver, +controlled by the [`netdns` setting](/pkg/net/#hdr-Name_Resolution). +There is no plan to remove this setting. |