Go: doc/go_spec.html

"Fossies" - the Fresh Open Source Software Archive

Member "go/doc/go_spec.html" (26 Apr 2023, 269432 Bytes) of package /linux/misc/go1.20.4.src.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1  6 7 <h2 id="Introduction">Introduction</h2> 8 9 10 This is the reference manual for the Go programming language. 11 The pre-Go1.18 version, without generics, can be found 12 <a href="/doc/go1.17_spec.html">here</a>. 13 For more information and other documents, see <a href="/">golang.org</a>. 14 15 16 17 Go is a general-purpose language designed with systems programming 18 in mind. It is strongly typed and garbage-collected and has explicit 19 support for concurrent programming. Programs are constructed from 20 packages, whose properties allow efficient management of 21 dependencies. 22 23 24 25 The syntax is compact and simple to parse, allowing for easy analysis 26 by automatic tools such as integrated development environments. 27 28 29 <h2 id="Notation">Notation</h2> 30 31 The syntax is specified using a 32 <a href="https://en.wikipedia.org/wiki/Wirth_syntax_notation">variant</a> 33 of Extended Backus-Naur Form (EBNF): 34 35 36 <pre class="grammar"> 37 Syntax = { Production } . 38 Production = production_name "=" [ Expression ] "." . 39 Expression = Term { "|" Term } . 40 Term = Factor { Factor } . 41 Factor = production_name | token [ "…" token ] | Group | Option | Repetition . 42 Group = "(" Expression ")" . 43 Option = "[" Expression "]" . 44 Repetition = "{" Expression "}" . 45 </pre> 46 47 48 Productions are expressions constructed from terms and the following 49 operators, in increasing precedence: 50 51 <pre class="grammar"> 52 | alternation 53 () grouping 54 [] option (0 or 1 times) 55 {} repetition (0 to n times) 56 </pre> 57 58 59 Lowercase production names are used to identify lexical (terminal) tokens. 60 Non-terminals are in CamelCase. Lexical tokens are enclosed in 61 double quotes <code>""</code> or back quotes <code>``</code>. 62 63 64 65 The form <code>a … b</code> represents the set of characters from 66 <code>a</code> through <code>b</code> as alternatives. The horizontal 67 ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various 68 enumerations or code snippets that are not further specified. The character <code>…</code> 69 (as opposed to the three characters <code>...</code>) is not a token of the Go 70 language. 71 72 73 <h2 id="Source_code_representation">Source code representation</h2> 74 75 76 Source code is Unicode text encoded in 77 <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not 78 canonicalized, so a single accented code point is distinct from the 79 same character constructed from combining an accent and a letter; 80 those are treated as two code points. For simplicity, this document 81 will use the unqualified term character to refer to a Unicode code point 82 in the source text. 83 84 85 Each code point is distinct; for instance, uppercase and lowercase letters 86 are different characters. 87 88 89 Implementation restriction: For compatibility with other tools, a 90 compiler may disallow the NUL character (U+0000) in the source text. 91 92 93 Implementation restriction: For compatibility with other tools, a 94 compiler may ignore a UTF-8-encoded byte order mark 95 (U+FEFF) if it is the first Unicode code point in the source text. 96 A byte order mark may be disallowed anywhere else in the source. 97 98 99 <h3 id="Characters">Characters</h3> 100 101 102 The following terms are used to denote specific Unicode character categories: 103 104 <pre class="ebnf"> 105 newline = /* the Unicode code point U+000A */ . 106 unicode_char = /* an arbitrary Unicode code point except newline */ . 107 unicode_letter = /* a Unicode code point categorized as "Letter" */ . 108 unicode_digit = /* a Unicode code point categorized as "Number, decimal digit" */ . 109 </pre> 110 111 112 In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>, 113 Section 4.5 "General Category" defines a set of character categories. 114 Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo 115 as Unicode letters, and those in the Number category Nd as Unicode digits. 116 117 118 <h3 id="Letters_and_digits">Letters and digits</h3> 119 120 121 The underscore character <code>_</code> (U+005F) is considered a lowercase letter. 122 123 <pre class="ebnf"> 124 letter = unicode_letter | "_" . 125 decimal_digit = "0" … "9" . 126 binary_digit = "0" | "1" . 127 octal_digit = "0" … "7" . 128 hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . 129 </pre> 130 131 <h2 id="Lexical_elements">Lexical elements</h2> 132 133 <h3 id="Comments">Comments</h3> 134 135 136 Comments serve as program documentation. There are two forms: 137 138 139 <ol> 140 <li> 141 Line comments start with the character sequence <code>//</code> 142 and stop at the end of the line. 143 </li> 144 <li> 145 General comments start with the character sequence <code>/*</code> 146 and stop with the first subsequent character sequence <code>*/</code>. 147 </li> 148 </ol> 149 150 151 A comment cannot start inside a <a href="#Rune_literals">rune</a> or 152 <a href="#String_literals">string literal</a>, or inside a comment. 153 A general comment containing no newlines acts like a space. 154 Any other comment acts like a newline. 155 156 157 <h3 id="Tokens">Tokens</h3> 158 159 160 Tokens form the vocabulary of the Go language. 161 There are four classes: identifiers, keywords, operators 162 and punctuation, and literals. White space, formed from 163 spaces (U+0020), horizontal tabs (U+0009), 164 carriage returns (U+000D), and newlines (U+000A), 165 is ignored except as it separates tokens 166 that would otherwise combine into a single token. Also, a newline or end of file 167 may trigger the insertion of a <a href="#Semicolons">semicolon</a>. 168 While breaking the input into tokens, 169 the next token is the longest sequence of characters that form a 170 valid token. 171 172 173 <h3 id="Semicolons">Semicolons</h3> 174 175 176 The formal syntax uses semicolons <code>";"</code> as terminators in 177 a number of productions. Go programs may omit most of these semicolons 178 using the following two rules: 179 180 181 <ol> 182 <li> 183 When the input is broken into tokens, a semicolon is automatically inserted 184 into the token stream immediately after a line's final token if that token is 185 <ul> 186 <li>an 187 <a href="#Identifiers">identifier</a> 188 </li> 189 190 <li>an 191 <a href="#Integer_literals">integer</a>, 192 <a href="#Floating-point_literals">floating-point</a>, 193 <a href="#Imaginary_literals">imaginary</a>, 194 <a href="#Rune_literals">rune</a>, or 195 <a href="#String_literals">string</a> literal 196 </li> 197 198 <li>one of the <a href="#Keywords">keywords</a> 199 <code>break</code>, 200 <code>continue</code>, 201 <code>fallthrough</code>, or 202 <code>return</code> 203 </li> 204 205 <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a> 206 <code>++</code>, 207 <code>--</code>, 208 <code>)</code>, 209 <code>]</code>, or 210 <code>}</code> 211 </li> 212 </ul> 213 </li> 214 215 <li> 216 To allow complex statements to occupy a single line, a semicolon 217 may be omitted before a closing <code>")"</code> or <code>"}"</code>. 218 </li> 219 </ol> 220 221 222 To reflect idiomatic use, code examples in this document elide semicolons 223 using these rules. 224 225 226 227 <h3 id="Identifiers">Identifiers</h3> 228 229 230 Identifiers name program entities such as variables and types. 231 An identifier is a sequence of one or more letters and digits. 232 The first character in an identifier must be a letter. 233 234 <pre class="ebnf"> 235 identifier = letter { letter | unicode_digit } . 236 </pre> 237 <pre> 238 a 239 _x9 240 ThisVariableIsExported 241 αβ 242 </pre> 243 244 245 Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. 246 247 248 249 <h3 id="Keywords">Keywords</h3> 250 251 252 The following keywords are reserved and may not be used as identifiers. 253 254 <pre class="grammar"> 255 break default func interface select 256 case defer go map struct 257 chan else goto package switch 258 const fallthrough if range type 259 continue for import return var 260 </pre> 261 262 <h3 id="Operators_and_punctuation">Operators and punctuation</h3> 263 264 265 The following character sequences represent <a href="#Operators">operators</a> 266 (including <a href="#Assignment_statements">assignment operators</a>) and punctuation: 267 268 <pre class="grammar"> 269 + & += &= && == != ( ) 270 - | -= |= || < <= [ ] 271 * ^ *= ^= <- > >= { } 272 / << /= <<= ++ = := , ; 273 % >> %= >>= -- ! ... . : 274 &^ &^= ~ 275 </pre> 276 277 <h3 id="Integer_literals">Integer literals</h3> 278 279 280 An integer literal is a sequence of digits representing an 281 <a href="#Constants">integer constant</a>. 282 An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code> 283 for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal, 284 and <code>0x</code> or <code>0X</code> for hexadecimal. 285 A single <code>0</code> is considered a decimal zero. 286 In hexadecimal literals, letters <code>a</code> through <code>f</code> 287 and <code>A</code> through <code>F</code> represent values 10 through 15. 288 289 290 291 For readability, an underscore character <code>_</code> may appear after 292 a base prefix or between successive digits; such underscores do not change 293 the literal's value. 294 295 <pre class="ebnf"> 296 int_lit = decimal_lit | binary_lit | octal_lit | hex_lit . 297 decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] . 298 binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits . 299 octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits . 300 hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits . 301 302 decimal_digits = decimal_digit { [ "_" ] decimal_digit } . 303 binary_digits = binary_digit { [ "_" ] binary_digit } . 304 octal_digits = octal_digit { [ "_" ] octal_digit } . 305 hex_digits = hex_digit { [ "_" ] hex_digit } . 306 </pre> 307 308 <pre> 309 42 310 4_2 311 0600 312 0_600 313 0o600 314 0O600 // second character is capital letter 'O' 315 0xBadFace 316 0xBad_Face 317 0x_67_7a_2f_cc_40_c6 318 170141183460469231731687303715884105727 319 170_141183_460469_231731_687303_715884_105727 320 321 _42 // an identifier, not an integer literal 322 42_ // invalid: _ must separate successive digits 323 4__2 // invalid: only one _ at a time 324 0_xBadFace // invalid: _ must separate successive digits 325 </pre> 326 327 328 <h3 id="Floating-point_literals">Floating-point literals</h3> 329 330 331 A floating-point literal is a decimal or hexadecimal representation of a 332 <a href="#Constants">floating-point constant</a>. 333 334 335 336 A decimal floating-point literal consists of an integer part (decimal digits), 337 a decimal point, a fractional part (decimal digits), and an exponent part 338 (<code>e</code> or <code>E</code> followed by an optional sign and decimal digits). 339 One of the integer part or the fractional part may be elided; one of the decimal point 340 or the exponent part may be elided. 341 An exponent value exp scales the mantissa (integer and fractional part) by 10exp. 342 343 344 345 A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code> 346 prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits), 347 and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits). 348 One of the integer part or the fractional part may be elided; the radix point may be elided as well, 349 but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.) 350 An exponent value exp scales the mantissa (integer and fractional part) by 2exp. 351 352 353 354 For readability, an underscore character <code>_</code> may appear after 355 a base prefix or between successive digits; such underscores do not change 356 the literal value. 357 358 359 <pre class="ebnf"> 360 float_lit = decimal_float_lit | hex_float_lit . 361 362 decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] | 363 decimal_digits decimal_exponent | 364 "." decimal_digits [ decimal_exponent ] . 365 decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits . 366 367 hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent . 368 hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] | 369 [ "_" ] hex_digits | 370 "." hex_digits . 371 hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits . 372 </pre> 373 374 <pre> 375 0. 376 72.40 377 072.40 // == 72.40 378 2.71828 379 1.e+0 380 6.67428e-11 381 1E6 382 .25 383 .12345E+5 384 1_5. // == 15.0 385 0.15e+0_2 // == 15.0 386 387 0x1p-2 // == 0.25 388 0x2.p10 // == 2048.0 389 0x1.Fp+0 // == 1.9375 390 0X.8p-0 // == 0.5 391 0X_1FFFP-16 // == 0.1249847412109375 392 0x15e-2 // == 0x15e - 2 (integer subtraction) 393 394 0x.p1 // invalid: mantissa has no digits 395 1p-2 // invalid: p exponent requires hexadecimal mantissa 396 0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent 397 1_.5 // invalid: _ must separate successive digits 398 1._5 // invalid: _ must separate successive digits 399 1.5_e1 // invalid: _ must separate successive digits 400 1.5e_1 // invalid: _ must separate successive digits 401 1.5e1_ // invalid: _ must separate successive digits 402 </pre> 403 404 405 <h3 id="Imaginary_literals">Imaginary literals</h3> 406 407 408 An imaginary literal represents the imaginary part of a 409 <a href="#Constants">complex constant</a>. 410 It consists of an <a href="#Integer_literals">integer</a> or 411 <a href="#Floating-point_literals">floating-point</a> literal 412 followed by the lowercase letter <code>i</code>. 413 The value of an imaginary literal is the value of the respective 414 integer or floating-point literal multiplied by the imaginary unit i. 415 416 417 <pre class="ebnf"> 418 imaginary_lit = (decimal_digits | int_lit | float_lit) "i" . 419 </pre> 420 421 422 For backward compatibility, an imaginary literal's integer part consisting 423 entirely of decimal digits (and possibly underscores) is considered a decimal 424 integer, even if it starts with a leading <code>0</code>. 425 426 427 <pre> 428 0i 429 0123i // == 123i for backward-compatibility 430 0o123i // == 0o123 * 1i == 83i 431 0xabci // == 0xabc * 1i == 2748i 432 0.i 433 2.71828i 434 1.e+0i 435 6.67428e-11i 436 1E6i 437 .25i 438 .12345E+5i 439 0x1p-2i // == 0x1p-2 * 1i == 0.25i 440 </pre> 441 442 443 <h3 id="Rune_literals">Rune literals</h3> 444 445 446 A rune literal represents a <a href="#Constants">rune constant</a>, 447 an integer value identifying a Unicode code point. 448 A rune literal is expressed as one or more characters enclosed in single quotes, 449 as in <code>'x'</code> or <code>'\n'</code>. 450 Within the quotes, any character may appear except newline and unescaped single 451 quote. A single quoted character represents the Unicode value 452 of the character itself, 453 while multi-character sequences beginning with a backslash encode 454 values in various formats. 455 456 457 458 The simplest form represents the single character within the quotes; 459 since Go source text is Unicode characters encoded in UTF-8, multiple 460 UTF-8-encoded bytes may represent a single integer value. For 461 instance, the literal <code>'a'</code> holds a single byte representing 462 a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while 463 <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing 464 a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. 465 466 467 468 Several backslash escapes allow arbitrary values to be encoded as 469 ASCII text. There are four ways to represent the integer value 470 as a numeric constant: <code>\x</code> followed by exactly two hexadecimal 471 digits; <code>\u</code> followed by exactly four hexadecimal digits; 472 <code>\U</code> followed by exactly eight hexadecimal digits, and a 473 plain backslash <code>\</code> followed by exactly three octal digits. 474 In each case the value of the literal is the value represented by 475 the digits in the corresponding base. 476 477 478 479 Although these representations all result in an integer, they have 480 different valid ranges. Octal escapes must represent a value between 481 0 and 255 inclusive. Hexadecimal escapes satisfy this condition 482 by construction. The escapes <code>\u</code> and <code>\U</code> 483 represent Unicode code points so within them some values are illegal, 484 in particular those above <code>0x10FFFF</code> and surrogate halves. 485 486 487 488 After a backslash, certain single-character escapes represent special values: 489 490 491 <pre class="grammar"> 492 \a U+0007 alert or bell 493 \b U+0008 backspace 494 \f U+000C form feed 495 \n U+000A line feed or newline 496 \r U+000D carriage return 497 \t U+0009 horizontal tab 498 \v U+000B vertical tab 499 \\ U+005C backslash 500 \' U+0027 single quote (valid escape only within rune literals) 501 \" U+0022 double quote (valid escape only within string literals) 502 </pre> 503 504 505 An unrecognized character following a backslash in a rune literal is illegal. 506 507 508 <pre class="ebnf"> 509 rune_lit = "'" ( unicode_value | byte_value ) "'" . 510 unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . 511 byte_value = octal_byte_value | hex_byte_value . 512 octal_byte_value = `\` octal_digit octal_digit octal_digit . 513 hex_byte_value = `\` "x" hex_digit hex_digit . 514 little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit . 515 big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit 516 hex_digit hex_digit hex_digit hex_digit . 517 escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) . 518 </pre> 519 520 <pre> 521 'a' 522 'ä' 523 '本' 524 '\t' 525 '\000' 526 '\007' 527 '\377' 528 '\x07' 529 '\xff' 530 '\u12e4' 531 '\U00101234' 532 '\'' // rune literal containing single quote character 533 'aa' // illegal: too many characters 534 '\k' // illegal: k is not recognized after a backslash 535 '\xa' // illegal: too few hexadecimal digits 536 '\0' // illegal: too few octal digits 537 '\400' // illegal: octal value over 255 538 '\uDFFF' // illegal: surrogate half 539 '\U00110000' // illegal: invalid Unicode code point 540 </pre> 541 542 543 <h3 id="String_literals">String literals</h3> 544 545 546 A string literal represents a <a href="#Constants">string constant</a> 547 obtained from concatenating a sequence of characters. There are two forms: 548 raw string literals and interpreted string literals. 549 550 551 552 Raw string literals are character sequences between back quotes, as in 553 <code>`foo`</code>. Within the quotes, any character may appear except 554 back quote. The value of a raw string literal is the 555 string composed of the uninterpreted (implicitly UTF-8-encoded) characters 556 between the quotes; 557 in particular, backslashes have no special meaning and the string may 558 contain newlines. 559 Carriage return characters ('\r') inside raw string literals 560 are discarded from the raw string value. 561 562 563 564 Interpreted string literals are character sequences between double 565 quotes, as in <code>"bar"</code>. 566 Within the quotes, any character may appear except newline and unescaped double quote. 567 The text between the quotes forms the 568 value of the literal, with backslash escapes interpreted as they 569 are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and 570 <code>\"</code> is legal), with the same restrictions. 571 The three-digit octal (<code>\</code>nnn) 572 and two-digit hexadecimal (<code>\x</code>nn) escapes represent individual 573 bytes of the resulting string; all other escapes represent 574 the (possibly multi-byte) UTF-8 encoding of individual characters. 575 Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent 576 a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, 577 <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent 578 the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character 579 U+00FF. 580 581 582 <pre class="ebnf"> 583 string_lit = raw_string_lit | interpreted_string_lit . 584 raw_string_lit = "`" { unicode_char | newline } "`" . 585 interpreted_string_lit = `"` { unicode_value | byte_value } `"` . 586 </pre> 587 588 <pre> 589 `abc` // same as "abc" 590 `\n 591 \n` // same as "\\n\n\\n" 592 "\n" 593 "\"" // same as `"` 594 "Hello, world!\n" 595 "日本語" 596 "\u65e5本\U00008a9e" 597 "\xff\u00FF" 598 "\uD800" // illegal: surrogate half 599 "\U00110000" // illegal: invalid Unicode code point 600 </pre> 601 602 603 These examples all represent the same string: 604 605 606 <pre> 607 "日本語" // UTF-8 input text 608 `日本語` // UTF-8 input text as a raw literal 609 "\u65e5\u672c\u8a9e" // the explicit Unicode code points 610 "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points 611 "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes 612 </pre> 613 614 615 If the source code represents a character as two code points, such as 616 a combining form involving an accent and a letter, the result will be 617 an error if placed in a rune literal (it is not a single code 618 point), and will appear as two code points if placed in a string 619 literal. 620 621 622 623 <h2 id="Constants">Constants</h2> 624 625 There are boolean constants, 626 rune constants, 627 integer constants, 628 floating-point constants, complex constants, 629 and string constants. Rune, integer, floating-point, 630 and complex constants are 631 collectively called numeric constants. 632 633 634 635 A constant value is represented by a 636 <a href="#Rune_literals">rune</a>, 637 <a href="#Integer_literals">integer</a>, 638 <a href="#Floating-point_literals">floating-point</a>, 639 <a href="#Imaginary_literals">imaginary</a>, 640 or 641 <a href="#String_literals">string</a> literal, 642 an identifier denoting a constant, 643 a <a href="#Constant_expressions">constant expression</a>, 644 a <a href="#Conversions">conversion</a> with a result that is a constant, or 645 the result value of some built-in functions such as 646 <code>unsafe.Sizeof</code> applied to <a href="#Package_unsafe">certain values</a>, 647 <code>cap</code> or <code>len</code> applied to 648 <a href="#Length_and_capacity">some expressions</a>, 649 <code>real</code> and <code>imag</code> applied to a complex constant 650 and <code>complex</code> applied to numeric constants. 651 The boolean truth values are represented by the predeclared constants 652 <code>true</code> and <code>false</code>. The predeclared identifier 653 <a href="#Iota">iota</a> denotes an integer constant. 654 655 656 657 In general, complex constants are a form of 658 <a href="#Constant_expressions">constant expression</a> 659 and are discussed in that section. 660 661 662 663 Numeric constants represent exact values of arbitrary precision and do not overflow. 664 Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, 665 and not-a-number values. 666 667 668 669 Constants may be <a href="#Types">typed</a> or untyped. 670 Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, 671 and certain <a href="#Constant_expressions">constant expressions</a> 672 containing only untyped constant operands are untyped. 673 674 675 676 A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> 677 or <a href="#Conversions">conversion</a>, or implicitly when used in a 678 <a href="#Variable_declarations">variable declaration</a> or an 679 <a href="#Assignment_statements">assignment statement</a> or as an 680 operand in an <a href="#Expressions">expression</a>. 681 It is an error if the constant value 682 cannot be <a href="#Representability">represented</a> as a value of the respective type. 683 If the type is a type parameter, the constant is converted into a non-constant 684 value of the type parameter. 685 686 687 688 An untyped constant has a default type which is the type to which the 689 constant is implicitly converted in contexts where a typed value is required, 690 for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> 691 such as <code>i := 0</code> where there is no explicit type. 692 The default type of an untyped constant is <code>bool</code>, <code>rune</code>, 693 <code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> 694 respectively, depending on whether it is a boolean, rune, integer, floating-point, 695 complex, or string constant. 696 697 698 699 Implementation restriction: Although numeric constants have arbitrary 700 precision in the language, a compiler may implement them using an 701 internal representation with limited precision. That said, every 702 implementation must: 703 704 705 <ul> 706 <li>Represent integer constants with at least 256 bits.</li> 707 708 <li>Represent floating-point constants, including the parts of 709 a complex constant, with a mantissa of at least 256 bits 710 and a signed binary exponent of at least 16 bits.</li> 711 712 <li>Give an error if unable to represent an integer constant 713 precisely.</li> 714 715 <li>Give an error if unable to represent a floating-point or 716 complex constant due to overflow.</li> 717 718 <li>Round to the nearest representable constant if unable to 719 represent a floating-point or complex constant due to limits 720 on precision.</li> 721 </ul> 722 723 724 These requirements apply both to literal constants and to the result 725 of evaluating <a href="#Constant_expressions">constant 726 expressions</a>. 727 728 729 730 <h2 id="Variables">Variables</h2> 731 732 733 A variable is a storage location for holding a value. 734 The set of permissible values is determined by the 735 variable's <a href="#Types">type</a>. 736 737 738 739 A <a href="#Variable_declarations">variable declaration</a> 740 or, for function parameters and results, the signature 741 of a <a href="#Function_declarations">function declaration</a> 742 or <a href="#Function_literals">function literal</a> reserves 743 storage for a named variable. 744 745 Calling the built-in function <a href="#Allocation"><code>new</code></a> 746 or taking the address of a <a href="#Composite_literals">composite literal</a> 747 allocates storage for a variable at run time. 748 Such an anonymous variable is referred to via a (possibly implicit) 749 <a href="#Address_operators">pointer indirection</a>. 750 751 752 753 Structured variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, 754 and <a href="#Struct_types">struct</a> types have elements and fields that may 755 be <a href="#Address_operators">addressed</a> individually. Each such element 756 acts like a variable. 757 758 759 760 The static type (or just type) of a variable is the 761 type given in its declaration, the type provided in the 762 <code>new</code> call or composite literal, or the type of 763 an element of a structured variable. 764 Variables of interface type also have a distinct dynamic type, 765 which is the (non-interface) type of the value assigned to the variable at run time 766 (unless the value is the predeclared identifier <code>nil</code>, 767 which has no type). 768 The dynamic type may vary during execution but values stored in interface 769 variables are always <a href="#Assignability">assignable</a> 770 to the static type of the variable. 771 772 773 <pre> 774 var x interface{} // x is nil and has static type interface{} 775 var v *T // v has value nil, static type *T 776 x = 42 // x has value 42 and dynamic type int 777 x = v // x has value (*T)(nil) and dynamic type *T 778 </pre> 779 780 781 A variable's value is retrieved by referring to the variable in an 782 <a href="#Expressions">expression</a>; it is the most recent value 783 <a href="#Assignment_statements">assigned</a> to the variable. 784 If a variable has not yet been assigned a value, its value is the 785 <a href="#The_zero_value">zero value</a> for its type. 786 787 788 789 <h2 id="Types">Types</h2> 790 791 792 A type determines a set of values together with operations and methods specific 793 to those values. A type may be denoted by a type name, if it has one, which must be 794 followed by <a href="#Instantiations">type arguments</a> if the type is generic. 795 A type may also be specified using a type literal, which composes a type 796 from existing types. 797 798 799 <pre class="ebnf"> 800 Type = TypeName [ TypeArgs ] | TypeLit | "(" Type ")" . 801 TypeName = identifier | QualifiedIdent . 802 TypeArgs = "[" TypeList [ "," ] "]" . 803 TypeList = Type { "," Type } . 804 TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | 805 SliceType | MapType | ChannelType . 806 </pre> 807 808 809 The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. 810 Others are introduced with <a href="#Type_declarations">type declarations</a> 811 or <a href="#Type_parameter_declarations">type parameter lists</a>. 812 Composite types—array, struct, pointer, function, 813 interface, slice, map, and channel types—may be constructed using 814 type literals. 815 816 817 818 Predeclared types, defined types, and type parameters are called named types. 819 An alias denotes a named type if the type given in the alias declaration is a named type. 820 821 822 <h3 id="Boolean_types">Boolean types</h3> 823 824 825 A boolean type represents the set of Boolean truth values 826 denoted by the predeclared constants <code>true</code> 827 and <code>false</code>. The predeclared boolean type is <code>bool</code>; 828 it is a <a href="#Type_definitions">defined type</a>. 829 830 831 <h3 id="Numeric_types">Numeric types</h3> 832 833 834 An integer, floating-point, or complex type 835 represents the set of integer, floating-point, or complex values, respectively. 836 They are collectively called numeric types. 837 The predeclared architecture-independent numeric types are: 838 839 840 <pre class="grammar"> 841 uint8 the set of all unsigned 8-bit integers (0 to 255) 842 uint16 the set of all unsigned 16-bit integers (0 to 65535) 843 uint32 the set of all unsigned 32-bit integers (0 to 4294967295) 844 uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615) 845 846 int8 the set of all signed 8-bit integers (-128 to 127) 847 int16 the set of all signed 16-bit integers (-32768 to 32767) 848 int32 the set of all signed 32-bit integers (-2147483648 to 2147483647) 849 int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807) 850 851 float32 the set of all IEEE-754 32-bit floating-point numbers 852 float64 the set of all IEEE-754 64-bit floating-point numbers 853 854 complex64 the set of all complex numbers with float32 real and imaginary parts 855 complex128 the set of all complex numbers with float64 real and imaginary parts 856 857 byte alias for uint8 858 rune alias for int32 859 </pre> 860 861 862 The value of an n-bit integer is n bits wide and represented using 863 <a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. 864 865 866 867 There is also a set of predeclared integer types with implementation-specific sizes: 868 869 870 <pre class="grammar"> 871 uint either 32 or 64 bits 872 int same size as uint 873 uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value 874 </pre> 875 876 877 To avoid portability issues all numeric types are <a href="#Type_definitions">defined 878 types</a> and thus distinct except 879 <code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and 880 <code>rune</code>, which is an alias for <code>int32</code>. 881 Explicit conversions 882 are required when different numeric types are mixed in an expression 883 or assignment. For instance, <code>int32</code> and <code>int</code> 884 are not the same type even though they may have the same size on a 885 particular architecture. 886 887 888 <h3 id="String_types">String types</h3> 889 890 891 A string type represents the set of string values. 892 A string value is a (possibly empty) sequence of bytes. 893 The number of bytes is called the length of the string and is never negative. 894 Strings are immutable: once created, 895 it is impossible to change the contents of a string. 896 The predeclared string type is <code>string</code>; 897 it is a <a href="#Type_definitions">defined type</a>. 898 899 900 901 The length of a string <code>s</code> can be discovered using 902 the built-in function <a href="#Length_and_capacity"><code>len</code></a>. 903 The length is a compile-time constant if the string is a constant. 904 A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> 905 0 through <code>len(s)-1</code>. 906 It is illegal to take the address of such an element; if 907 <code>s[i]</code> is the <code>i</code>'th byte of a 908 string, <code>&s[i]</code> is invalid. 909 910 911 912 <h3 id="Array_types">Array types</h3> 913 914 915 An array is a numbered sequence of elements of a single 916 type, called the element type. 917 The number of elements is called the length of the array and is never negative. 918 919 920 <pre class="ebnf"> 921 ArrayType = "[" ArrayLength "]" ElementType . 922 ArrayLength = Expression . 923 ElementType = Type . 924 </pre> 925 926 927 The length is part of the array's type; it must evaluate to a 928 non-negative <a href="#Constants">constant</a> 929 <a href="#Representability">representable</a> by a value 930 of type <code>int</code>. 931 The length of array <code>a</code> can be discovered 932 using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. 933 The elements can be addressed by integer <a href="#Index_expressions">indices</a> 934 0 through <code>len(a)-1</code>. 935 Array types are always one-dimensional but may be composed to form 936 multi-dimensional types. 937 938 939 <pre> 940 [32]byte 941 [2*N] struct { x, y int32 } 942 [1000]*float64 943 [3][5]int 944 [2][2][2]float64 // same as [2]([2]([2]float64)) 945 </pre> 946 947 948 An array type <code>T</code> may not have an element of type <code>T</code>, 949 or of a type containing <code>T</code> as a component, directly or indirectly, 950 if those containing types are only array or struct types. 951 952 953 <pre> 954 // invalid array types 955 type ( 956 T1 [10]T1 // element type of T1 is T1 957 T2 [10]struct{ f T2 } // T2 contains T2 as component of a struct 958 T3 [10]T4 // T3 contains T3 as component of a struct in T4 959 T4 struct{ f T3 } // T4 contains T4 as component of array T3 in a struct 960 ) 961 962 // valid array types 963 type ( 964 T5 [10]*T5 // T5 contains T5 as component of a pointer 965 T6 [10]func() T6 // T6 contains T6 as component of a function type 966 T7 [10]struct{ f []T7 } // T7 contains T7 as component of a slice in a struct 967 ) 968 </pre> 969 970 <h3 id="Slice_types">Slice types</h3> 971 972 973 A slice is a descriptor for a contiguous segment of an underlying array and 974 provides access to a numbered sequence of elements from that array. 975 A slice type denotes the set of all slices of arrays of its element type. 976 The number of elements is called the length of the slice and is never negative. 977 The value of an uninitialized slice is <code>nil</code>. 978 979 980 <pre class="ebnf"> 981 SliceType = "[" "]" ElementType . 982 </pre> 983 984 985 The length of a slice <code>s</code> can be discovered by the built-in function 986 <a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during 987 execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> 988 0 through <code>len(s)-1</code>. The slice index of a 989 given element may be less than the index of the same element in the 990 underlying array. 991 992 993 A slice, once initialized, is always associated with an underlying 994 array that holds its elements. A slice therefore shares storage 995 with its array and with other slices of the same array; by contrast, 996 distinct arrays always represent distinct storage. 997 998 999 The array underlying a slice may extend past the end of the slice. 1000 The capacity is a measure of that extent: it is the sum of 1001 the length of the slice and the length of the array beyond the slice; 1002 a slice of length up to that capacity can be created by 1003 <a href="#Slice_expressions">slicing</a> a new one from the original slice. 1004 The capacity of a slice <code>a</code> can be discovered using the 1005 built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>. 1006 1007 1008 1009 A new, initialized slice value for a given element type <code>T</code> may be 1010 made using the built-in function 1011 <a href="#Making_slices_maps_and_channels"><code>make</code></a>, 1012 which takes a slice type 1013 and parameters specifying the length and optionally the capacity. 1014 A slice created with <code>make</code> always allocates a new, hidden array 1015 to which the returned slice value refers. That is, executing 1016 1017 1018 <pre> 1019 make([]T, length, capacity) 1020 </pre> 1021 1022 1023 produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> 1024 it, so these two expressions are equivalent: 1025 1026 1027 <pre> 1028 make([]int, 50, 100) 1029 new([100]int)[0:50] 1030 </pre> 1031 1032 1033 Like arrays, slices are always one-dimensional but may be composed to construct 1034 higher-dimensional objects. 1035 With arrays of arrays, the inner arrays are, by construction, always the same length; 1036 however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. 1037 Moreover, the inner slices must be initialized individually. 1038 1039 1040 <h3 id="Struct_types">Struct types</h3> 1041 1042 1043 A struct is a sequence of named elements, called fields, each of which has a 1044 name and a type. Field names may be specified explicitly (IdentifierList) or 1045 implicitly (EmbeddedField). 1046 Within a struct, non-<a href="#Blank_identifier">blank</a> field names must 1047 be <a href="#Uniqueness_of_identifiers">unique</a>. 1048 1049 1050 <pre class="ebnf"> 1051 StructType = "struct" "{" { FieldDecl ";" } "}" . 1052 FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . 1053 EmbeddedField = [ "*" ] TypeName [ TypeArgs ] . 1054 Tag = string_lit . 1055 </pre> 1056 1057 <pre> 1058 // An empty struct. 1059 struct {} 1060 1061 // A struct with 6 fields. 1062 struct { 1063 x, y int 1064 u float32 1065 _ float32 // padding 1066 A *[]int 1067 F func() 1068 } 1069 </pre> 1070 1071 1072 A field declared with a type but no explicit field name is called an embedded field. 1073 An embedded field must be specified as 1074 a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>, 1075 and <code>T</code> itself may not be 1076 a pointer type. The unqualified type name acts as the field name. 1077 1078 1079 <pre> 1080 // A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4 1081 struct { 1082 T1 // field name is T1 1083 *T2 // field name is T2 1084 P.T3 // field name is T3 1085 *P.T4 // field name is T4 1086 x, y int // field names are x and y 1087 } 1088 </pre> 1089 1090 1091 The following declaration is illegal because field names must be unique 1092 in a struct type: 1093 1094 1095 <pre> 1096 struct { 1097 T // conflicts with embedded field *T and *P.T 1098 *T // conflicts with embedded field T and *P.T 1099 *P.T // conflicts with embedded field T and *T 1100 } 1101 </pre> 1102 1103 1104 A field or <a href="#Method_declarations">method</a> <code>f</code> of an 1105 embedded field in a struct <code>x</code> is called promoted if 1106 <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes 1107 that field or method <code>f</code>. 1108 1109 1110 1111 Promoted fields act like ordinary fields 1112 of a struct except that they cannot be used as field names in 1113 <a href="#Composite_literals">composite literals</a> of the struct. 1114 1115 1116 1117 Given a struct type <code>S</code> and a <a href="#Types">named type</a> 1118 <code>T</code>, promoted methods are included in the method set of the struct as follows: 1119 1120 <ul> 1121 <li> 1122 If <code>S</code> contains an embedded field <code>T</code>, 1123 the <a href="#Method_sets">method sets</a> of <code>S</code> 1124 and <code>*S</code> both include promoted methods with receiver 1125 <code>T</code>. The method set of <code>*S</code> also 1126 includes promoted methods with receiver <code>*T</code>. 1127 </li> 1128 1129 <li> 1130 If <code>S</code> contains an embedded field <code>*T</code>, 1131 the method sets of <code>S</code> and <code>*S</code> both 1132 include promoted methods with receiver <code>T</code> or 1133 <code>*T</code>. 1134 </li> 1135 </ul> 1136 1137 1138 A field declaration may be followed by an optional string literal tag, 1139 which becomes an attribute for all the fields in the corresponding 1140 field declaration. An empty tag string is equivalent to an absent tag. 1141 The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> 1142 and take part in <a href="#Type_identity">type identity</a> for structs 1143 but are otherwise ignored. 1144 1145 1146 <pre> 1147 struct { 1148 x, y float64 "" // an empty tag string is like an absent tag 1149 name string "any string is permitted as a tag" 1150 _ [4]byte "ceci n'est pas un champ de structure" 1151 } 1152 1153 // A struct corresponding to a TimeStamp protocol buffer. 1154 // The tag strings define the protocol buffer field numbers; 1155 // they follow the convention outlined by the reflect package. 1156 struct { 1157 microsec uint64 `protobuf:"1"` 1158 serverIP6 uint64 `protobuf:"2"` 1159 } 1160 </pre> 1161 1162 1163 A struct type <code>T</code> may not contain a field of type <code>T</code>, 1164 or of a type containing <code>T</code> as a component, directly or indirectly, 1165 if those containing types are only array or struct types. 1166 1167 1168 <pre> 1169 // invalid struct types 1170 type ( 1171 T1 struct{ T1 } // T1 contains a field of T1 1172 T2 struct{ f [10]T2 } // T2 contains T2 as component of an array 1173 T3 struct{ T4 } // T3 contains T3 as component of an array in struct T4 1174 T4 struct{ f [10]T3 } // T4 contains T4 as component of struct T3 in an array 1175 ) 1176 1177 // valid struct types 1178 type ( 1179 T5 struct{ f *T5 } // T5 contains T5 as component of a pointer 1180 T6 struct{ f func() T6 } // T6 contains T6 as component of a function type 1181 T7 struct{ f [10][]T7 } // T7 contains T7 as component of a slice in an array 1182 ) 1183 </pre> 1184 1185 <h3 id="Pointer_types">Pointer types</h3> 1186 1187 1188 A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given 1189 type, called the base type of the pointer. 1190 The value of an uninitialized pointer is <code>nil</code>. 1191 1192 1193 <pre class="ebnf"> 1194 PointerType = "*" BaseType . 1195 BaseType = Type . 1196 </pre> 1197 1198 <pre> 1199 *Point 1200 *[4]int 1201 </pre> 1202 1203 <h3 id="Function_types">Function types</h3> 1204 1205 1206 A function type denotes the set of all functions with the same parameter 1207 and result types. The value of an uninitialized variable of function type 1208 is <code>nil</code>. 1209 1210 1211 <pre class="ebnf"> 1212 FunctionType = "func" Signature . 1213 Signature = Parameters [ Result ] . 1214 Result = Parameters | Type . 1215 Parameters = "(" [ ParameterList [ "," ] ] ")" . 1216 ParameterList = ParameterDecl { "," ParameterDecl } . 1217 ParameterDecl = [ IdentifierList ] [ "..." ] Type . 1218 </pre> 1219 1220 1221 Within a list of parameters or results, the names (IdentifierList) 1222 must either all be present or all be absent. If present, each name 1223 stands for one item (parameter or result) of the specified type and 1224 all non-<a href="#Blank_identifier">blank</a> names in the signature 1225 must be <a href="#Uniqueness_of_identifiers">unique</a>. 1226 If absent, each type stands for one item of that type. 1227 Parameter and result 1228 lists are always parenthesized except that if there is exactly 1229 one unnamed result it may be written as an unparenthesized type. 1230 1231 1232 1233 The final incoming parameter in a function signature may have 1234 a type prefixed with <code>...</code>. 1235 A function with such a parameter is called variadic and 1236 may be invoked with zero or more arguments for that parameter. 1237 1238 1239 <pre> 1240 func() 1241 func(x int) int 1242 func(a, _ int, z float32) bool 1243 func(a, b int, z float32) (bool) 1244 func(prefix string, values ...int) 1245 func(a, b int, z float64, opt ...interface{}) (success bool) 1246 func(int, int, float64) (float64, *[]int) 1247 func(n int) func(p *T) 1248 </pre> 1249 1250 <h3 id="Interface_types">Interface types</h3> 1251 1252 1253 An interface type defines a type set. 1254 A variable of interface type can store a value of any type that is in the type 1255 set of the interface. Such a type is said to 1256 <a href="#Implementing_an_interface">implement the interface</a>. 1257 The value of an uninitialized variable of interface type is <code>nil</code>. 1258 1259 1260 <pre class="ebnf"> 1261 InterfaceType = "interface" "{" { InterfaceElem ";" } "}" . 1262 InterfaceElem = MethodElem | TypeElem . 1263 MethodElem = MethodName Signature . 1264 MethodName = identifier . 1265 TypeElem = TypeTerm { "|" TypeTerm } . 1266 TypeTerm = Type | UnderlyingType . 1267 UnderlyingType = "~" Type . 1268 </pre> 1269 1270 1271 An interface type is specified by a list of interface elements. 1272 An interface element is either a method or a type element, 1273 where a type element is a union of one or more type terms. 1274 A type term is either a single type or a single underlying type. 1275 1276 1277 <h4 id="Basic_interfaces">Basic interfaces</h4> 1278 1279 1280 In its most basic form an interface specifies a (possibly empty) list of methods. 1281 The type set defined by such an interface is the set of types which implement all of 1282 those methods, and the corresponding <a href="#Method_sets">method set</a> consists 1283 exactly of the methods specified by the interface. 1284 Interfaces whose type sets can be defined entirely by a list of methods are called 1285 basic interfaces. 1286 1287 1288 <pre> 1289 // A simple File interface. 1290 interface { 1291 Read([]byte) (int, error) 1292 Write([]byte) (int, error) 1293 Close() error 1294 } 1295 </pre> 1296 1297 1298 The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a> 1299 and not <a href="#Blank_identifier">blank</a>. 1300 1301 1302 <pre> 1303 interface { 1304 String() string 1305 String() string // illegal: String not unique 1306 _(x int) // illegal: method must have non-blank name 1307 } 1308 </pre> 1309 1310 1311 More than one type may implement an interface. 1312 For instance, if two types <code>S1</code> and <code>S2</code> 1313 have the method set 1314 1315 1316 <pre> 1317 func (p T) Read(p []byte) (n int, err error) 1318 func (p T) Write(p []byte) (n int, err error) 1319 func (p T) Close() error 1320 </pre> 1321 1322 1323 (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) 1324 then the <code>File</code> interface is implemented by both <code>S1</code> and 1325 <code>S2</code>, regardless of what other methods 1326 <code>S1</code> and <code>S2</code> may have or share. 1327 1328 1329 1330 Every type that is a member of the type set of an interface implements that interface. 1331 Any given type may implement several distinct interfaces. 1332 For instance, all types implement the empty interface which stands for the set 1333 of all (non-interface) types: 1334 1335 1336 <pre> 1337 interface{} 1338 </pre> 1339 1340 1341 For convenience, the predeclared type <code>any</code> is an alias for the empty interface. 1342 1343 1344 1345 Similarly, consider this interface specification, 1346 which appears within a <a href="#Type_declarations">type declaration</a> 1347 to define an interface called <code>Locker</code>: 1348 1349 1350 <pre> 1351 type Locker interface { 1352 Lock() 1353 Unlock() 1354 } 1355 </pre> 1356 1357 1358 If <code>S1</code> and <code>S2</code> also implement 1359 1360 1361 <pre> 1362 func (p T) Lock() { … } 1363 func (p T) Unlock() { … } 1364 </pre> 1365 1366 1367 they implement the <code>Locker</code> interface as well 1368 as the <code>File</code> interface. 1369 1370 1371 <h4 id="Embedded_interfaces">Embedded interfaces</h4> 1372 1373 1374 In a slightly more general form 1375 an interface <code>T</code> may use a (possibly qualified) interface type 1376 name <code>E</code> as an interface element. This is called 1377 embedding interface <code>E</code> in <code>T</code>. 1378 The type set of <code>T</code> is the intersection of the type sets 1379 defined by <code>T</code>'s explicitly declared methods and the type sets 1380 of <code>T</code>’s embedded interfaces. 1381 In other words, the type set of <code>T</code> is the set of all types that implement all the 1382 explicitly declared methods of <code>T</code> and also all the methods of 1383 <code>E</code>. 1384 1385 1386 <pre> 1387 type Reader interface { 1388 Read(p []byte) (n int, err error) 1389 Close() error 1390 } 1391 1392 type Writer interface { 1393 Write(p []byte) (n int, err error) 1394 Close() error 1395 } 1396 1397 // ReadWriter's methods are Read, Write, and Close. 1398 type ReadWriter interface { 1399 Reader // includes methods of Reader in ReadWriter's method set 1400 Writer // includes methods of Writer in ReadWriter's method set 1401 } 1402 </pre> 1403 1404 1405 When embedding interfaces, methods with the 1406 <a href="#Uniqueness_of_identifiers">same</a> names must 1407 have <a href="#Type_identity">identical</a> signatures. 1408 1409 1410 <pre> 1411 type ReadCloser interface { 1412 Reader // includes methods of Reader in ReadCloser's method set 1413 Close() // illegal: signatures of Reader.Close and Close are different 1414 } 1415 </pre> 1416 1417 <h4 id="General_interfaces">General interfaces</h4> 1418 1419 1420 In their most general form, an interface element may also be an arbitrary type term 1421 <code>T</code>, or a term of the form <code>~T</code> specifying the underlying type <code>T</code>, 1422 or a union of terms <code>t1|t2|…|tn</code>. 1423 Together with method specifications, these elements enable the precise 1424 definition of an interface's type set as follows: 1425 1426 1427 <ul> 1428 <li>The type set of the empty interface is the set of all non-interface types. 1429 </li> 1430 1431 <li>The type set of a non-empty interface is the intersection of the type sets 1432 of its interface elements. 1433 </li> 1434 1435 <li>The type set of a method specification is the set of all non-interface types 1436 whose method sets include that method. 1437 </li> 1438 1439 <li>The type set of a non-interface type term is the set consisting 1440 of just that type. 1441 </li> 1442 1443 <li>The type set of a term of the form <code>~T</code> 1444 is the set of all types whose underlying type is <code>T</code>. 1445 </li> 1446 1447 <li>The type set of a union of terms 1448 <code>t1|t2|…|tn</code> 1449 is the union of the type sets of the terms. 1450 </li> 1451 </ul> 1452 1453 1454 The quantification "the set of all non-interface types" refers not just to all (non-interface) 1455 types declared in the program at hand, but all possible types in all possible programs, and 1456 hence is infinite. 1457 Similarly, given the set of all non-interface types that implement a particular method, the 1458 intersection of the method sets of those types will contain exactly that method, even if all 1459 types in the program at hand always pair that method with another method. 1460 1461 1462 1463 By construction, an interface's type set never contains an interface type. 1464 1465 1466 <pre> 1467 // An interface representing only the type int. 1468 interface { 1469 int 1470 } 1471 1472 // An interface representing all types with underlying type int. 1473 interface { 1474 ~int 1475 } 1476 1477 // An interface representing all types with underlying type int that implement the String method. 1478 interface { 1479 ~int 1480 String() string 1481 } 1482 1483 // An interface representing an empty type set: there is no type that is both an int and a string. 1484 interface { 1485 int 1486 string 1487 } 1488 </pre> 1489 1490 1491 In a term of the form <code>~T</code>, the underlying type of <code>T</code> 1492 must be itself, and <code>T</code> cannot be an interface. 1493 1494 1495 <pre> 1496 type MyInt int 1497 1498 interface { 1499 ~[]byte // the underlying type of []byte is itself 1500 ~MyInt // illegal: the underlying type of MyInt is not MyInt 1501 ~error // illegal: error is an interface 1502 } 1503 </pre> 1504 1505 1506 Union elements denote unions of type sets: 1507 1508 1509 <pre> 1510 // The Float interface represents all floating-point types 1511 // (including any named types whose underlying types are 1512 // either float32 or float64). 1513 type Float interface { 1514 ~float32 | ~float64 1515 } 1516 </pre> 1517 1518 1519 The type <code>T</code> in a term of the form <code>T</code> or <code>~T</code> cannot 1520 be a <a href="#Type_parameter_declarations">type parameter</a>, and the type sets of all 1521 non-interface terms must be pairwise disjoint (the pairwise intersection of the type sets must be empty). 1522 Given a type parameter <code>P</code>: 1523 1524 1525 <pre> 1526 interface { 1527 P // illegal: P is a type parameter 1528 int | ~P // illegal: P is a type parameter 1529 ~int | MyInt // illegal: the type sets for ~int and MyInt are not disjoint (~int includes MyInt) 1530 float32 | Float // overlapping type sets but Float is an interface 1531 } 1532 </pre> 1533 1534 1535 Implementation restriction: 1536 A union (with more than one term) cannot contain the 1537 <a href="#Predeclared_identifiers">predeclared identifier</a> <code>comparable</code> 1538 or interfaces that specify methods, or embed <code>comparable</code> or interfaces 1539 that specify methods. 1540 1541 1542 1543 Interfaces that are not <a href="#Basic_interfaces">basic</a> may only be used as type 1544 constraints, or as elements of other interfaces used as constraints. 1545 They cannot be the types of values or variables, or components of other, 1546 non-interface types. 1547 1548 1549 <pre> 1550 var x Float // illegal: Float is not a basic interface 1551 1552 var x interface{} = Float(nil) // illegal 1553 1554 type Floatish struct { 1555 f Float // illegal 1556 } 1557 </pre> 1558 1559 1560 An interface type <code>T</code> may not embed a type element 1561 that is, contains, or embeds <code>T</code>, directly or indirectly. 1562 1563 1564 <pre> 1565 // illegal: Bad may not embed itself 1566 type Bad interface { 1567 Bad 1568 } 1569 1570 // illegal: Bad1 may not embed itself using Bad2 1571 type Bad1 interface { 1572 Bad2 1573 } 1574 type Bad2 interface { 1575 Bad1 1576 } 1577 1578 // illegal: Bad3 may not embed a union containing Bad3 1579 type Bad3 interface { 1580 ~int | ~string | Bad3 1581 } 1582 1583 // illegal: Bad4 may not embed an array containing Bad4 as element type 1584 type Bad4 interface { 1585 [10]Bad4 1586 } 1587 </pre> 1588 1589 <h4 id="Implementing_an_interface">Implementing an interface</h4> 1590 1591 1592 A type <code>T</code> implements an interface <code>I</code> if 1593 1594 1595 <ul> 1596 <li> 1597 <code>T</code> is not an interface and is an element of the type set of <code>I</code>; or 1598 </li> 1599 <li> 1600 <code>T</code> is an interface and the type set of <code>T</code> is a subset of the 1601 type set of <code>I</code>. 1602 </li> 1603 </ul> 1604 1605 1606 A value of type <code>T</code> implements an interface if <code>T</code> 1607 implements the interface. 1608 1609 1610 <h3 id="Map_types">Map types</h3> 1611 1612 1613 A map is an unordered group of elements of one type, called the 1614 element type, indexed by a set of unique keys of another type, 1615 called the key type. 1616 The value of an uninitialized map is <code>nil</code>. 1617 1618 1619 <pre class="ebnf"> 1620 MapType = "map" "[" KeyType "]" ElementType . 1621 KeyType = Type . 1622 </pre> 1623 1624 1625 The <a href="#Comparison_operators">comparison operators</a> 1626 <code>==</code> and <code>!=</code> must be fully defined 1627 for operands of the key type; thus the key type must not be a function, map, or 1628 slice. 1629 If the key type is an interface type, these 1630 comparison operators must be defined for the dynamic key values; 1631 failure will cause a <a href="#Run_time_panics">run-time panic</a>. 1632 1633 1634 <pre> 1635 map[string]int 1636 map[*T]struct{ x, y float64 } 1637 map[string]interface{} 1638 </pre> 1639 1640 1641 The number of map elements is called its length. 1642 For a map <code>m</code>, it can be discovered using the 1643 built-in function <a href="#Length_and_capacity"><code>len</code></a> 1644 and may change during execution. Elements may be added during execution 1645 using <a href="#Assignment_statements">assignments</a> and retrieved with 1646 <a href="#Index_expressions">index expressions</a>; they may be removed with the 1647 <a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function. 1648 1649 1650 A new, empty map value is made using the built-in 1651 function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, 1652 which takes the map type and an optional capacity hint as arguments: 1653 1654 1655 <pre> 1656 make(map[string]int) 1657 make(map[string]int, 100) 1658 </pre> 1659 1660 1661 The initial capacity does not bound its size: 1662 maps grow to accommodate the number of items 1663 stored in them, with the exception of <code>nil</code> maps. 1664 A <code>nil</code> map is equivalent to an empty map except that no elements 1665 may be added. 1666 1667 <h3 id="Channel_types">Channel types</h3> 1668 1669 1670 A channel provides a mechanism for 1671 <a href="#Go_statements">concurrently executing functions</a> 1672 to communicate by 1673 <a href="#Send_statements">sending</a> and 1674 <a href="#Receive_operator">receiving</a> 1675 values of a specified element type. 1676 The value of an uninitialized channel is <code>nil</code>. 1677 1678 1679 <pre class="ebnf"> 1680 ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . 1681 </pre> 1682 1683 1684 The optional <code><-</code> operator specifies the channel direction, 1685 send or receive. If a direction is given, the channel is directional, 1686 otherwise it is bidirectional. 1687 A channel may be constrained only to send or only to receive by 1688 <a href="#Assignment_statements">assignment</a> or 1689 explicit <a href="#Conversions">conversion</a>. 1690 1691 1692 <pre> 1693 chan T // can be used to send and receive values of type T 1694 chan<- float64 // can only be used to send float64s 1695 <-chan int // can only be used to receive ints 1696 </pre> 1697 1698 1699 The <code><-</code> operator associates with the leftmost <code>chan</code> 1700 possible: 1701 1702 1703 <pre> 1704 chan<- chan int // same as chan<- (chan int) 1705 chan<- <-chan int // same as chan<- (<-chan int) 1706 <-chan <-chan int // same as <-chan (<-chan int) 1707 chan (<-chan int) 1708 </pre> 1709 1710 1711 A new, initialized channel 1712 value can be made using the built-in function 1713 <a href="#Making_slices_maps_and_channels"><code>make</code></a>, 1714 which takes the channel type and an optional capacity as arguments: 1715 1716 1717 <pre> 1718 make(chan int, 100) 1719 </pre> 1720 1721 1722 The capacity, in number of elements, sets the size of the buffer in the channel. 1723 If the capacity is zero or absent, the channel is unbuffered and communication 1724 succeeds only when both a sender and receiver are ready. Otherwise, the channel 1725 is buffered and communication succeeds without blocking if the buffer 1726 is not full (sends) or not empty (receives). 1727 A <code>nil</code> channel is never ready for communication. 1728 1729 1730 1731 A channel may be closed with the built-in function 1732 <a href="#Close"><code>close</code></a>. 1733 The multi-valued assignment form of the 1734 <a href="#Receive_operator">receive operator</a> 1735 reports whether a received value was sent before 1736 the channel was closed. 1737 1738 1739 1740 A single channel may be used in 1741 <a href="#Send_statements">send statements</a>, 1742 <a href="#Receive_operator">receive operations</a>, 1743 and calls to the built-in functions 1744 <a href="#Length_and_capacity"><code>cap</code></a> and 1745 <a href="#Length_and_capacity"><code>len</code></a> 1746 by any number of goroutines without further synchronization. 1747 Channels act as first-in-first-out queues. 1748 For example, if one goroutine sends values on a channel 1749 and a second goroutine receives them, the values are 1750 received in the order sent. 1751 1752 1753 <h2 id="Properties_of_types_and_values">Properties of types and values</h2> 1754 1755 <h3 id="Underlying_types">Underlying types</h3> 1756 1757 1758 Each type <code>T</code> has an underlying type: If <code>T</code> 1759 is one of the predeclared boolean, numeric, or string types, or a type literal, 1760 the corresponding underlying type is <code>T</code> itself. 1761 Otherwise, <code>T</code>'s underlying type is the underlying type of the 1762 type to which <code>T</code> refers in its declaration. 1763 For a type parameter that is the underlying type of its 1764 <a href="#Type_constraints">type constraint</a>, which is always an interface. 1765 1766 1767 <pre> 1768 type ( 1769 A1 = string 1770 A2 = A1 1771 ) 1772 1773 type ( 1774 B1 string 1775 B2 B1 1776 B3 []B1 1777 B4 B3 1778 ) 1779 1780 func f[P any](x P) { … } 1781 </pre> 1782 1783 1784 The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, 1785 and <code>B2</code> is <code>string</code>. 1786 The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>. 1787 The underlying type of <code>P</code> is <code>interface{}</code>. 1788 1789 1790 <h3 id="Core_types">Core types</h3> 1791 1792 1793 Each non-interface type <code>T</code> has a core type, which is the same as the 1794 <a href="#Underlying_types">underlying type</a> of <code>T</code>. 1795 1796 1797 1798 An interface <code>T</code> has a core type if one of the following 1799 conditions is satisfied: 1800 1801 1802 <ol> 1803 <li> 1804 There is a single type <code>U</code> which is the <a href="#Underlying_types">underlying type</a> 1805 of all types in the <a href="#Interface_types">type set</a> of <code>T</code>; or 1806 </li> 1807 <li> 1808 the type set of <code>T</code> contains only <a href="#Channel_types">channel types</a> 1809 with identical element type <code>E</code>, and all directional channels have the same 1810 direction. 1811 </li> 1812 </ol> 1813 1814 1815 No other interfaces have a core type. 1816 1817 1818 1819 The core type of an interface is, depending on the condition that is satisfied, either: 1820 1821 1822 <ol> 1823 <li> 1824 the type <code>U</code>; or 1825 </li> 1826 <li> 1827 the type <code>chan E</code> if <code>T</code> contains only bidirectional 1828 channels, or the type <code>chan<- E</code> or <code><-chan E</code> 1829 depending on the direction of the directional channels present. 1830 </li> 1831 </ol> 1832 1833 1834 By definition, a core type is never a <a href="#Type_definitions">defined type</a>, 1835 <a href="#Type_parameter_declarations">type parameter</a>, or 1836 <a href="#Interface_types">interface type</a>. 1837 1838 1839 1840 Examples of interfaces with core types: 1841 1842 1843 <pre> 1844 type Celsius float32 1845 type Kelvin float32 1846 1847 interface{ int } // int 1848 interface{ Celsius|Kelvin } // float32 1849 interface{ ~chan int } // chan int 1850 interface{ ~chan int|~chan<- int } // chan<- int 1851 interface{ ~[]*data; String() string } // []*data 1852 </pre> 1853 1854 1855 Examples of interfaces without core types: 1856 1857 1858 <pre> 1859 interface{} // no single underlying type 1860 interface{ Celsius|float64 } // no single underlying type 1861 interface{ chan int | chan<- string } // channels have different element types 1862 interface{ <-chan int | chan<- int } // directional channels have different directions 1863 </pre> 1864 1865 1866 Some operations (<a href="#Slice_expressions">slice expressions</a>, 1867 <a href="#Appending_and_copying_slices"><code>append</code> and <code>copy</code></a>) 1868 rely on a slightly more loose form of core types which accept byte slices and strings. 1869 Specifically, if there are exactly two types, <code>[]byte</code> and <code>string</code>, 1870 which are the underlying types of all types in the type set of interface <code>T</code>, 1871 the core type of <code>T</code> is called <code>bytestring</code>. 1872 1873 1874 1875 Examples of interfaces with <code>bytestring</code> core types: 1876 1877 1878 <pre> 1879 interface{ int } // int (same as ordinary core type) 1880 interface{ []byte | string } // bytestring 1881 interface{ ~[]byte | myString } // bytestring 1882 </pre> 1883 1884 1885 Note that <code>bytestring</code> is not a real type; it cannot be used to declare 1886 variables are compose other types. It exists solely to describe the behavior of some 1887 operations that read from a sequence of bytes, which may be a byte slice or a string. 1888 1889 1890 <h3 id="Type_identity">Type identity</h3> 1891 1892 1893 Two types are either identical or different. 1894 1895 1896 1897 A <a href="#Types">named type</a> is always different from any other type. 1898 Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are 1899 structurally equivalent; that is, they have the same literal structure and corresponding 1900 components have identical types. In detail: 1901 1902 1903 <ul> 1904 <li>Two array types are identical if they have identical element types and 1905 the same array length.</li> 1906 1907 <li>Two slice types are identical if they have identical element types.</li> 1908 1909 <li>Two struct types are identical if they have the same sequence of fields, 1910 and if corresponding fields have the same names, and identical types, 1911 and identical tags. 1912 <a href="#Exported_identifiers">Non-exported</a> field names from different 1913 packages are always different.</li> 1914 1915 <li>Two pointer types are identical if they have identical base types.</li> 1916 1917 <li>Two function types are identical if they have the same number of parameters 1918 and result values, corresponding parameter and result types are 1919 identical, and either both functions are variadic or neither is. 1920 Parameter and result names are not required to match.</li> 1921 1922 <li>Two interface types are identical if they define the same type set. 1923 </li> 1924 1925 <li>Two map types are identical if they have identical key and element types.</li> 1926 1927 <li>Two channel types are identical if they have identical element types and 1928 the same direction.</li> 1929 1930 <li>Two <a href="#Instantiations">instantiated</a> types are identical if 1931 their defined types and all type arguments are identical. 1932 </li> 1933 </ul> 1934 1935 1936 Given the declarations 1937 1938 1939 <pre> 1940 type ( 1941 A0 = []string 1942 A1 = A0 1943 A2 = struct{ a, b int } 1944 A3 = int 1945 A4 = func(A3, float64) *A0 1946 A5 = func(x int, _ float64) *[]string 1947 1948 B0 A0 1949 B1 []string 1950 B2 struct{ a, b int } 1951 B3 struct{ a, c int } 1952 B4 func(int, float64) *B0 1953 B5 func(x int, y float64) *A1 1954 1955 C0 = B0 1956 D0[P1, P2 any] struct{ x P1; y P2 } 1957 E0 = D0[int, string] 1958 ) 1959 </pre> 1960 1961 1962 these types are identical: 1963 1964 1965 <pre> 1966 A0, A1, and []string 1967 A2 and struct{ a, b int } 1968 A3 and int 1969 A4, func(int, float64) *[]string, and A5 1970 1971 B0 and C0 1972 D0[int, string] and E0 1973 []int and []int 1974 struct{ a, b *B5 } and struct{ a, b *B5 } 1975 func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5 1976 </pre> 1977 1978 1979 <code>B0</code> and <code>B1</code> are different because they are new types 1980 created by distinct <a href="#Type_definitions">type definitions</a>; 1981 <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> 1982 are different because <code>B0</code> is different from <code>[]string</code>; 1983 and <code>P1</code> and <code>P2</code> are different because they are different 1984 type parameters. 1985 <code>D0[int, string]</code> and <code>struct{ x int; y string }</code> are 1986 different because the former is an <a href="#Instantiations">instantiated</a> 1987 defined type while the latter is a type literal 1988 (but they are still <a href="#Assignability">assignable</a>). 1989 1990 1991 <h3 id="Assignability">Assignability</h3> 1992 1993 1994 A value <code>x</code> of type <code>V</code> is assignable to a <a href="#Variables">variable</a> of type <code>T</code> 1995 ("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies: 1996 1997 1998 <ul> 1999 <li> 2000 <code>V</code> and <code>T</code> are identical. 2001 </li> 2002 <li> 2003 <code>V</code> and <code>T</code> have identical 2004 <a href="#Underlying_types">underlying types</a> 2005 but are not type parameters and at least one of <code>V</code> 2006 or <code>T</code> is not a <a href="#Types">named type</a>. 2007 </li> 2008 <li> 2009 <code>V</code> and <code>T</code> are channel types with 2010 identical element types, <code>V</code> is a bidirectional channel, 2011 and at least one of <code>V</code> or <code>T</code> is not a <a href="#Types">named type</a>. 2012 </li> 2013 <li> 2014 <code>T</code> is an interface type, but not a type parameter, and 2015 <code>x</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>. 2016 </li> 2017 <li> 2018 <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> 2019 is a pointer, function, slice, map, channel, or interface type, 2020 but not a type parameter. 2021 </li> 2022 <li> 2023 <code>x</code> is an untyped <a href="#Constants">constant</a> 2024 <a href="#Representability">representable</a> 2025 by a value of type <code>T</code>. 2026 </li> 2027 </ul> 2028 2029 2030 Additionally, if <code>x</code>'s type <code>V</code> or <code>T</code> are type parameters, <code>x</code> 2031 is assignable to a variable of type <code>T</code> if one of the following conditions applies: 2032 2033 2034 <ul> 2035 <li> 2036 <code>x</code> is the predeclared identifier <code>nil</code>, <code>T</code> is 2037 a type parameter, and <code>x</code> is assignable to each type in 2038 <code>T</code>'s type set. 2039 </li> 2040 <li> 2041 <code>V</code> is not a <a href="#Types">named type</a>, <code>T</code> is 2042 a type parameter, and <code>x</code> is assignable to each type in 2043 <code>T</code>'s type set. 2044 </li> 2045 <li> 2046 <code>V</code> is a type parameter and <code>T</code> is not a named type, 2047 and values of each type in <code>V</code>'s type set are assignable 2048 to <code>T</code>. 2049 </li> 2050 </ul> 2051 2052 <h3 id="Representability">Representability</h3> 2053 2054 2055 A <a href="#Constants">constant</a> <code>x</code> is representable 2056 by a value of type <code>T</code>, 2057 where <code>T</code> is not a <a href="#Type_parameter_declarations">type parameter</a>, 2058 if one of the following conditions applies: 2059 2060 2061 <ul> 2062 <li> 2063 <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. 2064 </li> 2065 2066 <li> 2067 <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 2068 precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE 2069 negative zero further simplified to an unsigned zero. Note that constant values never result 2070 in an IEEE negative zero, NaN, or infinity. 2071 </li> 2072 2073 <li> 2074 <code>T</code> is a complex type, and <code>x</code>'s 2075 <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> 2076 are representable by values of <code>T</code>'s component type (<code>float32</code> or 2077 <code>float64</code>). 2078 </li> 2079 </ul> 2080 2081 2082 If <code>T</code> is a type parameter, 2083 <code>x</code> is representable by a value of type <code>T</code> if <code>x</code> is representable 2084 by a value of each type in <code>T</code>'s type set. 2085 2086 2087 <pre> 2088 x T x is representable by a value of T because 2089 2090 'a' byte 97 is in the set of byte values 2091 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers 2092 "foo" string "foo" is in the set of string values 2093 1024 int16 1024 is in the set of 16-bit integers 2094 42.0 byte 42 is in the set of unsigned 8-bit integers 2095 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers 2096 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values 2097 -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 2098 0i int 0 is an integer value 2099 (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values 2100 </pre> 2101 2102 <pre> 2103 x T x is not representable by a value of T because 2104 2105 0 bool 0 is not in the set of boolean values 2106 'a' string 'a' is a rune, it is not in the set of string values 2107 1024 byte 1024 is not in the set of unsigned 8-bit integers 2108 -1 uint16 -1 is not in the set of unsigned 16-bit integers 2109 1.1 int 1.1 is not an integer value 2110 42i float32 (0 + 42i) is not in the set of float32 values 2111 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding 2112 </pre> 2113 2114 <h3 id="Method_sets">Method sets</h3> 2115 2116 2117 The method set of a type determines the methods that can be 2118 <a href="#Calls">called</a> on an <a href="#Operands">operand</a> of that type. 2119 Every type has a (possibly empty) method set associated with it: 2120 2121 2122 <ul> 2123 <li>The method set of a <a href="#Type_definitions">defined type</a> <code>T</code> consists of all 2124 <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. 2125 </li> 2126 2127 <li> 2128 The method set of a pointer to a defined type <code>T</code> 2129 (where <code>T</code> is neither a pointer nor an interface) 2130 is the set of all methods declared with receiver <code>*T</code> or <code>T</code>. 2131 </li> 2132 2133 <li>The method set of an <a href="#Interface_types">interface type</a> is the intersection 2134 of the method sets of each type in the interface's <a href="#Interface_types">type set</a> 2135 (the resulting method set is usually just the set of declared methods in the interface). 2136 </li> 2137 </ul> 2138 2139 2140 Further rules apply to structs (and pointer to structs) containing embedded fields, 2141 as described in the section on <a href="#Struct_types">struct types</a>. 2142 Any other type has an empty method set. 2143 2144 2145 2146 In a method set, each method must have a 2147 <a href="#Uniqueness_of_identifiers">unique</a> 2148 non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. 2149 2150 2151 <h2 id="Blocks">Blocks</h2> 2152 2153 2154 A block is a possibly empty sequence of declarations and statements 2155 within matching brace brackets. 2156 2157 2158 <pre class="ebnf"> 2159 Block = "{" StatementList "}" . 2160 StatementList = { Statement ";" } . 2161 </pre> 2162 2163 2164 In addition to explicit blocks in the source code, there are implicit blocks: 2165 2166 2167 <ol> 2168 <li>The universe block encompasses all Go source text.</li> 2169 2170 <li>Each <a href="#Packages">package</a> has a package block containing all 2171 Go source text for that package.</li> 2172 2173 <li>Each file has a file block containing all Go source text 2174 in that file.</li> 2175 2176 <li>Each <a href="#If_statements">"if"</a>, 2177 <a href="#For_statements">"for"</a>, and 2178 <a href="#Switch_statements">"switch"</a> 2179 statement is considered to be in its own implicit block.</li> 2180 2181 <li>Each clause in a <a href="#Switch_statements">"switch"</a> 2182 or <a href="#Select_statements">"select"</a> statement 2183 acts as an implicit block.</li> 2184 </ol> 2185 2186 2187 Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. 2188 2189 2190 2191 <h2 id="Declarations_and_scope">Declarations and scope</h2> 2192 2193 2194 A declaration binds a non-<a href="#Blank_identifier">blank</a> identifier to a 2195 <a href="#Constant_declarations">constant</a>, 2196 <a href="#Type_declarations">type</a>, 2197 <a href="#Type_parameter_declarations">type parameter</a>, 2198 <a href="#Variable_declarations">variable</a>, 2199 <a href="#Function_declarations">function</a>, 2200 <a href="#Labeled_statements">label</a>, or 2201 <a href="#Import_declarations">package</a>. 2202 Every identifier in a program must be declared. 2203 No identifier may be declared twice in the same block, and 2204 no identifier may be declared in both the file and package block. 2205 2206 2207 2208 The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier 2209 in a declaration, but it does not introduce a binding and thus is not declared. 2210 In the package block, the identifier <code>init</code> may only be used for 2211 <a href="#Package_initialization"><code>init</code> function</a> declarations, 2212 and like the blank identifier it does not introduce a new binding. 2213 2214 2215 <pre class="ebnf"> 2216 Declaration = ConstDecl | TypeDecl | VarDecl . 2217 TopLevelDecl = Declaration | FunctionDecl | MethodDecl . 2218 </pre> 2219 2220 2221 The scope of a declared identifier is the extent of source text in which 2222 the identifier denotes the specified constant, type, variable, function, label, or package. 2223 2224 2225 2226 Go is lexically scoped using <a href="#Blocks">blocks</a>: 2227 2228 2229 <ol> 2230 <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li> 2231 2232 <li>The scope of an identifier denoting a constant, type, variable, 2233 or function (but not method) declared at top level (outside any 2234 function) is the package block.</li> 2235 2236 <li>The scope of the package name of an imported package is the file block 2237 of the file containing the import declaration.</li> 2238 2239 <li>The scope of an identifier denoting a method receiver, function parameter, 2240 or result variable is the function body.</li> 2241 2242 <li>The scope of an identifier denoting a type parameter of a function 2243 or declared by a method receiver begins after the name of the function 2244 and ends at the end of the function body.</li> 2245 2246 <li>The scope of an identifier denoting a type parameter of a type 2247 begins after the name of the type and ends at the end 2248 of the TypeSpec.</li> 2249 2250 <li>The scope of a constant or variable identifier declared 2251 inside a function begins at the end of the ConstSpec or VarSpec 2252 (ShortVarDecl for short variable declarations) 2253 and ends at the end of the innermost containing block.</li> 2254 2255 <li>The scope of a type identifier declared inside a function 2256 begins at the identifier in the TypeSpec 2257 and ends at the end of the innermost containing block.</li> 2258 </ol> 2259 2260 2261 An identifier declared in a block may be redeclared in an inner block. 2262 While the identifier of the inner declaration is in scope, it denotes 2263 the entity declared by the inner declaration. 2264 2265 2266 2267 The <a href="#Package_clause">package clause</a> is not a declaration; the package name 2268 does not appear in any scope. Its purpose is to identify the files belonging 2269 to the same <a href="#Packages">package</a> and to specify the default package name for import 2270 declarations. 2271 2272 2273 2274 <h3 id="Label_scopes">Label scopes</h3> 2275 2276 2277 Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are 2278 used in the <a href="#Break_statements">"break"</a>, 2279 <a href="#Continue_statements">"continue"</a>, and 2280 <a href="#Goto_statements">"goto"</a> statements. 2281 It is illegal to define a label that is never used. 2282 In contrast to other identifiers, labels are not block scoped and do 2283 not conflict with identifiers that are not labels. The scope of a label 2284 is the body of the function in which it is declared and excludes 2285 the body of any nested function. 2286 2287 2288 2289 <h3 id="Blank_identifier">Blank identifier</h3> 2290 2291 2292 The blank identifier is represented by the underscore character <code>_</code>. 2293 It serves as an anonymous placeholder instead of a regular (non-blank) 2294 identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, 2295 as an <a href="#Operands">operand</a>, and in <a href="#Assignment_statements">assignment statements</a>. 2296 2297 2298 2299 <h3 id="Predeclared_identifiers">Predeclared identifiers</h3> 2300 2301 2302 The following identifiers are implicitly declared in the 2303 <a href="#Blocks">universe block</a>: 2304 2305 <pre class="grammar"> 2306 Types: 2307 any bool byte comparable 2308 complex64 complex128 error float32 float64 2309 int int8 int16 int32 int64 rune string 2310 uint uint8 uint16 uint32 uint64 uintptr 2311 2312 Constants: 2313 true false iota 2314 2315 Zero value: 2316 nil 2317 2318 Functions: 2319 append cap close complex copy delete imag len 2320 make new panic print println real recover 2321 </pre> 2322 2323 <h3 id="Exported_identifiers">Exported identifiers</h3> 2324 2325 2326 An identifier may be exported to permit access to it from another package. 2327 An identifier is exported if both: 2328 2329 <ol> 2330 <li>the first character of the identifier's name is a Unicode uppercase 2331 letter (Unicode character category Lu); and</li> 2332 <li>the identifier is declared in the <a href="#Blocks">package block</a> 2333 or it is a <a href="#Struct_types">field name</a> or 2334 <a href="#MethodName">method name</a>.</li> 2335 </ol> 2336 2337 All other identifiers are not exported. 2338 2339 2340 <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> 2341 2342 2343 Given a set of identifiers, an identifier is called unique if it is 2344 different from every other in the set. 2345 Two identifiers are different if they are spelled differently, or if they 2346 appear in different <a href="#Packages">packages</a> and are not 2347 <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. 2348 2349 2350 <h3 id="Constant_declarations">Constant declarations</h3> 2351 2352 2353 A constant declaration binds a list of identifiers (the names of 2354 the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. 2355 The number of identifiers must be equal 2356 to the number of expressions, and the nth identifier on 2357 the left is bound to the value of the nth expression on the 2358 right. 2359 2360 2361 <pre class="ebnf"> 2362 ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . 2363 ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . 2364 2365 IdentifierList = identifier { "," identifier } . 2366 ExpressionList = Expression { "," Expression } . 2367 </pre> 2368 2369 2370 If the type is present, all constants take the type specified, and 2371 the expressions must be <a href="#Assignability">assignable</a> to that type, 2372 which must not be a type parameter. 2373 If the type is omitted, the constants take the 2374 individual types of the corresponding expressions. 2375 If the expression values are untyped <a href="#Constants">constants</a>, 2376 the declared constants remain untyped and the constant identifiers 2377 denote the constant values. For instance, if the expression is a 2378 floating-point literal, the constant identifier denotes a floating-point 2379 constant, even if the literal's fractional part is zero. 2380 2381 2382 <pre> 2383 const Pi float64 = 3.14159265358979323846 2384 const zero = 0.0 // untyped floating-point constant 2385 const ( 2386 size int64 = 1024 2387 eof = -1 // untyped integer constant 2388 ) 2389 const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants 2390 const u, v float32 = 0, 3 // u = 0.0, v = 3.0 2391 </pre> 2392 2393 2394 Within a parenthesized <code>const</code> declaration list the 2395 expression list may be omitted from any but the first ConstSpec. 2396 Such an empty list is equivalent to the textual substitution of the 2397 first preceding non-empty expression list and its type if any. 2398 Omitting the list of expressions is therefore equivalent to 2399 repeating the previous list. The number of identifiers must be equal 2400 to the number of expressions in the previous list. 2401 Together with the <a href="#Iota"><code>iota</code> constant generator</a> 2402 this mechanism permits light-weight declaration of sequential values: 2403 2404 2405 <pre> 2406 const ( 2407 Sunday = iota 2408 Monday 2409 Tuesday 2410 Wednesday 2411 Thursday 2412 Friday 2413 Partyday 2414 numberOfDays // this constant is not exported 2415 ) 2416 </pre> 2417 2418 2419 <h3 id="Iota">Iota</h3> 2420 2421 2422 Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier 2423 <code>iota</code> represents successive untyped integer <a href="#Constants"> 2424 constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> 2425 in that constant declaration, starting at zero. 2426 It can be used to construct a set of related constants: 2427 2428 2429 <pre> 2430 const ( 2431 c0 = iota // c0 == 0 2432 c1 = iota // c1 == 1 2433 c2 = iota // c2 == 2 2434 ) 2435 2436 const ( 2437 a = 1 << iota // a == 1 (iota == 0) 2438 b = 1 << iota // b == 2 (iota == 1) 2439 c = 3 // c == 3 (iota == 2, unused) 2440 d = 1 << iota // d == 8 (iota == 3) 2441 ) 2442 2443 const ( 2444 u = iota * 42 // u == 0 (untyped integer constant) 2445 v float64 = iota * 42 // v == 42.0 (float64 constant) 2446 w = iota * 42 // w == 84 (untyped integer constant) 2447 ) 2448 2449 const x = iota // x == 0 2450 const y = iota // y == 0 2451 </pre> 2452 2453 2454 By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value: 2455 2456 2457 <pre> 2458 const ( 2459 bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) 2460 bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) 2461 _, _ // (iota == 2, unused) 2462 bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) 2463 ) 2464 </pre> 2465 2466 2467 This last example exploits the <a href="#Constant_declarations">implicit repetition</a> 2468 of the last non-empty expression list. 2469 2470 2471 2472 <h3 id="Type_declarations">Type declarations</h3> 2473 2474 2475 A type declaration binds an identifier, the type name, to a <a href="#Types">type</a>. 2476 Type declarations come in two forms: alias declarations and type definitions. 2477 2478 2479 <pre class="ebnf"> 2480 TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . 2481 TypeSpec = AliasDecl | TypeDef . 2482 </pre> 2483 2484 <h4 id="Alias_declarations">Alias declarations</h4> 2485 2486 2487 An alias declaration binds an identifier to the given type. 2488 2489 2490 <pre class="ebnf"> 2491 AliasDecl = identifier "=" Type . 2492 </pre> 2493 2494 2495 Within the <a href="#Declarations_and_scope">scope</a> of 2496 the identifier, it serves as an alias for the type. 2497 2498 2499 <pre> 2500 type ( 2501 nodeList = []*Node // nodeList and []*Node are identical types 2502 Polar = polar // Polar and polar denote identical types 2503 ) 2504 </pre> 2505 2506 2507 <h4 id="Type_definitions">Type definitions</h4> 2508 2509 2510 A type definition creates a new, distinct type with the same 2511 <a href="#Types">underlying type</a> and operations as the given type 2512 and binds an identifier, the type name, to it. 2513 2514 2515 <pre class="ebnf"> 2516 TypeDef = identifier [ TypeParameters ] Type . 2517 </pre> 2518 2519 2520 The new type is called a defined type. 2521 It is <a href="#Type_identity">different</a> from any other type, 2522 including the type it is created from. 2523 2524 2525 <pre> 2526 type ( 2527 Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types 2528 polar Point // polar and Point denote different types 2529 ) 2530 2531 type TreeNode struct { 2532 left, right *TreeNode 2533 value any 2534 } 2535 2536 type Block interface { 2537 BlockSize() int 2538 Encrypt(src, dst []byte) 2539 Decrypt(src, dst []byte) 2540 } 2541 </pre> 2542 2543 2544 A defined type may have <a href="#Method_declarations">methods</a> associated with it. 2545 It does not inherit any methods bound to the given type, 2546 but the <a href="#Method_sets">method set</a> 2547 of an interface type or of elements of a composite type remains unchanged: 2548 2549 2550 <pre> 2551 // A Mutex is a data type with two methods, Lock and Unlock. 2552 type Mutex struct { /* Mutex fields */ } 2553 func (m *Mutex) Lock() { /* Lock implementation */ } 2554 func (m *Mutex) Unlock() { /* Unlock implementation */ } 2555 2556 // NewMutex has the same composition as Mutex but its method set is empty. 2557 type NewMutex Mutex 2558 2559 // The method set of PtrMutex's underlying type *Mutex remains unchanged, 2560 // but the method set of PtrMutex is empty. 2561 type PtrMutex *Mutex 2562 2563 // The method set of *PrintableMutex contains the methods 2564 // Lock and Unlock bound to its embedded field Mutex. 2565 type PrintableMutex struct { 2566 Mutex 2567 } 2568 2569 // MyBlock is an interface type that has the same method set as Block. 2570 type MyBlock Block 2571 </pre> 2572 2573 2574 Type definitions may be used to define different boolean, numeric, 2575 or string types and associate methods with them: 2576 2577 2578 <pre> 2579 type TimeZone int 2580 2581 const ( 2582 EST TimeZone = -(5 + iota) 2583 CST 2584 MST 2585 PST 2586 ) 2587 2588 func (tz TimeZone) String() string { 2589 return fmt.Sprintf("GMT%+dh", tz) 2590 } 2591 </pre> 2592 2593 2594 If the type definition specifies <a href="#Type_parameter_declarations">type parameters</a>, 2595 the type name denotes a generic type. 2596 Generic types must be <a href="#Instantiations">instantiated</a> when they 2597 are used. 2598 2599 2600 <pre> 2601 type List[T any] struct { 2602 next *List[T] 2603 value T 2604 } 2605 </pre> 2606 2607 2608 In a type definition the given type cannot be a type parameter. 2609 2610 2611 <pre> 2612 type T[P any] P // illegal: P is a type parameter 2613 2614 func f[T any]() { 2615 type L T // illegal: T is a type parameter declared by the enclosing function 2616 } 2617 </pre> 2618 2619 2620 A generic type may also have <a href="#Method_declarations">methods</a> associated with it. 2621 In this case, the method receivers must declare the same number of type parameters as 2622 present in the generic type definition. 2623 2624 2625 <pre> 2626 // The method Len returns the number of elements in the linked list l. 2627 func (l *List[T]) Len() int { … } 2628 </pre> 2629 2630 <h3 id="Type_parameter_declarations">Type parameter declarations</h3> 2631 2632 2633 A type parameter list declares the type parameters of a generic function or type declaration. 2634 The type parameter list looks like an ordinary <a href="#Function_types">function parameter list</a> 2635 except that the type parameter names must all be present and the list is enclosed 2636 in square brackets rather than parentheses. 2637 2638 2639 <pre class="ebnf"> 2640 TypeParameters = "[" TypeParamList [ "," ] "]" . 2641 TypeParamList = TypeParamDecl { "," TypeParamDecl } . 2642 TypeParamDecl = IdentifierList TypeConstraint . 2643 </pre> 2644 2645 2646 All non-blank names in the list must be unique. 2647 Each name declares a type parameter, which is a new and different <a href="#Types">named type</a> 2648 that acts as a place holder for an (as of yet) unknown type in the declaration. 2649 The type parameter is replaced with a type argument upon 2650 <a href="#Instantiations">instantiation</a> of the generic function or type. 2651 2652 2653 <pre> 2654 [P any] 2655 [S interface{ ~[]byte|string }] 2656 [S ~[]E, E any] 2657 [P Constraint[int]] 2658 [_ any] 2659 </pre> 2660 2661 2662 Just as each ordinary function parameter has a parameter type, each type parameter 2663 has a corresponding (meta-)type which is called its 2664 <a href="#Type_constraints">type constraint</a>. 2665 2666 2667 2668 A parsing ambiguity arises when the type parameter list for a generic type 2669 declares a single type parameter <code>P</code> with a constraint <code>C</code> 2670 such that the text <code>P C</code> forms a valid expression: 2671 2672 2673 <pre> 2674 type T[P *C] … 2675 type T[P (C)] … 2676 type T[P *C|Q] … 2677 … 2678 </pre> 2679 2680 2681 In these rare cases, the type parameter list is indistinguishable from an 2682 expression and the type declaration is parsed as an array type declaration. 2683 To resolve the ambiguity, embed the constraint in an 2684 <a href="#Interface_types">interface</a> or use a trailing comma: 2685 2686 2687 <pre> 2688 type T[P interface{*C}] … 2689 type T[P *C,] … 2690 </pre> 2691 2692 2693 Type parameters may also be declared by the receiver specification 2694 of a <a href="#Method_declarations">method declaration</a> associated 2695 with a generic type. 2696 2697 2698 2699 Within a type parameter list of a generic type <code>T</code>, a type constraint 2700 may not (directly, or indirectly through the type parameter list of another 2701 generic type) refer to <code>T</code>. 2702 2703 2704 <pre> 2705 type T1[P T1[P]] … // illegal: T1 refers to itself 2706 type T2[P interface{ T2[int] }] … // illegal: T2 refers to itself 2707 type T3[P interface{ m(T3[int])}] … // illegal: T3 refers to itself 2708 type T4[P T5[P]] … // illegal: T4 refers to T5 and 2709 type T5[P T4[P]] … // T5 refers to T4 2710 2711 type T6[P int] struct{ f *T6[P] } // ok: reference to T6 is not in type parameter list 2712 </pre> 2713 2714 <h4 id="Type_constraints">Type constraints</h4> 2715 2716 2717 A type constraint is an <a href="#Interface_types">interface</a> that defines the 2718 set of permissible type arguments for the respective type parameter and controls the 2719 operations supported by values of that type parameter. 2720 2721 2722 <pre class="ebnf"> 2723 TypeConstraint = TypeElem . 2724 </pre> 2725 2726 2727 If the constraint is an interface literal of the form <code>interface{E}</code> where 2728 <code>E</code> is an embedded <a href="#Interface_types">type element</a> (not a method), in a type parameter list 2729 the enclosing <code>interface{ … }</code> may be omitted for convenience: 2730 2731 2732 <pre> 2733 [T []P] // = [T interface{[]P}] 2734 [T ~int] // = [T interface{~int}] 2735 [T int|string] // = [T interface{int|string}] 2736 type Constraint ~int // illegal: ~int is not in a type parameter list 2737 </pre> 2738 2739  2744 2745 2746 The <a href="#Predeclared_identifiers">predeclared</a> 2747 <a href="#Interface_types">interface type</a> <code>comparable</code> 2748 denotes the set of all non-interface types that are 2749 <a href="#Comparison_operators">strictly comparable</a>. 2750 2751 2752 2753 Even though interfaces that are not type parameters are <a href="#Comparison_operators">comparable</a>, 2754 they are not strictly comparable and therefore they do not implement <code>comparable</code>. 2755 However, they <a href="#Satisfying_a_type_constraint">satisfy</a> <code>comparable</code>. 2756 2757 2758 <pre> 2759 int // implements comparable (int is strictly comparable) 2760 []byte // does not implement comparable (slices cannot be compared) 2761 interface{} // does not implement comparable (see above) 2762 interface{ ~int | ~string } // type parameter only: implements comparable (int, string types are stricly comparable) 2763 interface{ comparable } // type parameter only: implements comparable (comparable implements itself) 2764 interface{ ~int | ~[]byte } // type parameter only: does not implement comparable (slices are not comparable) 2765 interface{ ~struct{ any } } // type parameter only: does not implement comparable (field any is not strictly comparable) 2766 </pre> 2767 2768 2769 The <code>comparable</code> interface and interfaces that (directly or indirectly) embed 2770 <code>comparable</code> may only be used as type constraints. They cannot be the types of 2771 values or variables, or components of other, non-interface types. 2772 2773 2774 <h4 id="Satisfying_a_type_constraint">Satisfying a type constraint</h4> 2775 2776 2777 A type argument <code>T</code> satisfies a type constraint <code>C</code> 2778 if <code>T</code> is an element of the type set defined by <code>C</code>; i.e., 2779 if <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>. 2780 As an exception, a <a href="#Comparison_operators">strictly comparable</a> 2781 type constraint may also be satisfied by a <a href="#Comparison_operators">comparable</a> 2782 (not necessarily strictly comparable) type argument. 2783 More precisely: 2784 2785 2786 2787 A type T satisfies a constraint <code>C</code> if 2788 2789 2790 <ul> 2791 <li> 2792 <code>T</code> <a href="#Implementing_an_interface">implements</a> <code>C</code>; or 2793 </li> 2794 <li> 2795 <code>C</code> can be written in the form <code>interface{ comparable; E }</code>, 2796 where <code>E</code> is a <a href="#Basic_interfaces">basic interface</a> and 2797 <code>T</code> is <a href="#Comparison_operators">comparable</a> and implements <code>E</code>. 2798 </li> 2799 </ul> 2800 2801 <pre> 2802 type argument type constraint // constraint satisfaction 2803 2804 int interface{ ~int } // satisfied: int implements interface{ ~int } 2805 string comparable // satisfied: string implements comparable (string is stricty comparable) 2806 []byte comparable // not satisfied: slices are not comparable 2807 any interface{ comparable; int } // not satisfied: any does not implement interface{ int } 2808 any comparable // satisfied: any is comparable and implements the basic interface any 2809 struct{f any} comparable // satisfied: struct{f any} is comparable and implements the basic interface any 2810 any interface{ comparable; m() } // not satisfied: any does not implement the basic interface interface{ m() } 2811 interface{ m() } interface{ comparable; m() } // satisfied: interface{ m() } is comparable and implements the basic interface interface{ m() } 2812 </pre> 2813 2814 2815 Because of the exception in the constraint satisfaction rule, comparing operands of type parameter type 2816 may panic at run-time (even though comparable type parameters are always strictly comparable). 2817 2818 2819 <h3 id="Variable_declarations">Variable declarations</h3> 2820 2821 2822 A variable declaration creates one or more <a href="#Variables">variables</a>, 2823 binds corresponding identifiers to them, and gives each a type and an initial value. 2824 2825 2826 <pre class="ebnf"> 2827 VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . 2828 VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . 2829 </pre> 2830 2831 <pre> 2832 var i int 2833 var U, V, W float64 2834 var k = 0 2835 var x, y float32 = -1, -2 2836 var ( 2837 i int 2838 u, v, s = 2.0, 3.0, "bar" 2839 ) 2840 var re, im = complexSqrt(-1) 2841 var _, found = entries[name] // map lookup; only interested in "found" 2842 </pre> 2843 2844 2845 If a list of expressions is given, the variables are initialized 2846 with the expressions following the rules for <a href="#Assignment_statements">assignment statements</a>. 2847 Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. 2848 2849 2850 2851 If a type is present, each variable is given that type. 2852 Otherwise, each variable is given the type of the corresponding 2853 initialization value in the assignment. 2854 If that value is an untyped constant, it is first implicitly 2855 <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; 2856 if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>. 2857 The predeclared value <code>nil</code> cannot be used to initialize a variable 2858 with no explicit type. 2859 2860 2861 <pre> 2862 var d = math.Sin(0.5) // d is float64 2863 var i = 42 // i is int 2864 var t, ok = x.(T) // t is T, ok is bool 2865 var n = nil // illegal 2866 </pre> 2867 2868 2869 Implementation restriction: A compiler may make it illegal to declare a variable 2870 inside a <a href="#Function_declarations">function body</a> if the variable is 2871 never used. 2872 2873 2874 <h3 id="Short_variable_declarations">Short variable declarations</h3> 2875 2876 2877 A short variable declaration uses the syntax: 2878 2879 2880 <pre class="ebnf"> 2881 ShortVarDecl = IdentifierList ":=" ExpressionList . 2882 </pre> 2883 2884 2885 It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a> 2886 with initializer expressions but no types: 2887 2888 2889 <pre class="grammar"> 2890 "var" IdentifierList "=" ExpressionList . 2891 </pre> 2892 2893 <pre> 2894 i, j := 0, 10 2895 f := func() int { return 7 } 2896 ch := make(chan int) 2897 r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any 2898 _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate 2899 </pre> 2900 2901 2902 Unlike regular variable declarations, a short variable declaration may redeclare 2903 variables provided they were originally declared earlier in the same block 2904 (or the parameter lists if the block is the function body) with the same type, 2905 and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. 2906 As a consequence, redeclaration can only appear in a multi-variable short declaration. 2907 Redeclaration does not introduce a new variable; it just assigns a new value to the original. 2908 The non-blank variable names on the left side of <code>:=</code> 2909 must be <a href="#Uniqueness_of_identifiers">unique</a>. 2910 2911 2912 <pre> 2913 field1, offset := nextField(str, 0) 2914 field2, offset := nextField(str, offset) // redeclares offset 2915 x, y, x := 1, 2, 3 // illegal: x repeated on left side of := 2916 </pre> 2917 2918 2919 Short variable declarations may appear only inside functions. 2920 In some contexts such as the initializers for 2921 <a href="#If_statements">"if"</a>, 2922 <a href="#For_statements">"for"</a>, or 2923 <a href="#Switch_statements">"switch"</a> statements, 2924 they can be used to declare local temporary variables. 2925 2926 2927 <h3 id="Function_declarations">Function declarations</h3> 2928 2929  2934 2935 2936 A function declaration binds an identifier, the function name, 2937 to a function. 2938 2939 2940 <pre class="ebnf"> 2941 FunctionDecl = "func" FunctionName [ TypeParameters ] Signature [ FunctionBody ] . 2942 FunctionName = identifier . 2943 FunctionBody = Block . 2944 </pre> 2945 2946 2947 If the function's <a href="#Function_types">signature</a> declares 2948 result parameters, the function body's statement list must end in 2949 a <a href="#Terminating_statements">terminating statement</a>. 2950 2951 2952 <pre> 2953 func IndexRune(s string, r rune) int { 2954 for i, c := range s { 2955 if c == r { 2956 return i 2957 } 2958 } 2959 // invalid: missing return statement 2960 } 2961 </pre> 2962 2963 2964 If the function declaration specifies <a href="#Type_parameter_declarations">type parameters</a>, 2965 the function name denotes a generic function. 2966 A generic function must be <a href="#Instantiations">instantiated</a> before it can be 2967 called or used as a value. 2968 2969 2970 <pre> 2971 func min[T ~int|~float64](x, y T) T { 2972 if x < y { 2973 return x 2974 } 2975 return y 2976 } 2977 </pre> 2978 2979 2980 A function declaration without type parameters may omit the body. 2981 Such a declaration provides the signature for a function implemented outside Go, 2982 such as an assembly routine. 2983 2984 2985 <pre> 2986 func flushICache(begin, end uintptr) // implemented externally 2987 </pre> 2988 2989 <h3 id="Method_declarations">Method declarations</h3> 2990 2991 2992 A method is a <a href="#Function_declarations">function</a> with a receiver. 2993 A method declaration binds an identifier, the method name, to a method, 2994 and associates the method with the receiver's base type. 2995 2996 2997 <pre class="ebnf"> 2998 MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . 2999 Receiver = Parameters . 3000 </pre> 3001 3002 3003 The receiver is specified via an extra parameter section preceding the method 3004 name. That parameter section must declare a single non-variadic parameter, the receiver. 3005 Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a 3006 pointer to a defined type <code>T</code>, possibly followed by a list of type parameter 3007 names <code>[P1, P2, …]</code> enclosed in square brackets. 3008 <code>T</code> is called the receiver base type. A receiver base type cannot be 3009 a pointer or interface type and it must be defined in the same package as the method. 3010 The method is said to be bound to its receiver base type and the method name 3011 is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> 3012 or <code>*T</code>. 3013 3014 3015 3016 A non-<a href="#Blank_identifier">blank</a> receiver identifier must be 3017 <a href="#Uniqueness_of_identifiers">unique</a> in the method signature. 3018 If the receiver's value is not referenced inside the body of the method, 3019 its identifier may be omitted in the declaration. The same applies in 3020 general to parameters of functions and methods. 3021 3022 3023 3024 For a base type, the non-blank names of methods bound to it must be unique. 3025 If the base type is a <a href="#Struct_types">struct type</a>, 3026 the non-blank method and field names must be distinct. 3027 3028 3029 3030 Given defined type <code>Point</code> the declarations 3031 3032 3033 <pre> 3034 func (p *Point) Length() float64 { 3035 return math.Sqrt(p.x * p.x + p.y * p.y) 3036 } 3037 3038 func (p *Point) Scale(factor float64) { 3039 p.x *= factor 3040 p.y *= factor 3041 } 3042 </pre> 3043 3044 3045 bind the methods <code>Length</code> and <code>Scale</code>, 3046 with receiver type <code>*Point</code>, 3047 to the base type <code>Point</code>. 3048 3049 3050 3051 If the receiver base type is a <a href="#Type_declarations">generic type</a>, the 3052 receiver specification must declare corresponding type parameters for the method 3053 to use. This makes the receiver type parameters available to the method. 3054 Syntactically, this type parameter declaration looks like an 3055 <a href="#Instantiations">instantiation</a> of the receiver base type: the type 3056 arguments must be identifiers denoting the type parameters being declared, one 3057 for each type parameter of the receiver base type. 3058 The type parameter names do not need to match their corresponding parameter names in the 3059 receiver base type definition, and all non-blank parameter names must be unique in the 3060 receiver parameter section and the method signature. 3061 The receiver type parameter constraints are implied by the receiver base type definition: 3062 corresponding type parameters have corresponding constraints. 3063 3064 3065 <pre> 3066 type Pair[A, B any] struct { 3067 a A 3068 b B 3069 } 3070 3071 func (p Pair[A, B]) Swap() Pair[B, A] { … } // receiver declares A, B 3072 func (p Pair[First, _]) First() First { … } // receiver declares First, corresponds to A in Pair 3073 </pre> 3074 3075 <h2 id="Expressions">Expressions</h2> 3076 3077 3078 An expression specifies the computation of a value by applying 3079 operators and functions to operands. 3080 3081 3082 <h3 id="Operands">Operands</h3> 3083 3084 3085 Operands denote the elementary values in an expression. An operand may be a 3086 literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) 3087 non-<a href="#Blank_identifier">blank</a> identifier denoting a 3088 <a href="#Constant_declarations">constant</a>, 3089 <a href="#Variable_declarations">variable</a>, or 3090 <a href="#Function_declarations">function</a>, 3091 or a parenthesized expression. 3092 3093 3094 <pre class="ebnf"> 3095 Operand = Literal | OperandName [ TypeArgs ] | "(" Expression ")" . 3096 Literal = BasicLit | CompositeLit | FunctionLit . 3097 BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . 3098 OperandName = identifier | QualifiedIdent . 3099 </pre> 3100 3101 3102 An operand name denoting a <a href="#Function_declarations">generic function</a> 3103 may be followed by a list of <a href="#Instantiations">type arguments</a>; the 3104 resulting operand is an <a href="#Instantiations">instantiated</a> function. 3105 3106 3107 3108 The <a href="#Blank_identifier">blank identifier</a> may appear as an 3109 operand only on the left-hand side of an <a href="#Assignment_statements">assignment statement</a>. 3110 3111 3112 3113 Implementation restriction: A compiler need not report an error if an operand's 3114 type is a <a href="#Type_parameter_declarations">type parameter</a> with an empty 3115 <a href="#Interface_types">type set</a>. Functions with such type parameters 3116 cannot be <a href="#Instantiations">instantiated</a>; any attempt will lead 3117 to an error at the instantiation site. 3118 3119 3120 <h3 id="Qualified_identifiers">Qualified identifiers</h3> 3121 3122 3123 A qualified identifier is an identifier qualified with a package name prefix. 3124 Both the package name and the identifier must not be 3125 <a href="#Blank_identifier">blank</a>. 3126 3127 3128 <pre class="ebnf"> 3129 QualifiedIdent = PackageName "." identifier . 3130 </pre> 3131 3132 3133 A qualified identifier accesses an identifier in a different package, which 3134 must be <a href="#Import_declarations">imported</a>. 3135 The identifier must be <a href="#Exported_identifiers">exported</a> and 3136 declared in the <a href="#Blocks">package block</a> of that package. 3137 3138 3139 <pre> 3140 math.Sin // denotes the Sin function in package math 3141 </pre> 3142 3143 <h3 id="Composite_literals">Composite literals</h3> 3144 3145 3146 Composite literals construct new composite values each time they are evaluated. 3147 They consist of the type of the literal followed by a brace-bound list of elements. 3148 Each element may optionally be preceded by a corresponding key. 3149 3150 3151 <pre class="ebnf"> 3152 CompositeLit = LiteralType LiteralValue . 3153 LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | 3154 SliceType | MapType | TypeName [ TypeArgs ] . 3155 LiteralValue = "{" [ ElementList [ "," ] ] "}" . 3156 ElementList = KeyedElement { "," KeyedElement } . 3157 KeyedElement = [ Key ":" ] Element . 3158 Key = FieldName | Expression | LiteralValue . 3159 FieldName = identifier . 3160 Element = Expression | LiteralValue . 3161 </pre> 3162 3163 3164 The LiteralType's <a href="#Core_types">core type</a> <code>T</code> 3165 must be a struct, array, slice, or map type 3166 (the syntax enforces this constraint except when the type is given 3167 as a TypeName). 3168 The types of the elements and keys must be <a href="#Assignability">assignable</a> 3169 to the respective field, element, and key types of type <code>T</code>; 3170 there is no additional conversion. 3171 The key is interpreted as a field name for struct literals, 3172 an index for array and slice literals, and a key for map literals. 3173 For map literals, all elements must have a key. It is an error 3174 to specify multiple elements with the same field name or 3175 constant key value. For non-constant map keys, see the section on 3176 <a href="#Order_of_evaluation">evaluation order</a>. 3177 3178 3179 3180 For struct literals the following rules apply: 3181 3182 <ul> 3183 <li>A key must be a field name declared in the struct type. 3184 </li> 3185 <li>An element list that does not contain any keys must 3186 list an element for each struct field in the 3187 order in which the fields are declared. 3188 </li> 3189 <li>If any element has a key, every element must have a key. 3190 </li> 3191 <li>An element list that contains keys does not need to 3192 have an element for each struct field. Omitted fields 3193 get the zero value for that field. 3194 </li> 3195 <li>A literal may omit the element list; such a literal evaluates 3196 to the zero value for its type. 3197 </li> 3198 <li>It is an error to specify an element for a non-exported 3199 field of a struct belonging to a different package. 3200 </li> 3201 </ul> 3202 3203 3204 Given the declarations 3205 3206 <pre> 3207 type Point3D struct { x, y, z float64 } 3208 type Line struct { p, q Point3D } 3209 </pre> 3210 3211 3212 one may write 3213 3214 3215 <pre> 3216 origin := Point3D{} // zero value for Point3D 3217 line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x 3218 </pre> 3219 3220 3221 For array and slice literals the following rules apply: 3222 3223 <ul> 3224 <li>Each element has an associated integer index marking 3225 its position in the array. 3226 </li> 3227 <li>An element with a key uses the key as its index. The 3228 key must be a non-negative constant 3229 <a href="#Representability">representable</a> by 3230 a value of type <code>int</code>; and if it is typed 3231 it must be of <a href="#Numeric_types">integer type</a>. 3232 </li> 3233 <li>An element without a key uses the previous element's index plus one. 3234 If the first element has no key, its index is zero. 3235 </li> 3236 </ul> 3237 3238 3239 <a href="#Address_operators">Taking the address</a> of a composite literal 3240 generates a pointer to a unique <a href="#Variables">variable</a> initialized 3241 with the literal's value. 3242 3243 3244 <pre> 3245 var pointer *Point3D = &Point3D{y: 1000} 3246 </pre> 3247 3248 3249 Note that the <a href="#The_zero_value">zero value</a> for a slice or map 3250 type is not the same as an initialized but empty value of the same type. 3251 Consequently, taking the address of an empty slice or map composite literal 3252 does not have the same effect as allocating a new slice or map value with 3253 <a href="#Allocation">new</a>. 3254 3255 3256 <pre> 3257 p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0 3258 p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0 3259 </pre> 3260 3261 3262 The length of an array literal is the length specified in the literal type. 3263 If fewer elements than the length are provided in the literal, the missing 3264 elements are set to the zero value for the array element type. 3265 It is an error to provide elements with index values outside the index range 3266 of the array. The notation <code>...</code> specifies an array length equal 3267 to the maximum element index plus one. 3268 3269 3270 <pre> 3271 buffer := [10]string{} // len(buffer) == 10 3272 intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 3273 days := [...]string{"Sat", "Sun"} // len(days) == 2 3274 </pre> 3275 3276 3277 A slice literal describes the entire underlying array literal. 3278 Thus the length and capacity of a slice literal are the maximum 3279 element index plus one. A slice literal has the form 3280 3281 3282 <pre> 3283 []T{x1, x2, … xn} 3284 </pre> 3285 3286 3287 and is shorthand for a slice operation applied to an array: 3288 3289 3290 <pre> 3291 tmp := [n]T{x1, x2, … xn} 3292 tmp[0 : n] 3293 </pre> 3294 3295 3296 Within a composite literal of array, slice, or map type <code>T</code>, 3297 elements or map keys that are themselves composite literals may elide the respective 3298 literal type if it is identical to the element or key type of <code>T</code>. 3299 Similarly, elements or keys that are addresses of composite literals may elide 3300 the <code>&T</code> when the element or key type is <code>*T</code>. 3301 3302 3303 <pre> 3304 [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} 3305 [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} 3306 [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} 3307 map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}} 3308 map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"} 3309 3310 type PPoint *Point 3311 [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} 3312 [2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})} 3313 </pre> 3314 3315 3316 A parsing ambiguity arises when a composite literal using the 3317 TypeName form of the LiteralType appears as an operand between the 3318 <a href="#Keywords">keyword</a> and the opening brace of the block 3319 of an "if", "for", or "switch" statement, and the composite literal 3320 is not enclosed in parentheses, square brackets, or curly braces. 3321 In this rare case, the opening brace of the literal is erroneously parsed 3322 as the one introducing the block of statements. To resolve the ambiguity, 3323 the composite literal must appear within parentheses. 3324 3325 3326 <pre> 3327 if x == (T{a,b,c}[i]) { … } 3328 if (x == T{a,b,c}[i]) { … } 3329 </pre> 3330 3331 3332 Examples of valid array, slice, and map literals: 3333 3334 3335 <pre> 3336 // list of prime numbers 3337 primes := []int{2, 3, 5, 7, 9, 2147483647} 3338 3339 // vowels[ch] is true if ch is a vowel 3340 vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true} 3341 3342 // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} 3343 filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} 3344 3345 // frequencies in Hz for equal-tempered scale (A4 = 440Hz) 3346 noteFrequency := map[string]float32{ 3347 "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, 3348 "G0": 24.50, "A0": 27.50, "B0": 30.87, 3349 } 3350 </pre> 3351 3352 3353 <h3 id="Function_literals">Function literals</h3> 3354 3355 3356 A function literal represents an anonymous <a href="#Function_declarations">function</a>. 3357 Function literals cannot declare type parameters. 3358 3359 3360 <pre class="ebnf"> 3361 FunctionLit = "func" Signature FunctionBody . 3362 </pre> 3363 3364 <pre> 3365 func(a, b int, z float64) bool { return a*b < int(z) } 3366 </pre> 3367 3368 3369 A function literal can be assigned to a variable or invoked directly. 3370 3371 3372 <pre> 3373 f := func(x, y int) int { return x + y } 3374 func(ch chan int) { ch <- ACK }(replyChan) 3375 </pre> 3376 3377 3378 Function literals are closures: they may refer to variables 3379 defined in a surrounding function. Those variables are then shared between 3380 the surrounding function and the function literal, and they survive as long 3381 as they are accessible. 3382 3383 3384 3385 <h3 id="Primary_expressions">Primary expressions</h3> 3386 3387 3388 Primary expressions are the operands for unary and binary expressions. 3389 3390 3391 <pre class="ebnf"> 3392 PrimaryExpr = 3393 Operand | 3394 Conversion | 3395 MethodExpr | 3396 PrimaryExpr Selector | 3397 PrimaryExpr Index | 3398 PrimaryExpr Slice | 3399 PrimaryExpr TypeAssertion | 3400 PrimaryExpr Arguments . 3401 3402 Selector = "." identifier . 3403 Index = "[" Expression [ "," ] "]" . 3404 Slice = "[" [ Expression ] ":" [ Expression ] "]" | 3405 "[" [ Expression ] ":" Expression ":" Expression "]" . 3406 TypeAssertion = "." "(" Type ")" . 3407 Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . 3408 </pre> 3409 3410 3411 <pre> 3412 x 3413 2 3414 (s + ".txt") 3415 f(3.1415, true) 3416 Point{1, 2} 3417 m["foo"] 3418 s[i : j + 1] 3419 obj.color 3420 f.p[i].x() 3421 </pre> 3422 3423 3424 <h3 id="Selectors">Selectors</h3> 3425 3426 3427 For a <a href="#Primary_expressions">primary expression</a> <code>x</code> 3428 that is not a <a href="#Package_clause">package name</a>, the 3429 selector expression 3430 3431 3432 <pre> 3433 x.f 3434 </pre> 3435 3436 3437 denotes the field or method <code>f</code> of the value <code>x</code> 3438 (or sometimes <code>*x</code>; see below). 3439 The identifier <code>f</code> is called the (field or method) selector; 3440 it must not be the <a href="#Blank_identifier">blank identifier</a>. 3441 The type of the selector expression is the type of <code>f</code>. 3442 If <code>x</code> is a package name, see the section on 3443 <a href="#Qualified_identifiers">qualified identifiers</a>. 3444 3445 3446 3447 A selector <code>f</code> may denote a field or method <code>f</code> of 3448 a type <code>T</code>, or it may refer 3449 to a field or method <code>f</code> of a nested 3450 <a href="#Struct_types">embedded field</a> of <code>T</code>. 3451 The number of embedded fields traversed 3452 to reach <code>f</code> is called its depth in <code>T</code>. 3453 The depth of a field or method <code>f</code> 3454 declared in <code>T</code> is zero. 3455 The depth of a field or method <code>f</code> declared in 3456 an embedded field <code>A</code> in <code>T</code> is the 3457 depth of <code>f</code> in <code>A</code> plus one. 3458 3459 3460 3461 The following rules apply to selectors: 3462 3463 3464 <ol> 3465 <li> 3466 For a value <code>x</code> of type <code>T</code> or <code>*T</code> 3467 where <code>T</code> is not a pointer or interface type, 3468 <code>x.f</code> denotes the field or method at the shallowest depth 3469 in <code>T</code> where there is such an <code>f</code>. 3470 If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> 3471 with shallowest depth, the selector expression is illegal. 3472 </li> 3473 3474 <li> 3475 For a value <code>x</code> of type <code>I</code> where <code>I</code> 3476 is an interface type, <code>x.f</code> denotes the actual method with name 3477 <code>f</code> of the dynamic value of <code>x</code>. 3478 If there is no method with name <code>f</code> in the 3479 <a href="#Method_sets">method set</a> of <code>I</code>, the selector 3480 expression is illegal. 3481 </li> 3482 3483 <li> 3484 As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> 3485 pointer type and <code>(*x).f</code> is a valid selector expression denoting a field 3486 (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. 3487 </li> 3488 3489 <li> 3490 In all other cases, <code>x.f</code> is illegal. 3491 </li> 3492 3493 <li> 3494 If <code>x</code> is of pointer type and has the value 3495 <code>nil</code> and <code>x.f</code> denotes a struct field, 3496 assigning to or evaluating <code>x.f</code> 3497 causes a <a href="#Run_time_panics">run-time panic</a>. 3498 </li> 3499 3500 <li> 3501 If <code>x</code> is of interface type and has the value 3502 <code>nil</code>, <a href="#Calls">calling</a> or 3503 <a href="#Method_values">evaluating</a> the method <code>x.f</code> 3504 causes a <a href="#Run_time_panics">run-time panic</a>. 3505 </li> 3506 </ol> 3507 3508 3509 For example, given the declarations: 3510 3511 3512 <pre> 3513 type T0 struct { 3514 x int 3515 } 3516 3517 func (*T0) M0() 3518 3519 type T1 struct { 3520 y int 3521 } 3522 3523 func (T1) M1() 3524 3525 type T2 struct { 3526 z int 3527 T1 3528 *T0 3529 } 3530 3531 func (*T2) M2() 3532 3533 type Q *T2 3534 3535 var t T2 // with t.T0 != nil 3536 var p *T2 // with p != nil and (*p).T0 != nil 3537 var q Q = p 3538 </pre> 3539 3540 3541 one may write: 3542 3543 3544 <pre> 3545 t.z // t.z 3546 t.y // t.T1.y 3547 t.x // (*t.T0).x 3548 3549 p.z // (*p).z 3550 p.y // (*p).T1.y 3551 p.x // (*(*p).T0).x 3552 3553 q.x // (*(*q).T0).x (*q).x is a valid field selector 3554 3555 p.M0() // ((*p).T0).M0() M0 expects *T0 receiver 3556 p.M1() // ((*p).T1).M1() M1 expects T1 receiver 3557 p.M2() // p.M2() M2 expects *T2 receiver 3558 t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls 3559 </pre> 3560 3561 3562 but the following is invalid: 3563 3564 3565 <pre> 3566 q.M0() // (*q).M0 is valid but not a field selector 3567 </pre> 3568 3569 3570 <h3 id="Method_expressions">Method expressions</h3> 3571 3572 3573 If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, 3574 <code>T.M</code> is a function that is callable as a regular function 3575 with the same arguments as <code>M</code> prefixed by an additional 3576 argument that is the receiver of the method. 3577 3578 3579 <pre class="ebnf"> 3580 MethodExpr = ReceiverType "." MethodName . 3581 ReceiverType = Type . 3582 </pre> 3583 3584 3585 Consider a struct type <code>T</code> with two methods, 3586 <code>Mv</code>, whose receiver is of type <code>T</code>, and 3587 <code>Mp</code>, whose receiver is of type <code>*T</code>. 3588 3589 3590 <pre> 3591 type T struct { 3592 a int 3593 } 3594 func (tv T) Mv(a int) int { return 0 } // value receiver 3595 func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver 3596 3597 var t T 3598 </pre> 3599 3600 3601 The expression 3602 3603 3604 <pre> 3605 T.Mv 3606 </pre> 3607 3608 3609 yields a function equivalent to <code>Mv</code> but 3610 with an explicit receiver as its first argument; it has signature 3611 3612 3613 <pre> 3614 func(tv T, a int) int 3615 </pre> 3616 3617 3618 That function may be called normally with an explicit receiver, so 3619 these five invocations are equivalent: 3620 3621 3622 <pre> 3623 t.Mv(7) 3624 T.Mv(t, 7) 3625 (T).Mv(t, 7) 3626 f1 := T.Mv; f1(t, 7) 3627 f2 := (T).Mv; f2(t, 7) 3628 </pre> 3629 3630 3631 Similarly, the expression 3632 3633 3634 <pre> 3635 (*T).Mp 3636 </pre> 3637 3638 3639 yields a function value representing <code>Mp</code> with signature 3640 3641 3642 <pre> 3643 func(tp *T, f float32) float32 3644 </pre> 3645 3646 3647 For a method with a value receiver, one can derive a function 3648 with an explicit pointer receiver, so 3649 3650 3651 <pre> 3652 (*T).Mv 3653 </pre> 3654 3655 3656 yields a function value representing <code>Mv</code> with signature 3657 3658 3659 <pre> 3660 func(tv *T, a int) int 3661 </pre> 3662 3663 3664 Such a function indirects through the receiver to create a value 3665 to pass as the receiver to the underlying method; 3666 the method does not overwrite the value whose address is passed in 3667 the function call. 3668 3669 3670 3671 The final case, a value-receiver function for a pointer-receiver method, 3672 is illegal because pointer-receiver methods are not in the method set 3673 of the value type. 3674 3675 3676 3677 Function values derived from methods are called with function call syntax; 3678 the receiver is provided as the first argument to the call. 3679 That is, given <code>f := T.Mv</code>, <code>f</code> is invoked 3680 as <code>f(t, 7)</code> not <code>t.f(7)</code>. 3681 To construct a function that binds the receiver, use a 3682 <a href="#Function_literals">function literal</a> or 3683 <a href="#Method_values">method value</a>. 3684 3685 3686 3687 It is legal to derive a function value from a method of an interface type. 3688 The resulting function takes an explicit receiver of that interface type. 3689 3690 3691 <h3 id="Method_values">Method values</h3> 3692 3693 3694 If the expression <code>x</code> has static type <code>T</code> and 3695 <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, 3696 <code>x.M</code> is called a method value. 3697 The method value <code>x.M</code> is a function value that is callable 3698 with the same arguments as a method call of <code>x.M</code>. 3699 The expression <code>x</code> is evaluated and saved during the evaluation of the 3700 method value; the saved copy is then used as the receiver in any calls, 3701 which may be executed later. 3702 3703 3704 <pre> 3705 type S struct { *T } 3706 type T int 3707 func (t T) M() { print(t) } 3708 3709 t := new(T) 3710 s := S{T: t} 3711 f := t.M // receiver *t is evaluated and stored in f 3712 g := s.M // receiver *(s.T) is evaluated and stored in g 3713 *t = 42 // does not affect stored receivers in f and g 3714 </pre> 3715 3716 3717 The type <code>T</code> may be an interface or non-interface type. 3718 3719 3720 3721 As in the discussion of <a href="#Method_expressions">method expressions</a> above, 3722 consider a struct type <code>T</code> with two methods, 3723 <code>Mv</code>, whose receiver is of type <code>T</code>, and 3724 <code>Mp</code>, whose receiver is of type <code>*T</code>. 3725 3726 3727 <pre> 3728 type T struct { 3729 a int 3730 } 3731 func (tv T) Mv(a int) int { return 0 } // value receiver 3732 func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver 3733 3734 var t T 3735 var pt *T 3736 func makeT() T 3737 </pre> 3738 3739 3740 The expression 3741 3742 3743 <pre> 3744 t.Mv 3745 </pre> 3746 3747 3748 yields a function value of type 3749 3750 3751 <pre> 3752 func(int) int 3753 </pre> 3754 3755 3756 These two invocations are equivalent: 3757 3758 3759 <pre> 3760 t.Mv(7) 3761 f := t.Mv; f(7) 3762 </pre> 3763 3764 3765 Similarly, the expression 3766 3767 3768 <pre> 3769 pt.Mp 3770 </pre> 3771 3772 3773 yields a function value of type 3774 3775 3776 <pre> 3777 func(float32) float32 3778 </pre> 3779 3780 3781 As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver 3782 using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. 3783 3784 3785 3786 As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver 3787 using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. 3788 3789 3790 <pre> 3791 f := t.Mv; f(7) // like t.Mv(7) 3792 f := pt.Mp; f(7) // like pt.Mp(7) 3793 f := pt.Mv; f(7) // like (*pt).Mv(7) 3794 f := t.Mp; f(7) // like (&t).Mp(7) 3795 f := makeT().Mp // invalid: result of makeT() is not addressable 3796 </pre> 3797 3798 3799 Although the examples above use non-interface types, it is also legal to create a method value 3800 from a value of interface type. 3801 3802 3803 <pre> 3804 var i interface { M(int) } = myVal 3805 f := i.M; f(7) // like i.M(7) 3806 </pre> 3807 3808 3809 <h3 id="Index_expressions">Index expressions</h3> 3810 3811 3812 A primary expression of the form 3813 3814 3815 <pre> 3816 a[x] 3817 </pre> 3818 3819 3820 denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. 3821 The value <code>x</code> is called the index or map key, respectively. 3822 The following rules apply: 3823 3824 3825 3826 If <code>a</code> is neither a map nor a type parameter: 3827 3828 <ul> 3829 <li>the index <code>x</code> must be an untyped constant or its 3830 <a href="#Core_types">core type</a> must be an <a href="#Numeric_types">integer</a></li> 3831 <li>a constant index must be non-negative and 3832 <a href="#Representability">representable</a> by a value of type <code>int</code></li> 3833 <li>a constant index that is untyped is given type <code>int</code></li> 3834 <li>the index <code>x</code> is in range if <code>0 <= x < len(a)</code>, 3835 otherwise it is out of range</li> 3836 </ul> 3837 3838 3839 For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>: 3840 3841 <ul> 3842 <li>a <a href="#Constants">constant</a> index must be in range</li> 3843 <li>if <code>x</code> is out of range at run time, 3844 a <a href="#Run_time_panics">run-time panic</a> occurs</li> 3845 <li><code>a[x]</code> is the array element at index <code>x</code> and the type of 3846 <code>a[x]</code> is the element type of <code>A</code></li> 3847 </ul> 3848 3849 3850 For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type: 3851 3852 <ul> 3853 <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> 3854 </ul> 3855 3856 3857 For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: 3858 3859 <ul> 3860 <li>if <code>x</code> is out of range at run time, 3861 a <a href="#Run_time_panics">run-time panic</a> occurs</li> 3862 <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of 3863 <code>a[x]</code> is the element type of <code>S</code></li> 3864 </ul> 3865 3866 3867 For <code>a</code> of <a href="#String_types">string type</a>: 3868 3869 <ul> 3870 <li>a <a href="#Constants">constant</a> index must be in range 3871 if the string <code>a</code> is also constant</li> 3872 <li>if <code>x</code> is out of range at run time, 3873 a <a href="#Run_time_panics">run-time panic</a> occurs</li> 3874 <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of 3875 <code>a[x]</code> is <code>byte</code></li> 3876 <li><code>a[x]</code> may not be assigned to</li> 3877 </ul> 3878 3879 3880 For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>: 3881 3882 <ul> 3883 <li><code>x</code>'s type must be 3884 <a href="#Assignability">assignable</a> 3885 to the key type of <code>M</code></li> 3886 <li>if the map contains an entry with key <code>x</code>, 3887 <code>a[x]</code> is the map element with key <code>x</code> 3888 and the type of <code>a[x]</code> is the element type of <code>M</code></li> 3889 <li>if the map is <code>nil</code> or does not contain such an entry, 3890 <code>a[x]</code> is the <a href="#The_zero_value">zero value</a> 3891 for the element type of <code>M</code></li> 3892 </ul> 3893 3894 3895 For <code>a</code> of <a href="#Type_parameter_declarations">type parameter type</a> <code>P</code>: 3896 3897 <ul> 3898 <li>The index expression <code>a[x]</code> must be valid for values 3899 of all types in <code>P</code>'s type set.</li> 3900 <li>The element types of all types in <code>P</code>'s type set must be identical. 3901 In this context, the element type of a string type is <code>byte</code>.</li> 3902 <li>If there is a map type in the type set of <code>P</code>, 3903 all types in that type set must be map types, and the respective key types 3904 must be all identical.</li> 3905 <li><code>a[x]</code> is the array, slice, or string element at index <code>x</code>, 3906 or the map element with key <code>x</code> of the type argument 3907 that <code>P</code> is instantiated with, and the type of <code>a[x]</code> is 3908 the type of the (identical) element types.</li> 3909 <li><code>a[x]</code> may not be assigned to if <code>P</code>'s type set 3910 includes string types. 3911 </ul> 3912 3913 3914 Otherwise <code>a[x]</code> is illegal. 3915 3916 3917 3918 An index expression on a map <code>a</code> of type <code>map[K]V</code> 3919 used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form 3920 3921 3922 <pre> 3923 v, ok = a[x] 3924 v, ok := a[x] 3925 var v, ok = a[x] 3926 </pre> 3927 3928 3929 yields an additional untyped boolean value. The value of <code>ok</code> is 3930 <code>true</code> if the key <code>x</code> is present in the map, and 3931 <code>false</code> otherwise. 3932 3933 3934 3935 Assigning to an element of a <code>nil</code> map causes a 3936 <a href="#Run_time_panics">run-time panic</a>. 3937 3938 3939 3940 <h3 id="Slice_expressions">Slice expressions</h3> 3941 3942 3943 Slice expressions construct a substring or slice from a string, array, pointer 3944 to array, or slice. There are two variants: a simple form that specifies a low 3945 and high bound, and a full form that also specifies a bound on the capacity. 3946 3947 3948 <h4>Simple slice expressions</h4> 3949 3950 3951 The primary expression 3952 3953 3954 <pre> 3955 a[low : high] 3956 </pre> 3957 3958 3959 constructs a substring or slice. The <a href="#Core_types">core type</a> of 3960 <code>a</code> must be a string, array, pointer to array, slice, or a 3961 <a href="#Core_types"><code>bytestring</code></a>. 3962 The indices <code>low</code> and 3963 <code>high</code> select which elements of operand <code>a</code> appear 3964 in the result. The result has indices starting at 0 and length equal to 3965 <code>high</code> - <code>low</code>. 3966 After slicing the array <code>a</code> 3967 3968 3969 <pre> 3970 a := [5]int{1, 2, 3, 4, 5} 3971 s := a[1:4] 3972 </pre> 3973 3974 3975 the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements 3976 3977 3978 <pre> 3979 s[0] == 2 3980 s[1] == 3 3981 s[2] == 4 3982 </pre> 3983 3984 3985 For convenience, any of the indices may be omitted. A missing <code>low</code> 3986 index defaults to zero; a missing <code>high</code> index defaults to the length of the 3987 sliced operand: 3988 3989 3990 <pre> 3991 a[2:] // same as a[2 : len(a)] 3992 a[:3] // same as a[0 : 3] 3993 a[:] // same as a[0 : len(a)] 3994 </pre> 3995 3996 3997 If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for 3998 <code>(*a)[low : high]</code>. 3999 4000 4001 4002 For arrays or strings, the indices are in range if 4003 <code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>, 4004 otherwise they are out of range. 4005 For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. 4006 A <a href="#Constants">constant</a> index must be non-negative and 4007 <a href="#Representability">representable</a> by a value of type 4008 <code>int</code>; for arrays or constant strings, constant indices must also be in range. 4009 If both indices are constant, they must satisfy <code>low <= high</code>. 4010 If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. 4011 4012 4013 4014 Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, 4015 the result of the slice operation is a non-constant value of the same type as the operand. 4016 For untyped string operands the result is a non-constant value of type <code>string</code>. 4017 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> 4018 and the result of the slice operation is a slice with the same element type as the array. 4019 4020 4021 4022 If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result 4023 is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying 4024 array with the operand. 4025 4026 4027 <pre> 4028 var a [10]int 4029 s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5] 4030 s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5] 4031 s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element 4032 4033 var s []int 4034 s3 := s[:0] // s3 == nil 4035 </pre> 4036 4037 4038 <h4>Full slice expressions</h4> 4039 4040 4041 The primary expression 4042 4043 4044 <pre> 4045 a[low : high : max] 4046 </pre> 4047 4048 4049 constructs a slice of the same type, and with the same length and elements as the simple slice 4050 expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity 4051 by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. 4052 The <a href="#Core_types">core type</a> of <code>a</code> must be an array, pointer to array, 4053 or slice (but not a string). 4054 After slicing the array <code>a</code> 4055 4056 4057 <pre> 4058 a := [5]int{1, 2, 3, 4, 5} 4059 t := a[1:3:5] 4060 </pre> 4061 4062 4063 the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements 4064 4065 4066 <pre> 4067 t[0] == 2 4068 t[1] == 3 4069 </pre> 4070 4071 4072 As for simple slice expressions, if <code>a</code> is a pointer to an array, 4073 <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. 4074 If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. 4075 4076 4077 4078 The indices are in range if <code>0 <= low <= high <= max <= cap(a)</code>, 4079 otherwise they are out of range. 4080 A <a href="#Constants">constant</a> index must be non-negative and 4081 <a href="#Representability">representable</a> by a value of type 4082 <code>int</code>; for arrays, constant indices must also be in range. 4083 If multiple indices are constant, the constants that are present must be in range relative to each 4084 other. 4085 If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. 4086 4087 4088 <h3 id="Type_assertions">Type assertions</h3> 4089 4090 4091 For an expression <code>x</code> of <a href="#Interface_types">interface type</a>, 4092 but not a <a href="#Type_parameter_declarations">type parameter</a>, and a type <code>T</code>, 4093 the primary expression 4094 4095 4096 <pre> 4097 x.(T) 4098 </pre> 4099 4100 4101 asserts that <code>x</code> is not <code>nil</code> 4102 and that the value stored in <code>x</code> is of type <code>T</code>. 4103 The notation <code>x.(T)</code> is called a type assertion. 4104 4105 4106 More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts 4107 that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> 4108 to the type <code>T</code>. 4109 In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; 4110 otherwise the type assertion is invalid since it is not possible for <code>x</code> 4111 to store a value of type <code>T</code>. 4112 If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type 4113 of <code>x</code> <a href="#Implementing_an_interface">implements</a> the interface <code>T</code>. 4114 4115 4116 If the type assertion holds, the value of the expression is the value 4117 stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, 4118 a <a href="#Run_time_panics">run-time panic</a> occurs. 4119 In other words, even though the dynamic type of <code>x</code> 4120 is known only at run time, the type of <code>x.(T)</code> is 4121 known to be <code>T</code> in a correct program. 4122 4123 4124 <pre> 4125 var x interface{} = 7 // x has dynamic type int and value 7 4126 i := x.(int) // i has type int and value 7 4127 4128 type I interface { m() } 4129 4130 func f(y I) { 4131 s := y.(string) // illegal: string does not implement I (missing method m) 4132 r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader 4133 … 4134 } 4135 </pre> 4136 4137 4138 A type assertion used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form 4139 4140 4141 <pre> 4142 v, ok = x.(T) 4143 v, ok := x.(T) 4144 var v, ok = x.(T) 4145 var v, ok interface{} = x.(T) // dynamic types of v and ok are T and bool 4146 </pre> 4147 4148 4149 yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> 4150 if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is 4151 the <a href="#The_zero_value">zero value</a> for type <code>T</code>. 4152 No <a href="#Run_time_panics">run-time panic</a> occurs in this case. 4153 4154 4155 4156 <h3 id="Calls">Calls</h3> 4157 4158 4159 Given an expression <code>f</code> with a <a href="#Core_types">core type</a> 4160 <code>F</code> of <a href="#Function_types">function type</a>, 4161 4162 4163 <pre> 4164 f(a1, a2, … an) 4165 </pre> 4166 4167 4168 calls <code>f</code> with arguments <code>a1, a2, … an</code>. 4169 Except for one special case, arguments must be single-valued expressions 4170 <a href="#Assignability">assignable</a> to the parameter types of 4171 <code>F</code> and are evaluated before the function is called. 4172 The type of the expression is the result type 4173 of <code>F</code>. 4174 A method invocation is similar but the method itself 4175 is specified as a selector upon a value of the receiver type for 4176 the method. 4177 4178 4179 <pre> 4180 math.Atan2(x, y) // function call 4181 var pt *Point 4182 pt.Scale(3.5) // method call with receiver pt 4183 </pre> 4184 4185 4186 If <code>f</code> denotes a generic function, it must be 4187 <a href="#Instantiations">instantiated</a> before it can be called 4188 or used as a function value. 4189 4190 4191 4192 In a function call, the function value and arguments are evaluated in 4193 <a href="#Order_of_evaluation">the usual order</a>. 4194 After they are evaluated, the parameters of the call are passed by value to the function 4195 and the called function begins execution. 4196 The return parameters of the function are passed by value 4197 back to the caller when the function returns. 4198 4199 4200 4201 Calling a <code>nil</code> function value 4202 causes a <a href="#Run_time_panics">run-time panic</a>. 4203 4204 4205 4206 As a special case, if the return values of a function or method 4207 <code>g</code> are equal in number and individually 4208 assignable to the parameters of another function or method 4209 <code>f</code>, then the call <code>f(g(parameters_of_g))</code> 4210 will invoke <code>f</code> after binding the return values of 4211 <code>g</code> to the parameters of <code>f</code> in order. The call 4212 of <code>f</code> must contain no parameters other than the call of <code>g</code>, 4213 and <code>g</code> must have at least one return value. 4214 If <code>f</code> has a final <code>...</code> parameter, it is 4215 assigned the return values of <code>g</code> that remain after 4216 assignment of regular parameters. 4217 4218 4219 <pre> 4220 func Split(s string, pos int) (string, string) { 4221 return s[0:pos], s[pos:] 4222 } 4223 4224 func Join(s, t string) string { 4225 return s + t 4226 } 4227 4228 if Join(Split(value, len(value)/2)) != value { 4229 log.Panic("test fails") 4230 } 4231 </pre> 4232 4233 4234 A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> 4235 of (the type of) <code>x</code> contains <code>m</code> and the 4236 argument list can be assigned to the parameter list of <code>m</code>. 4237 If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method 4238 set contains <code>m</code>, <code>x.m()</code> is shorthand 4239 for <code>(&x).m()</code>: 4240 4241 4242 <pre> 4243 var p Point 4244 p.Scale(3.5) 4245 </pre> 4246 4247 4248 There is no distinct method type and there are no method literals. 4249 4250 4251 <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> 4252 4253 4254 If <code>f</code> is <a href="#Function_types">variadic</a> with a final 4255 parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> 4256 the type of <code>p</code> is equivalent to type <code>[]T</code>. 4257 If <code>f</code> is invoked with no actual arguments for <code>p</code>, 4258 the value passed to <code>p</code> is <code>nil</code>. 4259 Otherwise, the value passed is a new slice 4260 of type <code>[]T</code> with a new underlying array whose successive elements 4261 are the actual arguments, which all must be <a href="#Assignability">assignable</a> 4262 to <code>T</code>. The length and capacity of the slice is therefore 4263 the number of arguments bound to <code>p</code> and may differ for each 4264 call site. 4265 4266 4267 4268 Given the function and calls 4269 4270 <pre> 4271 func Greeting(prefix string, who ...string) 4272 Greeting("nobody") 4273 Greeting("hello:", "Joe", "Anna", "Eileen") 4274 </pre> 4275 4276 4277 within <code>Greeting</code>, <code>who</code> will have the value 4278 <code>nil</code> in the first call, and 4279 <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. 4280 4281 4282 4283 If the final argument is assignable to a slice type <code>[]T</code> and 4284 is followed by <code>...</code>, it is passed unchanged as the value 4285 for a <code>...T</code> parameter. In this case no new slice is created. 4286 4287 4288 4289 Given the slice <code>s</code> and call 4290 4291 4292 <pre> 4293 s := []string{"James", "Jasmine"} 4294 Greeting("goodbye:", s...) 4295 </pre> 4296 4297 4298 within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> 4299 with the same underlying array. 4300 4301 4302 <h3 id="Instantiations">Instantiations</h3> 4303 4304 4305 A generic function or type is instantiated by substituting type arguments 4306 for the type parameters. 4307 Instantiation proceeds in two steps: 4308 4309 4310 <ol> 4311 <li> 4312 Each type argument is substituted for its corresponding type parameter in the generic 4313 declaration. 4314 This substitution happens across the entire function or type declaration, 4315 including the type parameter list itself and any types in that list. 4316 </li> 4317 4318 <li> 4319 After substitution, each type argument must <a href="#Satisfying_a_type_constraint">satisfy</a> 4320 the <a href="#Type_parameter_declarations">constraint</a> (instantiated, if necessary) 4321 of the corresponding type parameter. Otherwise instantiation fails. 4322 </li> 4323 </ol> 4324 4325 4326 Instantiating a type results in a new non-generic <a href="#Types">named type</a>; 4327 instantiating a function produces a new non-generic function. 4328 4329 4330 <pre> 4331 type parameter list type arguments after substitution 4332 4333 [P any] int int satisfies any 4334 [S ~[]E, E any] []int, int []int satisfies ~[]int, int satisfies any 4335 [P io.Writer] string illegal: string doesn't satisfy io.Writer 4336 [P comparable] any any satisfies (but does not implement) comparable 4337 </pre> 4338 4339 4340 For a generic function, type arguments may be provided explicitly, or they 4341 may be partially or completely <a href="#Type_inference">inferred</a>. 4342 A generic function that is not <a href="#Calls">called</a> requires a 4343 type argument list for instantiation; if the list is partial, all 4344 remaining type arguments must be inferrable. 4345 A generic function that is called may provide a (possibly partial) type 4346 argument list, or may omit it entirely if the omitted type arguments are 4347 inferrable from the ordinary (non-type) function arguments. 4348 4349 4350 <pre> 4351 func min[T ~int|~float64](x, y T) T { … } 4352 4353 f := min // illegal: min must be instantiated with type arguments when used without being called 4354 minInt := min[int] // minInt has type func(x, y int) int 4355 a := minInt(2, 3) // a has value 2 of type int 4356 b := min[float64](2.0, 3) // b has value 2.0 of type float64 4357 c := min(b, -1) // c has value -1.0 of type float64 4358 </pre> 4359 4360 4361 A partial type argument list cannot be empty; at least the first argument must be present. 4362 The list is a prefix of the full list of type arguments, leaving the remaining arguments 4363 to be inferred. Loosely speaking, type arguments may be omitted from "right to left". 4364 4365 4366 <pre> 4367 func apply[S ~[]E, E any](s S, f func(E) E) S { … } 4368 4369 f0 := apply[] // illegal: type argument list cannot be empty 4370 f1 := apply[[]int] // type argument for S explicitly provided, type argument for E inferred 4371 f2 := apply[[]string, string] // both type arguments explicitly provided 4372 4373 var bytes []byte 4374 r := apply(bytes, func(byte) byte { … }) // both type arguments inferred from the function arguments 4375 </pre> 4376 4377 4378 For a generic type, all type arguments must always be provided explicitly. 4379 4380 4381 <h3 id="Type_inference">Type inference</h3> 4382 4383 4384 Missing function type arguments may be inferred by a series of steps, described below. 4385 Each step attempts to use known information to infer additional type arguments. 4386 Type inference stops as soon as all type arguments are known. 4387 After type inference is complete, it is still necessary to substitute all type arguments 4388 for type parameters and verify that each type argument 4389 <a href="#Implementing_an_interface">implements</a> the relevant constraint; 4390 it is possible for an inferred type argument to fail to implement a constraint, in which 4391 case instantiation fails. 4392 4393 4394 4395 Type inference is based on 4396 4397 4398 <ul> 4399 <li> 4400 a <a href="#Type_parameter_declarations">type parameter list</a> 4401 </li> 4402 <li> 4403 a substitution map M initialized with the known type arguments, if any 4404 </li> 4405 <li> 4406 a (possibly empty) list of ordinary function arguments (in case of a function call only) 4407 </li> 4408 </ul> 4409 4410 4411 and then proceeds with the following steps: 4412 4413 4414 <ol> 4415 <li> 4416 apply <a href="#Function_argument_type_inference">function argument type inference</a> 4417 to all typed ordinary function arguments 4418 </li> 4419 <li> 4420 apply <a href="#Constraint_type_inference">constraint type inference</a> 4421 </li> 4422 <li> 4423 apply function argument type inference to all untyped ordinary function arguments 4424 using the default type for each of the untyped function arguments 4425 </li> 4426 <li> 4427 apply constraint type inference 4428 </li> 4429 </ol> 4430 4431 4432 If there are no ordinary or untyped function arguments, the respective steps are skipped. 4433 Constraint type inference is skipped if the previous step didn't infer any new type arguments, 4434 but it is run at least once if there are missing type arguments. 4435 4436 4437 4438 The substitution map M is carried through all steps, and each step may add entries to M. 4439 The process stops as soon as M has a type argument for each type parameter or if an inference step fails. 4440 If an inference step fails, or if M is still missing type arguments after the last step, type inference fails. 4441 4442 4443 <h4 id="Type_unification">Type unification</h4> 4444 4445 4446 Type inference is based on type unification. A single unification step 4447 applies to a <a href="#Type_inference">substitution map</a> and two types, either 4448 or both of which may be or contain type parameters. The substitution map tracks 4449 the known (explicitly provided or already inferred) type arguments: the map 4450 contains an entry <code>P</code> &RightArrow; <code>A</code> for each type 4451 parameter <code>P</code> and corresponding known type argument <code>A</code>. 4452 During unification, known type arguments take the place of their corresponding type 4453 parameters when comparing types. Unification is the process of finding substitution 4454 map entries that make the two types equivalent. 4455 4456 4457 4458 For unification, two types that don't contain any type parameters from the current type 4459 parameter list are equivalent 4460 if they are identical, or if they are channel types that are identical ignoring channel 4461 direction, or if their underlying types are equivalent. 4462 4463 4464 4465 Unification works by comparing the structure of pairs of types: their structure 4466 disregarding type parameters must be identical, and types other than type parameters 4467 must be equivalent. 4468 A type parameter in one type may match any complete subtype in the other type; 4469 each successful match causes an entry to be added to the substitution map. 4470 If the structure differs, or types other than type parameters are not equivalent, 4471 unification fails. 4472 4473 4474  4479 4480 4481 For example, if <code>T1</code> and <code>T2</code> are type parameters, 4482 <code>[]map[int]bool</code> can be unified with any of the following: 4483 4484 4485 <pre> 4486 []map[int]bool // types are identical 4487 T1 // adds T1 &RightArrow; []map[int]bool to substitution map 4488 []T1 // adds T1 &RightArrow; map[int]bool to substitution map 4489 []map[T1]T2 // adds T1 &RightArrow; int and T2 &RightArrow; bool to substitution map 4490 </pre> 4491 4492 4493 On the other hand, <code>[]map[int]bool</code> cannot be unified with any of 4494 4495 4496 <pre> 4497 int // int is not a slice 4498 struct{} // a struct is not a slice 4499 []struct{} // a struct is not a map 4500 []map[T1]string // map element types don't match 4501 </pre> 4502 4503 4504 As an exception to this general rule, because a <a href="#Type_definitions">defined type</a> 4505 <code>D</code> and a type literal <code>L</code> are never equivalent, 4506 unification compares the underlying type of <code>D</code> with <code>L</code> instead. 4507 For example, given the defined type 4508 4509 4510 <pre> 4511 type Vector []float64 4512 </pre> 4513 4514 4515 and the type literal <code>[]E</code>, unification compares <code>[]float64</code> with 4516 <code>[]E</code> and adds an entry <code>E</code> &RightArrow; <code>float64</code> to 4517 the substitution map. 4518 4519 4520 <h4 id="Function_argument_type_inference">Function argument type inference</h4> 4521 4522  4525 4526 4527 Function argument type inference infers type arguments from function arguments: 4528 if a function parameter is declared with a type <code>T</code> that uses 4529 type parameters, 4530 <a href="#Type_unification">unifying</a> the type of the corresponding 4531 function argument with <code>T</code> may infer type arguments for the type 4532 parameters used by <code>T</code>. 4533 4534 4535 4536 For instance, given the generic function 4537 4538 4539 <pre> 4540 func scale[Number ~int64|~float64|~complex128](v []Number, s Number) []Number 4541 </pre> 4542 4543 4544 and the call 4545 4546 4547 <pre> 4548 var vector []float64 4549 scaledVector := scale(vector, 42) 4550 </pre> 4551 4552 4553 the type argument for <code>Number</code> can be inferred from the function argument 4554 <code>vector</code> by unifying the type of <code>vector</code> with the corresponding 4555 parameter type: <code>[]float64</code> and <code>[]Number</code> 4556 match in structure and <code>float64</code> matches with <code>Number</code>. 4557 This adds the entry <code>Number</code> &RightArrow; <code>float64</code> to the 4558 <a href="#Type_unification">substitution map</a>. 4559 Untyped arguments, such as the second function argument <code>42</code> here, are ignored 4560 in the first round of function argument type inference and only considered if there are 4561 unresolved type parameters left. 4562 4563 4564 4565 Inference happens in two separate phases; each phase operates on a specific list of 4566 (parameter, argument) pairs: 4567 4568 4569 <ol> 4570 <li> 4571 The list Lt contains all (parameter, argument) pairs where the parameter 4572 type uses type parameters and where the function argument is typed. 4573 </li> 4574 <li> 4575 The list Lu contains all remaining pairs where the parameter type is a single 4576 type parameter. In this list, the respective function arguments are untyped. 4577 </li> 4578 </ol> 4579 4580 4581 Any other (parameter, argument) pair is ignored. 4582 4583 4584 4585 By construction, the arguments of the pairs in Lu are untyped constants 4586 (or the untyped boolean result of a comparison). And because <a href="#Constants">default types</a> 4587 of untyped values are always predeclared non-composite types, they can never match against 4588 a composite type, so it is sufficient to only consider parameter types that are single type 4589 parameters. 4590 4591 4592 4593 Each list is processed in a separate phase: 4594 4595 4596 <ol> 4597 <li> 4598 In the first phase, the parameter and argument types of each pair in Lt 4599 are unified. If unification succeeds for a pair, it may yield new entries that 4600 are added to the substitution map M. If unification fails, type inference 4601 fails. 4602 </li> 4603 <li> 4604 The second phase considers the entries of list Lu. Type parameters for 4605 which the type argument has already been determined are ignored in this phase. 4606 For each remaining pair, the parameter type (which is a single type parameter) and 4607 the <a href="#Constants">default type</a> of the corresponding untyped argument is 4608 unified. If unification fails, type inference fails. 4609 </li> 4610 </ol> 4611 4612 4613 While unification is successful, processing of each list continues until all list elements 4614 are considered, even if all type arguments are inferred before the last list element has 4615 been processed. 4616 4617 4618 4619 Example: 4620 4621 4622 <pre> 4623 func min[T ~int|~float64](x, y T) T 4624 4625 var x int 4626 min(x, 2.0) // T is int, inferred from typed argument x; 2.0 is assignable to int 4627 min(1.0, 2.0) // T is float64, inferred from default type for 1.0 and matches default type for 2.0 4628 min(1.0, 2) // illegal: default type float64 (for 1.0) doesn't match default type int (for 2) 4629 </pre> 4630 4631 4632 In the example <code>min(1.0, 2)</code>, processing the function argument <code>1.0</code> 4633 yields the substitution map entry <code>T</code> &RightArrow; <code>float64</code>. Because 4634 processing continues until all untyped arguments are considered, an error is reported. This 4635 ensures that type inference does not depend on the order of the untyped arguments. 4636 4637 4638 <h4 id="Constraint_type_inference">Constraint type inference</h4> 4639 4640 4641 Constraint type inference infers type arguments by considering type constraints. 4642 If a type parameter <code>P</code> has a constraint with a 4643 <a href="#Core_types">core type</a> <code>C</code>, 4644 <a href="#Type_unification">unifying</a> <code>P</code> with <code>C</code> 4645 may infer additional type arguments, either the type argument for <code>P</code>, 4646 or if that is already known, possibly the type arguments for type parameters 4647 used in <code>C</code>. 4648 4649 4650 4651 For instance, consider the type parameter list with type parameters <code>List</code> and 4652 <code>Elem</code>: 4653 4654 4655 <pre> 4656 [List ~[]Elem, Elem any] 4657 </pre> 4658 4659 4660 Constraint type inference can deduce the type of <code>Elem</code> from the type argument 4661 for <code>List</code> because <code>Elem</code> is a type parameter in the core type 4662 <code>[]Elem</code> of <code>List</code>. 4663 If the type argument is <code>Bytes</code>: 4664 4665 4666 <pre> 4667 type Bytes []byte 4668 </pre> 4669 4670 4671 unifying the underlying type of <code>Bytes</code> with the core type means 4672 unifying <code>[]byte</code> with <code>[]Elem</code>. That unification succeeds and yields 4673 the <a href="#Type_unification">substitution map</a> entry 4674 <code>Elem</code> &RightArrow; <code>byte</code>. 4675 Thus, in this example, constraint type inference can infer the second type argument from the 4676 first one. 4677 4678 4679 4680 Using the core type of a constraint may lose some information: In the (unlikely) case that 4681 the constraint's type set contains a single <a href="#Type_definitions">defined type</a> 4682 <code>N</code>, the corresponding core type is <code>N</code>'s underlying type rather than 4683 <code>N</code> itself. In this case, constraint type inference may succeed but instantiation 4684 will fail because the inferred type is not in the type set of the constraint. 4685 Thus, constraint type inference uses the adjusted core type of 4686 a constraint: if the type set contains a single type, use that type; otherwise use the 4687 constraint's core type. 4688 4689 4690 4691 Generally, constraint type inference proceeds in two phases: Starting with a given 4692 substitution map M 4693 4694 4695 <ol> 4696 <li> 4697 For all type parameters with an adjusted core type, unify the type parameter with that 4698 type. If any unification fails, constraint type inference fails. 4699 </li> 4700 4701 <li> 4702 At this point, some entries in M may map type parameters to other 4703 type parameters or to types containing type parameters. For each entry 4704 <code>P</code> &RightArrow; <code>A</code> in M where <code>A</code> is or 4705 contains type parameters <code>Q</code> for which there exist entries 4706 <code>Q</code> &RightArrow; <code>B</code> in M, substitute those 4707 <code>Q</code> with the respective <code>B</code> in <code>A</code>. 4708 Stop when no further substitution is possible. 4709 </li> 4710 </ol> 4711 4712 4713 The result of constraint type inference is the final substitution map M from type 4714 parameters <code>P</code> to type arguments <code>A</code> where no type parameter <code>P</code> 4715 appears in any of the <code>A</code>. 4716 4717 4718 4719 For instance, given the type parameter list 4720 4721 4722 <pre> 4723 [A any, B []C, C *A] 4724 </pre> 4725 4726 4727 and the single provided type argument <code>int</code> for type parameter <code>A</code>, 4728 the initial substitution map M contains the entry <code>A</code> &RightArrow; <code>int</code>. 4729 4730 4731 4732 In the first phase, the type parameters <code>B</code> and <code>C</code> are unified 4733 with the core type of their respective constraints. This adds the entries 4734 <code>B</code> &RightArrow; <code>[]C</code> and <code>C</code> &RightArrow; <code>*A</code> 4735 to M. 4736 4737 4738 At this point there are two entries in M where the right-hand side 4739 is or contains type parameters for which there exists other entries in M: 4740 <code>[]C</code> and <code>*A</code>. 4741 In the second phase, these type parameters are replaced with their respective 4742 types. It doesn't matter in which order this happens. Starting with the state 4743 of M after the first phase: 4744 4745 4746 4747 <code>A</code> &RightArrow; <code>int</code>, 4748 <code>B</code> &RightArrow; <code>[]C</code>, 4749 <code>C</code> &RightArrow; <code>*A</code> 4750 4751 4752 4753 Replace <code>A</code> on the right-hand side of &RightArrow; with <code>int</code>: 4754 4755 4756 4757 <code>A</code> &RightArrow; <code>int</code>, 4758 <code>B</code> &RightArrow; <code>[]C</code>, 4759 <code>C</code> &RightArrow; <code>*int</code> 4760 4761 4762 4763 Replace <code>C</code> on the right-hand side of &RightArrow; with <code>*int</code>: 4764 4765 4766 4767 <code>A</code> &RightArrow; <code>int</code>, 4768 <code>B</code> &RightArrow; <code>[]*int</code>, 4769 <code>C</code> &RightArrow; <code>*int</code> 4770 4771 4772 4773 At this point no further substitution is possible and the map is full. 4774 Therefore, <code>M</code> represents the final map of type parameters 4775 to type arguments for the given type parameter list. 4776 4777 4778 <h3 id="Operators">Operators</h3> 4779 4780 4781 Operators combine operands into expressions. 4782 4783 4784 <pre class="ebnf"> 4785 Expression = UnaryExpr | Expression binary_op Expression . 4786 UnaryExpr = PrimaryExpr | unary_op UnaryExpr . 4787 4788 binary_op = "||" | "&&" | rel_op | add_op | mul_op . 4789 rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . 4790 add_op = "+" | "-" | "|" | "^" . 4791 mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . 4792 4793 unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . 4794 </pre> 4795 4796 4797 Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. 4798 For other binary operators, the operand types must be <a href="#Type_identity">identical</a> 4799 unless the operation involves shifts or untyped <a href="#Constants">constants</a>. 4800 For operations involving constants only, see the section on 4801 <a href="#Constant_expressions">constant expressions</a>. 4802 4803 4804 4805 Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> 4806 and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a> 4807 to the type of the other operand. 4808 4809 4810 4811 The right operand in a shift expression must have <a href="#Numeric_types">integer type</a> 4812 or be an untyped constant <a href="#Representability">representable</a> by a 4813 value of type <code>uint</code>. 4814 If the left operand of a non-constant shift expression is an untyped constant, 4815 it is first implicitly converted to the type it would assume if the shift expression were 4816 replaced by its left operand alone. 4817 4818 4819 <pre> 4820 var a [1024]byte 4821 var s uint = 33 4822 4823 // The results of the following examples are given for 64-bit ints. 4824 var i = 1<<s // 1 has type int 4825 var j int32 = 1<<s // 1 has type int32; j == 0 4826 var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 4827 var m int = 1.0<<s // 1.0 has type int; m == 1<<33 4828 var n = 1.0<<s == j // 1.0 has type int32; n == true 4829 var o = 1<<s == 2<<s // 1 and 2 have type int; o == false 4830 var p = 1<<s == 1<<33 // 1 has type int; p == true 4831 var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift 4832 var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift 4833 var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift 4834 var v1 float32 = 1<<s // illegal: 1 has type float32, cannot shift 4835 var v2 = string(1<<s) // illegal: 1 is converted to a string, cannot shift 4836 var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression; w == 1<<33 4837 var x = a[1.0<<s] // panics: 1.0 has type int, but 1<<33 overflows array bounds 4838 var b = make([]byte, 1.0<<s) // 1.0 has type int; len(b) == 1<<33 4839 4840 // The results of the following examples are given for 32-bit ints, 4841 // which means the shifts will overflow. 4842 var mm int = 1.0<<s // 1.0 has type int; mm == 0 4843 var oo = 1<<s == 2<<s // 1 and 2 have type int; oo == true 4844 var pp = 1<<s == 1<<33 // illegal: 1 has type int, but 1<<33 overflows int 4845 var xx = a[1.0<<s] // 1.0 has type int; xx == a[0] 4846 var bb = make([]byte, 1.0<<s) // 1.0 has type int; len(bb) == 0 4847 </pre> 4848 4849 <h4 id="Operator_precedence">Operator precedence</h4> 4850 4851 Unary operators have the highest precedence. 4852 As the <code>++</code> and <code>--</code> operators form 4853 statements, not expressions, they fall 4854 outside the operator hierarchy. 4855 As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. 4856 4857 There are five precedence levels for binary operators. 4858 Multiplication operators bind strongest, followed by addition 4859 operators, comparison operators, <code>&&</code> (logical AND), 4860 and finally <code>||</code> (logical OR): 4861 4862 4863 <pre class="grammar"> 4864 Precedence Operator 4865 5 * / % << >> & &^ 4866 4 + - | ^ 4867 3 == != < <= > >= 4868 2 && 4869 1 || 4870 </pre> 4871 4872 4873 Binary operators of the same precedence associate from left to right. 4874 For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. 4875 4876 4877 <pre> 4878 +x 4879 23 + 3*x[i] 4880 x <= f() 4881 ^a >> b 4882 f() || g() 4883 x == y+1 && <-chanInt > 0 4884 </pre> 4885 4886 4887 <h3 id="Arithmetic_operators">Arithmetic operators</h3> 4888 4889 Arithmetic operators apply to numeric values and yield a result of the same 4890 type as the first operand. The four standard arithmetic operators (<code>+</code>, 4891 <code>-</code>, <code>*</code>, <code>/</code>) apply to 4892 <a href="#Numeric_types">integer</a>, <a href="#Numeric_types">floating-point</a>, and 4893 <a href="#Numeric_types">complex</a> types; <code>+</code> also applies to <a href="#String_types">strings</a>. 4894 The bitwise logical and shift operators apply to integers only. 4895 4896 4897 <pre class="grammar"> 4898 + sum integers, floats, complex values, strings 4899 - difference integers, floats, complex values 4900 * product integers, floats, complex values 4901 / quotient integers, floats, complex values 4902 % remainder integers 4903 4904 & bitwise AND integers 4905 | bitwise OR integers 4906 ^ bitwise XOR integers 4907 &^ bit clear (AND NOT) integers 4908 4909 << left shift integer << integer >= 0 4910 >> right shift integer >> integer >= 0 4911 </pre> 4912 4913 4914 If the operand type is a <a href="#Type_parameter_declarations">type parameter</a>, 4915 the operator must apply to each type in that type set. 4916 The operands are represented as values of the type argument that the type parameter 4917 is <a href="#Instantiations">instantiated</a> with, and the operation is computed 4918 with the precision of that type argument. For example, given the function: 4919 4920 4921 <pre> 4922 func dotProduct[F ~float32|~float64](v1, v2 []F) F { 4923 var s F 4924 for i, x := range v1 { 4925 y := v2[i] 4926 s += x * y 4927 } 4928 return s 4929 } 4930 </pre> 4931 4932 4933 the product <code>x * y</code> and the addition <code>s += x * y</code> 4934 are computed with <code>float32</code> or <code>float64</code> precision, 4935 respectively, depending on the type argument for <code>F</code>. 4936 4937 4938 <h4 id="Integer_operators">Integer operators</h4> 4939 4940 4941 For two integer values <code>x</code> and <code>y</code>, the integer quotient 4942 <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following 4943 relationships: 4944 4945 4946 <pre> 4947 x = q*y + r and |r| < |y| 4948 </pre> 4949 4950 4951 with <code>x / y</code> truncated towards zero 4952 (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). 4953 4954 4955 <pre> 4956 x y x / y x % y 4957 5 3 1 2 4958 -5 3 -1 -2 4959 5 -3 -1 2 4960 -5 -3 1 -2 4961 </pre> 4962 4963 4964 The one exception to this rule is that if the dividend <code>x</code> is 4965 the most negative value for the int type of <code>x</code>, the quotient 4966 <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) 4967 due to two's-complement <a href="#Integer_overflow">integer overflow</a>: 4968 4969 4970 <pre> 4971 x, q 4972 int8 -128 4973 int16 -32768 4974 int32 -2147483648 4975 int64 -9223372036854775808 4976 </pre> 4977 4978 4979 If the divisor is a <a href="#Constants">constant</a>, it must not be zero. 4980 If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. 4981 If the dividend is non-negative and the divisor is a constant power of 2, 4982 the division may be replaced by a right shift, and computing the remainder may 4983 be replaced by a bitwise AND operation: 4984 4985 4986 <pre> 4987 x x / 4 x % 4 x >> 2 x & 3 4988 11 2 3 2 3 4989 -11 -2 -3 -3 1 4990 </pre> 4991 4992 4993 The shift operators shift the left operand by the shift count specified by the 4994 right operand, which must be non-negative. If the shift count is negative at run time, 4995 a <a href="#Run_time_panics">run-time panic</a> occurs. 4996 The shift operators implement arithmetic shifts if the left operand is a signed 4997 integer and logical shifts if it is an unsigned integer. 4998 There is no upper limit on the shift count. Shifts behave 4999 as if the left operand is shifted <code>n</code> times by 1 for a shift 5000 count of <code>n</code>. 5001 As a result, <code>x << 1</code> is the same as <code>x*2</code> 5002 and <code>x >> 1</code> is the same as 5003 <code>x/2</code> but truncated towards negative infinity. 5004 5005 5006 5007 For integer operands, the unary operators 5008 <code>+</code>, <code>-</code>, and <code>^</code> are defined as 5009 follows: 5010 5011 5012 <pre class="grammar"> 5013 +x is 0 + x 5014 -x negation is 0 - x 5015 ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x 5016 and m = -1 for signed x 5017 </pre> 5018 5019 5020 <h4 id="Integer_overflow">Integer overflow</h4> 5021 5022 5023 For <a href="#Numeric_types">unsigned integer</a> values, the operations <code>+</code>, 5024 <code>-</code>, <code>*</code>, and <code><<</code> are 5025 computed modulo 2n, where n is the bit width of 5026 the unsigned integer's type. 5027 Loosely speaking, these unsigned integer operations 5028 discard high bits upon overflow, and programs may rely on "wrap around". 5029 5030 5031 5032 For signed integers, the operations <code>+</code>, 5033 <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally 5034 overflow and the resulting value exists and is deterministically defined 5035 by the signed integer representation, the operation, and its operands. 5036 Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>. 5037 A compiler may not optimize code under the assumption that overflow does 5038 not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. 5039 5040 5041 <h4 id="Floating_point_operators">Floating-point operators</h4> 5042 5043 5044 For floating-point and complex numbers, 5045 <code>+x</code> is the same as <code>x</code>, 5046 while <code>-x</code> is the negation of <code>x</code>. 5047 The result of a floating-point or complex division by zero is not specified beyond the 5048 IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> 5049 occurs is implementation-specific. 5050 5051 5052 5053 An implementation may combine multiple floating-point operations into a single 5054 fused operation, possibly across statements, and produce a result that differs 5055 from the value obtained by executing and rounding the instructions individually. 5056 An explicit <a href="#Numeric_types">floating-point type</a> <a href="#Conversions">conversion</a> rounds to 5057 the precision of the target type, preventing fusion that would discard that rounding. 5058 5059 5060 5061 For instance, some architectures provide a "fused multiply and add" (FMA) instruction 5062 that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>. 5063 These examples show when a Go implementation can use that instruction: 5064 5065 5066 <pre> 5067 // FMA allowed for computing r, because x*y is not explicitly rounded: 5068 r = x*y + z 5069 r = z; r += x*y 5070 t = x*y; r = t + z 5071 *p = x*y; r = *p + z 5072 r = x*y + float64(z) 5073 5074 // FMA disallowed for computing r, because it would omit rounding of x*y: 5075 r = float64(x*y) + z 5076 r = z; r += float64(x*y) 5077 t = float64(x*y); r = t + z 5078 </pre> 5079 5080 <h4 id="String_concatenation">String concatenation</h4> 5081 5082 5083 Strings can be concatenated using the <code>+</code> operator 5084 or the <code>+=</code> assignment operator: 5085 5086 5087 <pre> 5088 s := "hi" + string(c) 5089 s += " and good bye" 5090 </pre> 5091 5092 5093 String addition creates a new string by concatenating the operands. 5094 5095 5096 <h3 id="Comparison_operators">Comparison operators</h3> 5097 5098 5099 Comparison operators compare two operands and yield an untyped boolean value. 5100 5101 5102 <pre class="grammar"> 5103 == equal 5104 != not equal 5105 < less 5106 <= less or equal 5107 > greater 5108 >= greater or equal 5109 </pre> 5110 5111 5112 In any comparison, the first operand 5113 must be <a href="#Assignability">assignable</a> 5114 to the type of the second operand, or vice versa. 5115 5116 5117 The equality operators <code>==</code> and <code>!=</code> apply 5118 to operands of comparable types. 5119 The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> 5120 apply to operands of ordered types. 5121 These terms and the result of the comparisons are defined as follows: 5122 5123 5124 <ul> 5125 <li> 5126 Boolean types are comparable. 5127 Two boolean values are equal if they are either both 5128 <code>true</code> or both <code>false</code>. 5129 </li> 5130 5131 <li> 5132 Integer types are comparable and ordered. 5133 Two integer values are compared in the usual way. 5134 </li> 5135 5136 <li> 5137 Floating-point types are comparable and ordered. 5138 Two floating-point values are compared as defined by the IEEE-754 standard. 5139 </li> 5140 5141 <li> 5142 Complex types are comparable. 5143 Two complex values <code>u</code> and <code>v</code> are 5144 equal if both <code>real(u) == real(v)</code> and 5145 <code>imag(u) == imag(v)</code>. 5146 </li> 5147 5148 <li> 5149 String types are comparable and ordered. 5150 Two string values are compared lexically byte-wise. 5151 </li> 5152 5153 <li> 5154 Pointer types are comparable. 5155 Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>. 5156 Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal. 5157 </li> 5158 5159 <li> 5160 Channel types are comparable. 5161 Two channel values are equal if they were created by the same call to 5162 <a href="#Making_slices_maps_and_channels"><code>make</code></a> 5163 or if both have value <code>nil</code>. 5164 </li> 5165 5166 <li> 5167 Interface types that are not type parameters are comparable. 5168 Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types 5169 and equal dynamic values or if both have value <code>nil</code>. 5170 </li> 5171 5172 <li> 5173 A value <code>x</code> of non-interface type <code>X</code> and 5174 a value <code>t</code> of interface type <code>T</code> can be compared 5175 if type <code>X</code> is comparable and 5176 <code>X</code> <a href="#Implementing_an_interface">implements</a> <code>T</code>. 5177 They are equal if <code>t</code>'s dynamic type is identical to <code>X</code> 5178 and <code>t</code>'s dynamic value is equal to <code>x</code>. 5179 </li> 5180 5181 <li> 5182 Struct types are comparable if all their field types are comparable. 5183 Two struct values are equal if their corresponding 5184 non-<a href="#Blank_identifier">blank</a> field values are equal. 5185 The fields are compared in source order, and comparison stops as 5186 soon as two field values differ (or all fields have been compared). 5187 </li> 5188 5189 <li> 5190 Array types are comparable if their array element types are comparable. 5191 Two array values are equal if their corresponding element values are equal. 5192 The elements are compared in ascending index order, and comparison stops 5193 as soon as two element values differ (or all elements have been compared). 5194 </li> 5195 5196 <li> 5197 Type parameters are comparable if they are strictly comparable (see below). 5198 </li> 5199 </ul> 5200 5201 5202 A comparison of two interface values with identical dynamic types 5203 causes a <a href="#Run_time_panics">run-time panic</a> if that type 5204 is not comparable. This behavior applies not only to direct interface 5205 value comparisons but also when comparing arrays of interface values 5206 or structs with interface-valued fields. 5207 5208 5209 5210 Slice, map, and function types are not comparable. 5211 However, as a special case, a slice, map, or function value may 5212 be compared to the predeclared identifier <code>nil</code>. 5213 Comparison of pointer, channel, and interface values to <code>nil</code> 5214 is also allowed and follows from the general rules above. 5215 5216 5217 <pre> 5218 const c = 3 < 4 // c is the untyped boolean constant true 5219 5220 type MyBool bool 5221 var x, y int 5222 var ( 5223 // The result of a comparison is an untyped boolean. 5224 // The usual assignment rules apply. 5225 b3 = x == y // b3 has type bool 5226 b4 bool = x == y // b4 has type bool 5227 b5 MyBool = x == y // b5 has type MyBool 5228 ) 5229 </pre> 5230 5231 5232 A type is strictly comparable if it is comparable and not an interface 5233 type nor composed of interface types. 5234 Specifically: 5235 5236 5237 <ul> 5238 <li> 5239 Boolean, numeric, string, pointer, and channel types are strictly comparable. 5240 </li> 5241 5242 <li> 5243 Struct types are strictly comparable if all their field types are strictly comparable. 5244 </li> 5245 5246 <li> 5247 Array types are strictly comparable if their array element types are strictly comparable. 5248 </li> 5249 5250 <li> 5251 Type parameters are strictly comparable if all types in their type set are strictly comparable. 5252 </li> 5253 </ul> 5254 5255 <h3 id="Logical_operators">Logical operators</h3> 5256 5257 5258 Logical operators apply to <a href="#Boolean_types">boolean</a> values 5259 and yield a result of the same type as the operands. 5260 The right operand is evaluated conditionally. 5261 5262 5263 <pre class="grammar"> 5264 && conditional AND p && q is "if p then q else false" 5265 || conditional OR p || q is "if p then true else q" 5266 ! NOT !p is "not p" 5267 </pre> 5268 5269 5270 <h3 id="Address_operators">Address operators</h3> 5271 5272 5273 For an operand <code>x</code> of type <code>T</code>, the address operation 5274 <code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. 5275 The operand must be addressable, 5276 that is, either a variable, pointer indirection, or slice indexing 5277 operation; or a field selector of an addressable struct operand; 5278 or an array indexing operation of an addressable array. 5279 As an exception to the addressability requirement, <code>x</code> may also be a 5280 (possibly parenthesized) 5281 <a href="#Composite_literals">composite literal</a>. 5282 If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, 5283 then the evaluation of <code>&x</code> does too. 5284 5285 5286 5287 For an operand <code>x</code> of pointer type <code>*T</code>, the pointer 5288 indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed 5289 to by <code>x</code>. 5290 If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> 5291 will cause a <a href="#Run_time_panics">run-time panic</a>. 5292 5293 5294 <pre> 5295 &x 5296 &a[f(2)] 5297 &Point{2, 3} 5298 *p 5299 *pf(x) 5300 5301 var x *int = nil 5302 *x // causes a run-time panic 5303 &*x // causes a run-time panic 5304 </pre> 5305 5306 5307 <h3 id="Receive_operator">Receive operator</h3> 5308 5309 5310 For an operand <code>ch</code> whose <a href="#Core_types">core type</a> is a 5311 <a href="#Channel_types">channel</a>, 5312 the value of the receive operation <code><-ch</code> is the value received 5313 from the channel <code>ch</code>. The channel direction must permit receive operations, 5314 and the type of the receive operation is the element type of the channel. 5315 The expression blocks until a value is available. 5316 Receiving from a <code>nil</code> channel blocks forever. 5317 A receive operation on a <a href="#Close">closed</a> channel can always proceed 5318 immediately, yielding the element type's <a href="#The_zero_value">zero value</a> 5319 after any previously sent values have been received. 5320 5321 5322 <pre> 5323 v1 := <-ch 5324 v2 = <-ch 5325 f(<-ch) 5326 <-strobe // wait until clock pulse and discard received value 5327 </pre> 5328 5329 5330 A receive expression used in an <a href="#Assignment_statements">assignment statement</a> or initialization of the special form 5331 5332 5333 <pre> 5334 x, ok = <-ch 5335 x, ok := <-ch 5336 var x, ok = <-ch 5337 var x, ok T = <-ch 5338 </pre> 5339 5340 5341 yields an additional untyped boolean result reporting whether the 5342 communication succeeded. The value of <code>ok</code> is <code>true</code> 5343 if the value received was delivered by a successful send operation to the 5344 channel, or <code>false</code> if it is a zero value generated because the 5345 channel is closed and empty. 5346 5347 5348 5349 <h3 id="Conversions">Conversions</h3> 5350 5351 5352 A conversion changes the <a href="#Types">type</a> of an expression 5353 to the type specified by the conversion. 5354 A conversion may appear literally in the source, or it may be implied 5355 by the context in which an expression appears. 5356 5357 5358 5359 An explicit conversion is an expression of the form <code>T(x)</code> 5360 where <code>T</code> is a type and <code>x</code> is an expression 5361 that can be converted to type <code>T</code>. 5362 5363 5364 <pre class="ebnf"> 5365 Conversion = Type "(" Expression [ "," ] ")" . 5366 </pre> 5367 5368 5369 If the type starts with the operator <code>*</code> or <code><-</code>, 5370 or if the type starts with the keyword <code>func</code> 5371 and has no result list, it must be parenthesized when 5372 necessary to avoid ambiguity: 5373 5374 5375 <pre> 5376 *Point(p) // same as *(Point(p)) 5377 (*Point)(p) // p is converted to *Point 5378 <-chan int(c) // same as <-(chan int(c)) 5379 (<-chan int)(c) // c is converted to <-chan int 5380 func()(x) // function signature func() x 5381 (func())(x) // x is converted to func() 5382 (func() int)(x) // x is converted to func() int 5383 func() int(x) // x is converted to func() int (unambiguous) 5384 </pre> 5385 5386 5387 A <a href="#Constants">constant</a> value <code>x</code> can be converted to 5388 type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a> 5389 by a value of <code>T</code>. 5390 As a special case, an integer constant <code>x</code> can be explicitly converted to a 5391 <a href="#String_types">string type</a> using the 5392 <a href="#Conversions_to_and_from_a_string_type">same rule</a> 5393 as for non-constant <code>x</code>. 5394 5395 5396 5397 Converting a constant to a type that is not a <a href="#Type_parameter_declarations">type parameter</a> 5398 yields a typed constant. 5399 5400 5401 <pre> 5402 uint(iota) // iota value of type uint 5403 float32(2.718281828) // 2.718281828 of type float32 5404 complex128(1) // 1.0 + 0.0i of type complex128 5405 float32(0.49999999) // 0.5 of type float32 5406 float64(-1e-1000) // 0.0 of type float64 5407 string('x') // "x" of type string 5408 string(0x266c) // "♬" of type string 5409 myString("foo" + "bar") // "foobar" of type myString 5410 string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant 5411 (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type 5412 int(1.2) // illegal: 1.2 cannot be represented as an int 5413 string(65.0) // illegal: 65.0 is not an integer constant 5414 </pre> 5415 5416 5417 Converting a constant to a type parameter yields a non-constant value of that type, 5418 with the value represented as a value of the type argument that the type parameter 5419 is <a href="#Instantiations">instantiated</a> with. 5420 For example, given the function: 5421 5422 5423 <pre> 5424 func f[P ~float32|~float64]() { 5425 … P(1.1) … 5426 } 5427 </pre> 5428 5429 5430 the conversion <code>P(1.1)</code> results in a non-constant value of type <code>P</code> 5431 and the value <code>1.1</code> is represented as a <code>float32</code> or a <code>float64</code> 5432 depending on the type argument for <code>f</code>. 5433 Accordingly, if <code>f</code> is instantiated with a <code>float32</code> type, 5434 the numeric value of the expression <code>P(1.1) + 1.2</code> will be computed 5435 with the same precision as the corresponding non-constant <code>float32</code> 5436 addition. 5437 5438 5439 5440 A non-constant value <code>x</code> can be converted to type <code>T</code> 5441 in any of these cases: 5442 5443 5444 <ul> 5445 <li> 5446 <code>x</code> is <a href="#Assignability">assignable</a> 5447 to <code>T</code>. 5448 </li> 5449 <li> 5450 ignoring struct tags (see below), 5451 <code>x</code>'s type and <code>T</code> are not 5452 <a href="#Type_parameter_declarations">type parameters</a> but have 5453 <a href="#Type_identity">identical</a> <a href="#Types">underlying types</a>. 5454 </li> 5455 <li> 5456 ignoring struct tags (see below), 5457 <code>x</code>'s type and <code>T</code> are pointer types 5458 that are not <a href="#Types">named types</a>, 5459 and their pointer base types are not type parameters but 5460 have identical underlying types. 5461 </li> 5462 <li> 5463 <code>x</code>'s type and <code>T</code> are both integer or floating 5464 point types. 5465 </li> 5466 <li> 5467 <code>x</code>'s type and <code>T</code> are both complex types. 5468 </li> 5469 <li> 5470 <code>x</code> is an integer or a slice of bytes or runes 5471 and <code>T</code> is a string type. 5472 </li> 5473 <li> 5474 <code>x</code> is a string and <code>T</code> is a slice of bytes or runes. 5475 </li> 5476 <li> 5477 <code>x</code> is a slice, <code>T</code> is an array or a pointer to an array, 5478 and the slice and array types have <a href="#Type_identity">identical</a> element types. 5479 </li> 5480 </ul> 5481 5482 5483 Additionally, if <code>T</code> or <code>x</code>'s type <code>V</code> are type 5484 parameters, <code>x</code> 5485 can also be converted to type <code>T</code> if one of the following conditions applies: 5486 5487 5488 <ul> 5489 <li> 5490 Both <code>V</code> and <code>T</code> are type parameters and a value of each 5491 type in <code>V</code>'s type set can be converted to each type in <code>T</code>'s 5492 type set. 5493 </li> 5494 <li> 5495 Only <code>V</code> is a type parameter and a value of each 5496 type in <code>V</code>'s type set can be converted to <code>T</code>. 5497 </li> 5498 <li> 5499 Only <code>T</code> is a type parameter and <code>x</code> can be converted to each 5500 type in <code>T</code>'s type set. 5501 </li> 5502 </ul> 5503 5504 5505 <a href="#Struct_types">Struct tags</a> are ignored when comparing struct types 5506 for identity for the purpose of conversion: 5507 5508 5509 <pre> 5510 type Person struct { 5511 Name string 5512 Address *struct { 5513 Street string 5514 City string 5515 } 5516 } 5517 5518 var data *struct { 5519 Name string `json:"name"` 5520 Address *struct { 5521 Street string `json:"street"` 5522 City string `json:"city"` 5523 } `json:"address"` 5524 } 5525 5526 var person = (*Person)(data) // ignoring tags, the underlying types are identical 5527 </pre> 5528 5529 5530 Specific rules apply to (non-constant) conversions between numeric types or 5531 to and from a string type. 5532 These conversions may change the representation of <code>x</code> 5533 and incur a run-time cost. 5534 All other conversions only change the type but not the representation 5535 of <code>x</code>. 5536 5537 5538 5539 There is no linguistic mechanism to convert between pointers and integers. 5540 The package <a href="#Package_unsafe"><code>unsafe</code></a> 5541 implements this functionality under restricted circumstances. 5542 5543 5544 <h4>Conversions between numeric types</h4> 5545 5546 5547 For the conversion of non-constant numeric values, the following rules apply: 5548 5549 5550 <ol> 5551 <li> 5552 When converting between <a href="#Numeric_types">integer types</a>, if the value is a signed integer, it is 5553 sign extended to implicit infinite precision; otherwise it is zero extended. 5554 It is then truncated to fit in the result type's size. 5555 For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>. 5556 The conversion always yields a valid value; there is no indication of overflow. 5557 </li> 5558 <li> 5559 When converting a <a href="#Numeric_types">floating-point number</a> to an integer, the fraction is discarded 5560 (truncation towards zero). 5561 </li> 5562 <li> 5563 When converting an integer or floating-point number to a floating-point type, 5564 or a <a href="#Numeric_types">complex number</a> to another complex type, the result value is rounded 5565 to the precision specified by the destination type. 5566 For instance, the value of a variable <code>x</code> of type <code>float32</code> 5567 may be stored using additional precision beyond that of an IEEE-754 32-bit number, 5568 but float32(x) represents the result of rounding <code>x</code>'s value to 5569 32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits 5570 of precision, but <code>float32(x + 0.1)</code> does not. 5571 </li> 5572 </ol> 5573 5574 5575 In all non-constant conversions involving floating-point or complex values, 5576 if the result type cannot represent the value the conversion 5577 succeeds but the result value is implementation-dependent. 5578 5579 5580 <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4> 5581 5582 <ol> 5583 <li> 5584 Converting a signed or unsigned integer value to a string type yields a 5585 string containing the UTF-8 representation of the integer. Values outside 5586 the range of valid Unicode code points are converted to <code>"\uFFFD"</code>. 5587 5588 <pre> 5589 string('a') // "a" 5590 string(-1) // "\ufffd" == "\xef\xbf\xbd" 5591 string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" 5592 5593 type myString string 5594 myString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" 5595 </pre> 5596 </li> 5597 5598 <li> 5599 Converting a slice of bytes to a string type yields 5600 a string whose successive bytes are the elements of the slice. 5601 5602 <pre> 5603 string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" 5604 string([]byte{}) // "" 5605 string([]byte(nil)) // "" 5606 5607 type bytes []byte 5608 string(bytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" 5609 5610 type myByte byte 5611 string([]myByte{'w', 'o', 'r', 'l', 'd', '!'}) // "world!" 5612 myString([]myByte{'\xf0', '\x9f', '\x8c', '\x8d'}) // "🌍" 5613 </pre> 5614 </li> 5615 5616 <li> 5617 Converting a slice of runes to a string type yields 5618 a string that is the concatenation of the individual rune values 5619 converted to strings. 5620 5621 <pre> 5622 string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" 5623 string([]rune{}) // "" 5624 string([]rune(nil)) // "" 5625 5626 type runes []rune 5627 string(runes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" 5628 5629 type myRune rune 5630 string([]myRune{0x266b, 0x266c}) // "\u266b\u266c" == "♫♬" 5631 myString([]myRune{0x1f30e}) // "\U0001f30e" == "🌎" 5632 </pre> 5633 </li> 5634 5635 <li> 5636 Converting a value of a string type to a slice of bytes type 5637 yields a slice whose successive elements are the bytes of the string. 5638 5639 <pre> 5640 []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} 5641 []byte("") // []byte{} 5642 5643 bytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} 5644 5645 []myByte("world!") // []myByte{'w', 'o', 'r', 'l', 'd', '!'} 5646 []myByte(myString("🌏")) // []myByte{'\xf0', '\x9f', '\x8c', '\x8f'} 5647 </pre> 5648 </li> 5649 5650 <li> 5651 Converting a value of a string type to a slice of runes type 5652 yields a slice containing the individual Unicode code points of the string. 5653 5654 <pre> 5655 []rune(myString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4} 5656 []rune("") // []rune{} 5657 5658 runes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4} 5659 5660 []myRune("♫♬") // []myRune{0x266b, 0x266c} 5661 []myRune(myString("🌐")) // []myRune{0x1f310} 5662 </pre> 5663 </li> 5664 </ol> 5665 5666 <h4 id="Conversions_from_slice_to_array_or_array_pointer">Conversions from slice to array or array pointer</h4> 5667 5668 5669 Converting a slice to an array yields an array containing the elements of the underlying array of the slice. 5670 Similarly, converting a slice to an array pointer yields a pointer to the underlying array of the slice. 5671 In both cases, if the <a href="#Length_and_capacity">length</a> of the slice is less than the length of the array, 5672 a <a href="#Run_time_panics">run-time panic</a> occurs. 5673 5674 5675 <pre> 5676 s := make([]byte, 2, 4) 5677 5678 a0 := [0]byte(s) 5679 a1 := [1]byte(s[1:]) // a1[0] == s[1] 5680 a2 := [2]byte(s) // a2[0] == s[0] 5681 a4 := [4]byte(s) // panics: len([4]byte) > len(s) 5682 5683 s0 := (*[0]byte)(s) // s0 != nil 5684 s1 := (*[1]byte)(s[1:]) // &s1[0] == &s[1] 5685 s2 := (*[2]byte)(s) // &s2[0] == &s[0] 5686 s4 := (*[4]byte)(s) // panics: len([4]byte) > len(s) 5687 5688 var t []string 5689 t0 := [0]string(t) // ok for nil slice t 5690 t1 := (*[0]string)(t) // t1 == nil 5691 t2 := (*[1]string)(t) // panics: len([1]string) > len(t) 5692 5693 u := make([]byte, 0) 5694 u0 := (*[0]byte)(u) // u0 != nil 5695 </pre> 5696 5697 <h3 id="Constant_expressions">Constant expressions</h3> 5698 5699 5700 Constant expressions may contain only <a href="#Constants">constant</a> 5701 operands and are evaluated at compile time. 5702 5703 5704 5705 Untyped boolean, numeric, and string constants may be used as operands 5706 wherever it is legal to use an operand of boolean, numeric, or string type, 5707 respectively. 5708 5709 5710 5711 A constant <a href="#Comparison_operators">comparison</a> always yields 5712 an untyped boolean constant. If the left operand of a constant 5713 <a href="#Operators">shift expression</a> is an untyped constant, the 5714 result is an integer constant; otherwise it is a constant of the same 5715 type as the left operand, which must be of 5716 <a href="#Numeric_types">integer type</a>. 5717 5718 5719 5720 Any other operation on untyped constants results in an untyped constant of the 5721 same kind; that is, a boolean, integer, floating-point, complex, or string 5722 constant. 5723 If the untyped operands of a binary operation (other than a shift) are of 5724 different kinds, the result is of the operand's kind that appears later in this 5725 list: integer, rune, floating-point, complex. 5726 For example, an untyped integer constant divided by an 5727 untyped complex constant yields an untyped complex constant. 5728 5729 5730 <pre> 5731 const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant) 5732 const b = 15 / 4 // b == 3 (untyped integer constant) 5733 const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant) 5734 const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division) 5735 const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division) 5736 const d = 1 << 3.0 // d == 8 (untyped integer constant) 5737 const e = 1.0 << 3 // e == 8 (untyped integer constant) 5738 const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32) 5739 const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) 5740 const h = "foo" > "bar" // h == true (untyped boolean constant) 5741 const j = true // j == true (untyped boolean constant) 5742 const k = 'w' + 1 // k == 'x' (untyped rune constant) 5743 const l = "hi" // l == "hi" (untyped string constant) 5744 const m = string(k) // m == "x" (type string) 5745 const Σ = 1 - 0.707i // (untyped complex constant) 5746 const Δ = Σ + 2.0e-4 // (untyped complex constant) 5747 const Φ = iota*1i - 1/1i // (untyped complex constant) 5748 </pre> 5749 5750 5751 Applying the built-in function <code>complex</code> to untyped 5752 integer, rune, or floating-point constants yields 5753 an untyped complex constant. 5754 5755 5756 <pre> 5757 const ic = complex(0, c) // ic == 3.75i (untyped complex constant) 5758 const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) 5759 </pre> 5760 5761 5762 Constant expressions are always evaluated exactly; intermediate values and the 5763 constants themselves may require precision significantly larger than supported 5764 by any predeclared type in the language. The following are legal declarations: 5765 5766 5767 <pre> 5768 const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant) 5769 const Four int8 = Huge >> 98 // Four == 4 (type int8) 5770 </pre> 5771 5772 5773 The divisor of a constant division or remainder operation must not be zero: 5774 5775 5776 <pre> 5777 3.14 / 0.0 // illegal: division by zero 5778 </pre> 5779 5780 5781 The values of typed constants must always be accurately 5782 <a href="#Representability">representable</a> by values 5783 of the constant type. The following constant expressions are illegal: 5784 5785 5786 <pre> 5787 uint(-1) // -1 cannot be represented as a uint 5788 int(3.14) // 3.14 cannot be represented as an int 5789 int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64 5790 Four * 300 // operand 300 cannot be represented as an int8 (type of Four) 5791 Four * 100 // product 400 cannot be represented as an int8 (type of Four) 5792 </pre> 5793 5794 5795 The mask used by the unary bitwise complement operator <code>^</code> matches 5796 the rule for non-constants: the mask is all 1s for unsigned constants 5797 and -1 for signed and untyped constants. 5798 5799 5800 <pre> 5801 ^1 // untyped integer constant, equal to -2 5802 uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8 5803 ^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) 5804 int8(^1) // same as int8(-2) 5805 ^int8(1) // same as -1 ^ int8(1) = -2 5806 </pre> 5807 5808 5809 Implementation restriction: A compiler may use rounding while 5810 computing untyped floating-point or complex constant expressions; see 5811 the implementation restriction in the section 5812 on <a href="#Constants">constants</a>. This rounding may cause a 5813 floating-point constant expression to be invalid in an integer 5814 context, even if it would be integral when calculated using infinite 5815 precision, and vice versa. 5816 5817 5818 5819 <h3 id="Order_of_evaluation">Order of evaluation</h3> 5820 5821 5822 At package level, <a href="#Package_initialization">initialization dependencies</a> 5823 determine the evaluation order of individual initialization expressions in 5824 <a href="#Variable_declarations">variable declarations</a>. 5825 Otherwise, when evaluating the <a href="#Operands">operands</a> of an 5826 expression, assignment, or 5827 <a href="#Return_statements">return statement</a>, 5828 all function calls, method calls, and 5829 communication operations are evaluated in lexical left-to-right 5830 order. 5831 5832 5833 5834 For example, in the (function-local) assignment 5835 5836 <pre> 5837 y[f()], ok = g(h(), i()+x[j()], <-c), k() 5838 </pre> 5839 5840 the function calls and communication happen in the order 5841 <code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, 5842 <code><-c</code>, <code>g()</code>, and <code>k()</code>. 5843 However, the order of those events compared to the evaluation 5844 and indexing of <code>x</code> and the evaluation 5845 of <code>y</code> is not specified. 5846 5847 5848 <pre> 5849 a := 1 5850 f := func() int { a++; return a } 5851 x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified 5852 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 5853 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 5854 </pre> 5855 5856 5857 At package level, initialization dependencies override the left-to-right rule 5858 for individual initialization expressions, but not for operands within each 5859 expression: 5860 5861 5862 <pre> 5863 var a, b, c = f() + v(), g(), sqr(u()) + v() 5864 5865 func f() int { return c } 5866 func g() int { return a } 5867 func sqr(x int) int { return x*x } 5868 5869 // functions u and v are independent of all other variables and functions 5870 </pre> 5871 5872 5873 The function calls happen in the order 5874 <code>u()</code>, <code>sqr()</code>, <code>v()</code>, 5875 <code>f()</code>, <code>v()</code>, and <code>g()</code>. 5876 5877 5878 5879 Floating-point operations within a single expression are evaluated according to 5880 the associativity of the operators. Explicit parentheses affect the evaluation 5881 by overriding the default associativity. 5882 In the expression <code>x + (y + z)</code> the addition <code>y + z</code> 5883 is performed before adding <code>x</code>. 5884 5885 5886 <h2 id="Statements">Statements</h2> 5887 5888 5889 Statements control execution. 5890 5891 5892 <pre class="ebnf"> 5893 Statement = 5894 Declaration | LabeledStmt | SimpleStmt | 5895 GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | 5896 FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | 5897 DeferStmt . 5898 5899 SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . 5900 </pre> 5901 5902 <h3 id="Terminating_statements">Terminating statements</h3> 5903 5904 5905 A terminating statement interrupts the regular flow of control in 5906 a <a href="#Blocks">block</a>. The following statements are terminating: 5907 5908 5909 <ol> 5910 <li> 5911 A <a href="#Return_statements">"return"</a> or 5912 <a href="#Goto_statements">"goto"</a> statement. 5913  5914 <ul> </ul> 5915 </li> 5916 5917 <li> 5918 A call to the built-in function 5919 <a href="#Handling_panics"><code>panic</code></a>. 5920  5921 <ul> </ul> 5922 </li> 5923 5924 <li> 5925 A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement. 5926  5927 <ul> </ul> 5928 </li> 5929 5930 <li> 5931 An <a href="#If_statements">"if" statement</a> in which: 5932 <ul> 5933 <li>the "else" branch is present, and</li> 5934 <li>both branches are terminating statements.</li> 5935 </ul> 5936 </li> 5937 5938 <li> 5939 A <a href="#For_statements">"for" statement</a> in which: 5940 <ul> 5941 <li>there are no "break" statements referring to the "for" statement, and</li> 5942 <li>the loop condition is absent, and</li> 5943 <li>the "for" statement does not use a range clause.</li> 5944 </ul> 5945 </li> 5946 5947 <li> 5948 A <a href="#Switch_statements">"switch" statement</a> in which: 5949 <ul> 5950 <li>there are no "break" statements referring to the "switch" statement,</li> 5951 <li>there is a default case, and</li> 5952 <li>the statement lists in each case, including the default, end in a terminating 5953 statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough" 5954 statement</a>.</li> 5955 </ul> 5956 </li> 5957 5958 <li> 5959 A <a href="#Select_statements">"select" statement</a> in which: 5960 <ul> 5961 <li>there are no "break" statements referring to the "select" statement, and</li> 5962 <li>the statement lists in each case, including the default if present, 5963 end in a terminating statement.</li> 5964 </ul> 5965 </li> 5966 5967 <li> 5968 A <a href="#Labeled_statements">labeled statement</a> labeling 5969 a terminating statement. 5970 </li> 5971 </ol> 5972 5973 5974 All other statements are not terminating. 5975 5976 5977 5978 A <a href="#Blocks">statement list</a> ends in a terminating statement if the list 5979 is not empty and its final non-empty statement is terminating. 5980 5981 5982 5983 <h3 id="Empty_statements">Empty statements</h3> 5984 5985 5986 The empty statement does nothing. 5987 5988 5989 <pre class="ebnf"> 5990 EmptyStmt = . 5991 </pre> 5992 5993 5994 <h3 id="Labeled_statements">Labeled statements</h3> 5995 5996 5997 A labeled statement may be the target of a <code>goto</code>, 5998 <code>break</code> or <code>continue</code> statement. 5999 6000 6001 <pre class="ebnf"> 6002 LabeledStmt = Label ":" Statement . 6003 Label = identifier . 6004 </pre> 6005 6006 <pre> 6007 Error: log.Panic("error encountered") 6008 </pre> 6009 6010 6011 <h3 id="Expression_statements">Expression statements</h3> 6012 6013 6014 With the exception of specific built-in functions, 6015 function and method <a href="#Calls">calls</a> and 6016 <a href="#Receive_operator">receive operations</a> 6017 can appear in statement context. Such statements may be parenthesized. 6018 6019 6020 <pre class="ebnf"> 6021 ExpressionStmt = Expression . 6022 </pre> 6023 6024 6025 The following built-in functions are not permitted in statement context: 6026 6027 6028 <pre> 6029 append cap complex imag len make new real 6030 unsafe.Add unsafe.Alignof unsafe.Offsetof unsafe.Sizeof unsafe.Slice 6031 </pre> 6032 6033 <pre> 6034 h(x+y) 6035 f.Close() 6036 <-ch 6037 (<-ch) 6038 len("foo") // illegal if len is the built-in function 6039 </pre> 6040 6041 6042 <h3 id="Send_statements">Send statements</h3> 6043 6044 6045 A send statement sends a value on a channel. 6046 The channel expression's <a href="#Core_types">core type</a> 6047 must be a <a href="#Channel_types">channel</a>, 6048 the channel direction must permit send operations, 6049 and the type of the value to be sent must be <a href="#Assignability">assignable</a> 6050 to the channel's element type. 6051 6052 6053 <pre class="ebnf"> 6054 SendStmt = Channel "<-" Expression . 6055 Channel = Expression . 6056 </pre> 6057 6058 6059 Both the channel and the value expression are evaluated before communication 6060 begins. Communication blocks until the send can proceed. 6061 A send on an unbuffered channel can proceed if a receiver is ready. 6062 A send on a buffered channel can proceed if there is room in the buffer. 6063 A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>. 6064 A send on a <code>nil</code> channel blocks forever. 6065 6066 6067 <pre> 6068 ch <- 3 // send value 3 to channel ch 6069 </pre> 6070 6071 6072 <h3 id="IncDec_statements">IncDec statements</h3> 6073 6074 6075 The "++" and "--" statements increment or decrement their operands 6076 by the untyped <a href="#Constants">constant</a> <code>1</code>. 6077 As with an assignment, the operand must be <a href="#Address_operators">addressable</a> 6078 or a map index expression. 6079 6080 6081 <pre class="ebnf"> 6082 IncDecStmt = Expression ( "++" | "--" ) . 6083 </pre> 6084 6085 6086 The following <a href="#Assignment_statements">assignment statements</a> are semantically 6087 equivalent: 6088 6089 6090 <pre class="grammar"> 6091 IncDec statement Assignment 6092 x++ x += 1 6093 x-- x -= 1 6094 </pre> 6095 6096 6097 <h3 id="Assignment_statements">Assignment statements</h3> 6098 6099 6100 An assignment replaces the current value stored in a <a href="#Variables">variable</a> 6101 with a new value specified by an <a href="#Expressions">expression</a>. 6102 An assignment statement may assign a single value to a single variable, or multiple values to a 6103 matching number of variables. 6104 6105 6106 <pre class="ebnf"> 6107 Assignment = ExpressionList assign_op ExpressionList . 6108 6109 assign_op = [ add_op | mul_op ] "=" . 6110 </pre> 6111 6112 6113 Each left-hand side operand must be <a href="#Address_operators">addressable</a>, 6114 a map index expression, or (for <code>=</code> assignments only) the 6115 <a href="#Blank_identifier">blank identifier</a>. 6116 Operands may be parenthesized. 6117 6118 6119 <pre> 6120 x = 1 6121 *p = f() 6122 a[i] = 23 6123 (k) = <-ch // same as: k = <-ch 6124 </pre> 6125 6126 6127 An assignment operation <code>x</code> op<code>=</code> 6128 <code>y</code> where op is a binary <a href="#Arithmetic_operators">arithmetic operator</a> 6129 is equivalent to <code>x</code> <code>=</code> <code>x</code> op 6130 <code>(y)</code> but evaluates <code>x</code> 6131 only once. The op<code>=</code> construct is a single token. 6132 In assignment operations, both the left- and right-hand expression lists 6133 must contain exactly one single-valued expression, and the left-hand 6134 expression must not be the blank identifier. 6135 6136 6137 <pre> 6138 a[i] <<= 2 6139 i &^= 1<<n 6140 </pre> 6141 6142 6143 A tuple assignment assigns the individual elements of a multi-valued 6144 operation to a list of variables. There are two forms. In the 6145 first, the right hand operand is a single multi-valued expression 6146 such as a function call, a <a href="#Channel_types">channel</a> or 6147 <a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. 6148 The number of operands on the left 6149 hand side must match the number of values. For instance, if 6150 <code>f</code> is a function returning two values, 6151 6152 6153 <pre> 6154 x, y = f() 6155 </pre> 6156 6157 6158 assigns the first value to <code>x</code> and the second to <code>y</code>. 6159 In the second form, the number of operands on the left must equal the number 6160 of expressions on the right, each of which must be single-valued, and the 6161 nth expression on the right is assigned to the nth 6162 operand on the left: 6163 6164 6165 <pre> 6166 one, two, three = '一', '二', '三' 6167 </pre> 6168 6169 6170 The <a href="#Blank_identifier">blank identifier</a> provides a way to 6171 ignore right-hand side values in an assignment: 6172 6173 6174 <pre> 6175 _ = x // evaluate x but ignore it 6176 x, _ = f() // evaluate f() but ignore second result value 6177 </pre> 6178 6179 6180 The assignment proceeds in two phases. 6181 First, the operands of <a href="#Index_expressions">index expressions</a> 6182 and <a href="#Address_operators">pointer indirections</a> 6183 (including implicit pointer indirections in <a href="#Selectors">selectors</a>) 6184 on the left and the expressions on the right are all 6185 <a href="#Order_of_evaluation">evaluated in the usual order</a>. 6186 Second, the assignments are carried out in left-to-right order. 6187 6188 6189 <pre> 6190 a, b = b, a // exchange a and b 6191 6192 x := []int{1, 2, 3} 6193 i := 0 6194 i, x[i] = 1, 2 // set i = 1, x[0] = 2 6195 6196 i = 0 6197 x[i], i = 2, 1 // set x[0] = 2, i = 1 6198 6199 x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end) 6200 6201 x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5. 6202 6203 type Point struct { x, y int } 6204 var p *Point 6205 x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7 6206 6207 i = 2 6208 x = []int{3, 5, 7} 6209 for i, x[i] = range x { // set i, x[2] = 0, x[0] 6210 break 6211 } 6212 // after this loop, i == 0 and x == []int{3, 5, 3} 6213 </pre> 6214 6215 6216 In assignments, each value must be <a href="#Assignability">assignable</a> 6217 to the type of the operand to which it is assigned, with the following special cases: 6218 6219 6220 <ol> 6221 <li> 6222 Any typed value may be assigned to the blank identifier. 6223 </li> 6224 6225 <li> 6226 If an untyped constant 6227 is assigned to a variable of interface type or the blank identifier, 6228 the constant is first implicitly <a href="#Conversions">converted</a> to its 6229 <a href="#Constants">default type</a>. 6230 </li> 6231 6232 <li> 6233 If an untyped boolean value is assigned to a variable of interface type or 6234 the blank identifier, it is first implicitly converted to type <code>bool</code>. 6235 </li> 6236 </ol> 6237 6238 <h3 id="If_statements">If statements</h3> 6239 6240 6241 "If" statements specify the conditional execution of two branches 6242 according to the value of a boolean expression. If the expression 6243 evaluates to true, the "if" branch is executed, otherwise, if 6244 present, the "else" branch is executed. 6245 6246 6247 <pre class="ebnf"> 6248 IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] . 6249 </pre> 6250 6251 <pre> 6252 if x > max { 6253 x = max 6254 } 6255 </pre> 6256 6257 6258 The expression may be preceded by a simple statement, which 6259 executes before the expression is evaluated. 6260 6261 6262 <pre> 6263 if x := f(); x < y { 6264 return x 6265 } else if x > z { 6266 return z 6267 } else { 6268 return y 6269 } 6270 </pre> 6271 6272 6273 <h3 id="Switch_statements">Switch statements</h3> 6274 6275 6276 "Switch" statements provide multi-way execution. 6277 An expression or type is compared to the "cases" 6278 inside the "switch" to determine which branch 6279 to execute. 6280 6281 6282 <pre class="ebnf"> 6283 SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . 6284 </pre> 6285 6286 6287 There are two forms: expression switches and type switches. 6288 In an expression switch, the cases contain expressions that are compared 6289 against the value of the switch expression. 6290 In a type switch, the cases contain types that are compared against the 6291 type of a specially annotated switch expression. 6292 The switch expression is evaluated exactly once in a switch statement. 6293 6294 6295 <h4 id="Expression_switches">Expression switches</h4> 6296 6297 6298 In an expression switch, 6299 the switch expression is evaluated and 6300 the case expressions, which need not be constants, 6301 are evaluated left-to-right and top-to-bottom; the first one that equals the 6302 switch expression 6303 triggers execution of the statements of the associated case; 6304 the other cases are skipped. 6305 If no case matches and there is a "default" case, 6306 its statements are executed. 6307 There can be at most one default case and it may appear anywhere in the 6308 "switch" statement. 6309 A missing switch expression is equivalent to the boolean value 6310 <code>true</code>. 6311 6312 6313 <pre class="ebnf"> 6314 ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . 6315 ExprCaseClause = ExprSwitchCase ":" StatementList . 6316 ExprSwitchCase = "case" ExpressionList | "default" . 6317 </pre> 6318 6319 6320 If the switch expression evaluates to an untyped constant, it is first implicitly 6321 <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>. 6322 The predeclared untyped value <code>nil</code> cannot be used as a switch expression. 6323 The switch expression type must be <a href="#Comparison_operators">comparable</a>. 6324 6325 6326 6327 If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a> 6328 to the type of the switch expression. 6329 For each (possibly converted) case expression <code>x</code> and the value <code>t</code> 6330 of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>. 6331 6332 6333 6334 In other words, the switch expression is treated as if it were used to declare and 6335 initialize a temporary variable <code>t</code> without explicit type; it is that 6336 value of <code>t</code> against which each case expression <code>x</code> is tested 6337 for equality. 6338 6339 6340 6341 In a case or default clause, the last non-empty statement 6342 may be a (possibly <a href="#Labeled_statements">labeled</a>) 6343 <a href="#Fallthrough_statements">"fallthrough" statement</a> to 6344 indicate that control should flow from the end of this clause to 6345 the first statement of the next clause. 6346 Otherwise control flows to the end of the "switch" statement. 6347 A "fallthrough" statement may appear as the last statement of all 6348 but the last clause of an expression switch. 6349 6350 6351 6352 The switch expression may be preceded by a simple statement, which 6353 executes before the expression is evaluated. 6354 6355 6356 <pre> 6357 switch tag { 6358 default: s3() 6359 case 0, 1, 2, 3: s1() 6360 case 4, 5, 6, 7: s2() 6361 } 6362 6363 switch x := f(); { // missing switch expression means "true" 6364 case x < 0: return -x 6365 default: return x 6366 } 6367 6368 switch { 6369 case x < y: f1() 6370 case x < z: f2() 6371 case x == 4: f3() 6372 } 6373 </pre> 6374 6375 6376 Implementation restriction: A compiler may disallow multiple case 6377 expressions evaluating to the same constant. 6378 For instance, the current compilers disallow duplicate integer, 6379 floating point, or string constants in case expressions. 6380 6381 6382 <h4 id="Type_switches">Type switches</h4> 6383 6384 6385 A type switch compares types rather than values. It is otherwise similar 6386 to an expression switch. It is marked by a special switch expression that 6387 has the form of a <a href="#Type_assertions">type assertion</a> 6388 using the keyword <code>type</code> rather than an actual type: 6389 6390 6391 <pre> 6392 switch x.(type) { 6393 // cases 6394 } 6395 </pre> 6396 6397 6398 Cases then match actual types <code>T</code> against the dynamic type of the 6399 expression <code>x</code>. As with type assertions, <code>x</code> must be of 6400 <a href="#Interface_types">interface type</a>, but not a 6401 <a href="#Type_parameter_declarations">type parameter</a>, and each non-interface type 6402 <code>T</code> listed in a case must implement the type of <code>x</code>. 6403 The types listed in the cases of a type switch must all be 6404 <a href="#Type_identity">different</a>. 6405 6406 6407 <pre class="ebnf"> 6408 TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . 6409 TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . 6410 TypeCaseClause = TypeSwitchCase ":" StatementList . 6411 TypeSwitchCase = "case" TypeList | "default" . 6412 </pre> 6413 6414 6415 The TypeSwitchGuard may include a 6416 <a href="#Short_variable_declarations">short variable declaration</a>. 6417 When that form is used, the variable is declared at the end of the 6418 TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause. 6419 In clauses with a case listing exactly one type, the variable 6420 has that type; otherwise, the variable has the type of the expression 6421 in the TypeSwitchGuard. 6422 6423 6424 6425 Instead of a type, a case may use the predeclared identifier 6426 <a href="#Predeclared_identifiers"><code>nil</code></a>; 6427 that case is selected when the expression in the TypeSwitchGuard 6428 is a <code>nil</code> interface value. 6429 There may be at most one <code>nil</code> case. 6430 6431 6432 6433 Given an expression <code>x</code> of type <code>interface{}</code>, 6434 the following type switch: 6435 6436 6437 <pre> 6438 switch i := x.(type) { 6439 case nil: 6440 printString("x is nil") // type of i is type of x (interface{}) 6441 case int: 6442 printInt(i) // type of i is int 6443 case float64: 6444 printFloat64(i) // type of i is float64 6445 case func(int) float64: 6446 printFunction(i) // type of i is func(int) float64 6447 case bool, string: 6448 printString("type is bool or string") // type of i is type of x (interface{}) 6449 default: 6450 printString("don't know the type") // type of i is type of x (interface{}) 6451 } 6452 </pre> 6453 6454 6455 could be rewritten: 6456 6457 6458 <pre> 6459 v := x // x is evaluated exactly once 6460 if v == nil { 6461 i := v // type of i is type of x (interface{}) 6462 printString("x is nil") 6463 } else if i, isInt := v.(int); isInt { 6464 printInt(i) // type of i is int 6465 } else if i, isFloat64 := v.(float64); isFloat64 { 6466 printFloat64(i) // type of i is float64 6467 } else if i, isFunc := v.(func(int) float64); isFunc { 6468 printFunction(i) // type of i is func(int) float64 6469 } else { 6470 _, isBool := v.(bool) 6471 _, isString := v.(string) 6472 if isBool || isString { 6473 i := v // type of i is type of x (interface{}) 6474 printString("type is bool or string") 6475 } else { 6476 i := v // type of i is type of x (interface{}) 6477 printString("don't know the type") 6478 } 6479 } 6480 </pre> 6481 6482 6483 A <a href="#Type_parameter_declarations">type parameter</a> or a <a href="#Type_declarations">generic type</a> 6484 may be used as a type in a case. If upon <a href="#Instantiations">instantiation</a> that type turns 6485 out to duplicate another entry in the switch, the first matching case is chosen. 6486 6487 6488 <pre> 6489 func f[P any](x any) int { 6490 switch x.(type) { 6491 case P: 6492 return 0 6493 case string: 6494 return 1 6495 case []P: 6496 return 2 6497 case []byte: 6498 return 3 6499 default: 6500 return 4 6501 } 6502 } 6503 6504 var v1 = f[string]("foo") // v1 == 0 6505 var v2 = f[byte]([]byte{}) // v2 == 2 6506 </pre> 6507 6508 6509 The type switch guard may be preceded by a simple statement, which 6510 executes before the guard is evaluated. 6511 6512 6513 6514 The "fallthrough" statement is not permitted in a type switch. 6515 6516 6517 <h3 id="For_statements">For statements</h3> 6518 6519 6520 A "for" statement specifies repeated execution of a block. There are three forms: 6521 The iteration may be controlled by a single condition, a "for" clause, or a "range" clause. 6522 6523 6524 <pre class="ebnf"> 6525 ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . 6526 Condition = Expression . 6527 </pre> 6528 6529 <h4 id="For_condition">For statements with single condition</h4> 6530 6531 6532 In its simplest form, a "for" statement specifies the repeated execution of 6533 a block as long as a boolean condition evaluates to true. 6534 The condition is evaluated before each iteration. 6535 If the condition is absent, it is equivalent to the boolean value 6536 <code>true</code>. 6537 6538 6539 <pre> 6540 for a 6544 6545 <h4 id="For_clause">For statements with <code>for</code> clause</h4> 6546 6547 6548 A "for" statement with a ForClause is also controlled by its condition, but 6549 additionally it may specify an init 6550 and a post statement, such as an assignment, 6551 an increment or decrement statement. The init statement may be a 6552 <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. 6553 Variables declared by the init statement are re-used in each iteration. 6554 6555 6556 <pre class="ebnf"> 6557 ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . 6558 InitStmt = SimpleStmt . 6559 PostStmt = SimpleStmt . 6560 </pre> 6561 6562 <pre> 6563 for i := 0; i < 10; i++ { 6564 f(i) 6565 } 6566 </pre> 6567 6568 6569 If non-empty, the init statement is executed once before evaluating the 6570 condition for the first iteration; 6571 the post statement is executed after each execution of the block (and 6572 only if the block was executed). 6573 Any element of the ForClause may be empty but the 6574 <a href="#Semicolons">semicolons</a> are 6575 required unless there is only a condition. 6576 If the condition is absent, it is equivalent to the boolean value 6577 <code>true</code>. 6578 6579 6580 <pre> 6581 for cond { S() } is the same as for ; cond ; { S() } 6582 for { S() } is the same as for true { S() } 6583 </pre> 6584 6585 <h4 id="For_range">For statements with <code>range</code> clause</h4> 6586 6587 6588 A "for" statement with a "range" clause 6589 iterates through all entries of an array, slice, string or map, 6590 or values received on a channel. For each entry it assigns iteration values 6591 to corresponding iteration variables if present and then executes the block. 6592 6593 6594 <pre class="ebnf"> 6595 RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . 6596 </pre> 6597 6598 6599 The expression on the right in the "range" clause is called the range expression, 6600 its <a href="#Core_types">core type</a> must be 6601 an array, pointer to an array, slice, string, map, or channel permitting 6602 <a href="#Receive_operator">receive operations</a>. 6603 As with an assignment, if present the operands on the left must be 6604 <a href="#Address_operators">addressable</a> or map index expressions; they 6605 denote the iteration variables. If the range expression is a channel, at most 6606 one iteration variable is permitted, otherwise there may be up to two. 6607 If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, 6608 the range clause is equivalent to the same clause without that identifier. 6609 6610 6611 6612 The range expression <code>x</code> is evaluated once before beginning the loop, 6613 with one exception: if at most one iteration variable is present and 6614 <code>len(x)</code> is <a href="#Length_and_capacity">constant</a>, 6615 the range expression is not evaluated. 6616 6617 6618 6619 Function calls on the left are evaluated once per iteration. 6620 For each iteration, iteration values are produced as follows 6621 if the respective iteration variables are present: 6622 6623 6624 <pre class="grammar"> 6625 Range expression 1st value 2nd value 6626 6627 array or slice a [n]E, *[n]E, or []E index i int a[i] E 6628 string s string type index i int see below rune 6629 map m map[K]V key k K m[k] V 6630 channel c chan E, <-chan E element e E 6631 </pre> 6632 6633 <ol> 6634 <li> 6635 For an array, pointer to array, or slice value <code>a</code>, the index iteration 6636 values are produced in increasing order, starting at element index 0. 6637 If at most one iteration variable is present, the range loop produces 6638 iteration values from 0 up to <code>len(a)-1</code> and does not index into the array 6639 or slice itself. For a <code>nil</code> slice, the number of iterations is 0. 6640 </li> 6641 6642 <li> 6643 For a string value, the "range" clause iterates over the Unicode code points 6644 in the string starting at byte index 0. On successive iterations, the index value will be the 6645 index of the first byte of successive UTF-8-encoded code points in the string, 6646 and the second value, of type <code>rune</code>, will be the value of 6647 the corresponding code point. If the iteration encounters an invalid 6648 UTF-8 sequence, the second value will be <code>0xFFFD</code>, 6649 the Unicode replacement character, and the next iteration will advance 6650 a single byte in the string. 6651 </li> 6652 6653 <li> 6654 The iteration order over maps is not specified 6655 and is not guaranteed to be the same from one iteration to the next. 6656 If a map entry that has not yet been reached is removed during iteration, 6657 the corresponding iteration value will not be produced. If a map entry is 6658 created during iteration, that entry may be produced during the iteration or 6659 may be skipped. The choice may vary for each entry created and from one 6660 iteration to the next. 6661 If the map is <code>nil</code>, the number of iterations is 0. 6662 </li> 6663 6664 <li> 6665 For channels, the iteration values produced are the successive values sent on 6666 the channel until the channel is <a href="#Close">closed</a>. If the channel 6667 is <code>nil</code>, the range expression blocks forever. 6668 </li> 6669 </ol> 6670 6671 6672 The iteration values are assigned to the respective 6673 iteration variables as in an <a href="#Assignment_statements">assignment statement</a>. 6674 6675 6676 6677 The iteration variables may be declared by the "range" clause using a form of 6678 <a href="#Short_variable_declarations">short variable declaration</a> 6679 (<code>:=</code>). 6680 In this case their types are set to the types of the respective iteration values 6681 and their <a href="#Declarations_and_scope">scope</a> is the block of the "for" 6682 statement; they are re-used in each iteration. 6683 If the iteration variables are declared outside the "for" statement, 6684 after execution their values will be those of the last iteration. 6685 6686 6687 <pre> 6688 var testdata *struct { 6689 a *[7]int 6690 } 6691 for i, _ := range testdata.a { 6692 // testdata.a is never evaluated; len(testdata.a) is constant 6693 // i ranges from 0 to 6 6694 f(i) 6695 } 6696 6697 var a [10]string 6698 for i, s := range a { 6699 // type of i is int 6700 // type of s is string 6701 // s == a[i] 6702 g(i, s) 6703 } 6704 6705 var key string 6706 var val interface{} // element type of m is assignable to val 6707 m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6} 6708 for key, val = range m { 6709 h(key, val) 6710 } 6711 // key == last map key encountered in iteration 6712 // val == map[key] 6713 6714 var ch chan Work = producer() 6715 for w := range ch { 6716 doWork(w) 6717 } 6718 6719 // empty a channel 6720 for range ch {} 6721 </pre> 6722 6723 6724 <h3 id="Go_statements">Go statements</h3> 6725 6726 6727 A "go" statement starts the execution of a function call 6728 as an independent concurrent thread of control, or goroutine, 6729 within the same address space. 6730 6731 6732 <pre class="ebnf"> 6733 GoStmt = "go" Expression . 6734 </pre> 6735 6736 6737 The expression must be a function or method call; it cannot be parenthesized. 6738 Calls of built-in functions are restricted as for 6739 <a href="#Expression_statements">expression statements</a>. 6740 6741 6742 6743 The function value and parameters are 6744 <a href="#Calls">evaluated as usual</a> 6745 in the calling goroutine, but 6746 unlike with a regular call, program execution does not wait 6747 for the invoked function to complete. 6748 Instead, the function begins executing independently 6749 in a new goroutine. 6750 When the function terminates, its goroutine also terminates. 6751 If the function has any return values, they are discarded when the 6752 function completes. 6753 6754 6755 <pre> 6756 go Server() 6757 go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c) 6758 </pre> 6759 6760 6761 <h3 id="Select_statements">Select statements</h3> 6762 6763 6764 A "select" statement chooses which of a set of possible 6765 <a href="#Send_statements">send</a> or 6766 <a href="#Receive_operator">receive</a> 6767 operations will proceed. 6768 It looks similar to a 6769 <a href="#Switch_statements">"switch"</a> statement but with the 6770 cases all referring to communication operations. 6771 6772 6773 <pre class="ebnf"> 6774 SelectStmt = "select" "{" { CommClause } "}" . 6775 CommClause = CommCase ":" StatementList . 6776 CommCase = "case" ( SendStmt | RecvStmt ) | "default" . 6777 RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr . 6778 RecvExpr = Expression . 6779 </pre> 6780 6781 6782 A case with a RecvStmt may assign the result of a RecvExpr to one or 6783 two variables, which may be declared using a 6784 <a href="#Short_variable_declarations">short variable declaration</a>. 6785 The RecvExpr must be a (possibly parenthesized) receive operation. 6786 There can be at most one default case and it may appear anywhere 6787 in the list of cases. 6788 6789 6790 6791 Execution of a "select" statement proceeds in several steps: 6792 6793 6794 <ol> 6795 <li> 6796 For all the cases in the statement, the channel operands of receive operations 6797 and the channel and right-hand-side expressions of send statements are 6798 evaluated exactly once, in source order, upon entering the "select" statement. 6799 The result is a set of channels to receive from or send to, 6800 and the corresponding values to send. 6801 Any side effects in that evaluation will occur irrespective of which (if any) 6802 communication operation is selected to proceed. 6803 Expressions on the left-hand side of a RecvStmt with a short variable declaration 6804 or assignment are not yet evaluated. 6805 </li> 6806 6807 <li> 6808 If one or more of the communications can proceed, 6809 a single one that can proceed is chosen via a uniform pseudo-random selection. 6810 Otherwise, if there is a default case, that case is chosen. 6811 If there is no default case, the "select" statement blocks until 6812 at least one of the communications can proceed. 6813 </li> 6814 6815 <li> 6816 Unless the selected case is the default case, the respective communication 6817 operation is executed. 6818 </li> 6819 6820 <li> 6821 If the selected case is a RecvStmt with a short variable declaration or 6822 an assignment, the left-hand side expressions are evaluated and the 6823 received value (or values) are assigned. 6824 </li> 6825 6826 <li> 6827 The statement list of the selected case is executed. 6828 </li> 6829 </ol> 6830 6831 6832 Since communication on <code>nil</code> channels can never proceed, 6833 a select with only <code>nil</code> channels and no default case blocks forever. 6834 6835 6836 <pre> 6837 var a []int 6838 var c, c1, c2, c3, c4 chan int 6839 var i1, i2 int 6840 select { 6841 case i1 = <-c1: 6842 print("received ", i1, " from c1\n") 6843 case c2 <- i2: 6844 print("sent ", i2, " to c2\n") 6845 case i3, ok := (<-c3): // same as: i3, ok := <-c3 6846 if ok { 6847 print("received ", i3, " from c3\n") 6848 } else { 6849 print("c3 is closed\n") 6850 } 6851 case a[f()] = <-c4: 6852 // same as: 6853 // case t := <-c4 6854 // a[f()] = t 6855 default: 6856 print("no communication\n") 6857 } 6858 6859 for { // send random sequence of bits to c 6860 select { 6861 case c <- 0: // note: no statement, no fallthrough, no folding of cases 6862 case c <- 1: 6863 } 6864 } 6865 6866 select {} // block forever 6867 </pre> 6868 6869 6870 <h3 id="Return_statements">Return statements</h3> 6871 6872 6873 A "return" statement in a function <code>F</code> terminates the execution 6874 of <code>F</code>, and optionally provides one or more result values. 6875 Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> 6876 are executed before <code>F</code> returns to its caller. 6877 6878 6879 <pre class="ebnf"> 6880 ReturnStmt = "return" [ ExpressionList ] . 6881 </pre> 6882 6883 6884 In a function without a result type, a "return" statement must not 6885 specify any result values. 6886 6887 <pre> 6888 func noResult() { 6889 return 6890 } 6891 </pre> 6892 6893 6894 There are three ways to return values from a function with a result 6895 type: 6896 6897 6898 <ol> 6899 <li>The return value or values may be explicitly listed 6900 in the "return" statement. Each expression must be single-valued 6901 and <a href="#Assignability">assignable</a> 6902 to the corresponding element of the function's result type. 6903 <pre> 6904 func simpleF() int { 6905 return 2 6906 } 6907 6908 func complexF1() (re float64, im float64) { 6909 return -7.0, -4.0 6910 } 6911 </pre> 6912 </li> 6913 <li>The expression list in the "return" statement may be a single 6914 call to a multi-valued function. The effect is as if each value 6915 returned from that function were assigned to a temporary 6916 variable with the type of the respective value, followed by a 6917 "return" statement listing these variables, at which point the 6918 rules of the previous case apply. 6919 <pre> 6920 func complexF2() (re float64, im float64) { 6921 return complexF1() 6922 } 6923 </pre> 6924 </li> 6925 <li>The expression list may be empty if the function's result 6926 type specifies names for its <a href="#Function_types">result parameters</a>. 6927 The result parameters act as ordinary local variables 6928 and the function may assign values to them as necessary. 6929 The "return" statement returns the values of these variables. 6930 <pre> 6931 func complexF3() (re float64, im float64) { 6932 re = 7.0 6933 im = 4.0 6934 return 6935 } 6936 6937 func (devnull) Write(p []byte) (n int, _ error) { 6938 n = len(p) 6939 return 6940 } 6941 </pre> 6942 </li> 6943 </ol> 6944 6945 6946 Regardless of how they are declared, all the result values are initialized to 6947 the <a href="#The_zero_value">zero values</a> for their type upon entry to the 6948 function. A "return" statement that specifies results sets the result parameters before 6949 any deferred functions are executed. 6950 6951 6952 6953 Implementation restriction: A compiler may disallow an empty expression list 6954 in a "return" statement if a different entity (constant, type, or variable) 6955 with the same name as a result parameter is in 6956 <a href="#Declarations_and_scope">scope</a> at the place of the return. 6957 6958 6959 <pre> 6960 func f(n int) (res int, err error) { 6961 if _, err := f(n-1); err != nil { 6962 return // invalid return statement: err is shadowed 6963 } 6964 return 6965 } 6966 </pre> 6967 6968 <h3 id="Break_statements">Break statements</h3> 6969 6970 6971 A "break" statement terminates execution of the innermost 6972 <a href="#For_statements">"for"</a>, 6973 <a href="#Switch_statements">"switch"</a>, or 6974 <a href="#Select_statements">"select"</a> statement 6975 within the same function. 6976 6977 6978 <pre class="ebnf"> 6979 BreakStmt = "break" [ Label ] . 6980 </pre> 6981 6982 6983 If there is a label, it must be that of an enclosing 6984 "for", "switch", or "select" statement, 6985 and that is the one whose execution terminates. 6986 6987 6988 <pre> 6989 OuterLoop: 6990 for i = 0; i < n; i++ { 6991 for j = 0; j < m; j++ { 6992 switch a[i][j] { 6993 case nil: 6994 state = Error 6995 break OuterLoop 6996 case item: 6997 state = Found 6998 break OuterLoop 6999 } 7000 } 7001 } 7002 </pre> 7003 7004 <h3 id="Continue_statements">Continue statements</h3> 7005 7006 7007 A "continue" statement begins the next iteration of the 7008 innermost enclosing <a href="#For_statements">"for" loop</a> 7009 by advancing control to the end of the loop block. 7010 The "for" loop must be within the same function. 7011 7012 7013 <pre class="ebnf"> 7014 ContinueStmt = "continue" [ Label ] . 7015 </pre> 7016 7017 7018 If there is a label, it must be that of an enclosing 7019 "for" statement, and that is the one whose execution 7020 advances. 7021 7022 7023 <pre> 7024 RowLoop: 7025 for y, row := range rows { 7026 for x, data := range row { 7027 if data == endOfRow { 7028 continue RowLoop 7029 } 7030 row[x] = data + bias(x, y) 7031 } 7032 } 7033 </pre> 7034 7035 <h3 id="Goto_statements">Goto statements</h3> 7036 7037 7038 A "goto" statement transfers control to the statement with the corresponding label 7039 within the same function. 7040 7041 7042 <pre class="ebnf"> 7043 GotoStmt = "goto" Label . 7044 </pre> 7045 7046 <pre> 7047 goto Error 7048 </pre> 7049 7050 7051 Executing the "goto" statement must not cause any variables to come into 7052 <a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. 7053 For instance, this example: 7054 7055 7056 <pre> 7057 goto L // BAD 7058 v := 3 7059 L: 7060 </pre> 7061 7062 7063 is erroneous because the jump to label <code>L</code> skips 7064 the creation of <code>v</code>. 7065 7066 7067 7068 A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. 7069 For instance, this example: 7070 7071 7072 <pre> 7073 if n%2 == 1 { 7074 goto L1 7075 } 7076 for n > 0 { 7077 f() 7078 n-- 7079 L1: 7080 f() 7081 n-- 7082 } 7083 </pre> 7084 7085 7086 is erroneous because the label <code>L1</code> is inside 7087 the "for" statement's block but the <code>goto</code> is not. 7088 7089 7090 <h3 id="Fallthrough_statements">Fallthrough statements</h3> 7091 7092 7093 A "fallthrough" statement transfers control to the first statement of the 7094 next case clause in an <a href="#Expression_switches">expression "switch" statement</a>. 7095 It may be used only as the final non-empty statement in such a clause. 7096 7097 7098 <pre class="ebnf"> 7099 FallthroughStmt = "fallthrough" . 7100 </pre> 7101 7102 7103 <h3 id="Defer_statements">Defer statements</h3> 7104 7105 7106 A "defer" statement invokes a function whose execution is deferred 7107 to the moment the surrounding function returns, either because the 7108 surrounding function executed a <a href="#Return_statements">return statement</a>, 7109 reached the end of its <a href="#Function_declarations">function body</a>, 7110 or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>. 7111 7112 7113 <pre class="ebnf"> 7114 DeferStmt = "defer" Expression . 7115 </pre> 7116 7117 7118 The expression must be a function or method call; it cannot be parenthesized. 7119 Calls of built-in functions are restricted as for 7120 <a href="#Expression_statements">expression statements</a>. 7121 7122 7123 7124 Each time a "defer" statement 7125 executes, the function value and parameters to the call are 7126 <a href="#Calls">evaluated as usual</a> 7127 and saved anew but the actual function is not invoked. 7128 Instead, deferred functions are invoked immediately before 7129 the surrounding function returns, in the reverse order 7130 they were deferred. That is, if the surrounding function 7131 returns through an explicit <a href="#Return_statements">return statement</a>, 7132 deferred functions are executed after any result parameters are set 7133 by that return statement but before the function returns to its caller. 7134 If a deferred function value evaluates 7135 to <code>nil</code>, execution <a href="#Handling_panics">panics</a> 7136 when the function is invoked, not when the "defer" statement is executed. 7137 7138 7139 7140 For instance, if the deferred function is