2 "Title": "The Go Programming Language Specification - Go 1.18 Draft (incomplete)",
3 "Subtitle": "Version of Feb 10, 2022",
7 <h2>Earlier version</h2>
10 For the pre-Go1.18 specification without generics support see
11 <a href="/doc/go1.17_spec.html">The Go Programming Language Specification</a>.
14 <h2 id="Introduction">Introduction</h2>
17 This is a reference manual for the Go programming language. For
18 more information and other documents, see <a href="/">golang.org</a>.
22 Go is a general-purpose language designed with systems programming
23 in mind. It is strongly typed and garbage-collected and has explicit
24 support for concurrent programming. Programs are constructed from
25 <i>packages</i>, whose properties allow efficient management of
30 The grammar is compact and simple to parse, allowing for easy analysis
31 by automatic tools such as integrated development environments.
34 <h2 id="Notation">Notation</h2>
36 The syntax is specified using Extended Backus-Naur Form (EBNF):
40 Production = production_name "=" [ Expression ] "." .
41 Expression = Alternative { "|" Alternative } .
42 Alternative = Term { Term } .
43 Term = production_name | token [ "…" token ] | Group | Option | Repetition .
44 Group = "(" Expression ")" .
45 Option = "[" Expression "]" .
46 Repetition = "{" Expression "}" .
50 Productions are expressions constructed from terms and the following
51 operators, in increasing precedence:
56 [] option (0 or 1 times)
57 {} repetition (0 to n times)
61 Lower-case production names are used to identify lexical tokens.
62 Non-terminals are in CamelCase. Lexical tokens are enclosed in
63 double quotes <code>""</code> or back quotes <code>``</code>.
67 The form <code>a … b</code> represents the set of characters from
68 <code>a</code> through <code>b</code> as alternatives. The horizontal
69 ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various
70 enumerations or code snippets that are not further specified. The character <code>…</code>
71 (as opposed to the three characters <code>...</code>) is not a token of the Go
75 <h2 id="Source_code_representation">Source code representation</h2>
78 Source code is Unicode text encoded in
79 <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
80 canonicalized, so a single accented code point is distinct from the
81 same character constructed from combining an accent and a letter;
82 those are treated as two code points. For simplicity, this document
83 will use the unqualified term <i>character</i> to refer to a Unicode code point
87 Each code point is distinct; for instance, upper and lower case letters
88 are different characters.
91 Implementation restriction: For compatibility with other tools, a
92 compiler may disallow the NUL character (U+0000) in the source text.
95 Implementation restriction: For compatibility with other tools, a
96 compiler may ignore a UTF-8-encoded byte order mark
97 (U+FEFF) if it is the first Unicode code point in the source text.
98 A byte order mark may be disallowed anywhere else in the source.
101 <h3 id="Characters">Characters</h3>
104 The following terms are used to denote specific Unicode character classes:
107 newline = /* the Unicode code point U+000A */ .
108 unicode_char = /* an arbitrary Unicode code point except newline */ .
109 unicode_letter = /* a Unicode code point classified as "Letter" */ .
110 unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ .
114 In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>,
115 Section 4.5 "General Category" defines a set of character categories.
116 Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo
117 as Unicode letters, and those in the Number category Nd as Unicode digits.
120 <h3 id="Letters_and_digits">Letters and digits</h3>
123 The underscore character <code>_</code> (U+005F) is considered a letter.
126 letter = unicode_letter | "_" .
127 decimal_digit = "0" … "9" .
128 binary_digit = "0" | "1" .
129 octal_digit = "0" … "7" .
130 hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
133 <h2 id="Lexical_elements">Lexical elements</h2>
135 <h3 id="Comments">Comments</h3>
138 Comments serve as program documentation. There are two forms:
143 <i>Line comments</i> start with the character sequence <code>//</code>
144 and stop at the end of the line.
147 <i>General comments</i> start with the character sequence <code>/*</code>
148 and stop with the first subsequent character sequence <code>*/</code>.
153 A comment cannot start inside a <a href="#Rune_literals">rune</a> or
154 <a href="#String_literals">string literal</a>, or inside a comment.
155 A general comment containing no newlines acts like a space.
156 Any other comment acts like a newline.
159 <h3 id="Tokens">Tokens</h3>
162 Tokens form the vocabulary of the Go language.
163 There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators
164 and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from
165 spaces (U+0020), horizontal tabs (U+0009),
166 carriage returns (U+000D), and newlines (U+000A),
167 is ignored except as it separates tokens
168 that would otherwise combine into a single token. Also, a newline or end of file
169 may trigger the insertion of a <a href="#Semicolons">semicolon</a>.
170 While breaking the input into tokens,
171 the next token is the longest sequence of characters that form a
175 <h3 id="Semicolons">Semicolons</h3>
178 The formal grammar uses semicolons <code>";"</code> as terminators in
179 a number of productions. Go programs may omit most of these semicolons
180 using the following two rules:
185 When the input is broken into tokens, a semicolon is automatically inserted
186 into the token stream immediately after a line's final token if that token is
189 <a href="#Identifiers">identifier</a>
193 <a href="#Integer_literals">integer</a>,
194 <a href="#Floating-point_literals">floating-point</a>,
195 <a href="#Imaginary_literals">imaginary</a>,
196 <a href="#Rune_literals">rune</a>, or
197 <a href="#String_literals">string</a> literal
200 <li>one of the <a href="#Keywords">keywords</a>
202 <code>continue</code>,
203 <code>fallthrough</code>, or
207 <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a>
218 To allow complex statements to occupy a single line, a semicolon
219 may be omitted before a closing <code>")"</code> or <code>"}"</code>.
224 To reflect idiomatic use, code examples in this document elide semicolons
229 <h3 id="Identifiers">Identifiers</h3>
232 Identifiers name program entities such as variables and types.
233 An identifier is a sequence of one or more letters and digits.
234 The first character in an identifier must be a letter.
237 identifier = letter { letter | unicode_digit } .
242 ThisVariableIsExported
247 Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
251 <h3 id="Keywords">Keywords</h3>
254 The following keywords are reserved and may not be used as identifiers.
256 <pre class="grammar">
257 break default func interface select
258 case defer go map struct
259 chan else goto package switch
260 const fallthrough if range type
261 continue for import return var
264 <h3 id="Operators_and_punctuation">Operators and punctuation</h3>
267 The following character sequences represent <a href="#Operators">operators</a>
268 (including <a href="#Assignments">assignment operators</a>) and punctuation:
270 <pre class="grammar">
271 + & += &= && == != ( )
272 - | -= |= || < <= [ ]
273 * ^ *= ^= <- > >= { }
274 / << /= <<= ++ = := , ;
275 % >> %= >>= -- ! ... . :
279 <h3 id="Integer_literals">Integer literals</h3>
282 An integer literal is a sequence of digits representing an
283 <a href="#Constants">integer constant</a>.
284 An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code>
285 for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal,
286 and <code>0x</code> or <code>0X</code> for hexadecimal.
287 A single <code>0</code> is considered a decimal zero.
288 In hexadecimal literals, letters <code>a</code> through <code>f</code>
289 and <code>A</code> through <code>F</code> represent values 10 through 15.
293 For readability, an underscore character <code>_</code> may appear after
294 a base prefix or between successive digits; such underscores do not change
298 int_lit = decimal_lit | binary_lit | octal_lit | hex_lit .
299 decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] .
300 binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits .
301 octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits .
302 hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits .
304 decimal_digits = decimal_digit { [ "_" ] decimal_digit } .
305 binary_digits = binary_digit { [ "_" ] binary_digit } .
306 octal_digits = octal_digit { [ "_" ] octal_digit } .
307 hex_digits = hex_digit { [ "_" ] hex_digit } .
316 0O600 // second character is capital letter 'O'
320 170141183460469231731687303715884105727
321 170_141183_460469_231731_687303_715884_105727
323 _42 // an identifier, not an integer literal
324 42_ // invalid: _ must separate successive digits
325 4__2 // invalid: only one _ at a time
326 0_xBadFace // invalid: _ must separate successive digits
330 <h3 id="Floating-point_literals">Floating-point literals</h3>
333 A floating-point literal is a decimal or hexadecimal representation of a
334 <a href="#Constants">floating-point constant</a>.
338 A decimal floating-point literal consists of an integer part (decimal digits),
339 a decimal point, a fractional part (decimal digits), and an exponent part
340 (<code>e</code> or <code>E</code> followed by an optional sign and decimal digits).
341 One of the integer part or the fractional part may be elided; one of the decimal point
342 or the exponent part may be elided.
343 An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>.
347 A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code>
348 prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits),
349 and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits).
350 One of the integer part or the fractional part may be elided; the radix point may be elided as well,
351 but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.)
352 An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>.
356 For readability, an underscore character <code>_</code> may appear after
357 a base prefix or between successive digits; such underscores do not change
362 float_lit = decimal_float_lit | hex_float_lit .
364 decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] |
365 decimal_digits decimal_exponent |
366 "." decimal_digits [ decimal_exponent ] .
367 decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits .
369 hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent .
370 hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] |
373 hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits .
391 0x1.Fp+0 // == 1.9375
393 0X_1FFFP-16 // == 0.1249847412109375
394 0x15e-2 // == 0x15e - 2 (integer subtraction)
396 0x.p1 // invalid: mantissa has no digits
397 1p-2 // invalid: p exponent requires hexadecimal mantissa
398 0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent
399 1_.5 // invalid: _ must separate successive digits
400 1._5 // invalid: _ must separate successive digits
401 1.5_e1 // invalid: _ must separate successive digits
402 1.5e_1 // invalid: _ must separate successive digits
403 1.5e1_ // invalid: _ must separate successive digits
407 <h3 id="Imaginary_literals">Imaginary literals</h3>
410 An imaginary literal represents the imaginary part of a
411 <a href="#Constants">complex constant</a>.
412 It consists of an <a href="#Integer_literals">integer</a> or
413 <a href="#Floating-point_literals">floating-point</a> literal
414 followed by the lower-case letter <code>i</code>.
415 The value of an imaginary literal is the value of the respective
416 integer or floating-point literal multiplied by the imaginary unit <i>i</i>.
420 imaginary_lit = (decimal_digits | int_lit | float_lit) "i" .
424 For backward compatibility, an imaginary literal's integer part consisting
425 entirely of decimal digits (and possibly underscores) is considered a decimal
426 integer, even if it starts with a leading <code>0</code>.
431 0123i // == 123i for backward-compatibility
432 0o123i // == 0o123 * 1i == 83i
433 0xabci // == 0xabc * 1i == 2748i
441 0x1p-2i // == 0x1p-2 * 1i == 0.25i
445 <h3 id="Rune_literals">Rune literals</h3>
448 A rune literal represents a <a href="#Constants">rune constant</a>,
449 an integer value identifying a Unicode code point.
450 A rune literal is expressed as one or more characters enclosed in single quotes,
451 as in <code>'x'</code> or <code>'\n'</code>.
452 Within the quotes, any character may appear except newline and unescaped single
453 quote. A single quoted character represents the Unicode value
454 of the character itself,
455 while multi-character sequences beginning with a backslash encode
456 values in various formats.
460 The simplest form represents the single character within the quotes;
461 since Go source text is Unicode characters encoded in UTF-8, multiple
462 UTF-8-encoded bytes may represent a single integer value. For
463 instance, the literal <code>'a'</code> holds a single byte representing
464 a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while
465 <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing
466 a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>.
470 Several backslash escapes allow arbitrary values to be encoded as
471 ASCII text. There are four ways to represent the integer value
472 as a numeric constant: <code>\x</code> followed by exactly two hexadecimal
473 digits; <code>\u</code> followed by exactly four hexadecimal digits;
474 <code>\U</code> followed by exactly eight hexadecimal digits, and a
475 plain backslash <code>\</code> followed by exactly three octal digits.
476 In each case the value of the literal is the value represented by
477 the digits in the corresponding base.
481 Although these representations all result in an integer, they have
482 different valid ranges. Octal escapes must represent a value between
483 0 and 255 inclusive. Hexadecimal escapes satisfy this condition
484 by construction. The escapes <code>\u</code> and <code>\U</code>
485 represent Unicode code points so within them some values are illegal,
486 in particular those above <code>0x10FFFF</code> and surrogate halves.
490 After a backslash, certain single-character escapes represent special values:
493 <pre class="grammar">
494 \a U+0007 alert or bell
497 \n U+000A line feed or newline
498 \r U+000D carriage return
499 \t U+0009 horizontal tab
500 \v U+000B vertical tab
502 \' U+0027 single quote (valid escape only within rune literals)
503 \" U+0022 double quote (valid escape only within string literals)
507 All other sequences starting with a backslash are illegal inside rune literals.
510 rune_lit = "'" ( unicode_value | byte_value ) "'" .
511 unicode_value = unicode_char | little_u_value | big_u_value | escaped_char .
512 byte_value = octal_byte_value | hex_byte_value .
513 octal_byte_value = `\` octal_digit octal_digit octal_digit .
514 hex_byte_value = `\` "x" hex_digit hex_digit .
515 little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit .
516 big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit
517 hex_digit hex_digit hex_digit hex_digit .
518 escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
533 '\'' // rune literal containing single quote character
534 'aa' // illegal: too many characters
535 '\xa' // illegal: too few hexadecimal digits
536 '\0' // illegal: too few octal digits
537 '\uDFFF' // illegal: surrogate half
538 '\U00110000' // illegal: invalid Unicode code point
542 <h3 id="String_literals">String literals</h3>
545 A string literal represents a <a href="#Constants">string constant</a>
546 obtained from concatenating a sequence of characters. There are two forms:
547 raw string literals and interpreted string literals.
551 Raw string literals are character sequences between back quotes, as in
552 <code>`foo`</code>. Within the quotes, any character may appear except
553 back quote. The value of a raw string literal is the
554 string composed of the uninterpreted (implicitly UTF-8-encoded) characters
556 in particular, backslashes have no special meaning and the string may
558 Carriage return characters ('\r') inside raw string literals
559 are discarded from the raw string value.
563 Interpreted string literals are character sequences between double
564 quotes, as in <code>"bar"</code>.
565 Within the quotes, any character may appear except newline and unescaped double quote.
566 The text between the quotes forms the
567 value of the literal, with backslash escapes interpreted as they
568 are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and
569 <code>\"</code> is legal), with the same restrictions.
570 The three-digit octal (<code>\</code><i>nnn</i>)
571 and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
572 <i>bytes</i> of the resulting string; all other escapes represent
573 the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
574 Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent
575 a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>,
576 <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent
577 the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
582 string_lit = raw_string_lit | interpreted_string_lit .
583 raw_string_lit = "`" { unicode_char | newline } "`" .
584 interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
588 `abc` // same as "abc"
590 \n` // same as "\\n\n\\n"
597 "\uD800" // illegal: surrogate half
598 "\U00110000" // illegal: invalid Unicode code point
602 These examples all represent the same string:
606 "日本語" // UTF-8 input text
607 `日本語` // UTF-8 input text as a raw literal
608 "\u65e5\u672c\u8a9e" // the explicit Unicode code points
609 "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points
610 "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes
614 If the source code represents a character as two code points, such as
615 a combining form involving an accent and a letter, the result will be
616 an error if placed in a rune literal (it is not a single code
617 point), and will appear as two code points if placed in a string
622 <h2 id="Constants">Constants</h2>
624 <p>There are <i>boolean constants</i>,
625 <i>rune constants</i>,
626 <i>integer constants</i>,
627 <i>floating-point constants</i>, <i>complex constants</i>,
628 and <i>string constants</i>. Rune, integer, floating-point,
629 and complex constants are
630 collectively called <i>numeric constants</i>.
634 A constant value is represented by a
635 <a href="#Rune_literals">rune</a>,
636 <a href="#Integer_literals">integer</a>,
637 <a href="#Floating-point_literals">floating-point</a>,
638 <a href="#Imaginary_literals">imaginary</a>,
640 <a href="#String_literals">string</a> literal,
641 an identifier denoting a constant,
642 a <a href="#Constant_expressions">constant expression</a>,
643 a <a href="#Conversions">conversion</a> with a result that is a constant, or
644 the result value of some built-in functions such as
645 <code>unsafe.Sizeof</code> applied to <a href="#Package_unsafe">certain values</a>,
646 <code>cap</code> or <code>len</code> applied to
647 <a href="#Length_and_capacity">some expressions</a>,
648 <code>real</code> and <code>imag</code> applied to a complex constant
649 and <code>complex</code> applied to numeric constants.
650 The boolean truth values are represented by the predeclared constants
651 <code>true</code> and <code>false</code>. The predeclared identifier
652 <a href="#Iota">iota</a> denotes an integer constant.
656 In general, complex constants are a form of
657 <a href="#Constant_expressions">constant expression</a>
658 and are discussed in that section.
662 Numeric constants represent exact values of arbitrary precision and do not overflow.
663 Consequently, there are no constants denoting the IEEE-754 negative zero, infinity,
664 and not-a-number values.
668 Constants may be <a href="#Types">typed</a> or <i>untyped</i>.
669 Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>,
670 and certain <a href="#Constant_expressions">constant expressions</a>
671 containing only untyped constant operands are untyped.
675 A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a>
676 or <a href="#Conversions">conversion</a>, or implicitly when used in a
677 <a href="#Variable_declarations">variable declaration</a> or an
678 <a href="#Assignments">assignment</a> or as an
679 operand in an <a href="#Expressions">expression</a>.
680 It is an error if the constant value
681 cannot be <a href="#Representability">represented</a> as a value of the respective type.
682 If the type is a type parameter, the constant is converted into a non-constant
683 value of the type parameter.
687 An untyped constant has a <i>default type</i> which is the type to which the
688 constant is implicitly converted in contexts where a typed value is required,
689 for instance, in a <a href="#Short_variable_declarations">short variable declaration</a>
690 such as <code>i := 0</code> where there is no explicit type.
691 The default type of an untyped constant is <code>bool</code>, <code>rune</code>,
692 <code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code>
693 respectively, depending on whether it is a boolean, rune, integer, floating-point,
694 complex, or string constant.
698 Implementation restriction: Although numeric constants have arbitrary
699 precision in the language, a compiler may implement them using an
700 internal representation with limited precision. That said, every
705 <li>Represent integer constants with at least 256 bits.</li>
707 <li>Represent floating-point constants, including the parts of
708 a complex constant, with a mantissa of at least 256 bits
709 and a signed binary exponent of at least 16 bits.</li>
711 <li>Give an error if unable to represent an integer constant
714 <li>Give an error if unable to represent a floating-point or
715 complex constant due to overflow.</li>
717 <li>Round to the nearest representable constant if unable to
718 represent a floating-point or complex constant due to limits
723 These requirements apply both to literal constants and to the result
724 of evaluating <a href="#Constant_expressions">constant
729 <h2 id="Variables">Variables</h2>
732 A variable is a storage location for holding a <i>value</i>.
733 The set of permissible values is determined by the
734 variable's <i><a href="#Types">type</a></i>.
738 A <a href="#Variable_declarations">variable declaration</a>
739 or, for function parameters and results, the signature
740 of a <a href="#Function_declarations">function declaration</a>
741 or <a href="#Function_literals">function literal</a> reserves
742 storage for a named variable.
744 Calling the built-in function <a href="#Allocation"><code>new</code></a>
745 or taking the address of a <a href="#Composite_literals">composite literal</a>
746 allocates storage for a variable at run time.
747 Such an anonymous variable is referred to via a (possibly implicit)
748 <a href="#Address_operators">pointer indirection</a>.
752 <i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>,
753 and <a href="#Struct_types">struct</a> types have elements and fields that may
754 be <a href="#Address_operators">addressed</a> individually. Each such element
755 acts like a variable.
759 The <i>static type</i> (or just <i>type</i>) of a variable is the
760 type given in its declaration, the type provided in the
761 <code>new</code> call or composite literal, or the type of
762 an element of a structured variable.
763 Variables of interface type also have a distinct <i>dynamic type</i>,
764 which is the concrete type of the value assigned to the variable at run time
765 (unless the value is the predeclared identifier <code>nil</code>,
767 The dynamic type may vary during execution but values stored in interface
768 variables are always <a href="#Assignability">assignable</a>
769 to the static type of the variable.
773 var x interface{} // x is nil and has static type interface{}
774 var v *T // v has value nil, static type *T
775 x = 42 // x has value 42 and dynamic type int
776 x = v // x has value (*T)(nil) and dynamic type *T
780 A variable's value is retrieved by referring to the variable in an
781 <a href="#Expressions">expression</a>; it is the most recent value
782 <a href="#Assignments">assigned</a> to the variable.
783 If a variable has not yet been assigned a value, its value is the
784 <a href="#The_zero_value">zero value</a> for its type.
788 <h2 id="Types">Types</h2>
791 A type determines a set of values together with operations and methods specific
792 to those values. A type may be denoted by a <i>type name</i>, if it has one, which must be
793 followed by <a href="#Instantiations">type arguments</a> if the type is generic.
794 A type may also be specified using a <i>type literal</i>, which composes a type
799 Type = TypeName [ TypeArgs ] | TypeLit | "(" Type ")" .
800 TypeName = identifier | QualifiedIdent .
801 TypeArgs = "[" TypeList [ "," ] "]" .
802 TypeList = Type { "," Type } .
803 TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
804 SliceType | MapType | ChannelType .
808 The language <a href="#Predeclared_identifiers">predeclares</a> certain type names.
809 Others are introduced with <a href="#Type_declarations">type declarations</a>
810 or <a href="#Type_parameter_lists">type parameter lists</a>.
811 <i>Composite types</i>—array, struct, pointer, function,
812 interface, slice, map, and channel types—may be constructed using
817 Predeclared types, defined types, and type parameters are called <i>named types</i>.
818 An alias denotes a named type if the type given in the alias declaration is a named type.
821 <h3 id="Boolean_types">Boolean types</h3>
824 A <i>boolean type</i> represents the set of Boolean truth values
825 denoted by the predeclared constants <code>true</code>
826 and <code>false</code>. The predeclared boolean type is <code>bool</code>;
827 it is a <a href="#Type_definitions">defined type</a>.
830 <h3 id="Numeric_types">Numeric types</h3>
833 An <i>integer</i>, <i>floating-point</i>, or <i>complex</i> type
834 represents the set of integer, floating-point, or complex values, respectively.
835 They are collectively called <i>numeric types</i>.
836 The predeclared architecture-independent numeric types are:
839 <pre class="grammar">
840 uint8 the set of all unsigned 8-bit integers (0 to 255)
841 uint16 the set of all unsigned 16-bit integers (0 to 65535)
842 uint32 the set of all unsigned 32-bit integers (0 to 4294967295)
843 uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615)
845 int8 the set of all signed 8-bit integers (-128 to 127)
846 int16 the set of all signed 16-bit integers (-32768 to 32767)
847 int32 the set of all signed 32-bit integers (-2147483648 to 2147483647)
848 int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
850 float32 the set of all IEEE-754 32-bit floating-point numbers
851 float64 the set of all IEEE-754 64-bit floating-point numbers
853 complex64 the set of all complex numbers with float32 real and imaginary parts
854 complex128 the set of all complex numbers with float64 real and imaginary parts
861 The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
862 <a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
866 There is also a set of predeclared integer types with implementation-specific sizes:
869 <pre class="grammar">
870 uint either 32 or 64 bits
871 int same size as uint
872 uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value
876 To avoid portability issues all numeric types are <a href="#Type_definitions">defined
877 types</a> and thus distinct except
878 <code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and
879 <code>rune</code>, which is an alias for <code>int32</code>.
881 are required when different numeric types are mixed in an expression
882 or assignment. For instance, <code>int32</code> and <code>int</code>
883 are not the same type even though they may have the same size on a
884 particular architecture.
887 <h3 id="String_types">String types</h3>
890 A <i>string type</i> represents the set of string values.
891 A string value is a (possibly empty) sequence of bytes.
892 The number of bytes is called the length of the string and is never negative.
893 Strings are immutable: once created,
894 it is impossible to change the contents of a string.
895 The predeclared string type is <code>string</code>;
896 it is a <a href="#Type_definitions">defined type</a>.
900 The length of a string <code>s</code> can be discovered using
901 the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
902 The length is a compile-time constant if the string is a constant.
903 A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a>
904 0 through <code>len(s)-1</code>.
905 It is illegal to take the address of such an element; if
906 <code>s[i]</code> is the <code>i</code>'th byte of a
907 string, <code>&s[i]</code> is invalid.
911 <h3 id="Array_types">Array types</h3>
914 An array is a numbered sequence of elements of a single
915 type, called the element type.
916 The number of elements is called the length of the array and is never negative.
920 ArrayType = "[" ArrayLength "]" ElementType .
921 ArrayLength = Expression .
926 The length is part of the array's type; it must evaluate to a
927 non-negative <a href="#Constants">constant</a>
928 <a href="#Representability">representable</a> by a value
929 of type <code>int</code>.
930 The length of array <code>a</code> can be discovered
931 using the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
932 The elements can be addressed by integer <a href="#Index_expressions">indices</a>
933 0 through <code>len(a)-1</code>.
934 Array types are always one-dimensional but may be composed to form
935 multi-dimensional types.
940 [2*N] struct { x, y int32 }
943 [2][2][2]float64 // same as [2]([2]([2]float64))
946 <h3 id="Slice_types">Slice types</h3>
949 A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
950 provides access to a numbered sequence of elements from that array.
951 A slice type denotes the set of all slices of arrays of its element type.
952 The number of elements is called the length of the slice and is never negative.
953 The value of an uninitialized slice is <code>nil</code>.
957 SliceType = "[" "]" ElementType .
961 The length of a slice <code>s</code> can be discovered by the built-in function
962 <a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during
963 execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a>
964 0 through <code>len(s)-1</code>. The slice index of a
965 given element may be less than the index of the same element in the
969 A slice, once initialized, is always associated with an underlying
970 array that holds its elements. A slice therefore shares storage
971 with its array and with other slices of the same array; by contrast,
972 distinct arrays always represent distinct storage.
975 The array underlying a slice may extend past the end of the slice.
976 The <i>capacity</i> is a measure of that extent: it is the sum of
977 the length of the slice and the length of the array beyond the slice;
978 a slice of length up to that capacity can be created by
979 <a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
980 The capacity of a slice <code>a</code> can be discovered using the
981 built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
985 A new, initialized slice value for a given element type <code>T</code> is
986 made using the built-in function
987 <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
988 which takes a slice type
989 and parameters specifying the length and optionally the capacity.
990 A slice created with <code>make</code> always allocates a new, hidden array
991 to which the returned slice value refers. That is, executing
995 make([]T, length, capacity)
999 produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
1000 it, so these two expressions are equivalent:
1004 make([]int, 50, 100)
1009 Like arrays, slices are always one-dimensional but may be composed to construct
1010 higher-dimensional objects.
1011 With arrays of arrays, the inner arrays are, by construction, always the same length;
1012 however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
1013 Moreover, the inner slices must be initialized individually.
1016 <h3 id="Struct_types">Struct types</h3>
1019 A struct is a sequence of named elements, called fields, each of which has a
1020 name and a type. Field names may be specified explicitly (IdentifierList) or
1021 implicitly (EmbeddedField).
1022 Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
1023 be <a href="#Uniqueness_of_identifiers">unique</a>.
1027 StructType = "struct" "{" { FieldDecl ";" } "}" .
1028 FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] .
1029 EmbeddedField = [ "*" ] TypeName .
1037 // A struct with 6 fields.
1041 _ float32 // padding
1048 A field declared with a type but no explicit field name is called an <i>embedded field</i>.
1049 An embedded field must be specified as
1050 a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
1051 and <code>T</code> itself may not be
1052 a pointer type. The unqualified type name acts as the field name.
1056 // A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4
1058 T1 // field name is T1
1059 *T2 // field name is T2
1060 P.T3 // field name is T3
1061 *P.T4 // field name is T4
1062 x, y int // field names are x and y
1067 The following declaration is illegal because field names must be unique
1073 T // conflicts with embedded field *T and *P.T
1074 *T // conflicts with embedded field T and *P.T
1075 *P.T // conflicts with embedded field T and *T
1080 A field or <a href="#Method_declarations">method</a> <code>f</code> of an
1081 embedded field in a struct <code>x</code> is called <i>promoted</i> if
1082 <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes
1083 that field or method <code>f</code>.
1087 Promoted fields act like ordinary fields
1088 of a struct except that they cannot be used as field names in
1089 <a href="#Composite_literals">composite literals</a> of the struct.
1093 Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a>
1094 <code>T</code>, promoted methods are included in the method set of the struct as follows:
1098 If <code>S</code> contains an embedded field <code>T</code>,
1099 the <a href="#Method_sets">method sets</a> of <code>S</code>
1100 and <code>*S</code> both include promoted methods with receiver
1101 <code>T</code>. The method set of <code>*S</code> also
1102 includes promoted methods with receiver <code>*T</code>.
1106 If <code>S</code> contains an embedded field <code>*T</code>,
1107 the method sets of <code>S</code> and <code>*S</code> both
1108 include promoted methods with receiver <code>T</code> or
1114 A field declaration may be followed by an optional string literal <i>tag</i>,
1115 which becomes an attribute for all the fields in the corresponding
1116 field declaration. An empty tag string is equivalent to an absent tag.
1117 The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a>
1118 and take part in <a href="#Type_identity">type identity</a> for structs
1119 but are otherwise ignored.
1124 x, y float64 "" // an empty tag string is like an absent tag
1125 name string "any string is permitted as a tag"
1126 _ [4]byte "ceci n'est pas un champ de structure"
1129 // A struct corresponding to a TimeStamp protocol buffer.
1130 // The tag strings define the protocol buffer field numbers;
1131 // they follow the convention outlined by the reflect package.
1133 microsec uint64 `protobuf:"1"`
1134 serverIP6 uint64 `protobuf:"2"`
1138 <h3 id="Pointer_types">Pointer types</h3>
1141 A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given
1142 type, called the <i>base type</i> of the pointer.
1143 The value of an uninitialized pointer is <code>nil</code>.
1147 PointerType = "*" BaseType .
1156 <h3 id="Function_types">Function types</h3>
1159 A function type denotes the set of all functions with the same parameter
1160 and result types. The value of an uninitialized variable of function type
1161 is <code>nil</code>.
1165 FunctionType = "func" Signature .
1166 Signature = Parameters [ Result ] .
1167 Result = Parameters | Type .
1168 Parameters = "(" [ ParameterList [ "," ] ] ")" .
1169 ParameterList = ParameterDecl { "," ParameterDecl } .
1170 ParameterDecl = [ IdentifierList ] [ "..." ] Type .
1174 Within a list of parameters or results, the names (IdentifierList)
1175 must either all be present or all be absent. If present, each name
1176 stands for one item (parameter or result) of the specified type and
1177 all non-<a href="#Blank_identifier">blank</a> names in the signature
1178 must be <a href="#Uniqueness_of_identifiers">unique</a>.
1179 If absent, each type stands for one item of that type.
1180 Parameter and result
1181 lists are always parenthesized except that if there is exactly
1182 one unnamed result it may be written as an unparenthesized type.
1186 The final incoming parameter in a function signature may have
1187 a type prefixed with <code>...</code>.
1188 A function with such a parameter is called <i>variadic</i> and
1189 may be invoked with zero or more arguments for that parameter.
1195 func(a, _ int, z float32) bool
1196 func(a, b int, z float32) (bool)
1197 func(prefix string, values ...int)
1198 func(a, b int, z float64, opt ...interface{}) (success bool)
1199 func(int, int, float64) (float64, *[]int)
1200 func(n int) func(p *T)
1203 <h3 id="Interface_types">Interface types</h3>
1206 An interface type defines a <i>type set</i>.
1207 A variable of interface type can store a value of any type that is in the type
1208 set of the interface. Such a type is said to <i>implement the interface</i>.
1209 The value of an uninitialized variable of interface type is <code>nil</code>.
1213 InterfaceType = "interface" "{" { InterfaceElem ";" } "}" .
1214 InterfaceElem = MethodElem | TypeElem .
1215 MethodElem = MethodName Signature .
1216 MethodName = identifier .
1217 TypeElem = TypeTerm { "|" TypeTerm } .
1218 TypeTerm = Type | UnderlyingType .
1219 UnderlyingType = "~" Type .
1223 An interface type is specified by a list of <i>interface elements</i>.
1224 An interface element is either a <i>method</i> or a <i>type element</i>,
1225 where a type element is a union of one or more <i>type terms</i>.
1226 A type term is either a single type or a single underlying type.
1229 <h4 id="Basic_interfaces">Basic interfaces</h4>
1232 In its most basic form an interface specifies a (possibly empty) list of methods.
1233 The type set defined by such an interface is the set of types which implement all of
1234 those methods, and the corresponding <a href="#Method_sets">method set</a> consists
1235 exactly of the methods specified by the interface.
1236 Interfaces whose type sets can be defined entirely by a list of methods are called
1237 <i>basic interfaces.</i>
1241 // A simple File interface.
1243 Read([]byte) (int, error)
1244 Write([]byte) (int, error)
1250 The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a>
1251 and not <a href="#Blank_identifier">blank</a>.
1257 String() string // illegal: String not unique
1258 _(x int) // illegal: method must have non-blank name
1263 More than one type may implement an interface.
1264 For instance, if two types <code>S1</code> and <code>S2</code>
1269 func (p T) Read(p []byte) (n int, err error)
1270 func (p T) Write(p []byte) (n int, err error)
1271 func (p T) Close() error
1275 (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>)
1276 then the <code>File</code> interface is implemented by both <code>S1</code> and
1277 <code>S2</code>, regardless of what other methods
1278 <code>S1</code> and <code>S2</code> may have or share.
1282 Every type that is a member of the type set of an interface implements that interface.
1283 Any given type may implement several distinct interfaces.
1284 For instance, all types implement the <i>empty interface</i> which stands for the set of all types:
1292 For convenience, the predeclared type <code>any</code> is an alias for the empty interface.
1296 Similarly, consider this interface specification,
1297 which appears within a <a href="#Type_declarations">type declaration</a>
1298 to define an interface called <code>Locker</code>:
1302 type Locker interface {
1309 If <code>S1</code> and <code>S2</code> also implement
1313 func (p T) Lock() { … }
1314 func (p T) Unlock() { … }
1318 they implement the <code>Locker</code> interface as well
1319 as the <code>File</code> interface.
1322 <h4 id="Embedded_interfaces">Embedded interfaces</h4>
1325 In a slightly more general form
1326 an interface <code>T</code> may use a (possibly qualified) interface type
1327 name <code>E</code> as an interface element. This is called
1328 <i>embedding</i> interface <code>E</code> in <code>T</code>.
1329 The type set of <code>T</code> is the <i>intersection</i> of the type sets
1330 defined by <code>T</code>'s explicitly declared methods and the type sets
1331 of <code>T</code>’s embedded interfaces.
1332 In other words, the type set of <code>T</code> is the set of all types that implement all the
1333 explicitly declared methods of <code>T</code> and also all the methods of
1338 type Reader interface {
1339 Read(p []byte) (n int, err error)
1343 type Writer interface {
1344 Write(p []byte) (n int, err error)
1348 // ReadWriter's methods are Read, Write, and Close.
1349 type ReadWriter interface {
1350 Reader // includes methods of Reader in ReadWriter's method set
1351 Writer // includes methods of Writer in ReadWriter's method set
1356 When embedding interfaces, methods with the
1357 <a href="#Uniqueness_of_identifiers">same</a> names must
1358 have <a href="#Type_identity">identical</a> signatures.
1362 type ReadCloser interface {
1363 Reader // includes methods of Reader in ReadCloser's method set
1364 Close() // illegal: signatures of Reader.Close and Close are different
1368 <h4 id="General_interfaces">General interfaces</h4>
1371 In their most general form, an interface element may also be an arbitrary type term
1372 <code>T</code>, or a term of the form <code>~T</code> specifying the underlying type <code>T</code>,
1373 or a union of terms <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>.
1374 Together with method specifications, these elements enable the precise
1375 definition of an interface's type set as follows:
1379 <li>The type set of the empty interface is the set of all types.
1382 <li>The type set of a non-empty interface is the intersection of the type sets
1383 of its interface elements.
1386 <li>The type set of a method specification is the set of types
1387 whose method sets include that method.
1390 <li>The type set of a non-interface type term is the set consisting
1394 <li>The type set of a term of the form <code>~T</code>
1395 is the set of types whose underlying type is <code>T</code>.
1398 <li>The type set of a <i>union</i> of terms
1399 <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>
1400 is the union of the type sets of the terms.
1405 // An interface representing only the type int.
1410 // An interface representing all types with underlying type int.
1415 // An interface representing all types with underlying type int which implement the String method.
1421 // An interface representing an empty type set: there is no type that is both an int and a string.
1429 In a term of the form <code>~T</code>, the underlying type of <code>T</code>
1430 must be itself, and <code>T</code> cannot be an interface.
1437 ~[]byte // the underlying type of []byte is itself
1438 ~MyInt // illegal: the underlying type of MyInt is not MyInt
1439 ~error // illegal: error is an interface
1444 Union elements denote unions of type sets:
1448 // The Floats interface represents all floating-point types
1449 // (including any named types whose underlying types are
1450 // either float32 or float64).
1451 type Floats interface {
1457 In a union, a term cannot be a type parameter, and the type sets of all
1458 non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty).
1459 Given a type parameter <code>P</code>:
1464 P // illegal: the term P is a type parameter
1465 int | P // illegal: the term P is a type parameter
1466 ~int | MyInt // illegal: the type sets for ~int and MyInt are not disjoint (~int includes MyInt)
1467 float32 | Floats // overlapping type sets but Floats is an interface
1472 Implementation restriction:
1473 A union with more than one term cannot contain the
1474 <a href="#Predeclared_identifiers">predeclared identifier</a> <code>comparable</code>
1475 or interfaces that specify methods, or embed <code>comparable</code> or interfaces
1476 that specify methods.
1480 Interfaces that are not <a href="#Basic_interfaces">basic</a> may only be used as type
1481 constraints, or as elements of other interfaces used as constraints.
1482 They cannot be the types of values or variables, or components of other,
1483 non-interface types.
1487 var x Floats // illegal: Floats is not a basic interface
1489 var x interface{} = Floats(nil) // illegal
1491 type Floatish struct {
1496 <!-- TODO The rule below needs to be generalized to interface elements.
1497 It should be factored out and generalized to other types
1498 such as arrays and structs which are currently missing such a
1499 rule. See also #5069.
1503 An interface type <code>T</code> may not embed itself
1504 or any interface type that embeds <code>T</code>, recursively.
1508 // illegal: Bad cannot embed itself
1509 type Bad interface {
1513 // illegal: Bad1 cannot embed itself using Bad2
1514 type Bad1 interface {
1517 type Bad2 interface {
1522 <h3 id="Map_types">Map types</h3>
1525 A map is an unordered group of elements of one type, called the
1526 element type, indexed by a set of unique <i>keys</i> of another type,
1527 called the key type.
1528 The value of an uninitialized map is <code>nil</code>.
1532 MapType = "map" "[" KeyType "]" ElementType .
1537 The <a href="#Comparison_operators">comparison operators</a>
1538 <code>==</code> and <code>!=</code> must be fully defined
1539 for operands of the key type; thus the key type must not be a function, map, or
1541 If the key type is an interface type, these
1542 comparison operators must be defined for the dynamic key values;
1543 failure will cause a <a href="#Run_time_panics">run-time panic</a>.
1548 map[*T]struct{ x, y float64 }
1549 map[string]interface{}
1553 The number of map elements is called its length.
1554 For a map <code>m</code>, it can be discovered using the
1555 built-in function <a href="#Length_and_capacity"><code>len</code></a>
1556 and may change during execution. Elements may be added during execution
1557 using <a href="#Assignments">assignments</a> and retrieved with
1558 <a href="#Index_expressions">index expressions</a>; they may be removed with the
1559 <a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function.
1562 A new, empty map value is made using the built-in
1563 function <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
1564 which takes the map type and an optional capacity hint as arguments:
1568 make(map[string]int)
1569 make(map[string]int, 100)
1573 The initial capacity does not bound its size:
1574 maps grow to accommodate the number of items
1575 stored in them, with the exception of <code>nil</code> maps.
1576 A <code>nil</code> map is equivalent to an empty map except that no elements
1579 <h3 id="Channel_types">Channel types</h3>
1582 A channel provides a mechanism for
1583 <a href="#Go_statements">concurrently executing functions</a>
1585 <a href="#Send_statements">sending</a> and
1586 <a href="#Receive_operator">receiving</a>
1587 values of a specified element type.
1588 The value of an uninitialized channel is <code>nil</code>.
1592 ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType .
1596 The optional <code><-</code> operator specifies the channel <i>direction</i>,
1597 <i>send</i> or <i>receive</i>. If a direction is given, the channel is <i>directional</i>,
1598 otherwise it is <i>bidirectional</i>.
1599 A channel may be constrained only to send or only to receive by
1600 <a href="#Assignments">assignment</a> or
1601 explicit <a href="#Conversions">conversion</a>.
1605 chan T // can be used to send and receive values of type T
1606 chan<- float64 // can only be used to send float64s
1607 <-chan int // can only be used to receive ints
1611 The <code><-</code> operator associates with the leftmost <code>chan</code>
1616 chan<- chan int // same as chan<- (chan int)
1617 chan<- <-chan int // same as chan<- (<-chan int)
1618 <-chan <-chan int // same as <-chan (<-chan int)
1619 chan (<-chan int)
1623 A new, initialized channel
1624 value can be made using the built-in function
1625 <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
1626 which takes the channel type and an optional <i>capacity</i> as arguments:
1634 The capacity, in number of elements, sets the size of the buffer in the channel.
1635 If the capacity is zero or absent, the channel is unbuffered and communication
1636 succeeds only when both a sender and receiver are ready. Otherwise, the channel
1637 is buffered and communication succeeds without blocking if the buffer
1638 is not full (sends) or not empty (receives).
1639 A <code>nil</code> channel is never ready for communication.
1643 A channel may be closed with the built-in function
1644 <a href="#Close"><code>close</code></a>.
1645 The multi-valued assignment form of the
1646 <a href="#Receive_operator">receive operator</a>
1647 reports whether a received value was sent before
1648 the channel was closed.
1652 A single channel may be used in
1653 <a href="#Send_statements">send statements</a>,
1654 <a href="#Receive_operator">receive operations</a>,
1655 and calls to the built-in functions
1656 <a href="#Length_and_capacity"><code>cap</code></a> and
1657 <a href="#Length_and_capacity"><code>len</code></a>
1658 by any number of goroutines without further synchronization.
1659 Channels act as first-in-first-out queues.
1660 For example, if one goroutine sends values on a channel
1661 and a second goroutine receives them, the values are
1662 received in the order sent.
1665 <h3 id="Type_parameters">Type parameters</h3>
1668 A <i>type parameter</i> is an (unqualified) type name declared in the
1669 <a href="#Type_parameter_lists">type parameter list</a> of a
1670 <a href="#Function_declarations">function declaration</a> or
1671 <a href="#Type_definitions">type definition</a>; or in the receiver specification
1672 of a <a href="#Method_declarations">method declaration</a> that is associated
1673 with a generic type.
1674 A type parameter acts as a place holder for an (as of yet) unknown type in the declaration;
1675 the type parameter is replaced with a <i>type argument</i> upon
1676 <a href="#Instantiations">instantiation</a> of the generic function or type.
1680 The properties of a type parameter are determined by its
1681 <a href="#Type_constraints">type constraint</a>.
1684 <h2 id="Properties_of_types_and_values">Properties of types and values</h2>
1686 <h3 id="Underlying_types">Underlying types</h3>
1689 Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
1690 is one of the predeclared boolean, numeric, or string types, or a type literal,
1691 the corresponding underlying type is <code>T</code> itself.
1692 Otherwise, <code>T</code>'s underlying type is the underlying type of the
1693 type to which <code>T</code> refers in its <a href="#Type_declarations">type
1694 declaration</a>. The underlying type of a type parameter is the
1695 underlying type of its <a href="#Type_constraints">type constraint</a>, which
1696 is always an interface.
1712 func f[P any](x P) { … }
1716 The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>,
1717 and <code>B2</code> is <code>string</code>.
1718 The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>.
1719 The underlying type of <code>P</code> is <code>interface{}</code>.
1722 <h3 id="Core_types">Core types</h3>
1725 Each non-interface type <code>T</code> has a <i>core type</i>, which is the same as the
1726 <a href="#Underlying_types">underlying type</a> of <code>T</code>.
1730 An interface <code>T</code> has a core type if one of the following
1731 conditions is satisfied:
1736 There is a single type <code>U</code> which is the <a href="#Underlying_types">underlying type</a>
1737 of all types in the <a href="#Interface_types">type set</a> of <code>T</code>; or
1740 the type set of <code>T</code> contains only <a href="#Channel_types">channel types</a>
1741 with identical element type <code>E</code>, and all directional channels have the same
1747 All other interfaces don't have a core type.
1751 The core type of an interface is, depending on the condition that is satisfied, either:
1756 the type <code>U</code>; or
1759 the type <code>chan E</code> if <code>T</code> contains only bidirectional
1760 channels, or the type <code>chan<- E</code> or <code><-chan E</code>
1761 depending on the direction of the directional channels present.
1766 By definition, a core type is never a <a href="#Type_definitions">defined type</a>,
1767 <a href="#Type_parameters">type parameter</a>, or
1768 <a href="#Interface_types">interface type</a>.
1772 Examples of interfaces with core types:
1776 type Celsius float32
1779 interface{ int } // int
1780 interface{ Celsius|Kelvin } // float32
1781 interface{ ~chan int } // chan int
1782 interface{ ~chan int|~chan<- int } // chan<- int
1783 interface{ ~[]*data; String() string } // []*data
1787 Examples of interfaces whithout core types:
1791 interface{} // no single underlying type
1792 interface{ Celsius|float64 } // no single underlying type
1793 interface{ chan int | chan<- string } // channels have different element types
1794 interface{ <-chan int | chan<- int } // directional channels have different directions
1797 <h3 id="Specific_types">Specific types</h3>
1800 An interface specification that contains <a href="#Interface_types">type elements</a>
1801 defines a (possibly empty) set of <i>specific types</i>.
1802 Loosely speaking, these are the types <code>T</code> that appear in the
1803 interface definition in terms of the form <code>T</code>, <code>~T</code>,
1804 or in unions of such terms.
1808 More precisely, for a given interface, the set of specific types corresponds to
1809 the set 𝑅 of representative types of the interface, if 𝑅 is non-empty and finite.
1810 Otherwise, if 𝑅 is empty or infinite, the interface has <i>no specific types</i>.
1814 For a given interface, type element or type term, the set 𝑅 of representative types is defined as follows:
1818 <li>For an interface with no type elements, 𝑅 is the (infinite) set of all types.
1821 <li>For an interface with type elements,
1822 𝑅 is the intersection of the representative types of its type elements.
1825 <li>For a non-interface type term <code>T</code> or a term of the form <code>~T</code>,
1826 𝑅 is the set consisting of the type <code>T</code>.
1829 <li>For a <i>union</i> of terms
1830 <code>t<sub>1</sub>|t<sub>2</sub>|…|t<sub>n</sub></code>,
1831 𝑅 is the union of the representative types of the terms.
1836 An interface may have specific types even if its <a href="#Interface_types">type set</a>
1841 Examples of interfaces with their specific types:
1845 interface{} // no specific types
1846 interface{ int } // int
1847 interface{ ~string } // string
1848 interface{ int|~string } // int, string
1849 interface{ Celsius|Kelvin } // Celsius, Kelvin
1850 interface{ float64|any } // no specific types (union is all types)
1851 interface{ int; m() } // int (but type set is empty because int has no method m)
1852 interface{ ~int; m() } // int (but type set is infinite because many integer types have a method m)
1853 interface{ int; any } // int
1854 interface{ int; string } // no specific types (intersection is empty)
1857 <h3 id="Type_identity">Type identity</h3>
1860 Two types are either <i>identical</i> or <i>different</i>.
1864 A <a href="#Types">named type</a> is always different from any other type.
1865 Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are
1866 structurally equivalent; that is, they have the same literal structure and corresponding
1867 components have identical types. In detail:
1871 <li>Two array types are identical if they have identical element types and
1872 the same array length.</li>
1874 <li>Two slice types are identical if they have identical element types.</li>
1876 <li>Two struct types are identical if they have the same sequence of fields,
1877 and if corresponding fields have the same names, and identical types,
1879 <a href="#Exported_identifiers">Non-exported</a> field names from different
1880 packages are always different.</li>
1882 <li>Two pointer types are identical if they have identical base types.</li>
1884 <li>Two function types are identical if they have the same number of parameters
1885 and result values, corresponding parameter and result types are
1886 identical, and either both functions are variadic or neither is.
1887 Parameter and result names are not required to match.</li>
1889 <li>Two interface types are identical if they define the same type set.
1892 <li>Two map types are identical if they have identical key and element types.</li>
1894 <li>Two channel types are identical if they have identical element types and
1895 the same direction.</li>
1897 <li>Two <a href="#Instantiations">instantiated</a> types are identical if
1898 their defined types and all type arguments are identical.
1903 Given the declarations
1910 A2 = struct{ a, b int }
1912 A4 = func(A3, float64) *A0
1913 A5 = func(x int, _ float64) *[]string
1917 B2 struct{ a, b int }
1918 B3 struct{ a, c int }
1919 B4 func(int, float64) *B0
1920 B5 func(x int, y float64) *A1
1923 D0[P1, P2 any] struct{ x P1; y P2 }
1924 E0 = D0[int, string]
1929 these types are identical:
1933 A0, A1, and []string
1934 A2 and struct{ a, b int }
1936 A4, func(int, float64) *[]string, and A5
1939 D0[int, string] and E0
1941 struct{ a, b *T5 } and struct{ a, b *T5 }
1942 func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5
1946 <code>B0</code> and <code>B1</code> are different because they are new types
1947 created by distinct <a href="#Type_definitions">type definitions</a>;
1948 <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code>
1949 are different because <code>B0</code> is different from <code>[]string</code>;
1950 and <code>P1</code> and <code>P2</code> are different because they are different
1952 <code>D0[int, string]</code> and <code>struct{ x int; y string }</code> are
1953 different because the former is an <a href="#Instantiations">instantiated</a>
1954 defined type while the latter is a type literal
1955 (but they are still <a href="#Assignability">assignable</a>).
1958 <h3 id="Assignability">Assignability</h3>
1961 A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code>
1962 ("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies:
1967 <code>x</code>'s type is identical to <code>T</code>.
1970 <code>x</code>'s type <code>V</code> and <code>T</code> have identical
1971 <a href="#Underlying_types">underlying types</a> and at least one of <code>V</code>
1972 or <code>T</code> is not a <a href="#Types">named type</a>.
1975 <code>x</code>'s type <code>V</code> and <code>T</code> are channel types with
1976 identical element types, <code>V</code> is a bidirectional channel,
1977 and at least one of <code>V</code> or <code>T</code> is not a <a href="#Types">named type</a>.
1980 <code>T</code> is an interface type, but not a type parameter, and
1981 <code>x</code> <a href="#Interface_types">implements</a> <code>T</code>.
1984 <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
1985 is a pointer, function, slice, map, channel, or interface type,
1986 but not a type parameter.
1989 <code>x</code> is an untyped <a href="#Constants">constant</a>
1990 <a href="#Representability">representable</a>
1991 by a value of type <code>T</code>.
1996 Additionally, if <code>x's</code> type <code>V</code> or <code>T</code> are type parameters
1997 with <a href="#Specific_types">specific types</a>, <code>x</code>
1998 is assignable to a variable of type <code>T</code> if one of the following conditions applies:
2003 <code>x</code> is the predeclared identifier <code>nil</code>, <code>T</code> is
2004 a type parameter, and <code>x</code> is assignable to each specific type of
2008 <code>V</code> is not a <a href="#Types">named type</a>, <code>T</code> is
2009 a type parameter, and <code>x</code> is assignable to each specific type of
2013 <code>V</code> is a type parameter and <code>T</code> is not a named type,
2014 and values of each specific type of <code>V</code> are assignable
2019 <h3 id="Representability">Representability</h3>
2022 A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i>
2023 by a value of type <code>T</code>,
2024 where <code>T</code> is not a <a href="#Type_parameters">type parameter</a>,
2025 if one of the following conditions applies:
2030 <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>.
2034 <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
2035 precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE
2036 negative zero further simplified to an unsigned zero. Note that constant values never result
2037 in an IEEE negative zero, NaN, or infinity.
2041 <code>T</code> is a complex type, and <code>x</code>'s
2042 <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code>
2043 are representable by values of <code>T</code>'s component type (<code>float32</code> or
2044 <code>float64</code>).
2049 If <code>T</code> is a type parameter with <a href="#Specific_types">specific types</a>,
2050 <code>x</code> is representable by a value of type <code>T</code> if <code>x</code> is representable
2051 by a value of each specific type of <code>T</code>.
2055 x T x is representable by a value of T because
2057 'a' byte 97 is in the set of byte values
2058 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers
2059 "foo" string "foo" is in the set of string values
2060 1024 int16 1024 is in the set of 16-bit integers
2061 42.0 byte 42 is in the set of unsigned 8-bit integers
2062 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers
2063 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values
2064 -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0
2065 0i int 0 is an integer value
2066 (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values
2070 x T x is not representable by a value of T because
2072 0 bool 0 is not in the set of boolean values
2073 'a' string 'a' is a rune, it is not in the set of string values
2074 1024 byte 1024 is not in the set of unsigned 8-bit integers
2075 -1 uint16 -1 is not in the set of unsigned 16-bit integers
2076 1.1 int 1.1 is not an integer value
2077 42i float32 (0 + 42i) is not in the set of float32 values
2078 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding
2081 <h3 id="Method_sets">Method sets</h3>
2084 The <i>method set</i> of a type determines the methods that can be
2085 <a href="#Calls">called</a> on an <a href="#Operands">operand</a> of that type.
2086 Every type has a (possibly empty) method set associated with it:
2090 <li>The method set of a <a href="#Type_definitions">defined type</a> <code>T</code> consists of all
2091 <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>.
2095 The method set of a pointer to a defined type <code>T</code>
2096 (where <code>T</code> is neither a pointer nor an interface)
2097 is the set of all methods declared with receiver <code>*T</code> or <code>T</code>.
2100 <li>The method set of an <a href="#Interface_types">interface type</a> is the intersection
2101 of the method sets of each type in the interface's <a href="#Interface_types">type set</a>
2102 (the resulting method set is usually just the set of declared methods in the interface).
2107 Further rules apply to structs (and pointer to structs) containing embedded fields,
2108 as described in the section on <a href="#Struct_types">struct types</a>.
2109 Any other type has an empty method set.
2113 In a method set, each method must have a
2114 <a href="#Uniqueness_of_identifiers">unique</a>
2115 non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>.
2118 <h2 id="Blocks">Blocks</h2>
2121 A <i>block</i> is a possibly empty sequence of declarations and statements
2122 within matching brace brackets.
2126 Block = "{" StatementList "}" .
2127 StatementList = { Statement ";" } .
2131 In addition to explicit blocks in the source code, there are implicit blocks:
2135 <li>The <i>universe block</i> encompasses all Go source text.</li>
2137 <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
2138 Go source text for that package.</li>
2140 <li>Each file has a <i>file block</i> containing all Go source text
2143 <li>Each <a href="#If_statements">"if"</a>,
2144 <a href="#For_statements">"for"</a>, and
2145 <a href="#Switch_statements">"switch"</a>
2146 statement is considered to be in its own implicit block.</li>
2148 <li>Each clause in a <a href="#Switch_statements">"switch"</a>
2149 or <a href="#Select_statements">"select"</a> statement
2150 acts as an implicit block.</li>
2154 Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
2158 <h2 id="Declarations_and_scope">Declarations and scope</h2>
2161 A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a
2162 <a href="#Constant_declarations">constant</a>,
2163 <a href="#Type_declarations">type</a>,
2164 <a href="#Variable_declarations">variable</a>,
2165 <a href="#Function_declarations">function</a>,
2166 <a href="#Labeled_statements">label</a>, or
2167 <a href="#Import_declarations">package</a>.
2168 Every identifier in a program must be declared.
2169 No identifier may be declared twice in the same block, and
2170 no identifier may be declared in both the file and package block.
2174 The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
2175 in a declaration, but it does not introduce a binding and thus is not declared.
2176 In the package block, the identifier <code>init</code> may only be used for
2177 <a href="#Package_initialization"><code>init</code> function</a> declarations,
2178 and like the blank identifier it does not introduce a new binding.
2182 Declaration = ConstDecl | TypeDecl | VarDecl .
2183 TopLevelDecl = Declaration | FunctionDecl | MethodDecl .
2187 The <i>scope</i> of a declared identifier is the extent of source text in which
2188 the identifier denotes the specified constant, type, variable, function, label, or package.
2192 Go is lexically scoped using <a href="#Blocks">blocks</a>:
2196 <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li>
2198 <li>The scope of an identifier denoting a constant, type, variable,
2199 or function (but not method) declared at top level (outside any
2200 function) is the package block.</li>
2202 <li>The scope of the package name of an imported package is the file block
2203 of the file containing the import declaration.</li>
2205 <li>The scope of an identifier denoting a method receiver, function parameter,
2206 or result variable is the function body.</li>
2208 <li>The scope of an identifier denoting a type parameter of a generic function
2209 or declared by a method receiver is the function body and all parameter lists of the
2213 <li>The scope of an identifier denoting a type parameter of a generic type
2214 begins after the name of the generic type and ends at the end
2215 of the TypeSpec.</li>
2217 <li>The scope of a constant or variable identifier declared
2218 inside a function begins at the end of the ConstSpec or VarSpec
2219 (ShortVarDecl for short variable declarations)
2220 and ends at the end of the innermost containing block.</li>
2222 <li>The scope of a type identifier declared inside a function
2223 begins at the identifier in the TypeSpec
2224 and ends at the end of the innermost containing block.</li>
2228 An identifier declared in a block may be redeclared in an inner block.
2229 While the identifier of the inner declaration is in scope, it denotes
2230 the entity declared by the inner declaration.
2234 The <a href="#Package_clause">package clause</a> is not a declaration; the package name
2235 does not appear in any scope. Its purpose is to identify the files belonging
2236 to the same <a href="#Packages">package</a> and to specify the default package name for import
2241 <h3 id="Label_scopes">Label scopes</h3>
2244 Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
2245 used in the <a href="#Break_statements">"break"</a>,
2246 <a href="#Continue_statements">"continue"</a>, and
2247 <a href="#Goto_statements">"goto"</a> statements.
2248 It is illegal to define a label that is never used.
2249 In contrast to other identifiers, labels are not block scoped and do
2250 not conflict with identifiers that are not labels. The scope of a label
2251 is the body of the function in which it is declared and excludes
2252 the body of any nested function.
2256 <h3 id="Blank_identifier">Blank identifier</h3>
2259 The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
2260 It serves as an anonymous placeholder instead of a regular (non-blank)
2261 identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
2262 as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>.
2266 <h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
2269 The following identifiers are implicitly declared in the
2270 <a href="#Blocks">universe block</a>:
2272 <pre class="grammar">
2274 any bool byte comparable
2275 complex64 complex128 error float32 float64
2276 int int8 int16 int32 int64 rune string
2277 uint uint8 uint16 uint32 uint64 uintptr
2286 append cap close complex copy delete imag len
2287 make new panic print println real recover
2290 <h3 id="Exported_identifiers">Exported identifiers</h3>
2293 An identifier may be <i>exported</i> to permit access to it from another package.
2294 An identifier is exported if both:
2297 <li>the first character of the identifier's name is a Unicode upper case
2298 letter (Unicode class "Lu"); and</li>
2299 <li>the identifier is declared in the <a href="#Blocks">package block</a>
2300 or it is a <a href="#Struct_types">field name</a> or
2301 <a href="#MethodName">method name</a>.</li>
2304 All other identifiers are not exported.
2307 <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3>
2310 Given a set of identifiers, an identifier is called <i>unique</i> if it is
2311 <i>different</i> from every other in the set.
2312 Two identifiers are different if they are spelled differently, or if they
2313 appear in different <a href="#Packages">packages</a> and are not
2314 <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same.
2317 <h3 id="Constant_declarations">Constant declarations</h3>
2320 A constant declaration binds a list of identifiers (the names of
2321 the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>.
2322 The number of identifiers must be equal
2323 to the number of expressions, and the <i>n</i>th identifier on
2324 the left is bound to the value of the <i>n</i>th expression on the
2329 ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
2330 ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] .
2332 IdentifierList = identifier { "," identifier } .
2333 ExpressionList = Expression { "," Expression } .
2337 If the type is present, all constants take the type specified, and
2338 the expressions must be <a href="#Assignability">assignable</a> to that type,
2339 which must not be a type parameter.
2340 If the type is omitted, the constants take the
2341 individual types of the corresponding expressions.
2342 If the expression values are untyped <a href="#Constants">constants</a>,
2343 the declared constants remain untyped and the constant identifiers
2344 denote the constant values. For instance, if the expression is a
2345 floating-point literal, the constant identifier denotes a floating-point
2346 constant, even if the literal's fractional part is zero.
2350 const Pi float64 = 3.14159265358979323846
2351 const zero = 0.0 // untyped floating-point constant
2354 eof = -1 // untyped integer constant
2356 const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants
2357 const u, v float32 = 0, 3 // u = 0.0, v = 3.0
2361 Within a parenthesized <code>const</code> declaration list the
2362 expression list may be omitted from any but the first ConstSpec.
2363 Such an empty list is equivalent to the textual substitution of the
2364 first preceding non-empty expression list and its type if any.
2365 Omitting the list of expressions is therefore equivalent to
2366 repeating the previous list. The number of identifiers must be equal
2367 to the number of expressions in the previous list.
2368 Together with the <a href="#Iota"><code>iota</code> constant generator</a>
2369 this mechanism permits light-weight declaration of sequential values:
2381 numberOfDays // this constant is not exported
2386 <h3 id="Iota">Iota</h3>
2389 Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
2390 <code>iota</code> represents successive untyped integer <a href="#Constants">
2391 constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a>
2392 in that constant declaration, starting at zero.
2393 It can be used to construct a set of related constants:
2398 c0 = iota // c0 == 0
2399 c1 = iota // c1 == 1
2400 c2 = iota // c2 == 2
2404 a = 1 << iota // a == 1 (iota == 0)
2405 b = 1 << iota // b == 2 (iota == 1)
2406 c = 3 // c == 3 (iota == 2, unused)
2407 d = 1 << iota // d == 8 (iota == 3)
2411 u = iota * 42 // u == 0 (untyped integer constant)
2412 v float64 = iota * 42 // v == 42.0 (float64 constant)
2413 w = iota * 42 // w == 84 (untyped integer constant)
2416 const x = iota // x == 0
2417 const y = iota // y == 0
2421 By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value:
2426 bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0)
2427 bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1)
2428 _, _ // (iota == 2, unused)
2429 bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3)
2434 This last example exploits the <a href="#Constant_declarations">implicit repetition</a>
2435 of the last non-empty expression list.
2439 <h3 id="Type_declarations">Type declarations</h3>
2442 A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>.
2443 Type declarations come in two forms: alias declarations and type definitions.
2447 TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
2448 TypeSpec = AliasDecl | TypeDef .
2451 <h4 id="Alias_declarations">Alias declarations</h4>
2454 An alias declaration binds an identifier to the given type.
2458 AliasDecl = identifier "=" Type .
2462 Within the <a href="#Declarations_and_scope">scope</a> of
2463 the identifier, it serves as an <i>alias</i> for the type.
2468 nodeList = []*Node // nodeList and []*Node are identical types
2469 Polar = polar // Polar and polar denote identical types
2474 <h4 id="Type_definitions">Type definitions</h4>
2477 A type definition creates a new, distinct type with the same
2478 <a href="#Types">underlying type</a> and operations as the given type
2479 and binds an identifier, the <i>type name</i>, to it.
2483 TypeDef = identifier [ TypeParameters ] Type .
2487 The new type is called a <i>defined type</i>.
2488 It is <a href="#Type_identity">different</a> from any other type,
2489 including the type it is created from.
2494 Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types
2495 polar Point // polar and Point denote different types
2498 type TreeNode struct {
2499 left, right *TreeNode
2503 type Block interface {
2505 Encrypt(src, dst []byte)
2506 Decrypt(src, dst []byte)
2511 A defined type may have <a href="#Method_declarations">methods</a> associated with it.
2512 It does not inherit any methods bound to the given type,
2513 but the <a href="#Method_sets">method set</a>
2514 of an interface type or of elements of a composite type remains unchanged:
2518 // A Mutex is a data type with two methods, Lock and Unlock.
2519 type Mutex struct { /* Mutex fields */ }
2520 func (m *Mutex) Lock() { /* Lock implementation */ }
2521 func (m *Mutex) Unlock() { /* Unlock implementation */ }
2523 // NewMutex has the same composition as Mutex but its method set is empty.
2526 // The method set of PtrMutex's underlying type *Mutex remains unchanged,
2527 // but the method set of PtrMutex is empty.
2528 type PtrMutex *Mutex
2530 // The method set of *PrintableMutex contains the methods
2531 // Lock and Unlock bound to its embedded field Mutex.
2532 type PrintableMutex struct {
2536 // MyBlock is an interface type that has the same method set as Block.
2541 Type definitions may be used to define different boolean, numeric,
2542 or string types and associate methods with them:
2549 EST TimeZone = -(5 + iota)
2555 func (tz TimeZone) String() string {
2556 return fmt.Sprintf("GMT%+dh", tz)
2561 If the type definition specifies <a href="#Type_parameter_lists">type parameters</a>,
2562 the type name denotes a <i>generic type</i>.
2563 Generic types must be <a href="#Instantiations">instantiated</a> when they
2568 type List[T any] struct {
2573 type Tree[T constraints.Ordered] struct {
2574 left, right *Tree[T]
2580 The given type cannot be a type parameter in a type definition.
2584 type T[P any] P // illegal: P is a type parameter
2587 type L T // illegal: T is a type parameter declared by the enclosing function
2592 A generic type may also have methods associated with it. In this case,
2593 the method receivers must declare the same number of type parameters as
2594 present in the generic type definition.
2598 // The method Len returns the number of elements in the linked list l.
2599 func (l *List[T]) Len() int { … }
2602 <h3 id="Type_parameter_lists">Type parameter lists</h3>
2605 A type parameter list declares the <a href="#Type_parameters">type parameters</a>
2606 in a generic function or type declaration.
2607 The type parameter list looks like an ordinary <a href="#Function_types">function parameter list</a>
2608 except that the type parameter names must all be present and the list is enclosed
2609 in square brackets rather than parentheses.
2613 TypeParameters = "[" TypeParamList [ "," ] "]" .
2614 TypeParamList = TypeParamDecl { "," TypeParamDecl } .
2615 TypeParamDecl = IdentifierList TypeConstraint .
2619 Each identifier declares a type parameter.
2620 All non-blank names in the list must be unique.
2621 Each type parameter is a new and different <a href="#Types">named type</a>.
2626 [S interface{ ~[]byte|string }]
2633 Just as each ordinary function parameter has a parameter type, each type parameter
2634 has a corresponding (meta-)type which is called its
2635 <a href="#Type_constraints"><i>type constraint</i></a>.
2639 A parsing ambiguity arises when the type parameter list for a generic type
2640 declares a single type parameter with a type constraint of the form <code>*C</code>
2641 or <code>(C)</code> where <code>C</code> is not a (possibly parenthesized)
2642 <a href="#Types">type literal</a>:
2651 In these rare cases, the type parameter declaration is indistinguishable from
2652 the expressions <code>P*C</code> or <code>P(C)</code> and the type declaration
2653 is parsed as an array type declaration.
2654 To resolve the ambiguity, embed the constraint in an interface or use a trailing
2659 type T[P interface{*C}] …
2663 <h4 id="Type_constraints">Type constraints</h4>
2666 A type constraint is an <a href="#Interface_types">interface</a> that defines the
2667 set of permissible type arguments for the respective type parameter and controls the
2668 operations supported by values of that type parameter.
2672 TypeConstraint = TypeElem .
2676 If the constraint is an interface literal of the form <code>interface{E}</code> where
2677 <code>E</code> is an embedded type element (not a method), in a type parameter list
2678 the enclosing <code>interface{ … }</code> may be omitted for convenience:
2682 [T *P] // = [T interface{*P}]
2683 [T ~int] // = [T interface{~int}]
2684 [T int|string] // = [T interface{int|string}]
2685 type Constraint ~int // illegal: ~int is not inside a type parameter list
2689 We should be able to simplify the rules for comparable or delegate some of them
2690 elsewhere once we have a section that clearly defines how interfaces implement
2691 other interfaces based on their type sets. But this should get us going for now.
2695 The <a href="#Predeclared_identifiers">predeclared</a>
2696 <a href="#Interface_types">interface type</a> <code>comparable</code>
2697 denotes the set of all concrete (non-interface) types that are
2698 <a href="#Comparison_operators">comparable</a>. Specifically,
2699 a type <code>T</code> implements <code>comparable</code> if:
2704 <code>T</code> is not an interface type and <code>T</code> supports the operations
2705 <code>==</code> and <code>!=</code>; or
2708 <code>T</code> is an interface type and each type in <code>T</code>'s
2709 <a href="#Interface_types">type set</a> implements <code>comparable</code>.
2714 Even though interfaces that are not type parameters can be
2715 <a href="#Comparison_operators">compared</a>
2716 (possibly causing a run-time panic) they do not implement
2717 <code>comparable</code>.
2721 int // implements comparable
2722 []byte // does not implement comparable (slices cannot be compared)
2723 interface{} // does not implement comparable (see above)
2724 interface{ ~int | ~string } // type parameter only: implements comparable
2725 interface{ comparable } // type parameter only: implements comparable
2726 interface{ ~int | ~[]byte } // type parameter only: does not implement comparable (not all types in the type set are comparable)
2730 The <code>comparable</code> interface and interfaces that (directly or indirectly) embed
2731 <code>comparable</code> may only be used as type constraints. They cannot be the types of
2732 values or variables, or components of other, non-interface types.
2735 <h3 id="Variable_declarations">Variable declarations</h3>
2738 A variable declaration creates one or more <a href="#Variables">variables</a>,
2739 binds corresponding identifiers to them, and gives each a type and an initial value.
2743 VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
2744 VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
2751 var x, y float32 = -1, -2
2754 u, v, s = 2.0, 3.0, "bar"
2756 var re, im = complexSqrt(-1)
2757 var _, found = entries[name] // map lookup; only interested in "found"
2761 If a list of expressions is given, the variables are initialized
2762 with the expressions following the rules for <a href="#Assignments">assignments</a>.
2763 Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
2767 If a type is present, each variable is given that type.
2768 Otherwise, each variable is given the type of the corresponding
2769 initialization value in the assignment.
2770 If that value is an untyped constant, it is first implicitly
2771 <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
2772 if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
2773 The predeclared value <code>nil</code> cannot be used to initialize a variable
2774 with no explicit type.
2778 var d = math.Sin(0.5) // d is float64
2779 var i = 42 // i is int
2780 var t, ok = x.(T) // t is T, ok is bool
2781 var n = nil // illegal
2785 Implementation restriction: A compiler may make it illegal to declare a variable
2786 inside a <a href="#Function_declarations">function body</a> if the variable is
2790 <h3 id="Short_variable_declarations">Short variable declarations</h3>
2793 A <i>short variable declaration</i> uses the syntax:
2797 ShortVarDecl = IdentifierList ":=" ExpressionList .
2801 It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
2802 with initializer expressions but no types:
2805 <pre class="grammar">
2806 "var" IdentifierList = ExpressionList .
2811 f := func() int { return 7 }
2812 ch := make(chan int)
2813 r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any
2814 _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate
2818 Unlike regular variable declarations, a short variable declaration may <i>redeclare</i>
2819 variables provided they were originally declared earlier in the same block
2820 (or the parameter lists if the block is the function body) with the same type,
2821 and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new.
2822 As a consequence, redeclaration can only appear in a multi-variable short declaration.
2823 Redeclaration does not introduce a new variable; it just assigns a new value to the original.
2827 field1, offset := nextField(str, 0)
2828 field2, offset := nextField(str, offset) // redeclares offset
2829 a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere
2833 Short variable declarations may appear only inside functions.
2834 In some contexts such as the initializers for
2835 <a href="#If_statements">"if"</a>,
2836 <a href="#For_statements">"for"</a>, or
2837 <a href="#Switch_statements">"switch"</a> statements,
2838 they can be used to declare local temporary variables.
2841 <h3 id="Function_declarations">Function declarations</h3>
2844 Given the importance of functions, this section has always
2845 been woefully underdeveloped. Would be nice to expand this
2850 A function declaration binds an identifier, the <i>function name</i>,
2855 FunctionDecl = "func" FunctionName [ TypeParameters ] Signature [ FunctionBody ] .
2856 FunctionName = identifier .
2857 FunctionBody = Block .
2861 If the function's <a href="#Function_types">signature</a> declares
2862 result parameters, the function body's statement list must end in
2863 a <a href="#Terminating_statements">terminating statement</a>.
2867 func IndexRune(s string, r rune) int {
2868 for i, c := range s {
2873 // invalid: missing return statement
2878 If the function declaration specifies <a href="#Type_parameter_lists">type parameters</a>,
2879 the function name denotes a <i>generic function</i>.
2880 Generic functions must be <a href="#Instantiations">instantiated</a> when they
2885 func min[T constraints.Ordered](x, y T) T {
2894 A function declaration without type parameters may omit the body.
2895 Such a declaration provides the signature for a function implemented outside Go,
2896 such as an assembly routine.
2900 func flushICache(begin, end uintptr) // implemented externally
2903 <h3 id="Method_declarations">Method declarations</h3>
2906 A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
2907 A method declaration binds an identifier, the <i>method name</i>, to a method,
2908 and associates the method with the receiver's <i>base type</i>.
2912 MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] .
2913 Receiver = Parameters .
2917 The receiver is specified via an extra parameter section preceding the method
2918 name. That parameter section must declare a single non-variadic parameter, the receiver.
2919 Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a
2920 pointer to a defined type <code>T</code>, possibly followed by a list of type parameter
2921 names <code>[P1, P2, …]</code> enclosed in square brackets.
2922 <code>T</code> is called the receiver <i>base type</i>. A receiver base type cannot be
2923 a pointer or interface type and it must be defined in the same package as the method.
2924 The method is said to be <i>bound</i> to its receiver base type and the method name
2925 is visible only within <a href="#Selectors">selectors</a> for type <code>T</code>
2930 A non-<a href="#Blank_identifier">blank</a> receiver identifier must be
2931 <a href="#Uniqueness_of_identifiers">unique</a> in the method signature.
2932 If the receiver's value is not referenced inside the body of the method,
2933 its identifier may be omitted in the declaration. The same applies in
2934 general to parameters of functions and methods.
2938 For a base type, the non-blank names of methods bound to it must be unique.
2939 If the base type is a <a href="#Struct_types">struct type</a>,
2940 the non-blank method and field names must be distinct.
2944 Given defined type <code>Point</code>, the declarations
2948 func (p *Point) Length() float64 {
2949 return math.Sqrt(p.x * p.x + p.y * p.y)
2952 func (p *Point) Scale(factor float64) {
2959 bind the methods <code>Length</code> and <code>Scale</code>,
2960 with receiver type <code>*Point</code>,
2961 to the base type <code>Point</code>.
2965 If the receiver base type is a <a href="#Type_declarations">generic type</a>, the
2966 receiver specification must declare corresponding type parameters for the method
2967 to use. This makes the receiver type parameters available to the method.
2971 Syntactically, this type parameter declaration looks like an
2972 <a href="#Instantiations">instantiation</a> of the receiver base type, except that
2973 the type arguments are the type parameters being declared, one for each type parameter
2974 of the receiver base type.
2975 The type parameter names do not need to match their corresponding parameter names in the
2976 receiver base type definition, and all non-blank parameter names must be unique in the
2977 receiver parameter section and the method signature.
2978 The receiver type parameter constraints are implied by the receiver base type definition:
2979 corresponding type parameters have corresponding constraints.
2983 type Pair[A, B any] struct {
2988 func (p Pair[A, B]) Swap() Pair[B, A] { return Pair[B, A]{p.b, p.a} }
2989 func (p Pair[First, _]) First() First { return p.a }
2992 <h2 id="Expressions">Expressions</h2>
2995 An expression specifies the computation of a value by applying
2996 operators and functions to operands.
2999 <h3 id="Operands">Operands</h3>
3002 Operands denote the elementary values in an expression. An operand may be a
3003 literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
3004 non-<a href="#Blank_identifier">blank</a> identifier denoting a
3005 <a href="#Constant_declarations">constant</a>,
3006 <a href="#Variable_declarations">variable</a>, or
3007 <a href="#Function_declarations">function</a>,
3008 or a parenthesized expression.
3012 Operand = Literal | OperandName [ TypeArgs ] | "(" Expression ")" .
3013 Literal = BasicLit | CompositeLit | FunctionLit .
3014 BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
3015 OperandName = identifier | QualifiedIdent .
3019 An operand name denoting a <a href="#Function_declarations">generic function</a>
3020 may be followed by a list of <a href="#Instantiations">type arguments</a>; the
3021 resulting operand is an <a href="#Instantiations">instantiated</a> function.
3025 The <a href="#Blank_identifier">blank identifier</a> may appear as an
3026 operand only on the left-hand side of an <a href="#Assignments">assignment</a>.
3029 <h3 id="Qualified_identifiers">Qualified identifiers</h3>
3032 A <i>qualified identifier</i> is an identifier qualified with a package name prefix.
3033 Both the package name and the identifier must not be
3034 <a href="#Blank_identifier">blank</a>.
3038 QualifiedIdent = PackageName "." identifier .
3042 A qualified identifier accesses an identifier in a different package, which
3043 must be <a href="#Import_declarations">imported</a>.
3044 The identifier must be <a href="#Exported_identifiers">exported</a> and
3045 declared in the <a href="#Blocks">package block</a> of that package.
3049 math.Sin // denotes the Sin function in package math
3052 <h3 id="Composite_literals">Composite literals</h3>
3055 Composite literals construct new composite values each time they are evaluated.
3056 They consist of the type of the literal followed by a brace-bound list of elements.
3057 Each element may optionally be preceded by a corresponding key.
3061 CompositeLit = LiteralType LiteralValue .
3062 LiteralType = StructType | ArrayType | "[" "..." "]" ElementType |
3063 SliceType | MapType | TypeName .
3064 LiteralValue = "{" [ ElementList [ "," ] ] "}" .
3065 ElementList = KeyedElement { "," KeyedElement } .
3066 KeyedElement = [ Key ":" ] Element .
3067 Key = FieldName | Expression | LiteralValue .
3068 FieldName = identifier .
3069 Element = Expression | LiteralValue .
3073 The LiteralType's <a href="#Core_types">core type</a> <code>T</code>
3074 must be a struct, array, slice, or map type
3075 (the grammar enforces this constraint except when the type is given
3077 The types of the elements and keys must be <a href="#Assignability">assignable</a>
3078 to the respective field, element, and key types of type <code>T</code>;
3079 there is no additional conversion.
3080 The key is interpreted as a field name for struct literals,
3081 an index for array and slice literals, and a key for map literals.
3082 For map literals, all elements must have a key. It is an error
3083 to specify multiple elements with the same field name or
3084 constant key value. For non-constant map keys, see the section on
3085 <a href="#Order_of_evaluation">evaluation order</a>.
3089 For struct literals the following rules apply:
3092 <li>A key must be a field name declared in the struct type.
3094 <li>An element list that does not contain any keys must
3095 list an element for each struct field in the
3096 order in which the fields are declared.
3098 <li>If any element has a key, every element must have a key.
3100 <li>An element list that contains keys does not need to
3101 have an element for each struct field. Omitted fields
3102 get the zero value for that field.
3104 <li>A literal may omit the element list; such a literal evaluates
3105 to the zero value for its type.
3107 <li>It is an error to specify an element for a non-exported
3108 field of a struct belonging to a different package.
3113 Given the declarations
3116 type Point3D struct { x, y, z float64 }
3117 type Line struct { p, q Point3D }
3125 origin := Point3D{} // zero value for Point3D
3126 line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x
3130 For array and slice literals the following rules apply:
3133 <li>Each element has an associated integer index marking
3134 its position in the array.
3136 <li>An element with a key uses the key as its index. The
3137 key must be a non-negative constant
3138 <a href="#Representability">representable</a> by
3139 a value of type <code>int</code>; and if it is typed
3140 it must be of <a href="#Numeric_types">integer type</a>.
3142 <li>An element without a key uses the previous element's index plus one.
3143 If the first element has no key, its index is zero.
3148 <a href="#Address_operators">Taking the address</a> of a composite literal
3149 generates a pointer to a unique <a href="#Variables">variable</a> initialized
3150 with the literal's value.
3154 var pointer *Point3D = &Point3D{y: 1000}
3158 Note that the <a href="#The_zero_value">zero value</a> for a slice or map
3159 type is not the same as an initialized but empty value of the same type.
3160 Consequently, taking the address of an empty slice or map composite literal
3161 does not have the same effect as allocating a new slice or map value with
3162 <a href="#Allocation">new</a>.
3166 p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0
3167 p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0
3171 The length of an array literal is the length specified in the literal type.
3172 If fewer elements than the length are provided in the literal, the missing
3173 elements are set to the zero value for the array element type.
3174 It is an error to provide elements with index values outside the index range
3175 of the array. The notation <code>...</code> specifies an array length equal
3176 to the maximum element index plus one.
3180 buffer := [10]string{} // len(buffer) == 10
3181 intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6
3182 days := [...]string{"Sat", "Sun"} // len(days) == 2
3186 A slice literal describes the entire underlying array literal.
3187 Thus the length and capacity of a slice literal are the maximum
3188 element index plus one. A slice literal has the form
3196 and is shorthand for a slice operation applied to an array:
3200 tmp := [n]T{x1, x2, … xn}
3205 Within a composite literal of array, slice, or map type <code>T</code>,
3206 elements or map keys that are themselves composite literals may elide the respective
3207 literal type if it is identical to the element or key type of <code>T</code>.
3208 Similarly, elements or keys that are addresses of composite literals may elide
3209 the <code>&T</code> when the element or key type is <code>*T</code>.
3213 [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
3214 [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
3215 [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}}
3216 map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}}
3217 map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"}
3220 [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}}
3221 [2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})}
3225 A parsing ambiguity arises when a composite literal using the
3226 TypeName form of the LiteralType appears as an operand between the
3227 <a href="#Keywords">keyword</a> and the opening brace of the block
3228 of an "if", "for", or "switch" statement, and the composite literal
3229 is not enclosed in parentheses, square brackets, or curly braces.
3230 In this rare case, the opening brace of the literal is erroneously parsed
3231 as the one introducing the block of statements. To resolve the ambiguity,
3232 the composite literal must appear within parentheses.
3236 if x == (T{a,b,c}[i]) { … }
3237 if (x == T{a,b,c}[i]) { … }
3241 Examples of valid array, slice, and map literals:
3245 // list of prime numbers
3246 primes := []int{2, 3, 5, 7, 9, 2147483647}
3248 // vowels[ch] is true if ch is a vowel
3249 vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
3251 // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1}
3252 filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}
3254 // frequencies in Hz for equal-tempered scale (A4 = 440Hz)
3255 noteFrequency := map[string]float32{
3256 "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
3257 "G0": 24.50, "A0": 27.50, "B0": 30.87,
3262 <h3 id="Function_literals">Function literals</h3>
3265 A function literal represents an anonymous <a href="#Function_declarations">function</a>.
3266 Function literals cannot declare type parameters.
3270 FunctionLit = "func" Signature FunctionBody .
3274 func(a, b int, z float64) bool { return a*b < int(z) }
3278 A function literal can be assigned to a variable or invoked directly.
3282 f := func(x, y int) int { return x + y }
3283 func(ch chan int) { ch <- ACK }(replyChan)
3287 Function literals are <i>closures</i>: they may refer to variables
3288 defined in a surrounding function. Those variables are then shared between
3289 the surrounding function and the function literal, and they survive as long
3290 as they are accessible.
3294 <h3 id="Primary_expressions">Primary expressions</h3>
3297 Primary expressions are the operands for unary and binary expressions.
3305 PrimaryExpr Selector |
3308 PrimaryExpr TypeAssertion |
3309 PrimaryExpr Arguments .
3311 Selector = "." identifier .
3312 Index = "[" Expression "]" .
3313 Slice = "[" [ Expression ] ":" [ Expression ] "]" |
3314 "[" [ Expression ] ":" Expression ":" Expression "]" .
3315 TypeAssertion = "." "(" Type ")" .
3316 Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
3333 <h3 id="Selectors">Selectors</h3>
3335 <!-- This is missing rules for x of type parameter type. -->
3338 For a <a href="#Primary_expressions">primary expression</a> <code>x</code>
3339 that is not a <a href="#Package_clause">package name</a>, the
3340 <i>selector expression</i>
3348 denotes the field or method <code>f</code> of the value <code>x</code>
3349 (or sometimes <code>*x</code>; see below).
3350 The identifier <code>f</code> is called the (field or method) <i>selector</i>;
3351 it must not be the <a href="#Blank_identifier">blank identifier</a>.
3352 The type of the selector expression is the type of <code>f</code>.
3353 If <code>x</code> is a package name, see the section on
3354 <a href="#Qualified_identifiers">qualified identifiers</a>.
3358 A selector <code>f</code> may denote a field or method <code>f</code> of
3359 a type <code>T</code>, or it may refer
3360 to a field or method <code>f</code> of a nested
3361 <a href="#Struct_types">embedded field</a> of <code>T</code>.
3362 The number of embedded fields traversed
3363 to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
3364 The depth of a field or method <code>f</code>
3365 declared in <code>T</code> is zero.
3366 The depth of a field or method <code>f</code> declared in
3367 an embedded field <code>A</code> in <code>T</code> is the
3368 depth of <code>f</code> in <code>A</code> plus one.
3372 The following rules apply to selectors:
3377 For a value <code>x</code> of type <code>T</code> or <code>*T</code>
3378 where <code>T</code> is not a pointer or interface type,
3379 <code>x.f</code> denotes the field or method at the shallowest depth
3380 in <code>T</code> where there is such an <code>f</code>.
3381 If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a>
3382 with shallowest depth, the selector expression is illegal.
3386 For a value <code>x</code> of type <code>I</code> where <code>I</code>
3387 is an interface type, <code>x.f</code> denotes the actual method with name
3388 <code>f</code> of the dynamic value of <code>x</code>.
3389 If there is no method with name <code>f</code> in the
3390 <a href="#Method_sets">method set</a> of <code>I</code>, the selector
3391 expression is illegal.
3395 As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a>
3396 pointer type and <code>(*x).f</code> is a valid selector expression denoting a field
3397 (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>.
3401 In all other cases, <code>x.f</code> is illegal.
3405 If <code>x</code> is of pointer type and has the value
3406 <code>nil</code> and <code>x.f</code> denotes a struct field,
3407 assigning to or evaluating <code>x.f</code>
3408 causes a <a href="#Run_time_panics">run-time panic</a>.
3412 If <code>x</code> is of interface type and has the value
3413 <code>nil</code>, <a href="#Calls">calling</a> or
3414 <a href="#Method_values">evaluating</a> the method <code>x.f</code>
3415 causes a <a href="#Run_time_panics">run-time panic</a>.
3420 For example, given the declarations:
3446 var t T2 // with t.T0 != nil
3447 var p *T2 // with p != nil and (*p).T0 != nil
3464 q.x // (*(*q).T0).x (*q).x is a valid field selector
3466 p.M0() // ((*p).T0).M0() M0 expects *T0 receiver
3467 p.M1() // ((*p).T1).M1() M1 expects T1 receiver
3468 p.M2() // p.M2() M2 expects *T2 receiver
3469 t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls
3473 but the following is invalid:
3477 q.M0() // (*q).M0 is valid but not a field selector
3481 <h3 id="Method_expressions">Method expressions</h3>
3484 If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
3485 <code>T.M</code> is a function that is callable as a regular function
3486 with the same arguments as <code>M</code> prefixed by an additional
3487 argument that is the receiver of the method.
3491 MethodExpr = ReceiverType "." MethodName .
3492 ReceiverType = Type .
3496 Consider a struct type <code>T</code> with two methods,
3497 <code>Mv</code>, whose receiver is of type <code>T</code>, and
3498 <code>Mp</code>, whose receiver is of type <code>*T</code>.
3505 func (tv T) Mv(a int) int { return 0 } // value receiver
3506 func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
3520 yields a function equivalent to <code>Mv</code> but
3521 with an explicit receiver as its first argument; it has signature
3525 func(tv T, a int) int
3529 That function may be called normally with an explicit receiver, so
3530 these five invocations are equivalent:
3537 f1 := T.Mv; f1(t, 7)
3538 f2 := (T).Mv; f2(t, 7)
3542 Similarly, the expression
3550 yields a function value representing <code>Mp</code> with signature
3554 func(tp *T, f float32) float32
3558 For a method with a value receiver, one can derive a function
3559 with an explicit pointer receiver, so
3567 yields a function value representing <code>Mv</code> with signature
3571 func(tv *T, a int) int
3575 Such a function indirects through the receiver to create a value
3576 to pass as the receiver to the underlying method;
3577 the method does not overwrite the value whose address is passed in
3582 The final case, a value-receiver function for a pointer-receiver method,
3583 is illegal because pointer-receiver methods are not in the method set
3588 Function values derived from methods are called with function call syntax;
3589 the receiver is provided as the first argument to the call.
3590 That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
3591 as <code>f(t, 7)</code> not <code>t.f(7)</code>.
3592 To construct a function that binds the receiver, use a
3593 <a href="#Function_literals">function literal</a> or
3594 <a href="#Method_values">method value</a>.
3598 It is legal to derive a function value from a method of an interface type.
3599 The resulting function takes an explicit receiver of that interface type.
3602 <h3 id="Method_values">Method values</h3>
3605 If the expression <code>x</code> has static type <code>T</code> and
3606 <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
3607 <code>x.M</code> is called a <i>method value</i>.
3608 The method value <code>x.M</code> is a function value that is callable
3609 with the same arguments as a method call of <code>x.M</code>.
3610 The expression <code>x</code> is evaluated and saved during the evaluation of the
3611 method value; the saved copy is then used as the receiver in any calls,
3612 which may be executed later.
3616 type S struct { *T }
3618 func (t T) M() { print(t) }
3622 f := t.M // receiver *t is evaluated and stored in f
3623 g := s.M // receiver *(s.T) is evaluated and stored in g
3624 *t = 42 // does not affect stored receivers in f and g
3628 The type <code>T</code> may be an interface or non-interface type.
3632 As in the discussion of <a href="#Method_expressions">method expressions</a> above,
3633 consider a struct type <code>T</code> with two methods,
3634 <code>Mv</code>, whose receiver is of type <code>T</code>, and
3635 <code>Mp</code>, whose receiver is of type <code>*T</code>.
3642 func (tv T) Mv(a int) int { return 0 } // value receiver
3643 func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
3659 yields a function value of type
3667 These two invocations are equivalent:
3676 Similarly, the expression
3684 yields a function value of type
3688 func(float32) float32
3692 As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
3693 using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
3697 As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
3698 using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>.
3702 f := t.Mv; f(7) // like t.Mv(7)
3703 f := pt.Mp; f(7) // like pt.Mp(7)
3704 f := pt.Mv; f(7) // like (*pt).Mv(7)
3705 f := t.Mp; f(7) // like (&t).Mp(7)
3706 f := makeT().Mp // invalid: result of makeT() is not addressable
3710 Although the examples above use non-interface types, it is also legal to create a method value
3711 from a value of interface type.
3715 var i interface { M(int) } = myVal
3716 f := i.M; f(7) // like i.M(7)
3720 <h3 id="Index_expressions">Index expressions</h3>
3723 A primary expression of the form
3731 denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
3732 The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
3733 The following rules apply:
3737 If <code>a</code> is not a map:
3740 <li>the index <code>x</code> must be an untyped constant or its
3741 <a href="#Core_types">core type</a> must be an <a href="#Numeric_types">integer</a></li>
3742 <li>a constant index must be non-negative and
3743 <a href="#Representability">representable</a> by a value of type <code>int</code></li>
3744 <li>a constant index that is untyped is given type <code>int</code></li>
3745 <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>,
3746 otherwise it is <i>out of range</i></li>
3750 For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
3753 <li>a <a href="#Constants">constant</a> index must be in range</li>
3754 <li>if <code>x</code> is out of range at run time,
3755 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
3756 <li><code>a[x]</code> is the array element at index <code>x</code> and the type of
3757 <code>a[x]</code> is the element type of <code>A</code></li>
3761 For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
3764 <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
3768 For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
3771 <li>if <code>x</code> is out of range at run time,
3772 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
3773 <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
3774 <code>a[x]</code> is the element type of <code>S</code></li>
3778 For <code>a</code> of <a href="#String_types">string type</a>:
3781 <li>a <a href="#Constants">constant</a> index must be in range
3782 if the string <code>a</code> is also constant</li>
3783 <li>if <code>x</code> is out of range at run time,
3784 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
3785 <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
3786 <code>a[x]</code> is <code>byte</code></li>
3787 <li><code>a[x]</code> may not be assigned to</li>
3791 For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
3794 <li><code>x</code>'s type must be
3795 <a href="#Assignability">assignable</a>
3796 to the key type of <code>M</code></li>
3797 <li>if the map contains an entry with key <code>x</code>,
3798 <code>a[x]</code> is the map element with key <code>x</code>
3799 and the type of <code>a[x]</code> is the element type of <code>M</code></li>
3800 <li>if the map is <code>nil</code> or does not contain such an entry,
3801 <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
3802 for the element type of <code>M</code></li>
3806 For <code>a</code> of <a href="#Type_parameters">type parameter type</a> <code>P</code>:
3809 <li><code>P</code> must have <a href="#Specific_types">specific types</a>.</li>
3810 <li>The index expression <code>a[x]</code> must be valid for values
3811 of all specific types of <code>P</code>.</li>
3812 <li>The element types of all specific types of <code>P</code> must be identical.
3813 In this context, the element type of a string type is <code>byte</code>.</li>
3814 <li>If there is a map type among the specific types of <code>P</code>,
3815 all specific types must be map types, and the respective key types
3816 must be all identical.</li>
3817 <li><code>a[x]</code> is the array, slice, or string element at index <code>x</code>,
3818 or the map element with key <code>x</code> of the type argument
3819 that <code>P</code> is instantiated with, and the type of <code>a[x]</code> is
3820 the type of the (identical) element types.</li>
3821 <li><code>a[x]</code> may not be assigned to if the specific types of <code>P</code>
3822 include string types.
3826 Otherwise <code>a[x]</code> is illegal.
3830 An index expression on a map <code>a</code> of type <code>map[K]V</code>
3831 used in an <a href="#Assignments">assignment</a> or initialization of the special form
3841 yields an additional untyped boolean value. The value of <code>ok</code> is
3842 <code>true</code> if the key <code>x</code> is present in the map, and
3843 <code>false</code> otherwise.
3847 Assigning to an element of a <code>nil</code> map causes a
3848 <a href="#Run_time_panics">run-time panic</a>.
3852 <h3 id="Slice_expressions">Slice expressions</h3>
3855 Slice expressions construct a substring or slice from a string, array, pointer
3856 to array, or slice. There are two variants: a simple form that specifies a low
3857 and high bound, and a full form that also specifies a bound on the capacity.
3860 <h4>Simple slice expressions</h4>
3863 The primary expression
3871 constructs a substring or slice. The <a href="#Core_types">core type</a> of
3872 <code>a</code> must be a string, array, pointer to array, or slice.
3873 The <i>indices</i> <code>low</code> and
3874 <code>high</code> select which elements of operand <code>a</code> appear
3875 in the result. The result has indices starting at 0 and length equal to
3876 <code>high</code> - <code>low</code>.
3877 After slicing the array <code>a</code>
3881 a := [5]int{1, 2, 3, 4, 5}
3886 the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements
3896 For convenience, any of the indices may be omitted. A missing <code>low</code>
3897 index defaults to zero; a missing <code>high</code> index defaults to the length of the
3902 a[2:] // same as a[2 : len(a)]
3903 a[:3] // same as a[0 : 3]
3904 a[:] // same as a[0 : len(a)]
3908 If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
3909 <code>(*a)[low : high]</code>.
3913 For arrays or strings, the indices are <i>in range</i> if
3914 <code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>,
3915 otherwise they are <i>out of range</i>.
3916 For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
3917 A <a href="#Constants">constant</a> index must be non-negative and
3918 <a href="#Representability">representable</a> by a value of type
3919 <code>int</code>; for arrays or constant strings, constant indices must also be in range.
3920 If both indices are constant, they must satisfy <code>low <= high</code>.
3921 If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
3925 Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
3926 the result of the slice operation is a non-constant value of the same type as the operand.
3927 For untyped string operands the result is a non-constant value of type <code>string</code>.
3928 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
3929 and the result of the slice operation is a slice with the same element type as the array.
3933 If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
3934 is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying
3935 array with the operand.
3940 s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5]
3941 s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5]
3942 s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element
3946 <h4>Full slice expressions</h4>
3949 The primary expression
3957 constructs a slice of the same type, and with the same length and elements as the simple slice
3958 expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity
3959 by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0.
3960 The <a href="#Core_types">core type</a> of <code>a</code> must be an array, pointer to array,
3961 or slice (but not a string).
3962 After slicing the array <code>a</code>
3966 a := [5]int{1, 2, 3, 4, 5}
3971 the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements
3980 As for simple slice expressions, if <code>a</code> is a pointer to an array,
3981 <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>.
3982 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>.
3986 The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>,
3987 otherwise they are <i>out of range</i>.
3988 A <a href="#Constants">constant</a> index must be non-negative and
3989 <a href="#Representability">representable</a> by a value of type
3990 <code>int</code>; for arrays, constant indices must also be in range.
3991 If multiple indices are constant, the constants that are present must be in range relative to each
3993 If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
3996 <h3 id="Type_assertions">Type assertions</h3>
3999 For an expression <code>x</code> of <a href="#Interface_types">interface type</a>,
4000 but not a <a href="#Type_parameters">type parameter</a>, and a type <code>T</code>,
4001 the primary expression
4009 asserts that <code>x</code> is not <code>nil</code>
4010 and that the value stored in <code>x</code> is of type <code>T</code>.
4011 The notation <code>x.(T)</code> is called a <i>type assertion</i>.
4014 More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
4015 that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
4016 to the type <code>T</code>.
4017 In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>;
4018 otherwise the type assertion is invalid since it is not possible for <code>x</code>
4019 to store a value of type <code>T</code>.
4020 If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
4021 of <code>x</code> implements the interface <code>T</code>.
4024 If the type assertion holds, the value of the expression is the value
4025 stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false,
4026 a <a href="#Run_time_panics">run-time panic</a> occurs.
4027 In other words, even though the dynamic type of <code>x</code>
4028 is known only at run time, the type of <code>x.(T)</code> is
4029 known to be <code>T</code> in a correct program.
4033 var x interface{} = 7 // x has dynamic type int and value 7
4034 i := x.(int) // i has type int and value 7
4036 type I interface { m() }
4039 s := y.(string) // illegal: string does not implement I (missing method m)
4040 r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader
4046 A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form
4053 var v, ok interface{} = x.(T) // dynamic types of v and ok are T and bool
4057 yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code>
4058 if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is
4059 the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
4060 No <a href="#Run_time_panics">run-time panic</a> occurs in this case.
4064 <h3 id="Calls">Calls</h3>
4067 Given an expression <code>f</code> with a <a href="#Core_types">core type</a>
4068 <code>F</code> of <a href="#Function_types">function type</a>,
4076 calls <code>f</code> with arguments <code>a1, a2, … an</code>.
4077 Except for one special case, arguments must be single-valued expressions
4078 <a href="#Assignability">assignable</a> to the parameter types of
4079 <code>F</code> and are evaluated before the function is called.
4080 The type of the expression is the result type
4082 A method invocation is similar but the method itself
4083 is specified as a selector upon a value of the receiver type for
4088 math.Atan2(x, y) // function call
4090 pt.Scale(3.5) // method call with receiver pt
4094 If <code>f</code> denotes a generic function, it must be
4095 <a href="#Instantiations">instantiated</a> before it can be called
4096 or used as a function value.
4100 In a function call, the function value and arguments are evaluated in
4101 <a href="#Order_of_evaluation">the usual order</a>.
4102 After they are evaluated, the parameters of the call are passed by value to the function
4103 and the called function begins execution.
4104 The return parameters of the function are passed by value
4105 back to the caller when the function returns.
4109 Calling a <code>nil</code> function value
4110 causes a <a href="#Run_time_panics">run-time panic</a>.
4114 As a special case, if the return values of a function or method
4115 <code>g</code> are equal in number and individually
4116 assignable to the parameters of another function or method
4117 <code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
4118 will invoke <code>f</code> after binding the return values of
4119 <code>g</code> to the parameters of <code>f</code> in order. The call
4120 of <code>f</code> must contain no parameters other than the call of <code>g</code>,
4121 and <code>g</code> must have at least one return value.
4122 If <code>f</code> has a final <code>...</code> parameter, it is
4123 assigned the return values of <code>g</code> that remain after
4124 assignment of regular parameters.
4128 func Split(s string, pos int) (string, string) {
4129 return s[0:pos], s[pos:]
4132 func Join(s, t string) string {
4136 if Join(Split(value, len(value)/2)) != value {
4137 log.Panic("test fails")
4142 A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a>
4143 of (the type of) <code>x</code> contains <code>m</code> and the
4144 argument list can be assigned to the parameter list of <code>m</code>.
4145 If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method
4146 set contains <code>m</code>, <code>x.m()</code> is shorthand
4147 for <code>(&x).m()</code>:
4156 There is no distinct method type and there are no method literals.
4159 <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
4162 If <code>f</code> is <a href="#Function_types">variadic</a> with a final
4163 parameter <code>p</code> of type <code>...T</code>, then within <code>f</code>
4164 the type of <code>p</code> is equivalent to type <code>[]T</code>.
4165 If <code>f</code> is invoked with no actual arguments for <code>p</code>,
4166 the value passed to <code>p</code> is <code>nil</code>.
4167 Otherwise, the value passed is a new slice
4168 of type <code>[]T</code> with a new underlying array whose successive elements
4169 are the actual arguments, which all must be <a href="#Assignability">assignable</a>
4170 to <code>T</code>. The length and capacity of the slice is therefore
4171 the number of arguments bound to <code>p</code> and may differ for each
4176 Given the function and calls
4179 func Greeting(prefix string, who ...string)
4181 Greeting("hello:", "Joe", "Anna", "Eileen")
4185 within <code>Greeting</code>, <code>who</code> will have the value
4186 <code>nil</code> in the first call, and
4187 <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second.
4191 If the final argument is assignable to a slice type <code>[]T</code> and
4192 is followed by <code>...</code>, it is passed unchanged as the value
4193 for a <code>...T</code> parameter. In this case no new slice is created.
4197 Given the slice <code>s</code> and call
4201 s := []string{"James", "Jasmine"}
4202 Greeting("goodbye:", s...)
4206 within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code>
4207 with the same underlying array.
4210 <h3 id="Instantiations">Instantiations</h3>
4213 A generic function or type is <i>instantiated</i> by substituting <i>type arguments</i>
4214 for the type parameters.
4215 Instantiation proceeds in two phases:
4220 Each type argument is substituted for its corresponding type parameter in the generic
4222 This substitution happens across the entire function or type declaration,
4223 including the type parameter list itself and any types in that list.
4227 After substitution, each type argument must <a href="#Interface_types">implement</a>
4228 the <a href="#Type_parameter_lists">constraint</a> (instantiated, if necessary)
4229 of the corresponding type parameter. Otherwise instantiation fails.
4234 Instantiating a type results in a new non-generic <a href="#Types">named type</a>;
4235 instantiating a function produces a new non-generic function.
4239 type parameter list type arguments after substitution
4241 [P any] int [int any]
4242 [S ~[]E, E any] []int, int [[]int ~[]int, int any]
4243 [P io.Writer] string [string io.Writer] // illegal: string doesn't implement io.Writer
4247 Type arguments may be provided explicitly, or they may be partially or completely
4248 <a href="#Type_inference">inferred</a>.
4249 A partially provided type argument list cannot be empty; there must be at least the
4254 type T[P1 ~int, P2 ~[]P1] struct{ … }
4256 T[] // illegal: at least the first type argument must be present, even if it could be inferred
4257 T[int] // argument for P1 explicitly provided, argument for P2 inferred
4258 T[int, []int] // both arguments explicitly provided
4262 A partial type argument list specifies a prefix of the full list of type arguments, leaving
4263 the remaining arguments to be inferred. Loosely speaking, type arguments may be omitted from
4268 Generic types, and generic functions that are not <a href="#Calls">called</a>,
4269 require a type argument list for instantiation; if the list is partial, all
4270 remaining type arguments must be inferrable.
4271 Calls to generic functions may provide a (possibly partial) type
4272 argument list, or may omit it entirely if the omitted type arguments are
4273 inferrable from the ordinary (non-type) function arguments.
4277 func min[T constraints.Ordered](x, y T) T { … }
4279 f := min // illegal: min must be instantiated when used without being called
4280 minInt := min[int] // minInt has type func(x, y int) int
4281 a := minInt(2, 3) // a has value 2 of type int
4282 b := min[float64](2.0, 3) // b has value 2.0 of type float64
4283 c := min(b, -1) // c has value -1.0 of type float64
4286 <h3 id="Type_inference">Type inference</h3>
4289 Missing type arguments may be <i>inferred</i> by a series of steps, described below.
4290 Each step attempts to use known information to infer additional type arguments.
4291 Type inference stops as soon as all type arguments are known.
4292 After type inference is complete, it is still necessary to substitute all type arguments
4293 for type parameters and verify that each type argument implements the relevant constraint;
4294 it is possible for an inferred type argument to fail to implement a constraint, in which
4295 case instantiation fails.
4299 Type inference is based on
4304 a <a href="#Type_parameter_lists">type parameter list</a>
4307 a substitution map <i>M</i> initialized with the known type arguments, if any
4310 a (possibly empty) list of ordinary function arguments (in case of a function call only)
4315 and then proceeds with the following steps:
4320 apply <a href="#Function_argument_type_inference"><i>function argument type inference</i></a>
4321 to all <i>typed</i> ordinary function arguments
4324 apply <a href="#Constraint_type_inference"><i>constraint type inference</i></a>
4327 apply function argument type inference to all <i>untyped</i> ordinary function arguments
4328 using the default type for each of the untyped function arguments
4331 apply constraint type inference
4336 If there are no ordinary or untyped function arguments, the respective steps are skipped.
4337 Constraint type inference is skipped if the previous step didn't infer any new type arguments,
4338 but it is run at least once if there are missing type arguments.
4342 The substitution map <i>M</i> is carried through all steps, and each step may add entries to <i>M</i>.
4343 The process stops as soon as <i>M</i> has a type argument for each type parameter or if an inference step fails.
4344 If an inference step fails, or if <i>M</i> is still missing type arguments after the last step, type inference fails.
4347 <h4 id="Type_unification">Type unification</h3>
4350 Type inference is based on <i>type unification</i>. A single unification step
4351 applies to a <a href="#Type_inference">substitution map</a> and two types, either
4352 or both of which may be or contain type parameters. The substitution map tracks
4353 the known (explicitly provided or already inferred) type arguments: the map
4354 contains an entry <code>P</code> → <code>A</code> for each type
4355 parameter <code>P</code> and corresponding known type argument <code>A</code>.
4356 During unification, known type arguments take the place of their corresponding type
4357 parameters when comparing types. Unification is the process of finding substitution
4358 map entries that make the two types equivalent.
4362 For unification, two types that don't contain any type parameters from the current type
4363 parameter list are <i>equivalent</i>
4364 if they are identical, or if they are channel types that are identical ignoring channel
4365 direction, or if their underlying types are equivalent.
4369 Unification works by comparing the structure of pairs of types: their structure
4370 disregarding type parameters must be identical, and types other than type parameters
4372 A type parameter in one type may match any complete subtype in the other type;
4373 each successful match causes an entry to be added to the substitution map.
4374 If the structure differs, or types other than type parameters are not equivalent,
4379 TODO(gri) Somewhere we need to describe the process of adding an entry to the
4380 substitution map: if the entry is already present, the type argument
4381 values are themselves unified.
4385 For example, if <code>T1</code> and <code>T2</code> are type parameters,
4386 <code>[]map[int]bool</code> can be unified with any of the following:
4390 []map[int]bool // types are identical
4391 T1 // adds T1 → []map[int]bool to substitution map
4392 []T1 // adds T1 → map[int]bool to substitution map
4393 []map[T1]T2 // adds T1 → int and T2 → bool to substitution map
4397 On the other hand, <code>[]map[int]bool</code> cannot be unified with any of
4401 int // int is not a slice
4402 struct{} // a struct is not a slice
4403 []struct{} // a struct is not a map
4404 []map[T1]string // map element types don't match
4408 As an exception to this general rule, because a <a href="#Type_definitions">defined type</a>
4409 <code>D</code> and a type literal <code>L</code> are never equivalent,
4410 unification compares the underlying type of <code>D</code> with <code>L</code> instead.
4411 For example, given the defined type
4415 type Vector []float64
4419 and the type literal <code>[]E</code>, unification compares <code>[]float64</code> with
4420 <code>[]E</code> and adds an entry <code>E</code> → <code>float64</code> to
4421 the substitution map.
4424 <h4 id="Function_argument_type_inference">Function argument type inference</h3>
4426 <!-- In this section and the section on constraint type inference we start with examples
4427 rather than have the examples follow the rules as is customary elsewhere in spec.
4428 Hopefully this helps building an intuition and makes the rules easier to follow. -->
4431 Function argument type inference infers type arguments from function arguments:
4432 if a function parameter is declared with a type <code>T</code> that uses
4434 <a href="#Type_unification">unifying</a> the type of the corresponding
4435 function argument with <code>T</code> may infer type arguments for the type
4436 parameters used by <code>T</code>.
4440 For instance, given the generic function
4444 func scale[Number ~int64|~float64|~complex128](v []Number, s Number) []Number
4452 var vector []float64
4453 scaledVector := scale(vector, 42)
4457 the type argument for <code>Number</code> can be inferred from the function argument
4458 <code>vector</code> by unifying the type of <code>vector</code> with the corresponding
4459 parameter type: <code>[]float64</code> and <code>[]Number</code>
4460 match in structure and <code>float64</code> matches with <code>Number</code>.
4461 This adds the entry <code>Number</code> → <code>float64</code> to the
4462 <a href="#Type_unification">substitution map</a>.
4463 Untyped arguments, such as the second function argument <code>42</code> here, are ignored
4464 in the first round of function argument type inference and only considered if there are
4465 unresolved type parameters left.
4469 Function argument type inference can be used when the function has ordinary parameters
4470 whose types are defined using the function's type parameters. Inference happens in two
4471 separate phases; each phase operates on a specific list of (parameter, argument) pairs:
4476 The list <i>Lt</i> contains all (parameter, argument) pairs where the parameter
4477 type uses type parameters and where the function argument is <i>typed</i>.
4480 The list <i>Lu</i> contains all remaining pairs where the parameter type is a single
4481 type parameter. In this list, the respective function arguments are untyped.
4486 Any other (parameter, argument) pair is ignored.
4490 By construction, the arguments of the pairs in <i>Lu</i> are <i>untyped</i> constants
4491 (or the untyped boolean result of a comparison). And because <a href="#Constants">default types</a>
4492 of untyped values are always predeclared non-composite types, they can never match against
4493 a composite type, so it is sufficient to only consider parameter types that are single type
4498 Each list is processed in a separate phase:
4503 In the first phase, the parameter and argument types of each pair in <i>Lt</i>
4504 are unified. If unification succeeds for a pair, it may yield new entries that
4505 are added to the substitution map <i>M</i>. If unification fails, type inference
4509 The second phase considers the entries of list <i>Lu</i>. Type parameters for
4510 which the type argument has already been determined are ignored in this phase.
4511 For each remaining pair, the parameter type (which is a single type parameter) and
4512 the <a href="#Constants">default type</a> of the corresponding untyped argument is
4513 unified. If unification fails, type inference fails.
4518 While unification is successful, processing of each list continues until all list elements
4519 are considered, even if all type arguments are inferred before the last list element has
4528 func min[T constraints.Ordered](x, y T) T
4531 min(x, 2.0) // T is int, inferred from typed argument x; 2.0 is assignable to int
4532 min(1.0, 2.0) // T is float64, inferred from default type for 1.0 and matches default type for 2.0
4533 min(1.0, 2) // illegal: default type float64 (for 1.0) doesn't match default type int (for 2)
4537 In the example <code>min(1.0, 2)</code>, processing the function argument <code>1.0</code>
4538 yields the substitution map entry <code>T</code> → <code>float64</code>. Because
4539 processing continues until all untyped arguments are considered, an error is reported. This
4540 ensures that type inference does not depend on the order of the untyped arguments.
4543 <h4 id="Constraint_type_inference">Constraint type inference</h3>
4546 The next paragraph needs to be updated for the new definition of core type:
4547 The core type of an interface is the single underlying type of its type set,
4548 if it exists. But for constraint type inference, if the type set consists of exactly
4549 one type, we want to use that one type (which may be a defined type, different from
4550 its underlying == core type).
4554 Constraint type inference infers type arguments by considering type constraints.
4555 If a type parameter <code>P</code> has a constraint with a
4556 <a href="#Core_types">core type</a> <code>C</code>,
4557 <a href="#Type_unification">unifying</a> <code>P</code> with <code>C</code>
4558 may infer additional type arguments, either the type argument for <code>P</code>,
4559 or if that is already known, possibly the type arguments for type parameters
4560 used in <code>C</code>.
4564 For instance, consider the type parameter list with type parameters <code>List</code> and
4569 [List ~[]Elem, Elem any]
4573 Constraint type inference can deduce the type of <code>Elem</code> from the type argument
4574 for <code>List</code> because <code>Elem</code> is a type parameter in the core type
4575 <code>[]Elem</code> of <code>List</code>.
4576 If the type argument is <code>Bytes</code>:
4584 unifying the underlying type of <code>Bytes</code> with the core type means
4585 unifying <code>[]byte</code> with <code>[]Elem</code>. That unification succeeds and yields
4586 the <a href="#Type_unification">substitution map</a> entry
4587 <code>Elem</code> → <code>byte</code>.
4588 Thus, in this example, constraint type inference can infer the second type argument from the
4593 Generally, constraint type inference proceeds in two phases: Starting with a given
4594 substitution map <i>M</i>
4599 For all type parameters with a core type, unify the type parameter with the core
4600 type. If any unification fails, constraint type inference fails.
4604 At this point, some entries in <i>M</i> may map type parameters to other
4605 type parameters or to types containing type parameters. For each entry
4606 <code>P</code> → <code>A</code> in <i>M</i> where <code>A</code> is or
4607 contains type parameters <code>Q</code> for which there exist entries
4608 <code>Q</code> → <code>B</code> in <i>M</i>, substitute those
4609 <code>Q</code> with the respective <code>B</code> in <code>A</code>.
4610 Stop when no further substitution is possible.
4615 The result of constraint type inference is the final substitution map <i>M</i> from type
4616 parameters <code>P</code> to type arguments <code>A</code> where no type parameter <code>P</code>
4617 appears in any of the <code>A</code>.
4621 For instance, given the type parameter list
4625 [A any, B []C, C *A]
4629 and the single provided type argument <code>int</code> for type parameter <code>A</code>,
4630 the initial substitution map <i>M</i> contains the entry <code>A</code> → <code>int</code>.
4634 In the first phase, the type parameters <code>B</code> and <code>C</code> are unified
4635 with the core type of their respective constraints. This adds the entries
4636 <code>B</code> → <code>[]C</code> and <code>C</code> → <code>*A</code>
4640 At this point there are two entries in <i>M</i> where the right-hand side
4641 is or contains type parameters for which there exists other entries in <i>M</i>:
4642 <code>[]C</code> and <code>*A</code>.
4643 In the second phase, these type parameters are replaced with their respective
4644 types. It doesn't matter in which order this happens. Starting with the state
4645 of <i>M</i> after the first phase:
4649 <code>A</code> → <code>int</code>,
4650 <code>B</code> → <code>[]C</code>,
4651 <code>C</code> → <code>*A</code>
4655 Replace <code>A</code> on the right-hand side of → with <code>int</code>:
4659 <code>A</code> → <code>int</code>,
4660 <code>B</code> → <code>[]C</code>,
4661 <code>C</code> → <code>*int</code>
4665 Replace <code>C</code> on the right-hand side of → with <code>*int</code>:
4669 <code>A</code> → <code>int</code>,
4670 <code>B</code> → <code>[]*int</code>,
4671 <code>C</code> → <code>*int</code>
4675 At this point no further substitution is possible and the map is full.
4676 Therefore, <code>M</code> represents the final map of type parameters
4677 to type arguments for the given type parameter list.
4680 <h3 id="Operators">Operators</h3>
4683 Operators combine operands into expressions.
4687 Expression = UnaryExpr | Expression binary_op Expression .
4688 UnaryExpr = PrimaryExpr | unary_op UnaryExpr .
4690 binary_op = "||" | "&&" | rel_op | add_op | mul_op .
4691 rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" .
4692 add_op = "+" | "-" | "|" | "^" .
4693 mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" .
4695 unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" .
4699 Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
4700 For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
4701 unless the operation involves shifts or untyped <a href="#Constants">constants</a>.
4702 For operations involving constants only, see the section on
4703 <a href="#Constant_expressions">constant expressions</a>.
4707 Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a>
4708 and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a>
4709 to the type of the other operand.
4713 The right operand in a shift expression must have <a href="#Numeric_types">integer type</a>
4714 or be an untyped constant <a href="#Representability">representable</a> by a
4715 value of type <code>uint</code>.
4716 If the left operand of a non-constant shift expression is an untyped constant,
4717 it is first implicitly converted to the type it would assume if the shift expression were
4718 replaced by its left operand alone.
4725 // The results of the following examples are given for 64-bit ints.
4726 var i = 1<<s // 1 has type int
4727 var j int32 = 1<<s // 1 has type int32; j == 0
4728 var k = uint64(1<<s) // 1 has type uint64; k == 1<<33
4729 var m int = 1.0<<s // 1.0 has type int; m == 1<<33
4730 var n = 1.0<<s == j // 1.0 has type int32; n == true
4731 var o = 1<<s == 2<<s // 1 and 2 have type int; o == false
4732 var p = 1<<s == 1<<33 // 1 has type int; p == true
4733 var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift
4734 var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift
4735 var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift
4736 var v1 float32 = 1<<s // illegal: 1 has type float32, cannot shift
4737 var v2 = string(1<<s) // illegal: 1 is converted to a string, cannot shift
4738 var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression; w == 1<<33
4739 var x = a[1.0<<s] // panics: 1.0 has type int, but 1<<33 overflows array bounds
4740 var b = make([]byte, 1.0<<s) // 1.0 has type int; len(b) == 1<<33
4742 // The results of the following examples are given for 32-bit ints,
4743 // which means the shifts will overflow.
4744 var mm int = 1.0<<s // 1.0 has type int; mm == 0
4745 var oo = 1<<s == 2<<s // 1 and 2 have type int; oo == true
4746 var pp = 1<<s == 1<<33 // illegal: 1 has type int, but 1<<33 overflows int
4747 var xx = a[1.0<<s] // 1.0 has type int; xx == a[0]
4748 var bb = make([]byte, 1.0<<s) // 1.0 has type int; len(bb) == 0
4751 <h4 id="Operator_precedence">Operator precedence</h4>
4753 Unary operators have the highest precedence.
4754 As the <code>++</code> and <code>--</code> operators form
4755 statements, not expressions, they fall
4756 outside the operator hierarchy.
4757 As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
4759 There are five precedence levels for binary operators.
4760 Multiplication operators bind strongest, followed by addition
4761 operators, comparison operators, <code>&&</code> (logical AND),
4762 and finally <code>||</code> (logical OR):
4765 <pre class="grammar">
4767 5 * / % << >> & &^
4769 3 == != < <= > >=
4775 Binary operators of the same precedence associate from left to right.
4776 For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
4785 x == y+1 && <-chanInt > 0
4789 <h3 id="Arithmetic_operators">Arithmetic operators</h3>
4791 Arithmetic operators apply to numeric values and yield a result of the same
4792 type as the first operand. The four standard arithmetic operators (<code>+</code>,
4793 <code>-</code>, <code>*</code>, <code>/</code>) apply to
4794 <a href="#Numeric_types">integer</a>, <a href="#Numeric_types">floating-point</a>, and
4795 <a href="#Numeric_types">complex</a> types; <code>+</code> also applies to <a href="#String_types">strings</a>.
4796 The bitwise logical and shift operators apply to integers only.
4799 <pre class="grammar">
4800 + sum integers, floats, complex values, strings
4801 - difference integers, floats, complex values
4802 * product integers, floats, complex values
4803 / quotient integers, floats, complex values
4804 % remainder integers
4806 & bitwise AND integers
4807 | bitwise OR integers
4808 ^ bitwise XOR integers
4809 &^ bit clear (AND NOT) integers
4811 << left shift integer << integer >= 0
4812 >> right shift integer >> integer >= 0
4816 Excluding shifts, if the operand type is a <a href="#Type_parameters">type parameter</a>,
4817 it must have <a href="#Specific_types">specific types</a>, and the operator must
4818 apply to each specific type.
4819 The operands are represented as values of the type argument that the type parameter
4820 is <a href="#Instantiations">instantiated</a> with, and the operation is computed
4821 with the precision of that type argument. For example, given the function:
4825 func dotProduct[F ~float32|~float64](v1, v2 []F) F {
4827 for i, x := range v1 {
4836 the the product <code>x * y</code> and the addition <code>s += x * y</code>
4837 are computed with <code>float32</code> or <code>float64</code> precision,
4838 respectively, depending on the type argument for <code>F</code>.
4842 For shifts, the <a href="#Core_types">core type</a> of both operands must be
4846 <h4 id="Integer_operators">Integer operators</h4>
4849 For two integer values <code>x</code> and <code>y</code>, the integer quotient
4850 <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following
4855 x = q*y + r and |r| < |y|
4859 with <code>x / y</code> truncated towards zero
4860 (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
4872 The one exception to this rule is that if the dividend <code>x</code> is
4873 the most negative value for the int type of <code>x</code>, the quotient
4874 <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>)
4875 due to two's-complement <a href="#Integer_overflow">integer overflow</a>:
4883 int64 -9223372036854775808
4887 If the divisor is a <a href="#Constants">constant</a>, it must not be zero.
4888 If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
4889 If the dividend is non-negative and the divisor is a constant power of 2,
4890 the division may be replaced by a right shift, and computing the remainder may
4891 be replaced by a bitwise AND operation:
4895 x x / 4 x % 4 x >> 2 x & 3
4901 The shift operators shift the left operand by the shift count specified by the
4902 right operand, which must be non-negative. If the shift count is negative at run time,
4903 a <a href="#Run_time_panics">run-time panic</a> occurs.
4904 The shift operators implement arithmetic shifts if the left operand is a signed
4905 integer and logical shifts if it is an unsigned integer.
4906 There is no upper limit on the shift count. Shifts behave
4907 as if the left operand is shifted <code>n</code> times by 1 for a shift
4908 count of <code>n</code>.
4909 As a result, <code>x << 1</code> is the same as <code>x*2</code>
4910 and <code>x >> 1</code> is the same as
4911 <code>x/2</code> but truncated towards negative infinity.
4915 For integer operands, the unary operators
4916 <code>+</code>, <code>-</code>, and <code>^</code> are defined as
4920 <pre class="grammar">
4922 -x negation is 0 - x
4923 ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x
4924 and m = -1 for signed x
4928 <h4 id="Integer_overflow">Integer overflow</h4>
4931 For <a href="#Numeric_types">unsigned integer</a> values, the operations <code>+</code>,
4932 <code>-</code>, <code>*</code>, and <code><<</code> are
4933 computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
4934 the unsigned integer's type.
4935 Loosely speaking, these unsigned integer operations
4936 discard high bits upon overflow, and programs may rely on "wrap around".
4940 For signed integers, the operations <code>+</code>,
4941 <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally
4942 overflow and the resulting value exists and is deterministically defined
4943 by the signed integer representation, the operation, and its operands.
4944 Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>.
4945 A compiler may not optimize code under the assumption that overflow does
4946 not occur. For instance, it may not assume that <code>x < x + 1</code> is always true.
4949 <h4 id="Floating_point_operators">Floating-point operators</h4>
4952 For floating-point and complex numbers,
4953 <code>+x</code> is the same as <code>x</code>,
4954 while <code>-x</code> is the negation of <code>x</code>.
4955 The result of a floating-point or complex division by zero is not specified beyond the
4956 IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a>
4957 occurs is implementation-specific.
4961 An implementation may combine multiple floating-point operations into a single
4962 fused operation, possibly across statements, and produce a result that differs
4963 from the value obtained by executing and rounding the instructions individually.
4964 An explicit <a href="#Numeric_types">floating-point type</a> <a href="#Conversions">conversion</a> rounds to
4965 the precision of the target type, preventing fusion that would discard that rounding.
4969 For instance, some architectures provide a "fused multiply and add" (FMA) instruction
4970 that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>.
4971 These examples show when a Go implementation can use that instruction:
4975 // FMA allowed for computing r, because x*y is not explicitly rounded:
4979 *p = x*y; r = *p + z
4980 r = x*y + float64(z)
4982 // FMA disallowed for computing r, because it would omit rounding of x*y:
4983 r = float64(x*y) + z
4984 r = z; r += float64(x*y)
4985 t = float64(x*y); r = t + z
4988 <h4 id="String_concatenation">String concatenation</h4>
4991 Strings can be concatenated using the <code>+</code> operator
4992 or the <code>+=</code> assignment operator:
4996 s := "hi" + string(c)
4997 s += " and good bye"
5001 String addition creates a new string by concatenating the operands.
5004 <h3 id="Comparison_operators">Comparison operators</h3>
5007 Comparison operators compare two operands and yield an untyped boolean value.
5010 <pre class="grammar">
5016 >= greater or equal
5020 In any comparison, the first operand
5021 must be <a href="#Assignability">assignable</a>
5022 to the type of the second operand, or vice versa.
5025 The equality operators <code>==</code> and <code>!=</code> apply
5026 to operands that are <i>comparable</i>.
5027 The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code>
5028 apply to operands that are <i>ordered</i>.
5029 These terms and the result of the comparisons are defined as follows:
5034 Boolean values are comparable.
5035 Two boolean values are equal if they are either both
5036 <code>true</code> or both <code>false</code>.
5040 Integer values are comparable and ordered, in the usual way.
5044 Floating-point values are comparable and ordered,
5045 as defined by the IEEE-754 standard.
5049 Complex values are comparable.
5050 Two complex values <code>u</code> and <code>v</code> are
5051 equal if both <code>real(u) == real(v)</code> and
5052 <code>imag(u) == imag(v)</code>.
5056 String values are comparable and ordered, lexically byte-wise.
5060 Pointer values are comparable.
5061 Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>.
5062 Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal.
5066 Channel values are comparable.
5067 Two channel values are equal if they were created by the same call to
5068 <a href="#Making_slices_maps_and_channels"><code>make</code></a>
5069 or if both have value <code>nil</code>.
5073 Interface values are comparable.
5074 Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types
5075 and equal dynamic values or if both have value <code>nil</code>.
5079 A value <code>x</code> of non-interface type <code>X</code> and
5080 a value <code>t</code> of interface type <code>T</code> are comparable when values
5081 of type <code>X</code> are comparable and
5082 <code>X</code> implements <code>T</code>.
5083 They are equal if <code>t</code>'s dynamic type is identical to <code>X</code>
5084 and <code>t</code>'s dynamic value is equal to <code>x</code>.
5088 Struct values are comparable if all their fields are comparable.
5089 Two struct values are equal if their corresponding
5090 non-<a href="#Blank_identifier">blank</a> fields are equal.
5094 Array values are comparable if values of the array element type are comparable.
5095 Two array values are equal if their corresponding elements are equal.
5100 A comparison of two interface values with identical dynamic types
5101 causes a <a href="#Run_time_panics">run-time panic</a> if values
5102 of that type are not comparable. This behavior applies not only to direct interface
5103 value comparisons but also when comparing arrays of interface values
5104 or structs with interface-valued fields.
5108 Slice, map, and function values are not comparable.
5109 However, as a special case, a slice, map, or function value may
5110 be compared to the predeclared identifier <code>nil</code>.
5111 Comparison of pointer, channel, and interface values to <code>nil</code>
5112 is also allowed and follows from the general rules above.
5116 const c = 3 < 4 // c is the untyped boolean constant true
5121 // The result of a comparison is an untyped boolean.
5122 // The usual assignment rules apply.
5123 b3 = x == y // b3 has type bool
5124 b4 bool = x == y // b4 has type bool
5125 b5 MyBool = x == y // b5 has type MyBool
5129 <h3 id="Logical_operators">Logical operators</h3>
5132 Logical operators apply to <a href="#Boolean_types">boolean</a> values
5133 and yield a result of the same type as the operands.
5134 The right operand is evaluated conditionally.
5137 <pre class="grammar">
5138 && conditional AND p && q is "if p then q else false"
5139 || conditional OR p || q is "if p then true else q"
5144 <h3 id="Address_operators">Address operators</h3>
5147 For an operand <code>x</code> of type <code>T</code>, the address operation
5148 <code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>.
5149 The operand must be <i>addressable</i>,
5150 that is, either a variable, pointer indirection, or slice indexing
5151 operation; or a field selector of an addressable struct operand;
5152 or an array indexing operation of an addressable array.
5153 As an exception to the addressability requirement, <code>x</code> may also be a
5154 (possibly parenthesized)
5155 <a href="#Composite_literals">composite literal</a>.
5156 If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>,
5157 then the evaluation of <code>&x</code> does too.
5161 For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
5162 indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed
5163 to by <code>x</code>.
5164 If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code>
5165 will cause a <a href="#Run_time_panics">run-time panic</a>.
5176 *x // causes a run-time panic
5177 &*x // causes a run-time panic
5181 <h3 id="Receive_operator">Receive operator</h3>
5184 For an operand <code>ch</code> whose <a href="#Core_types">core type</a> is a
5185 <a href="#Channel_types">channel</a>,
5186 the value of the receive operation <code><-ch</code> is the value received
5187 from the channel <code>ch</code>. The channel direction must permit receive operations,
5188 and the type of the receive operation is the element type of the channel.
5189 The expression blocks until a value is available.
5190 Receiving from a <code>nil</code> channel blocks forever.
5191 A receive operation on a <a href="#Close">closed</a> channel can always proceed
5192 immediately, yielding the element type's <a href="#The_zero_value">zero value</a>
5193 after any previously sent values have been received.
5200 <-strobe // wait until clock pulse and discard received value
5204 A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form
5211 var x, ok T = <-ch
5215 yields an additional untyped boolean result reporting whether the
5216 communication succeeded. The value of <code>ok</code> is <code>true</code>
5217 if the value received was delivered by a successful send operation to the
5218 channel, or <code>false</code> if it is a zero value generated because the
5219 channel is closed and empty.
5223 <h3 id="Conversions">Conversions</h3>
5226 A conversion changes the <a href="#Types">type</a> of an expression
5227 to the type specified by the conversion.
5228 A conversion may appear literally in the source, or it may be <i>implied</i>
5229 by the context in which an expression appears.
5233 An <i>explicit</i> conversion is an expression of the form <code>T(x)</code>
5234 where <code>T</code> is a type and <code>x</code> is an expression
5235 that can be converted to type <code>T</code>.
5239 Conversion = Type "(" Expression [ "," ] ")" .
5243 If the type starts with the operator <code>*</code> or <code><-</code>,
5244 or if the type starts with the keyword <code>func</code>
5245 and has no result list, it must be parenthesized when
5246 necessary to avoid ambiguity:
5250 *Point(p) // same as *(Point(p))
5251 (*Point)(p) // p is converted to *Point
5252 <-chan int(c) // same as <-(chan int(c))
5253 (<-chan int)(c) // c is converted to <-chan int
5254 func()(x) // function signature func() x
5255 (func())(x) // x is converted to func()
5256 (func() int)(x) // x is converted to func() int
5257 func() int(x) // x is converted to func() int (unambiguous)
5261 A <a href="#Constants">constant</a> value <code>x</code> can be converted to
5262 type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a>
5263 by a value of <code>T</code>.
5264 As a special case, an integer constant <code>x</code> can be explicitly converted to a
5265 <a href="#String_types">string type</a> using the
5266 <a href="#Conversions_to_and_from_a_string_type">same rule</a>
5267 as for non-constant <code>x</code>.
5271 Converting a constant to a type that is not a <a href="#Type_parameters">type parameter</a>
5272 yields a typed constant.
5276 uint(iota) // iota value of type uint
5277 float32(2.718281828) // 2.718281828 of type float32
5278 complex128(1) // 1.0 + 0.0i of type complex128
5279 float32(0.49999999) // 0.5 of type float32
5280 float64(-1e-1000) // 0.0 of type float64
5281 string('x') // "x" of type string
5282 string(0x266c) // "♬" of type string
5283 MyString("foo" + "bar") // "foobar" of type MyString
5284 string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant
5285 (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
5286 int(1.2) // illegal: 1.2 cannot be represented as an int
5287 string(65.0) // illegal: 65.0 is not an integer constant
5291 Converting a constant to a type parameter yields a <i>non-constant</i> value of that type,
5292 with the value represented as a value of the type argument that the type parameter
5293 is <a href="#Instantiations">instantiated</a> with.
5294 For example, given the function:
5298 func f[P ~float32|~float64]() {
5304 the conversion <code>P(1.1)</code> results in a non-constant value of type <code>P</code>
5305 and the value <code>1.1</code> is represented as a <code>float32</code> or a <code>float64</code>
5306 depending on the type argument for <code>f</code>.
5307 Accordingly, if <code>f</code> is instantiated with a <code>float32</code> type,
5308 the numeric value of the expression <code>P(1.1) + 1.2</code> will be computed
5309 with the same precision as the corresponding non-constant <code>float32</code>
5314 A non-constant value <code>x</code> can be converted to type <code>T</code>
5315 in any of these cases:
5320 <code>x</code> is <a href="#Assignability">assignable</a>
5324 ignoring struct tags (see below),
5325 <code>x</code>'s type and <code>T</code> are not
5326 <a href="#Type_parameters">type parameters</a> but have
5327 <a href="#Type_identity">identical</a> <a href="#Types">underlying types</a>.
5330 ignoring struct tags (see below),
5331 <code>x</code>'s type and <code>T</code> are pointer types
5332 that are not <a href="#Types">named types</a>,
5333 and their pointer base types are not type parameters but
5334 have identical underlying types.
5337 <code>x</code>'s type and <code>T</code> are both integer or floating
5341 <code>x</code>'s type and <code>T</code> are both complex types.
5344 <code>x</code> is an integer or a slice of bytes or runes
5345 and <code>T</code> is a string type.
5348 <code>x</code> is a string and <code>T</code> is a slice of bytes or runes.
5351 <code>x</code> is a slice, <code>T</code> is a pointer to an array,
5352 and the slice and array types have <a href="#Type_identity">identical</a> element types.
5357 Additionally, if <code>T</code> or </code><code>x's</code> type <code>V</code> are type
5358 parameters with <a href="#Specific_types">specific types</a>, <code>x</code>
5359 can also be converted to type <code>T</code> if one of the following conditions applies:
5364 Both <code>V</code> and <code>T</code> are type parameters and a value of each
5365 specific type of <code>V</code> can be converted to each specific type
5369 Only <code>V</code> is a type parameter and a value of each
5370 specific type of <code>V</code> can be converted to <code>T</code>.
5373 Only <code>T</code> is a type parameter and <code>x</code> can be converted to each
5374 specific type of <code>T</code>.
5379 <a href="#Struct_types">Struct tags</a> are ignored when comparing struct types
5380 for identity for the purpose of conversion:
5384 type Person struct {
5393 Name string `json:"name"`
5395 Street string `json:"street"`
5396 City string `json:"city"`
5400 var person = (*Person)(data) // ignoring tags, the underlying types are identical
5404 Specific rules apply to (non-constant) conversions between numeric types or
5405 to and from a string type.
5406 These conversions may change the representation of <code>x</code>
5407 and incur a run-time cost.
5408 All other conversions only change the type but not the representation
5413 There is no linguistic mechanism to convert between pointers and integers.
5414 The package <a href="#Package_unsafe"><code>unsafe</code></a>
5415 implements this functionality under
5416 restricted circumstances.
5419 <h4>Conversions between numeric types</h4>
5422 For the conversion of non-constant numeric values, the following rules apply:
5427 When converting between <a href="#Numeric_types">integer types</a>, if the value is a signed integer, it is
5428 sign extended to implicit infinite precision; otherwise it is zero extended.
5429 It is then truncated to fit in the result type's size.
5430 For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>.
5431 The conversion always yields a valid value; there is no indication of overflow.
5434 When converting a <a href="#Numeric_types">floating-point number</a> to an integer, the fraction is discarded
5435 (truncation towards zero).
5438 When converting an integer or floating-point number to a floating-point type,
5439 or a <a href="#Numeric_types">complex number</a> to another complex type, the result value is rounded
5440 to the precision specified by the destination type.
5441 For instance, the value of a variable <code>x</code> of type <code>float32</code>
5442 may be stored using additional precision beyond that of an IEEE-754 32-bit number,
5443 but float32(x) represents the result of rounding <code>x</code>'s value to
5444 32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits
5445 of precision, but <code>float32(x + 0.1)</code> does not.
5450 In all non-constant conversions involving floating-point or complex values,
5451 if the result type cannot represent the value the conversion
5452 succeeds but the result value is implementation-dependent.
5455 <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
5459 Converting a signed or unsigned integer value to a string type yields a
5460 string containing the UTF-8 representation of the integer. Values outside
5461 the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
5465 string(-1) // "\ufffd" == "\xef\xbf\xbd"
5466 string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8"
5467 type MyString string
5468 MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5"
5473 Converting a slice of bytes to a string type yields
5474 a string whose successive bytes are the elements of the slice.
5477 string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
5478 string([]byte{}) // ""
5479 string([]byte(nil)) // ""
5482 string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
5487 Converting a slice of runes to a string type yields
5488 a string that is the concatenation of the individual rune values
5489 converted to strings.
5492 string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
5493 string([]rune{}) // ""
5494 string([]rune(nil)) // ""
5497 string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
5502 Converting a value of a string type to a slice of bytes type
5503 yields a slice whose successive elements are the bytes of the string.
5506 []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
5507 []byte("") // []byte{}
5509 MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
5514 Converting a value of a string type to a slice of runes type
5515 yields a slice containing the individual Unicode code points of the string.
5518 []rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4}
5519 []rune("") // []rune{}
5521 MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4}
5526 <h4 id="Conversions_from_slice_to_array_pointer">Conversions from slice to array pointer</h4>
5529 Converting a slice to an array pointer yields a pointer to the underlying array of the slice.
5530 If the <a href="#Length_and_capacity">length</a> of the slice is less than the length of the array,
5531 a <a href="#Run_time_panics">run-time panic</a> occurs.
5535 s := make([]byte, 2, 4)
5536 s0 := (*[0]byte)(s) // s0 != nil
5537 s1 := (*[1]byte)(s[1:]) // &s1[0] == &s[1]
5538 s2 := (*[2]byte)(s) // &s2[0] == &s[0]
5539 s4 := (*[4]byte)(s) // panics: len([4]byte) > len(s)
5542 t0 := (*[0]string)(t) // t0 == nil
5543 t1 := (*[1]string)(t) // panics: len([1]string) > len(t)
5545 u := make([]byte, 0)
5546 u0 := (*[0]byte)(u) // u0 != nil
5549 <h3 id="Constant_expressions">Constant expressions</h3>
5552 Constant expressions may contain only <a href="#Constants">constant</a>
5553 operands and are evaluated at compile time.
5557 Untyped boolean, numeric, and string constants may be used as operands
5558 wherever it is legal to use an operand of boolean, numeric, or string type,
5563 A constant <a href="#Comparison_operators">comparison</a> always yields
5564 an untyped boolean constant. If the left operand of a constant
5565 <a href="#Operators">shift expression</a> is an untyped constant, the
5566 result is an integer constant; otherwise it is a constant of the same
5567 type as the left operand, which must be of
5568 <a href="#Numeric_types">integer type</a>.
5572 Any other operation on untyped constants results in an untyped constant of the
5573 same kind; that is, a boolean, integer, floating-point, complex, or string
5575 If the untyped operands of a binary operation (other than a shift) are of
5576 different kinds, the result is of the operand's kind that appears later in this
5577 list: integer, rune, floating-point, complex.
5578 For example, an untyped integer constant divided by an
5579 untyped complex constant yields an untyped complex constant.
5583 const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant)
5584 const b = 15 / 4 // b == 3 (untyped integer constant)
5585 const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant)
5586 const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division)
5587 const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division)
5588 const d = 1 << 3.0 // d == 8 (untyped integer constant)
5589 const e = 1.0 << 3 // e == 8 (untyped integer constant)
5590 const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32)
5591 const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant)
5592 const h = "foo" > "bar" // h == true (untyped boolean constant)
5593 const j = true // j == true (untyped boolean constant)
5594 const k = 'w' + 1 // k == 'x' (untyped rune constant)
5595 const l = "hi" // l == "hi" (untyped string constant)
5596 const m = string(k) // m == "x" (type string)
5597 const Σ = 1 - 0.707i // (untyped complex constant)
5598 const Δ = Σ + 2.0e-4 // (untyped complex constant)
5599 const Φ = iota*1i - 1/1i // (untyped complex constant)
5603 Applying the built-in function <code>complex</code> to untyped
5604 integer, rune, or floating-point constants yields
5605 an untyped complex constant.
5609 const ic = complex(0, c) // ic == 3.75i (untyped complex constant)
5610 const iΘ = complex(0, Θ) // iΘ == 1i (type complex128)
5614 Constant expressions are always evaluated exactly; intermediate values and the
5615 constants themselves may require precision significantly larger than supported
5616 by any predeclared type in the language. The following are legal declarations:
5620 const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant)
5621 const Four int8 = Huge >> 98 // Four == 4 (type int8)
5625 The divisor of a constant division or remainder operation must not be zero:
5629 3.14 / 0.0 // illegal: division by zero
5633 The values of <i>typed</i> constants must always be accurately
5634 <a href="#Representability">representable</a> by values
5635 of the constant type. The following constant expressions are illegal:
5639 uint(-1) // -1 cannot be represented as a uint
5640 int(3.14) // 3.14 cannot be represented as an int
5641 int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64
5642 Four * 300 // operand 300 cannot be represented as an int8 (type of Four)
5643 Four * 100 // product 400 cannot be represented as an int8 (type of Four)
5647 The mask used by the unary bitwise complement operator <code>^</code> matches
5648 the rule for non-constants: the mask is all 1s for unsigned constants
5649 and -1 for signed and untyped constants.
5653 ^1 // untyped integer constant, equal to -2
5654 uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8
5655 ^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
5656 int8(^1) // same as int8(-2)
5657 ^int8(1) // same as -1 ^ int8(1) = -2
5661 Implementation restriction: A compiler may use rounding while
5662 computing untyped floating-point or complex constant expressions; see
5663 the implementation restriction in the section
5664 on <a href="#Constants">constants</a>. This rounding may cause a
5665 floating-point constant expression to be invalid in an integer
5666 context, even if it would be integral when calculated using infinite
5667 precision, and vice versa.
5671 <h3 id="Order_of_evaluation">Order of evaluation</h3>
5674 At package level, <a href="#Package_initialization">initialization dependencies</a>
5675 determine the evaluation order of individual initialization expressions in
5676 <a href="#Variable_declarations">variable declarations</a>.
5677 Otherwise, when evaluating the <a href="#Operands">operands</a> of an
5678 expression, assignment, or
5679 <a href="#Return_statements">return statement</a>,
5680 all function calls, method calls, and
5681 communication operations are evaluated in lexical left-to-right
5686 For example, in the (function-local) assignment
5689 y[f()], ok = g(h(), i()+x[j()], <-c), k()
5692 the function calls and communication happen in the order
5693 <code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>,
5694 <code><-c</code>, <code>g()</code>, and <code>k()</code>.
5695 However, the order of those events compared to the evaluation
5696 and indexing of <code>x</code> and the evaluation
5697 of <code>y</code> is not specified.
5702 f := func() int { a++; return a }
5703 x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
5704 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
5705 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
5709 At package level, initialization dependencies override the left-to-right rule
5710 for individual initialization expressions, but not for operands within each
5715 var a, b, c = f() + v(), g(), sqr(u()) + v()
5717 func f() int { return c }
5718 func g() int { return a }
5719 func sqr(x int) int { return x*x }
5721 // functions u and v are independent of all other variables and functions
5725 The function calls happen in the order
5726 <code>u()</code>, <code>sqr()</code>, <code>v()</code>,
5727 <code>f()</code>, <code>v()</code>, and <code>g()</code>.
5731 Floating-point operations within a single expression are evaluated according to
5732 the associativity of the operators. Explicit parentheses affect the evaluation
5733 by overriding the default associativity.
5734 In the expression <code>x + (y + z)</code> the addition <code>y + z</code>
5735 is performed before adding <code>x</code>.
5738 <h2 id="Statements">Statements</h2>
5741 Statements control execution.
5746 Declaration | LabeledStmt | SimpleStmt |
5747 GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
5748 FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
5751 SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
5754 <h3 id="Terminating_statements">Terminating statements</h3>
5757 A <i>terminating statement</i> interrupts the regular flow of control in
5758 a <a href="#Blocks">block</a>. The following statements are terminating:
5763 A <a href="#Return_statements">"return"</a> or
5764 <a href="#Goto_statements">"goto"</a> statement.
5765 <!-- ul below only for regular layout -->
5770 A call to the built-in function
5771 <a href="#Handling_panics"><code>panic</code></a>.
5772 <!-- ul below only for regular layout -->
5777 A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
5778 <!-- ul below only for regular layout -->
5783 An <a href="#If_statements">"if" statement</a> in which:
5785 <li>the "else" branch is present, and</li>
5786 <li>both branches are terminating statements.</li>
5791 A <a href="#For_statements">"for" statement</a> in which:
5793 <li>there are no "break" statements referring to the "for" statement, and</li>
5794 <li>the loop condition is absent, and</li>
5795 <li>the "for" statement does not use a range clause.</li>
5800 A <a href="#Switch_statements">"switch" statement</a> in which:
5802 <li>there are no "break" statements referring to the "switch" statement,</li>
5803 <li>there is a default case, and</li>
5804 <li>the statement lists in each case, including the default, end in a terminating
5805 statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
5811 A <a href="#Select_statements">"select" statement</a> in which:
5813 <li>there are no "break" statements referring to the "select" statement, and</li>
5814 <li>the statement lists in each case, including the default if present,
5815 end in a terminating statement.</li>
5820 A <a href="#Labeled_statements">labeled statement</a> labeling
5821 a terminating statement.
5826 All other statements are not terminating.
5830 A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
5831 is not empty and its final non-empty statement is terminating.
5835 <h3 id="Empty_statements">Empty statements</h3>
5838 The empty statement does nothing.
5846 <h3 id="Labeled_statements">Labeled statements</h3>
5849 A labeled statement may be the target of a <code>goto</code>,
5850 <code>break</code> or <code>continue</code> statement.
5854 LabeledStmt = Label ":" Statement .
5855 Label = identifier .
5859 Error: log.Panic("error encountered")
5863 <h3 id="Expression_statements">Expression statements</h3>
5866 With the exception of specific built-in functions,
5867 function and method <a href="#Calls">calls</a> and
5868 <a href="#Receive_operator">receive operations</a>
5869 can appear in statement context. Such statements may be parenthesized.
5873 ExpressionStmt = Expression .
5877 The following built-in functions are not permitted in statement context:
5881 append cap complex imag len make new real
5882 unsafe.Add unsafe.Alignof unsafe.Offsetof unsafe.Sizeof unsafe.Slice
5890 len("foo") // illegal if len is the built-in function
5894 <h3 id="Send_statements">Send statements</h3>
5897 A send statement sends a value on a channel.
5898 The channel expression's <a href="#Core_types">core type</a>
5899 must be a <a href="#Channel_types">channel</a>,
5900 the channel direction must permit send operations,
5901 and the type of the value to be sent must be <a href="#Assignability">assignable</a>
5902 to the channel's element type.
5906 SendStmt = Channel "<-" Expression .
5907 Channel = Expression .
5911 Both the channel and the value expression are evaluated before communication
5912 begins. Communication blocks until the send can proceed.
5913 A send on an unbuffered channel can proceed if a receiver is ready.
5914 A send on a buffered channel can proceed if there is room in the buffer.
5915 A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>.
5916 A send on a <code>nil</code> channel blocks forever.
5920 ch <- 3 // send value 3 to channel ch
5924 <h3 id="IncDec_statements">IncDec statements</h3>
5927 The "++" and "--" statements increment or decrement their operands
5928 by the untyped <a href="#Constants">constant</a> <code>1</code>.
5929 As with an assignment, the operand must be <a href="#Address_operators">addressable</a>
5930 or a map index expression.
5934 IncDecStmt = Expression ( "++" | "--" ) .
5938 The following <a href="#Assignments">assignment statements</a> are semantically
5942 <pre class="grammar">
5943 IncDec statement Assignment
5949 <h3 id="Assignments">Assignments</h3>
5952 Assignment = ExpressionList assign_op ExpressionList .
5954 assign_op = [ add_op | mul_op ] "=" .
5958 Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
5959 a map index expression, or (for <code>=</code> assignments only) the
5960 <a href="#Blank_identifier">blank identifier</a>.
5961 Operands may be parenthesized.
5968 (k) = <-ch // same as: k = <-ch
5972 An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
5973 <code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a>
5974 is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
5975 <code>(y)</code> but evaluates <code>x</code>
5976 only once. The <i>op</i><code>=</code> construct is a single token.
5977 In assignment operations, both the left- and right-hand expression lists
5978 must contain exactly one single-valued expression, and the left-hand
5979 expression must not be the blank identifier.
5984 i &^= 1<<n
5988 A tuple assignment assigns the individual elements of a multi-valued
5989 operation to a list of variables. There are two forms. In the
5990 first, the right hand operand is a single multi-valued expression
5991 such as a function call, a <a href="#Channel_types">channel</a> or
5992 <a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>.
5993 The number of operands on the left
5994 hand side must match the number of values. For instance, if
5995 <code>f</code> is a function returning two values,
6003 assigns the first value to <code>x</code> and the second to <code>y</code>.
6004 In the second form, the number of operands on the left must equal the number
6005 of expressions on the right, each of which must be single-valued, and the
6006 <i>n</i>th expression on the right is assigned to the <i>n</i>th
6007 operand on the left:
6011 one, two, three = '一', '二', '三'
6015 The <a href="#Blank_identifier">blank identifier</a> provides a way to
6016 ignore right-hand side values in an assignment:
6020 _ = x // evaluate x but ignore it
6021 x, _ = f() // evaluate f() but ignore second result value
6025 The assignment proceeds in two phases.
6026 First, the operands of <a href="#Index_expressions">index expressions</a>
6027 and <a href="#Address_operators">pointer indirections</a>
6028 (including implicit pointer indirections in <a href="#Selectors">selectors</a>)
6029 on the left and the expressions on the right are all
6030 <a href="#Order_of_evaluation">evaluated in the usual order</a>.
6031 Second, the assignments are carried out in left-to-right order.
6035 a, b = b, a // exchange a and b
6039 i, x[i] = 1, 2 // set i = 1, x[0] = 2
6042 x[i], i = 2, 1 // set x[0] = 2, i = 1
6044 x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end)
6046 x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5.
6048 type Point struct { x, y int }
6050 x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7
6054 for i, x[i] = range x { // set i, x[2] = 0, x[0]
6057 // after this loop, i == 0 and x == []int{3, 5, 3}
6061 In assignments, each value must be <a href="#Assignability">assignable</a>
6062 to the type of the operand to which it is assigned, with the following special cases:
6067 Any typed value may be assigned to the blank identifier.
6071 If an untyped constant
6072 is assigned to a variable of interface type or the blank identifier,
6073 the constant is first implicitly <a href="#Conversions">converted</a> to its
6074 <a href="#Constants">default type</a>.
6078 If an untyped boolean value is assigned to a variable of interface type or
6079 the blank identifier, it is first implicitly converted to type <code>bool</code>.
6083 <h3 id="If_statements">If statements</h3>
6086 "If" statements specify the conditional execution of two branches
6087 according to the value of a boolean expression. If the expression
6088 evaluates to true, the "if" branch is executed, otherwise, if
6089 present, the "else" branch is executed.
6093 IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
6103 The expression may be preceded by a simple statement, which
6104 executes before the expression is evaluated.
6108 if x := f(); x < y {
6110 } else if x > z {
6118 <h3 id="Switch_statements">Switch statements</h3>
6121 "Switch" statements provide multi-way execution.
6122 An expression or type is compared to the "cases"
6123 inside the "switch" to determine which branch
6128 SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
6132 There are two forms: expression switches and type switches.
6133 In an expression switch, the cases contain expressions that are compared
6134 against the value of the switch expression.
6135 In a type switch, the cases contain types that are compared against the
6136 type of a specially annotated switch expression.
6137 The switch expression is evaluated exactly once in a switch statement.
6140 <h4 id="Expression_switches">Expression switches</h4>
6143 In an expression switch,
6144 the switch expression is evaluated and
6145 the case expressions, which need not be constants,
6146 are evaluated left-to-right and top-to-bottom; the first one that equals the
6148 triggers execution of the statements of the associated case;
6149 the other cases are skipped.
6150 If no case matches and there is a "default" case,
6151 its statements are executed.
6152 There can be at most one default case and it may appear anywhere in the
6154 A missing switch expression is equivalent to the boolean value
6159 ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
6160 ExprCaseClause = ExprSwitchCase ":" StatementList .
6161 ExprSwitchCase = "case" ExpressionList | "default" .
6165 If the switch expression evaluates to an untyped constant, it is first implicitly
6166 <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>.
6167 The predeclared untyped value <code>nil</code> cannot be used as a switch expression.
6168 The switch expression type must be <a href="#Comparison_operators">comparable</a>.
6172 If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a>
6173 to the type of the switch expression.
6174 For each (possibly converted) case expression <code>x</code> and the value <code>t</code>
6175 of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>.
6179 In other words, the switch expression is treated as if it were used to declare and
6180 initialize a temporary variable <code>t</code> without explicit type; it is that
6181 value of <code>t</code> against which each case expression <code>x</code> is tested
6186 In a case or default clause, the last non-empty statement
6187 may be a (possibly <a href="#Labeled_statements">labeled</a>)
6188 <a href="#Fallthrough_statements">"fallthrough" statement</a> to
6189 indicate that control should flow from the end of this clause to
6190 the first statement of the next clause.
6191 Otherwise control flows to the end of the "switch" statement.
6192 A "fallthrough" statement may appear as the last statement of all
6193 but the last clause of an expression switch.
6197 The switch expression may be preceded by a simple statement, which
6198 executes before the expression is evaluated.
6204 case 0, 1, 2, 3: s1()
6205 case 4, 5, 6, 7: s2()
6208 switch x := f(); { // missing switch expression means "true"
6209 case x < 0: return -x
6221 Implementation restriction: A compiler may disallow multiple case
6222 expressions evaluating to the same constant.
6223 For instance, the current compilers disallow duplicate integer,
6224 floating point, or string constants in case expressions.
6227 <h4 id="Type_switches">Type switches</h4>
6230 A type switch compares types rather than values. It is otherwise similar
6231 to an expression switch. It is marked by a special switch expression that
6232 has the form of a <a href="#Type_assertions">type assertion</a>
6233 using the keyword <code>type</code> rather than an actual type:
6243 Cases then match actual types <code>T</code> against the dynamic type of the
6244 expression <code>x</code>. As with type assertions, <code>x</code> must be of
6245 <a href="#Interface_types">interface type</a>, but not a
6246 <a href="#Type_parameters">type parameter</a>, and each non-interface type
6247 <code>T</code> listed in a case must implement the type of <code>x</code>.
6248 The types listed in the cases of a type switch must all be
6249 <a href="#Type_identity">different</a>.
6253 TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
6254 TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
6255 TypeCaseClause = TypeSwitchCase ":" StatementList .
6256 TypeSwitchCase = "case" TypeList | "default" .
6260 The TypeSwitchGuard may include a
6261 <a href="#Short_variable_declarations">short variable declaration</a>.
6262 When that form is used, the variable is declared at the end of the
6263 TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause.
6264 In clauses with a case listing exactly one type, the variable
6265 has that type; otherwise, the variable has the type of the expression
6266 in the TypeSwitchGuard.
6270 Instead of a type, a case may use the predeclared identifier
6271 <a href="#Predeclared_identifiers"><code>nil</code></a>;
6272 that case is selected when the expression in the TypeSwitchGuard
6273 is a <code>nil</code> interface value.
6274 There may be at most one <code>nil</code> case.
6278 Given an expression <code>x</code> of type <code>interface{}</code>,
6279 the following type switch:
6283 switch i := x.(type) {
6285 printString("x is nil") // type of i is type of x (interface{})
6287 printInt(i) // type of i is int
6289 printFloat64(i) // type of i is float64
6290 case func(int) float64:
6291 printFunction(i) // type of i is func(int) float64
6293 printString("type is bool or string") // type of i is type of x (interface{})
6295 printString("don't know the type") // type of i is type of x (interface{})
6304 v := x // x is evaluated exactly once
6306 i := v // type of i is type of x (interface{})
6307 printString("x is nil")
6308 } else if i, isInt := v.(int); isInt {
6309 printInt(i) // type of i is int
6310 } else if i, isFloat64 := v.(float64); isFloat64 {
6311 printFloat64(i) // type of i is float64
6312 } else if i, isFunc := v.(func(int) float64); isFunc {
6313 printFunction(i) // type of i is func(int) float64
6315 _, isBool := v.(bool)
6316 _, isString := v.(string)
6317 if isBool || isString {
6318 i := v // type of i is type of x (interface{})
6319 printString("type is bool or string")
6321 i := v // type of i is type of x (interface{})
6322 printString("don't know the type")
6328 A <a href="#Type_parameters">type parameter</a> or a <a href="#Type_declarations">generic type</a>
6329 may be used as a type in a case. If upon <a href="#Instantiations">instantiation</a> that type turns
6330 out to duplicate another entry in the switch, the first matching case is chosen.
6334 func f[P any](x any) int {
6349 var v1 = f[string]("foo") // v1 == 0
6350 var v2 = f[byte]([]byte{}) // v2 == 2
6354 The type switch guard may be preceded by a simple statement, which
6355 executes before the guard is evaluated.
6359 The "fallthrough" statement is not permitted in a type switch.
6362 <h3 id="For_statements">For statements</h3>
6365 A "for" statement specifies repeated execution of a block. There are three forms:
6366 The iteration may be controlled by a single condition, a "for" clause, or a "range" clause.
6370 ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
6371 Condition = Expression .
6374 <h4 id="For_condition">For statements with single condition</h4>
6377 In its simplest form, a "for" statement specifies the repeated execution of
6378 a block as long as a boolean condition evaluates to true.
6379 The condition is evaluated before each iteration.
6380 If the condition is absent, it is equivalent to the boolean value
6390 <h4 id="For_clause">For statements with <code>for</code> clause</h4>
6393 A "for" statement with a ForClause is also controlled by its condition, but
6394 additionally it may specify an <i>init</i>
6395 and a <i>post</i> statement, such as an assignment,
6396 an increment or decrement statement. The init statement may be a
6397 <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
6398 Variables declared by the init statement are re-used in each iteration.
6402 ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
6403 InitStmt = SimpleStmt .
6404 PostStmt = SimpleStmt .
6408 for i := 0; i < 10; i++ {
6414 If non-empty, the init statement is executed once before evaluating the
6415 condition for the first iteration;
6416 the post statement is executed after each execution of the block (and
6417 only if the block was executed).
6418 Any element of the ForClause may be empty but the
6419 <a href="#Semicolons">semicolons</a> are
6420 required unless there is only a condition.
6421 If the condition is absent, it is equivalent to the boolean value
6426 for cond { S() } is the same as for ; cond ; { S() }
6427 for { S() } is the same as for true { S() }
6430 <h4 id="For_range">For statements with <code>range</code> clause</h4>
6433 A "for" statement with a "range" clause
6434 iterates through all entries of an array, slice, string or map,
6435 or values received on a channel. For each entry it assigns <i>iteration values</i>
6436 to corresponding <i>iteration variables</i> if present and then executes the block.
6440 RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
6444 The expression on the right in the "range" clause is called the <i>range expression</i>,
6445 its <a href="#Core_types">core type</a> must be
6446 an array, pointer to an array, slice, string, map, or channel permitting
6447 <a href="#Receive_operator">receive operations</a>.
6448 As with an assignment, if present the operands on the left must be
6449 <a href="#Address_operators">addressable</a> or map index expressions; they
6450 denote the iteration variables. If the range expression is a channel, at most
6451 one iteration variable is permitted, otherwise there may be up to two.
6452 If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
6453 the range clause is equivalent to the same clause without that identifier.
6457 The range expression <code>x</code> is evaluated once before beginning the loop,
6458 with one exception: if at most one iteration variable is present and
6459 <code>len(x)</code> is <a href="#Length_and_capacity">constant</a>,
6460 the range expression is not evaluated.
6464 Function calls on the left are evaluated once per iteration.
6465 For each iteration, iteration values are produced as follows
6466 if the respective iteration variables are present:
6469 <pre class="grammar">
6470 Range expression 1st value 2nd value
6472 array or slice a [n]E, *[n]E, or []E index i int a[i] E
6473 string s string type index i int see below rune
6474 map m map[K]V key k K m[k] V
6475 channel c chan E, <-chan E element e E
6480 For an array, pointer to array, or slice value <code>a</code>, the index iteration
6481 values are produced in increasing order, starting at element index 0.
6482 If at most one iteration variable is present, the range loop produces
6483 iteration values from 0 up to <code>len(a)-1</code> and does not index into the array
6484 or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
6488 For a string value, the "range" clause iterates over the Unicode code points
6489 in the string starting at byte index 0. On successive iterations, the index value will be the
6490 index of the first byte of successive UTF-8-encoded code points in the string,
6491 and the second value, of type <code>rune</code>, will be the value of
6492 the corresponding code point. If the iteration encounters an invalid
6493 UTF-8 sequence, the second value will be <code>0xFFFD</code>,
6494 the Unicode replacement character, and the next iteration will advance
6495 a single byte in the string.
6499 The iteration order over maps is not specified
6500 and is not guaranteed to be the same from one iteration to the next.
6501 If a map entry that has not yet been reached is removed during iteration,
6502 the corresponding iteration value will not be produced. If a map entry is
6503 created during iteration, that entry may be produced during the iteration or
6504 may be skipped. The choice may vary for each entry created and from one
6505 iteration to the next.
6506 If the map is <code>nil</code>, the number of iterations is 0.
6510 For channels, the iteration values produced are the successive values sent on
6511 the channel until the channel is <a href="#Close">closed</a>. If the channel
6512 is <code>nil</code>, the range expression blocks forever.
6517 The iteration values are assigned to the respective
6518 iteration variables as in an <a href="#Assignments">assignment statement</a>.
6522 The iteration variables may be declared by the "range" clause using a form of
6523 <a href="#Short_variable_declarations">short variable declaration</a>
6525 In this case their types are set to the types of the respective iteration values
6526 and their <a href="#Declarations_and_scope">scope</a> is the block of the "for"
6527 statement; they are re-used in each iteration.
6528 If the iteration variables are declared outside the "for" statement,
6529 after execution their values will be those of the last iteration.
6533 var testdata *struct {
6536 for i, _ := range testdata.a {
6537 // testdata.a is never evaluated; len(testdata.a) is constant
6538 // i ranges from 0 to 6
6543 for i, s := range a {
6545 // type of s is string
6551 var val interface{} // element type of m is assignable to val
6552 m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
6553 for key, val = range m {
6556 // key == last map key encountered in iteration
6559 var ch chan Work = producer()
6569 <h3 id="Go_statements">Go statements</h3>
6572 A "go" statement starts the execution of a function call
6573 as an independent concurrent thread of control, or <i>goroutine</i>,
6574 within the same address space.
6578 GoStmt = "go" Expression .
6582 The expression must be a function or method call; it cannot be parenthesized.
6583 Calls of built-in functions are restricted as for
6584 <a href="#Expression_statements">expression statements</a>.
6588 The function value and parameters are
6589 <a href="#Calls">evaluated as usual</a>
6590 in the calling goroutine, but
6591 unlike with a regular call, program execution does not wait
6592 for the invoked function to complete.
6593 Instead, the function begins executing independently
6595 When the function terminates, its goroutine also terminates.
6596 If the function has any return values, they are discarded when the
6602 go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c)
6606 <h3 id="Select_statements">Select statements</h3>
6609 A "select" statement chooses which of a set of possible
6610 <a href="#Send_statements">send</a> or
6611 <a href="#Receive_operator">receive</a>
6612 operations will proceed.
6613 It looks similar to a
6614 <a href="#Switch_statements">"switch"</a> statement but with the
6615 cases all referring to communication operations.
6619 SelectStmt = "select" "{" { CommClause } "}" .
6620 CommClause = CommCase ":" StatementList .
6621 CommCase = "case" ( SendStmt | RecvStmt ) | "default" .
6622 RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
6623 RecvExpr = Expression .
6627 A case with a RecvStmt may assign the result of a RecvExpr to one or
6628 two variables, which may be declared using a
6629 <a href="#Short_variable_declarations">short variable declaration</a>.
6630 The RecvExpr must be a (possibly parenthesized) receive operation.
6631 There can be at most one default case and it may appear anywhere
6632 in the list of cases.
6636 Execution of a "select" statement proceeds in several steps:
6641 For all the cases in the statement, the channel operands of receive operations
6642 and the channel and right-hand-side expressions of send statements are
6643 evaluated exactly once, in source order, upon entering the "select" statement.
6644 The result is a set of channels to receive from or send to,
6645 and the corresponding values to send.
6646 Any side effects in that evaluation will occur irrespective of which (if any)
6647 communication operation is selected to proceed.
6648 Expressions on the left-hand side of a RecvStmt with a short variable declaration
6649 or assignment are not yet evaluated.
6653 If one or more of the communications can proceed,
6654 a single one that can proceed is chosen via a uniform pseudo-random selection.
6655 Otherwise, if there is a default case, that case is chosen.
6656 If there is no default case, the "select" statement blocks until
6657 at least one of the communications can proceed.
6661 Unless the selected case is the default case, the respective communication
6662 operation is executed.
6666 If the selected case is a RecvStmt with a short variable declaration or
6667 an assignment, the left-hand side expressions are evaluated and the
6668 received value (or values) are assigned.
6672 The statement list of the selected case is executed.
6677 Since communication on <code>nil</code> channels can never proceed,
6678 a select with only <code>nil</code> channels and no default case blocks forever.
6683 var c, c1, c2, c3, c4 chan int
6687 print("received ", i1, " from c1\n")
6689 print("sent ", i2, " to c2\n")
6690 case i3, ok := (<-c3): // same as: i3, ok := <-c3
6692 print("received ", i3, " from c3\n")
6694 print("c3 is closed\n")
6696 case a[f()] = <-c4:
6698 // case t := <-c4
6701 print("no communication\n")
6704 for { // send random sequence of bits to c
6706 case c <- 0: // note: no statement, no fallthrough, no folding of cases
6711 select {} // block forever
6715 <h3 id="Return_statements">Return statements</h3>
6718 A "return" statement in a function <code>F</code> terminates the execution
6719 of <code>F</code>, and optionally provides one or more result values.
6720 Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
6721 are executed before <code>F</code> returns to its caller.
6725 ReturnStmt = "return" [ ExpressionList ] .
6729 In a function without a result type, a "return" statement must not
6730 specify any result values.
6739 There are three ways to return values from a function with a result
6744 <li>The return value or values may be explicitly listed
6745 in the "return" statement. Each expression must be single-valued
6746 and <a href="#Assignability">assignable</a>
6747 to the corresponding element of the function's result type.
6749 func simpleF() int {
6753 func complexF1() (re float64, im float64) {
6758 <li>The expression list in the "return" statement may be a single
6759 call to a multi-valued function. The effect is as if each value
6760 returned from that function were assigned to a temporary
6761 variable with the type of the respective value, followed by a
6762 "return" statement listing these variables, at which point the
6763 rules of the previous case apply.
6765 func complexF2() (re float64, im float64) {
6770 <li>The expression list may be empty if the function's result
6771 type specifies names for its <a href="#Function_types">result parameters</a>.
6772 The result parameters act as ordinary local variables
6773 and the function may assign values to them as necessary.
6774 The "return" statement returns the values of these variables.
6776 func complexF3() (re float64, im float64) {
6782 func (devnull) Write(p []byte) (n int, _ error) {
6791 Regardless of how they are declared, all the result values are initialized to
6792 the <a href="#The_zero_value">zero values</a> for their type upon entry to the
6793 function. A "return" statement that specifies results sets the result parameters before
6794 any deferred functions are executed.
6798 Implementation restriction: A compiler may disallow an empty expression list
6799 in a "return" statement if a different entity (constant, type, or variable)
6800 with the same name as a result parameter is in
6801 <a href="#Declarations_and_scope">scope</a> at the place of the return.
6805 func f(n int) (res int, err error) {
6806 if _, err := f(n-1); err != nil {
6807 return // invalid return statement: err is shadowed
6813 <h3 id="Break_statements">Break statements</h3>
6816 A "break" statement terminates execution of the innermost
6817 <a href="#For_statements">"for"</a>,
6818 <a href="#Switch_statements">"switch"</a>, or
6819 <a href="#Select_statements">"select"</a> statement
6820 within the same function.
6824 BreakStmt = "break" [ Label ] .
6828 If there is a label, it must be that of an enclosing
6829 "for", "switch", or "select" statement,
6830 and that is the one whose execution terminates.
6835 for i = 0; i < n; i++ {
6836 for j = 0; j < m; j++ {
6849 <h3 id="Continue_statements">Continue statements</h3>
6852 A "continue" statement begins the next iteration of the
6853 innermost <a href="#For_statements">"for" loop</a> at its post statement.
6854 The "for" loop must be within the same function.
6858 ContinueStmt = "continue" [ Label ] .
6862 If there is a label, it must be that of an enclosing
6863 "for" statement, and that is the one whose execution
6869 for y, row := range rows {
6870 for x, data := range row {
6871 if data == endOfRow {
6874 row[x] = data + bias(x, y)
6879 <h3 id="Goto_statements">Goto statements</h3>
6882 A "goto" statement transfers control to the statement with the corresponding label
6883 within the same function.
6887 GotoStmt = "goto" Label .
6895 Executing the "goto" statement must not cause any variables to come into
6896 <a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
6897 For instance, this example:
6907 is erroneous because the jump to label <code>L</code> skips
6908 the creation of <code>v</code>.
6912 A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
6913 For instance, this example:
6930 is erroneous because the label <code>L1</code> is inside
6931 the "for" statement's block but the <code>goto</code> is not.
6934 <h3 id="Fallthrough_statements">Fallthrough statements</h3>
6937 A "fallthrough" statement transfers control to the first statement of the
6938 next case clause in an <a href="#Expression_switches">expression "switch" statement</a>.
6939 It may be used only as the final non-empty statement in such a clause.
6943 FallthroughStmt = "fallthrough" .
6947 <h3 id="Defer_statements">Defer statements</h3>
6950 A "defer" statement invokes a function whose execution is deferred
6951 to the moment the surrounding function returns, either because the
6952 surrounding function executed a <a href="#Return_statements">return statement</a>,
6953 reached the end of its <a href="#Function_declarations">function body</a>,
6954 or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>.
6958 DeferStmt = "defer" Expression .
6962 The expression must be a function or method call; it cannot be parenthesized.
6963 Calls of built-in functions are restricted as for
6964 <a href="#Expression_statements">expression statements</a>.
6968 Each time a "defer" statement
6969 executes, the function value and parameters to the call are
6970 <a href="#Calls">evaluated as usual</a>
6971 and saved anew but the actual function is not invoked.
6972 Instead, deferred functions are invoked immediately before
6973 the surrounding function returns, in the reverse order
6974 they were deferred. That is, if the surrounding function
6975 returns through an explicit <a href="#Return_statements">return statement</a>,
6976 deferred functions are executed <i>after</i> any result parameters are set
6977 by that return statement but <i>before</i> the function returns to its caller.
6978 If a deferred function value evaluates
6979 to <code>nil</code>, execution <a href="#Handling_panics">panics</a>
6980 when the function is invoked, not when the "defer" statement is executed.
6984 For instance, if the deferred function is
6985 a <a href="#Function_literals">function literal</a> and the surrounding
6986 function has <a href="#Function_types">named result parameters</a> that
6987 are in scope within the literal, the deferred function may access and modify
6988 the result parameters before they are returned.
6989 If the deferred function has any return values, they are discarded when
6990 the function completes.
6991 (See also the section on <a href="#Handling_panics">handling panics</a>.)
6996 defer unlock(l) // unlocking happens before surrounding function returns
6998 // prints 3 2 1 0 before surrounding function returns
6999 for i := 0; i <= 3; i++ {
7004 func f() (result int) {
7006 // result is accessed after it was set to 6 by the return statement
7013 <h2 id="Built-in_functions">Built-in functions</h2>
7016 Built-in functions are
7017 <a href="#Predeclared_identifiers">predeclared</a>.
7018 They are called like any other function but some of them
7019 accept a type instead of an expression as the first argument.
7023 The built-in functions do not have standard Go types,
7024 so they can only appear in <a href="#Calls">call expressions</a>;
7025 they cannot be used as function values.
7028 <h3 id="Close">Close</h3>
7031 For an argument <code>ch</code> with a <a href="#Core_types">core type</a>
7032 that is a <a href="#Channel_types">channel</a>, the built-in function <code>close</code>
7033 records that no more values will be sent on the channel.
7034 It is an error if <code>ch</code> is a receive-only channel.
7035 Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
7036 Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>.
7037 After calling <code>close</code>, and after any previously
7038 sent values have been received, receive operations will return
7039 the zero value for the channel's type without blocking.
7040 The multi-valued <a href="#Receive_operator">receive operation</a>
7041 returns a received value along with an indication of whether the channel is closed.
7044 <h3 id="Length_and_capacity">Length and capacity</h3>
7047 The built-in functions <code>len</code> and <code>cap</code> take arguments
7048 of various types and return a result of type <code>int</code>.
7049 The implementation guarantees that the result always fits into an <code>int</code>.
7052 <pre class="grammar">
7053 Call Argument type Result
7055 len(s) string type string length in bytes
7056 [n]T, *[n]T array length (== n)
7058 map[K]T map length (number of defined keys)
7059 chan T number of elements queued in channel buffer
7060 type parameter see below
7062 cap(s) [n]T, *[n]T array length (== n)
7064 chan T channel buffer capacity
7065 type parameter see below
7069 If the argument type is a <a href="#Type_parameters">type parameter</a> <code>P</code>,
7070 <code>P</code> must have <a href="#Specific_types">specific types</a>, and
7071 the call <code>len(e)</code> (or <code>cap(e)</code> respectively) must be valid for
7072 each specific type of <code>P</code>.
7073 The result is the length (or capacity, respectively) of the argument whose type
7074 corresponds to the type argument with which <code>P</code> was
7075 <a href="#Instantiations">instantiated</a>.
7079 The capacity of a slice is the number of elements for which there is
7080 space allocated in the underlying array.
7081 At any time the following relationship holds:
7085 0 <= len(s) <= cap(s)
7089 The length of a <code>nil</code> slice, map or channel is 0.
7090 The capacity of a <code>nil</code> slice or channel is 0.
7094 The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
7095 <code>s</code> is a string constant. The expressions <code>len(s)</code> and
7096 <code>cap(s)</code> are constants if the type of <code>s</code> is an array
7097 or pointer to an array and the expression <code>s</code> does not contain
7098 <a href="#Receive_operator">channel receives</a> or (non-constant)
7099 <a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated.
7100 Otherwise, invocations of <code>len</code> and <code>cap</code> are not
7101 constant and <code>s</code> is evaluated.
7106 c1 = imag(2i) // imag(2i) = 2.0 is a constant
7107 c2 = len([10]float64{2}) // [10]float64{2} contains no function calls
7108 c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls
7109 c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued
7110 c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call
7115 <h3 id="Allocation">Allocation</h3>
7118 The built-in function <code>new</code> takes a type <code>T</code>,
7119 allocates storage for a <a href="#Variables">variable</a> of that type
7120 at run time, and returns a value of type <code>*T</code>
7121 <a href="#Pointer_types">pointing</a> to it.
7122 The variable is initialized as described in the section on
7123 <a href="#The_zero_value">initial values</a>.
7126 <pre class="grammar">
7135 type S struct { a int; b float64 }
7140 allocates storage for a variable of type <code>S</code>,
7141 initializes it (<code>a=0</code>, <code>b=0.0</code>),
7142 and returns a value of type <code>*S</code> containing the address
7146 <h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
7149 The built-in function <code>make</code> takes a type <code>T</code>,
7150 optionally followed by a type-specific list of expressions.
7151 The <a href="#Core_types">core type</a> of <code>T</code> must
7152 be a slice, map or channel.
7153 It returns a value of type <code>T</code> (not <code>*T</code>).
7154 The memory is initialized as described in the section on
7155 <a href="#The_zero_value">initial values</a>.
7158 <pre class="grammar">
7159 Call Core type Result
7161 make(T, n) slice slice of type T with length n and capacity n
7162 make(T, n, m) slice slice of type T with length n and capacity m
7164 make(T) map map of type T
7165 make(T, n) map map of type T with initial space for approximately n elements
7167 make(T) channel unbuffered channel of type T
7168 make(T, n) channel buffered channel of type T, buffer size n
7173 Each of the size arguments <code>n</code> and <code>m</code> must be of <a href="#Numeric_types">integer type</a>
7174 or an untyped <a href="#Constants">constant</a>.
7175 A constant size argument must be non-negative and <a href="#Representability">representable</a>
7176 by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>.
7177 If both <code>n</code> and <code>m</code> are provided and are constant, then
7178 <code>n</code> must be no larger than <code>m</code>.
7179 If <code>n</code> is negative or larger than <code>m</code> at run time,
7180 a <a href="#Run_time_panics">run-time panic</a> occurs.
7184 s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100
7185 s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000
7186 s := make([]int, 1<<63) // illegal: len(s) is not representable by a value of type int
7187 s := make([]int, 10, 0) // illegal: len(s) > cap(s)
7188 c := make(chan int, 10) // channel with a buffer size of 10
7189 m := make(map[string]int, 100) // map with initial space for approximately 100 elements
7193 Calling <code>make</code> with a map type and size hint <code>n</code> will
7194 create a map with initial space to hold <code>n</code> map elements.
7195 The precise behavior is implementation-dependent.
7199 <h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
7202 The built-in functions <code>append</code> and <code>copy</code> assist in
7203 common slice operations.
7204 For both functions, the result is independent of whether the memory referenced
7205 by the arguments overlaps.
7209 The <a href="#Function_types">variadic</a> function <code>append</code>
7210 appends zero or more values <code>x</code> to a slice <code>s</code>
7211 and returns the resulting slice.
7212 The <a href="#Core_types">core type</a> of <code>s</code> must be a slice
7213 of the form <code>[]E</code>.
7214 The values <code>x</code> are passed to a parameter of type <code>...E</code>
7215 and the respective <a href="#Passing_arguments_to_..._parameters">parameter
7216 passing rules</a> apply.
7217 As a special case, if the core type of <code>s</code> is <code>[]byte</code>,
7218 <code>append</code> also accepts a second argument with core type <code>string</code>
7219 followed by <code>...</code>. This form appends the bytes of the string.
7222 <pre class="grammar">
7223 append(s S, x ...E) S // E is the element type of the core type of S
7227 If the capacity of <code>s</code> is not large enough to fit the additional
7228 values, <code>append</code> allocates a new, sufficiently large underlying
7229 array that fits both the existing slice elements and the additional values.
7230 Otherwise, <code>append</code> re-uses the underlying array.
7235 s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2}
7236 s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7}
7237 s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
7238 s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
7241 t = append(t, 42, 3.1415, "foo") // t == []interface{}{42, 3.1415, "foo"}
7244 b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' }
7248 The function <code>copy</code> copies slice elements from
7249 a source <code>src</code> to a destination <code>dst</code> and returns the
7250 number of elements copied.
7251 The <a href="#Core_types">core types</a> of both arguments must be slices
7252 with <a href="#Type_identity">identical</a> element type.
7253 The number of elements copied is the minimum of
7254 <code>len(src)</code> and <code>len(dst)</code>.
7255 As a special case, if the destination's core type is <code>[]byte</code>,
7256 <code>copy</code> also accepts a source argument with core type <code>string</code>.
7257 This form copies the bytes from the string into the byte slice.
7260 <pre class="grammar">
7261 copy(dst, src []T) int
7262 copy(dst []byte, src string) int
7270 var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
7271 var s = make([]int, 6)
7272 var b = make([]byte, 5)
7273 n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5}
7274 n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5}
7275 n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello")
7279 <h3 id="Deletion_of_map_elements">Deletion of map elements</h3>
7282 The built-in function <code>delete</code> removes the element with key
7283 <code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The
7284 value <code>k</code> must be <a href="#Assignability">assignable</a>
7285 to the key type of <code>m</code>.
7288 <pre class="grammar">
7289 delete(m, k) // remove element m[k] from map m
7293 If the type of <code>m</code> is a <a href="#Type_parameters">type parameter</a>,
7294 it must have <a href="#Specific_types">specific types</a>, all specific types
7295 must be maps, and they must all have identical key types.
7299 If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code>
7300 does not exist, <code>delete</code> is a no-op.
7304 <h3 id="Complex_numbers">Manipulating complex numbers</h3>
7306 <!-- We don't support generic arguments for these operations yet. -->
7309 Three functions assemble and disassemble complex numbers.
7310 The built-in function <code>complex</code> constructs a complex
7311 value from a floating-point real and imaginary part, while
7312 <code>real</code> and <code>imag</code>
7313 extract the real and imaginary parts of a complex value.
7316 <pre class="grammar">
7317 complex(realPart, imaginaryPart floatT) complexT
7318 real(complexT) floatT
7319 imag(complexT) floatT
7323 The type of the arguments and return value correspond.
7324 For <code>complex</code>, the two arguments must be of the same
7325 <a href="#Numeric_types">floating-point type</a> and the return type is the
7326 <a href="#Numeric_types">complex type</a>
7327 with the corresponding floating-point constituents:
7328 <code>complex64</code> for <code>float32</code> arguments, and
7329 <code>complex128</code> for <code>float64</code> arguments.
7330 If one of the arguments evaluates to an untyped constant, it is first implicitly
7331 <a href="#Conversions">converted</a> to the type of the other argument.
7332 If both arguments evaluate to untyped constants, they must be non-complex
7333 numbers or their imaginary parts must be zero, and the return value of
7334 the function is an untyped complex constant.
7338 For <code>real</code> and <code>imag</code>, the argument must be
7339 of complex type, and the return type is the corresponding floating-point
7340 type: <code>float32</code> for a <code>complex64</code> argument, and
7341 <code>float64</code> for a <code>complex128</code> argument.
7342 If the argument evaluates to an untyped constant, it must be a number,
7343 and the return value of the function is an untyped floating-point constant.
7347 The <code>real</code> and <code>imag</code> functions together form the inverse of
7348 <code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>,
7349 <code>z == Z(complex(real(z), imag(z)))</code>.
7353 If the operands of these functions are all constants, the return
7354 value is a constant.
7358 var a = complex(2, -2) // complex128
7359 const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i
7360 x := float32(math.Cos(math.Pi/2)) // float32
7361 var c64 = complex(5, -x) // complex64
7362 var s int = complex(1, 0) // untyped complex constant 1 + 0i can be converted to int
7363 _ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift
7364 var rl = real(c64) // float32
7365 var im = imag(a) // float64
7366 const c = imag(b) // untyped constant -1.4
7367 _ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift
7370 <h3 id="Handling_panics">Handling panics</h3>
7372 <p> Two built-in functions, <code>panic</code> and <code>recover</code>,
7373 assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
7374 and program-defined error conditions.
7377 <pre class="grammar">
7378 func panic(interface{})
7379 func recover() interface{}
7383 While executing a function <code>F</code>,
7384 an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
7385 terminates the execution of <code>F</code>.
7386 Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
7387 are then executed as usual.
7388 Next, any deferred functions run by <code>F's</code> caller are run,
7389 and so on up to any deferred by the top-level function in the executing goroutine.
7390 At that point, the program is terminated and the error
7391 condition is reported, including the value of the argument to <code>panic</code>.
7392 This termination sequence is called <i>panicking</i>.
7397 panic("unreachable")
7398 panic(Error("cannot parse"))
7402 The <code>recover</code> function allows a program to manage behavior
7403 of a panicking goroutine.
7404 Suppose a function <code>G</code> defers a function <code>D</code> that calls
7405 <code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
7407 When the running of deferred functions reaches <code>D</code>,
7408 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>.
7409 If <code>D</code> returns normally, without starting a new
7410 <code>panic</code>, the panicking sequence stops. In that case,
7411 the state of functions called between <code>G</code> and the call to <code>panic</code>
7412 is discarded, and normal execution resumes.
7413 Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
7414 execution terminates by returning to its caller.
7418 The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds:
7422 <code>panic</code>'s argument was <code>nil</code>;
7425 the goroutine is not panicking;
7428 <code>recover</code> was not called directly by a deferred function.
7433 The <code>protect</code> function in the example below invokes
7434 the function argument <code>g</code> and protects callers from
7435 run-time panics raised by <code>g</code>.
7439 func protect(g func()) {
7441 log.Println("done") // Println executes normally even if there is a panic
7442 if x := recover(); x != nil {
7443 log.Printf("run time panic: %v", x)
7446 log.Println("start")
7452 <h3 id="Bootstrapping">Bootstrapping</h3>
7455 Current implementations provide several built-in functions useful during
7456 bootstrapping. These functions are documented for completeness but are not
7457 guaranteed to stay in the language. They do not return a result.
7460 <pre class="grammar">
7463 print prints all arguments; formatting of arguments is implementation-specific
7464 println like print but prints spaces between arguments and a newline at the end
7468 Implementation restriction: <code>print</code> and <code>println</code> need not
7469 accept arbitrary argument types, but printing of boolean, numeric, and string
7470 <a href="#Types">types</a> must be supported.
7473 <h2 id="Packages">Packages</h2>
7476 Go programs are constructed by linking together <i>packages</i>.
7477 A package in turn is constructed from one or more source files
7478 that together declare constants, types, variables and functions
7479 belonging to the package and which are accessible in all files
7480 of the same package. Those elements may be
7481 <a href="#Exported_identifiers">exported</a> and used in another package.
7484 <h3 id="Source_file_organization">Source file organization</h3>
7487 Each source file consists of a package clause defining the package
7488 to which it belongs, followed by a possibly empty set of import
7489 declarations that declare packages whose contents it wishes to use,
7490 followed by a possibly empty set of declarations of functions,
7491 types, variables, and constants.
7495 SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
7498 <h3 id="Package_clause">Package clause</h3>
7501 A package clause begins each source file and defines the package
7502 to which the file belongs.
7506 PackageClause = "package" PackageName .
7507 PackageName = identifier .
7511 The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
7519 A set of files sharing the same PackageName form the implementation of a package.
7520 An implementation may require that all source files for a package inhabit the same directory.
7523 <h3 id="Import_declarations">Import declarations</h3>
7526 An import declaration states that the source file containing the declaration
7527 depends on functionality of the <i>imported</i> package
7528 (<a href="#Program_initialization_and_execution">§Program initialization and execution</a>)
7529 and enables access to <a href="#Exported_identifiers">exported</a> identifiers
7531 The import names an identifier (PackageName) to be used for access and an ImportPath
7532 that specifies the package to be imported.
7536 ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
7537 ImportSpec = [ "." | PackageName ] ImportPath .
7538 ImportPath = string_lit .
7542 The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
7543 to access exported identifiers of the package within the importing source file.
7544 It is declared in the <a href="#Blocks">file block</a>.
7545 If the PackageName is omitted, it defaults to the identifier specified in the
7546 <a href="#Package_clause">package clause</a> of the imported package.
7547 If an explicit period (<code>.</code>) appears instead of a name, all the
7548 package's exported identifiers declared in that package's
7549 <a href="#Blocks">package block</a> will be declared in the importing source
7550 file's file block and must be accessed without a qualifier.
7554 The interpretation of the ImportPath is implementation-dependent but
7555 it is typically a substring of the full file name of the compiled
7556 package and may be relative to a repository of installed packages.
7560 Implementation restriction: A compiler may restrict ImportPaths to
7561 non-empty strings using only characters belonging to
7562 <a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a>
7563 L, M, N, P, and S general categories (the Graphic characters without
7564 spaces) and may also exclude the characters
7565 <code>!"#$%&'()*,:;<=>?[\]^`{|}</code>
7566 and the Unicode replacement character U+FFFD.
7570 Assume we have compiled a package containing the package clause
7571 <code>package math</code>, which exports function <code>Sin</code>, and
7572 installed the compiled package in the file identified by
7573 <code>"lib/math"</code>.
7574 This table illustrates how <code>Sin</code> is accessed in files
7575 that import the package after the
7576 various types of import declaration.
7579 <pre class="grammar">
7580 Import declaration Local name of Sin
7582 import "lib/math" math.Sin
7583 import m "lib/math" m.Sin
7584 import . "lib/math" Sin
7588 An import declaration declares a dependency relation between
7589 the importing and imported package.
7590 It is illegal for a package to import itself, directly or indirectly,
7591 or to directly import a package without
7592 referring to any of its exported identifiers. To import a package solely for
7593 its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
7594 identifier as explicit package name:
7602 <h3 id="An_example_package">An example package</h3>
7605 Here is a complete Go package that implements a concurrent prime sieve.
7613 // Send the sequence 2, 3, 4, … to channel 'ch'.
7614 func generate(ch chan<- int) {
7616 ch <- i // Send 'i' to channel 'ch'.
7620 // Copy the values from channel 'src' to channel 'dst',
7621 // removing those divisible by 'prime'.
7622 func filter(src <-chan int, dst chan<- int, prime int) {
7623 for i := range src { // Loop over values received from 'src'.
7625 dst <- i // Send 'i' to channel 'dst'.
7630 // The prime sieve: Daisy-chain filter processes together.
7632 ch := make(chan int) // Create a new channel.
7633 go generate(ch) // Start generate() as a subprocess.
7636 fmt.Print(prime, "\n")
7637 ch1 := make(chan int)
7638 go filter(ch, ch1, prime)
7648 <h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
7650 <h3 id="The_zero_value">The zero value</h3>
7652 When storage is allocated for a <a href="#Variables">variable</a>,
7653 either through a declaration or a call of <code>new</code>, or when
7654 a new value is created, either through a composite literal or a call
7655 of <code>make</code>,
7656 and no explicit initialization is provided, the variable or value is
7657 given a default value. Each element of such a variable or value is
7658 set to the <i>zero value</i> for its type: <code>false</code> for booleans,
7659 <code>0</code> for numeric types, <code>""</code>
7660 for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
7661 This initialization is done recursively, so for instance each element of an
7662 array of structs will have its fields zeroed if no value is specified.
7665 These two simple declarations are equivalent:
7678 type T struct { i int; f float64; next *T }
7683 the following holds:
7693 The same would also be true after
7700 <h3 id="Package_initialization">Package initialization</h3>
7703 Within a package, package-level variable initialization proceeds stepwise,
7704 with each step selecting the variable earliest in <i>declaration order</i>
7705 which has no dependencies on uninitialized variables.
7709 More precisely, a package-level variable is considered <i>ready for
7710 initialization</i> if it is not yet initialized and either has
7711 no <a href="#Variable_declarations">initialization expression</a> or
7712 its initialization expression has no <i>dependencies</i> on uninitialized variables.
7713 Initialization proceeds by repeatedly initializing the next package-level
7714 variable that is earliest in declaration order and ready for initialization,
7715 until there are no variables ready for initialization.
7719 If any variables are still uninitialized when this
7720 process ends, those variables are part of one or more initialization cycles,
7721 and the program is not valid.
7725 Multiple variables on the left-hand side of a variable declaration initialized
7726 by single (multi-valued) expression on the right-hand side are initialized
7727 together: If any of the variables on the left-hand side is initialized, all
7728 those variables are initialized in the same step.
7733 var a, b = f() // a and b are initialized together, before x is initialized
7737 For the purpose of package initialization, <a href="#Blank_identifier">blank</a>
7738 variables are treated like any other variables in declarations.
7742 The declaration order of variables declared in multiple files is determined
7743 by the order in which the files are presented to the compiler: Variables
7744 declared in the first file are declared before any of the variables declared
7745 in the second file, and so on.
7749 Dependency analysis does not rely on the actual values of the
7750 variables, only on lexical <i>references</i> to them in the source,
7751 analyzed transitively. For instance, if a variable <code>x</code>'s
7752 initialization expression refers to a function whose body refers to
7753 variable <code>y</code> then <code>x</code> depends on <code>y</code>.
7759 A reference to a variable or function is an identifier denoting that
7760 variable or function.
7764 A reference to a method <code>m</code> is a
7765 <a href="#Method_values">method value</a> or
7766 <a href="#Method_expressions">method expression</a> of the form
7767 <code>t.m</code>, where the (static) type of <code>t</code> is
7768 not an interface type, and the method <code>m</code> is in the
7769 <a href="#Method_sets">method set</a> of <code>t</code>.
7770 It is immaterial whether the resulting function value
7771 <code>t.m</code> is invoked.
7775 A variable, function, or method <code>x</code> depends on a variable
7776 <code>y</code> if <code>x</code>'s initialization expression or body
7777 (for functions and methods) contains a reference to <code>y</code>
7778 or to a function or method that depends on <code>y</code>.
7783 For example, given the declarations
7791 d = 3 // == 5 after initialization has finished
7801 the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>.
7802 Note that the order of subexpressions in initialization expressions is irrelevant:
7803 <code>a = c + b</code> and <code>a = b + c</code> result in the same initialization
7804 order in this example.
7808 Dependency analysis is performed per package; only references referring
7809 to variables, functions, and (non-interface) methods declared in the current
7810 package are considered. If other, hidden, data dependencies exists between
7811 variables, the initialization order between those variables is unspecified.
7815 For instance, given the declarations
7819 var x = I(T{}).ab() // x has an undetected, hidden dependency on a and b
7820 var _ = sideEffect() // unrelated to x, a, or b
7824 type I interface { ab() []int }
7826 func (T) ab() []int { return []int{a, b} }
7830 the variable <code>a</code> will be initialized after <code>b</code> but
7831 whether <code>x</code> is initialized before <code>b</code>, between
7832 <code>b</code> and <code>a</code>, or after <code>a</code>, and
7833 thus also the moment at which <code>sideEffect()</code> is called (before
7834 or after <code>x</code> is initialized) is not specified.
7838 Variables may also be initialized using functions named <code>init</code>
7839 declared in the package block, with no arguments and no result parameters.
7847 Multiple such functions may be defined per package, even within a single
7848 source file. In the package block, the <code>init</code> identifier can
7849 be used only to declare <code>init</code> functions, yet the identifier
7850 itself is not <a href="#Declarations_and_scope">declared</a>. Thus
7851 <code>init</code> functions cannot be referred to from anywhere
7856 A package with no imports is initialized by assigning initial values
7857 to all its package-level variables followed by calling all <code>init</code>
7858 functions in the order they appear in the source, possibly in multiple files,
7859 as presented to the compiler.
7860 If a package has imports, the imported packages are initialized
7861 before initializing the package itself. If multiple packages import
7862 a package, the imported package will be initialized only once.
7863 The importing of packages, by construction, guarantees that there
7864 can be no cyclic initialization dependencies.
7868 Package initialization—variable initialization and the invocation of
7869 <code>init</code> functions—happens in a single goroutine,
7870 sequentially, one package at a time.
7871 An <code>init</code> function may launch other goroutines, which can run
7872 concurrently with the initialization code. However, initialization
7874 the <code>init</code> functions: it will not invoke the next one
7875 until the previous one has returned.
7879 To ensure reproducible initialization behavior, build systems are encouraged
7880 to present multiple files belonging to the same package in lexical file name
7881 order to a compiler.
7885 <h3 id="Program_execution">Program execution</h3>
7887 A complete program is created by linking a single, unimported package
7888 called the <i>main package</i> with all the packages it imports, transitively.
7889 The main package must
7890 have package name <code>main</code> and
7891 declare a function <code>main</code> that takes no
7892 arguments and returns no value.
7900 Program execution begins by initializing the main package and then
7901 invoking the function <code>main</code>.
7902 When that function invocation returns, the program exits.
7903 It does not wait for other (non-<code>main</code>) goroutines to complete.
7906 <h2 id="Errors">Errors</h2>
7909 The predeclared type <code>error</code> is defined as
7913 type error interface {
7919 It is the conventional interface for representing an error condition,
7920 with the nil value representing no error.
7921 For instance, a function to read data from a file might be defined:
7925 func Read(f *File, b []byte) (n int, err error)
7928 <h2 id="Run_time_panics">Run-time panics</h2>
7931 Execution errors such as attempting to index an array out
7932 of bounds trigger a <i>run-time panic</i> equivalent to a call of
7933 the built-in function <a href="#Handling_panics"><code>panic</code></a>
7934 with a value of the implementation-defined interface type <code>runtime.Error</code>.
7935 That type satisfies the predeclared interface type
7936 <a href="#Errors"><code>error</code></a>.
7937 The exact error values that
7938 represent distinct run-time error conditions are unspecified.
7944 type Error interface {
7946 // and perhaps other methods
7950 <h2 id="System_considerations">System considerations</h2>
7952 <h3 id="Package_unsafe">Package <code>unsafe</code></h3>
7955 The built-in package <code>unsafe</code>, known to the compiler
7956 and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>,
7957 provides facilities for low-level programming including operations
7958 that violate the type system. A package using <code>unsafe</code>
7959 must be vetted manually for type safety and may not be portable.
7960 The package provides the following interface:
7963 <pre class="grammar">
7966 type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type
7967 type Pointer *ArbitraryType
7969 func Alignof(variable ArbitraryType) uintptr
7970 func Offsetof(selector ArbitraryType) uintptr
7971 func Sizeof(variable ArbitraryType) uintptr
7973 type IntegerType int // shorthand for an integer type; it is not a real type
7974 func Add(ptr Pointer, len IntegerType) Pointer
7975 func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType
7979 A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
7980 value may not be <a href="#Address_operators">dereferenced</a>.
7981 Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to
7982 a type of underlying type <code>Pointer</code> and vice versa.
7983 The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined.
7988 bits = *(*uint64)(unsafe.Pointer(&f))
7990 type ptr unsafe.Pointer
7991 bits = *(*uint64)(ptr(&f))
7997 The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
7998 of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
7999 as if <code>v</code> was declared via <code>var v = x</code>.
8002 The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
8003 <code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
8004 or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
8005 If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
8006 without pointer indirections through fields of the struct.
8007 For a struct <code>s</code> with field <code>f</code>:
8011 uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f))
8015 Computer architectures may require memory addresses to be <i>aligned</i>;
8016 that is, for addresses of a variable to be a multiple of a factor,
8017 the variable's type's <i>alignment</i>. The function <code>Alignof</code>
8018 takes an expression denoting a variable of any type and returns the
8019 alignment of the (type of the) variable in bytes. For a variable
8024 uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0
8028 A (variable of) type <code>T</code> has <i>variable size</i> if <code>T</code>
8029 is a type parameter, or if it is an array or struct type containing elements
8030 or fields of variable size. Otherwise the size is <i>constant</i>.
8031 Calls to <code>Alignof</code>, <code>Offsetof</code>, and <code>Sizeof</code>
8032 are compile-time <a href="#Constant_expressions">constant expressions</a> of
8033 type <code>uintptr</code> if their arguments (or the struct <code>s</code> in
8034 the selector expression <code>s.f</code> for <code>Offsetof</code>) are types
8039 The function <code>Add</code> adds <code>len</code> to <code>ptr</code>
8040 and returns the updated pointer <code>unsafe.Pointer(uintptr(ptr) + uintptr(len))</code>.
8041 The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>.
8042 A constant <code>len</code> argument must be <a href="#Representability">representable</a> by a value of type <code>int</code>;
8043 if it is an untyped constant it is given type <code>int</code>.
8044 The rules for <a href="/pkg/unsafe#Pointer">valid uses</a> of <code>Pointer</code> still apply.
8048 The function <code>Slice</code> returns a slice whose underlying array starts at <code>ptr</code>
8049 and whose length and capacity are <code>len</code>.
8050 <code>Slice(ptr, len)</code> is equivalent to
8054 (*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
8058 except that, as a special case, if <code>ptr</code>
8059 is <code>nil</code> and <code>len</code> is zero,
8060 <code>Slice</code> returns <code>nil</code>.
8064 The <code>len</code> argument must be of <a href="#Numeric_types">integer type</a> or an untyped <a href="#Constants">constant</a>.
8065 A constant <code>len</code> argument must be non-negative and <a href="#Representability">representable</a> by a value of type <code>int</code>;
8066 if it is an untyped constant it is given type <code>int</code>.
8067 At run time, if <code>len</code> is negative,
8068 or if <code>ptr</code> is <code>nil</code> and <code>len</code> is not zero,
8069 a <a href="#Run_time_panics">run-time panic</a> occurs.
8072 <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
8075 For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
8078 <pre class="grammar">
8083 uint32, int32, float32 4
8084 uint64, int64, float64, complex64 8
8089 The following minimal alignment properties are guaranteed:
8092 <li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
8095 <li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
8096 all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
8099 <li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
8100 the alignment of a variable of the array's element type.
8105 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.