go_spec.html 207 KB
Newer Older
1 2
<!--{
	"Title": "The Go Programming Language Specification",
3
	"Subtitle": "Version of July 31, 2019",
4
	"Path": "/ref/spec"
5
}-->
6

7
<h2 id="Introduction">Introduction</h2>
8

9
<p>
Rob Pike's avatar
Rob Pike committed
10
This is a reference manual for the Go programming language. For
11
more information and other documents, see <a href="/">golang.org</a>.
Rob Pike's avatar
Rob Pike committed
12
</p>
13

14
<p>
Rob Pike's avatar
Rob Pike committed
15
Go is a general-purpose language designed with systems programming
Rob Pike's avatar
Rob Pike committed
16
in mind. It is strongly typed and garbage-collected and has explicit
Rob Pike's avatar
Rob Pike committed
17 18
support for concurrent programming.  Programs are constructed from
<i>packages</i>, whose properties allow efficient management of
19
dependencies.
Rob Pike's avatar
Rob Pike committed
20
</p>
21

22
<p>
Rob Pike's avatar
Rob Pike committed
23 24 25
The grammar is compact and regular, allowing for easy analysis by
automatic tools such as integrated development environments.
</p>
26

27
<h2 id="Notation">Notation</h2>
Rob Pike's avatar
Rob Pike committed
28
<p>
29
The syntax is specified using Extended Backus-Naur Form (EBNF):
Rob Pike's avatar
Rob Pike committed
30
</p>
31

Rob Pike's avatar
Rob Pike committed
32
<pre class="grammar">
33
Production  = production_name "=" [ Expression ] "." .
Rob Pike's avatar
Rob Pike committed
34
Expression  = Alternative { "|" Alternative } .
35
Alternative = Term { Term } .
36
Term        = production_name | token [ "…" token ] | Group | Option | Repetition .
Rob Pike's avatar
Rob Pike committed
37
Group       = "(" Expression ")" .
38
Option      = "[" Expression "]" .
Rob Pike's avatar
Rob Pike committed
39
Repetition  = "{" Expression "}" .
40
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
41

Rob Pike's avatar
Rob Pike committed
42 43 44 45
<p>
Productions are expressions constructed from terms and the following
operators, in increasing precedence:
</p>
Rob Pike's avatar
Rob Pike committed
46
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
47 48 49 50
|   alternation
()  grouping
[]  option (0 or 1 times)
{}  repetition (0 to n times)
51
</pre>
52

53
<p>
Rob Pike's avatar
Rob Pike committed
54
Lower-case production names are used to identify lexical tokens.
55
Non-terminals are in CamelCase. Lexical tokens are enclosed in
Rob Pike's avatar
Rob Pike committed
56
double quotes <code>""</code> or back quotes <code>``</code>.
Rob Pike's avatar
Rob Pike committed
57 58
</p>

59
<p>
60 61
The form <code>a … b</code> represents the set of characters from
<code>a</code> through <code>b</code> as alternatives. The horizontal
62
ellipsis <code></code> is also used elsewhere in the spec to informally denote various
63
enumerations or code snippets that are not further specified. The character <code></code>
64 65
(as opposed to the three characters <code>...</code>) is not a token of the Go
language.
Rob Pike's avatar
Rob Pike committed
66 67
</p>

68
<h2 id="Source_code_representation">Source code representation</h2>
69

70
<p>
71
Source code is Unicode text encoded in
72
<a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
Rob Pike's avatar
Rob Pike committed
73 74 75
canonicalized, so a single accented code point is distinct from the
same character constructed from combining an accent and a letter;
those are treated as two code points.  For simplicity, this document
76 77
will use the unqualified term <i>character</i> to refer to a Unicode code point
in the source text.
Rob Pike's avatar
Rob Pike committed
78
</p>
79
<p>
Rob Pike's avatar
Rob Pike committed
80 81 82
Each code point is distinct; for instance, upper and lower case letters
are different characters.
</p>
83
<p>
84 85
Implementation restriction: For compatibility with other tools, a
compiler may disallow the NUL character (U+0000) in the source text.
86
</p>
87 88
<p>
Implementation restriction: For compatibility with other tools, a
89 90
compiler may ignore a UTF-8-encoded byte order mark
(U+FEFF) if it is the first Unicode code point in the source text.
91
A byte order mark may be disallowed anywhere else in the source.
92
</p>
93

94
<h3 id="Characters">Characters</h3>
95

96
<p>
Rob Pike's avatar
Rob Pike committed
97 98
The following terms are used to denote specific Unicode character classes:
</p>
99
<pre class="ebnf">
100 101
newline        = /* the Unicode code point U+000A */ .
unicode_char   = /* an arbitrary Unicode code point except newline */ .
102
unicode_letter = /* a Unicode code point classified as "Letter" */ .
103
unicode_digit  = /* a Unicode code point classified as "Number, decimal digit" */ .
104
</pre>
105

Rob Pike's avatar
Rob Pike committed
106
<p>
107
In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>,
108 109 110
Section 4.5 "General Category" defines a set of character categories.
Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo
as Unicode letters, and those in the Number category Nd as Unicode digits.
Rob Pike's avatar
Rob Pike committed
111
</p>
112

113
<h3 id="Letters_and_digits">Letters and digits</h3>
Rob Pike's avatar
Rob Pike committed
114 115

<p>
116
The underscore character <code>_</code> (U+005F) is considered a letter.
117 118
</p>
<pre class="ebnf">
119
letter        = unicode_letter | "_" .
120
decimal_digit = "0" … "9" .
121
binary_digit  = "0" | "1" .
122 123
octal_digit   = "0" … "7" .
hex_digit     = "0" … "9" | "A" … "F" | "a" … "f" .
124
</pre>
Rob Pike's avatar
Rob Pike committed
125

126
<h2 id="Lexical_elements">Lexical elements</h2>
127

128
<h3 id="Comments">Comments</h3>
129

Rob Pike's avatar
Rob Pike committed
130
<p>
131
Comments serve as program documentation. There are two forms:
Rob Pike's avatar
Rob Pike committed
132 133
</p>

134 135 136
<ol>
<li>
<i>Line comments</i> start with the character sequence <code>//</code>
137
and stop at the end of the line.
138 139 140
</li>
<li>
<i>General comments</i> start with the character sequence <code>/*</code>
141
and stop with the first subsequent character sequence <code>*/</code>.
142 143 144 145
</li>
</ol>

<p>
146 147 148 149
A comment cannot start inside a <a href="#Rune_literals">rune</a> or
<a href="#String_literals">string literal</a>, or inside a comment.
A general comment containing no newlines acts like a space.
Any other comment acts like a newline.
150 151
</p>

152
<h3 id="Tokens">Tokens</h3>
153

Rob Pike's avatar
Rob Pike committed
154 155
<p>
Tokens form the vocabulary of the Go language.
156
There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators
157
and punctuation</i>, and <i>literals</i>.  <i>White space</i>, formed from
158 159 160
spaces (U+0020), horizontal tabs (U+0009),
carriage returns (U+000D), and newlines (U+000A),
is ignored except as it separates tokens
161
that would otherwise combine into a single token. Also, a newline or end of file
162
may trigger the insertion of a <a href="#Semicolons">semicolon</a>.
163
While breaking the input into tokens,
Rob Pike's avatar
Rob Pike committed
164 165 166
the next token is the longest sequence of characters that form a
valid token.
</p>
167

168 169 170 171 172 173 174 175 176 177 178
<h3 id="Semicolons">Semicolons</h3>

<p>
The formal grammar uses semicolons <code>";"</code> as terminators in
a number of productions. Go programs may omit most of these semicolons
using the following two rules:
</p>

<ol>
<li>
When the input is broken into tokens, a semicolon is automatically inserted
179
into the token stream immediately after a line's final token if that token is
180
<ul>
181 182
	<li>an
	    <a href="#Identifiers">identifier</a>
183
	</li>
184

185 186 187 188
	<li>an
	    <a href="#Integer_literals">integer</a>,
	    <a href="#Floating-point_literals">floating-point</a>,
	    <a href="#Imaginary_literals">imaginary</a>,
189
	    <a href="#Rune_literals">rune</a>, or
190 191
	    <a href="#String_literals">string</a> literal
	</li>
192

193 194 195 196 197 198
	<li>one of the <a href="#Keywords">keywords</a>
	    <code>break</code>,
	    <code>continue</code>,
	    <code>fallthrough</code>, or
	    <code>return</code>
	</li>
199

200
	<li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a>
201 202 203 204 205
	    <code>++</code>,
	    <code>--</code>,
	    <code>)</code>,
	    <code>]</code>, or
	    <code>}</code>
206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
	</li>
</ul>
</li>

<li>
To allow complex statements to occupy a single line, a semicolon
may be omitted before a closing <code>")"</code> or <code>"}"</code>.
</li>
</ol>

<p>
To reflect idiomatic use, code examples in this document elide semicolons
using these rules.
</p>


222
<h3 id="Identifiers">Identifiers</h3>
223

Rob Pike's avatar
Rob Pike committed
224 225 226 227 228
<p>
Identifiers name program entities such as variables and types.
An identifier is a sequence of one or more letters and digits.
The first character in an identifier must be a letter.
</p>
229
<pre class="ebnf">
230
identifier = letter { letter | unicode_digit } .
231 232 233 234 235 236 237
</pre>
<pre>
a
_x9
ThisVariableIsExported
αβ
</pre>
238 239

<p>
Robert Griesemer's avatar
Robert Griesemer committed
240
Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
241 242
</p>

243

244
<h3 id="Keywords">Keywords</h3>
245

Rob Pike's avatar
Rob Pike committed
246 247 248 249 250 251 252 253 254 255
<p>
The following keywords are reserved and may not be used as identifiers.
</p>
<pre class="grammar">
break        default      func         interface    select
case         defer        go           map          struct
chan         else         goto         package      switch
const        fallthrough  if           range        type
continue     for          import       return       var
</pre>
256

257
<h3 id="Operators_and_punctuation">Operators and punctuation</h3>
Rob Pike's avatar
Rob Pike committed
258 259

<p>
260 261
The following character sequences represent <a href="#Operators">operators</a>
(including <a href="#assign_op">assignment operators</a>) and punctuation:
Rob Pike's avatar
Rob Pike committed
262 263 264 265 266
</p>
<pre class="grammar">
+    &amp;     +=    &amp;=     &amp;&amp;    ==    !=    (    )
-    |     -=    |=     ||    &lt;     &lt;=    [    ]
*    ^     *=    ^=     &lt;-    &gt;     &gt;=    {    }
267 268
/    &lt;&lt;    /=    &lt;&lt;=    ++    =     :=    ,    ;
%    &gt;&gt;    %=    &gt;&gt;=    --    !     ...   .    :
269
     &amp;^          &amp;^=
Rob Pike's avatar
Rob Pike committed
270 271
</pre>

272
<h3 id="Integer_literals">Integer literals</h3>
Rob Pike's avatar
Rob Pike committed
273 274

<p>
275 276
An integer literal is a sequence of digits representing an
<a href="#Constants">integer constant</a>.
277 278 279 280 281 282 283 284 285 286 287 288
An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code>
for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal,
and <code>0x</code> or <code>0X</code> for hexadecimal.
A single <code>0</code> is considered a decimal zero.
In hexadecimal literals, letters <code>a</code> through <code>f</code>
and <code>A</code> through <code>F</code> represent values 10 through 15.
</p>

<p>
For readability, an underscore character <code>_</code> may appear after
a base prefix or between successive digits; such underscores do not change
the literal's value.
Rob Pike's avatar
Rob Pike committed
289
</p>
290
<pre class="ebnf">
291 292 293 294 295 296 297 298 299 300
int_lit        = decimal_lit | binary_lit | octal_lit | hex_lit .
decimal_lit    = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] .
binary_lit     = "0" ( "b" | "B" ) [ "_" ] binary_digits .
octal_lit      = "0" [ "o" | "O" ] [ "_" ] octal_digits .
hex_lit        = "0" ( "x" | "X" ) [ "_" ] hex_digits .

decimal_digits = decimal_digit { [ "_" ] decimal_digit } .
binary_digits  = binary_digit { [ "_" ] binary_digit } .
octal_digits   = octal_digit { [ "_" ] octal_digit } .
hex_digits     = hex_digit { [ "_" ] hex_digit } .
301 302 303 304
</pre>

<pre>
42
305
4_2
306
0600
307 308 309
0_600
0o600
0O600       // second character is capital letter 'O'
310
0xBadFace
311 312
0xBad_Face
0x_67_7a_2f_cc_40_c6
313
170141183460469231731687303715884105727
314 315 316 317 318 319
170_141183_460469_231731_687303_715884_105727

_42         // an identifier, not an integer literal
42_         // invalid: _ must separate successive digits
4__2        // invalid: only one _ at a time
0_xBadFace  // invalid: _ must separate successive digits
320
</pre>
321

322

323
<h3 id="Floating-point_literals">Floating-point literals</h3>
324

Rob Pike's avatar
Rob Pike committed
325
<p>
326
A floating-point literal is a decimal or hexadecimal representation of a
327
<a href="#Constants">floating-point constant</a>.
Rob Pike's avatar
Rob Pike committed
328
</p>
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353

<p>
A decimal floating-point literal consists of an integer part (decimal digits),
a decimal point, a fractional part (decimal digits), and an exponent part
(<code>e</code> or <code>E</code> followed by an optional sign and decimal digits).
One of the integer part or the fractional part may be elided; one of the decimal point
or the exponent part may be elided.
An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>.
</p>

<p>
A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code>
prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits),
and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits).
One of the integer part or the fractional part may be elided; the radix point may be elided as well,
but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.)
An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>.
</p>

<p>
For readability, an underscore character <code>_</code> may appear after
a base prefix or between successive digits; such underscores do not change
the literal value.
</p>

354
<pre class="ebnf">
355 356 357 358 359 360 361 362 363 364 365 366
float_lit         = decimal_float_lit | hex_float_lit .

decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] |
                    decimal_digits decimal_exponent |
                    "." decimal_digits [ decimal_exponent ] .
decimal_exponent  = ( "e" | "E" ) [ "+" | "-" ] decimal_digits .

hex_float_lit     = "0" ( "x" | "X" ) hex_mantissa hex_exponent .
hex_mantissa      = [ "_" ] hex_digits "." [ hex_digits ] |
                    [ "_" ] hex_digits |
                    "." hex_digits .
hex_exponent      = ( "p" | "P" ) [ "+" | "-" ] decimal_digits .
367 368 369 370
</pre>

<pre>
0.
Rob Pike's avatar
Rob Pike committed
371
72.40
372
072.40       // == 72.40
373 374 375 376 377 378
2.71828
1.e+0
6.67428e-11
1E6
.25
.12345E+5
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
1_5.         // == 15.0
0.15e+0_2    // == 15.0

0x1p-2       // == 0.25
0x2.p10      // == 2048.0
0x1.Fp+0     // == 1.9375
0X.8p-0      // == 0.5
0X_1FFFP-16  // == 0.1249847412109375
0x15e-2      // == 0x15e - 2 (integer subtraction)

0x.p1        // invalid: mantissa has no digits
1p-2         // invalid: p exponent requires hexadecimal mantissa
0x1.5e-2     // invalid: hexadecimal mantissa requires p exponent
1_.5         // invalid: _ must separate successive digits
1._5         // invalid: _ must separate successive digits
1.5_e1       // invalid: _ must separate successive digits
1.5e_1       // invalid: _ must separate successive digits
1.5e1_       // invalid: _ must separate successive digits
397
</pre>
398

399

Rob Pike's avatar
Rob Pike committed
400
<h3 id="Imaginary_literals">Imaginary literals</h3>
401

Rob Pike's avatar
Rob Pike committed
402
<p>
403
An imaginary literal represents the imaginary part of a
Rob Pike's avatar
Rob Pike committed
404
<a href="#Constants">complex constant</a>.
405 406 407 408 409
It consists of an <a href="#Integer_literals">integer</a> or
<a href="#Floating-point_literals">floating-point</a> literal
followed by the lower-case letter <code>i</code>.
The value of an imaginary literal is the value of the respective
integer or floating-point literal multiplied by the imaginary unit <i>i</i>.
Rob Pike's avatar
Rob Pike committed
410
</p>
411

Rob Pike's avatar
Rob Pike committed
412
<pre class="ebnf">
413
imaginary_lit = (decimal_digits | int_lit | float_lit) "i" .
Rob Pike's avatar
Rob Pike committed
414 415
</pre>

416 417 418 419 420 421
<p>
For backward compatibility, an imaginary literal's integer part consisting
entirely of decimal digits (and possibly underscores) is considered a decimal
integer, even if it starts with a leading <code>0</code>.
</p>

Rob Pike's avatar
Rob Pike committed
422 423
<pre>
0i
424 425 426
0123i         // == 123i for backward-compatibility
0o123i        // == 0o123 * 1i == 83i
0xabci        // == 0xabc * 1i == 2748i
Rob Pike's avatar
Rob Pike committed
427 428 429 430 431 432 433
0.i
2.71828i
1.e+0i
6.67428e-11i
1E6i
.25i
.12345E+5i
434
0x1p-2i       // == 0x1p-2 * 1i == 0.25i
Rob Pike's avatar
Rob Pike committed
435 436
</pre>

437

438
<h3 id="Rune_literals">Rune literals</h3>
439

Rob Pike's avatar
Rob Pike committed
440
<p>
441 442
A rune literal represents a <a href="#Constants">rune constant</a>,
an integer value identifying a Unicode code point.
443 444 445 446
A rune literal is expressed as one or more characters enclosed in single quotes,
as in <code>'x'</code> or <code>'\n'</code>.
Within the quotes, any character may appear except newline and unescaped single
quote. A single quoted character represents the Unicode value
447
of the character itself,
Rob Pike's avatar
Rob Pike committed
448 449
while multi-character sequences beginning with a backslash encode
values in various formats.
Rob Pike's avatar
Rob Pike committed
450
</p>
451

452
<p>
Rob Pike's avatar
Rob Pike committed
453 454 455
The simplest form represents the single character within the quotes;
since Go source text is Unicode characters encoded in UTF-8, multiple
UTF-8-encoded bytes may represent a single integer value.  For
456 457 458 459
instance, the literal <code>'a'</code> holds a single byte representing
a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while
<code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing
a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>.
Rob Pike's avatar
Rob Pike committed
460
</p>
461

462
<p>
463
Several backslash escapes allow arbitrary values to be encoded as
Oling Cat's avatar
Oling Cat committed
464
ASCII text.  There are four ways to represent the integer value
465 466 467 468
as a numeric constant: <code>\x</code> followed by exactly two hexadecimal
digits; <code>\u</code> followed by exactly four hexadecimal digits;
<code>\U</code> followed by exactly eight hexadecimal digits, and a
plain backslash <code>\</code> followed by exactly three octal digits.
Rob Pike's avatar
Rob Pike committed
469 470 471
In each case the value of the literal is the value represented by
the digits in the corresponding base.
</p>
472

473
<p>
Rob Pike's avatar
Rob Pike committed
474 475
Although these representations all result in an integer, they have
different valid ranges.  Octal escapes must represent a value between
Rob Pike's avatar
Rob Pike committed
476 477
0 and 255 inclusive.  Hexadecimal escapes satisfy this condition
by construction. The escapes <code>\u</code> and <code>\U</code>
Rob Pike's avatar
Rob Pike committed
478
represent Unicode code points so within them some values are illegal,
479
in particular those above <code>0x10FFFF</code> and surrogate halves.
Rob Pike's avatar
Rob Pike committed
480
</p>
481

482
<p>
Rob Pike's avatar
Rob Pike committed
483 484
After a backslash, certain single-character escapes represent special values:
</p>
485

Rob Pike's avatar
Rob Pike committed
486 487 488 489 490 491 492 493 494
<pre class="grammar">
\a   U+0007 alert or bell
\b   U+0008 backspace
\f   U+000C form feed
\n   U+000A line feed or newline
\r   U+000D carriage return
\t   U+0009 horizontal tab
\v   U+000b vertical tab
\\   U+005c backslash
495
\'   U+0027 single quote  (valid escape only within rune literals)
Rob Pike's avatar
Rob Pike committed
496 497
\"   U+0022 double quote  (valid escape only within string literals)
</pre>
498

Rob Pike's avatar
Rob Pike committed
499
<p>
500
All other sequences starting with a backslash are illegal inside rune literals.
Rob Pike's avatar
Rob Pike committed
501
</p>
502
<pre class="ebnf">
503
rune_lit         = "'" ( unicode_value | byte_value ) "'" .
Rob Pike's avatar
Rob Pike committed
504 505
unicode_value    = unicode_char | little_u_value | big_u_value | escaped_char .
byte_value       = octal_byte_value | hex_byte_value .
506 507 508 509
octal_byte_value = `\` octal_digit octal_digit octal_digit .
hex_byte_value   = `\` "x" hex_digit hex_digit .
little_u_value   = `\` "u" hex_digit hex_digit hex_digit hex_digit .
big_u_value      = `\` "U" hex_digit hex_digit hex_digit hex_digit
Rob Pike's avatar
Rob Pike committed
510
                           hex_digit hex_digit hex_digit hex_digit .
511
escaped_char     = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
Rob Pike's avatar
Rob Pike committed
512
</pre>
513

514 515 516 517 518 519 520 521 522 523 524 525
<pre>
'a'
'ä'
'本'
'\t'
'\000'
'\007'
'\377'
'\x07'
'\xff'
'\u12e4'
'\U00101234'
526
'\''         // rune literal containing single quote character
527 528 529 530 531
'aa'         // illegal: too many characters
'\xa'        // illegal: too few hexadecimal digits
'\0'         // illegal: too few octal digits
'\uDFFF'     // illegal: surrogate half
'\U00110000' // illegal: invalid Unicode code point
532
</pre>
533 534


535
<h3 id="String_literals">String literals</h3>
Rob Pike's avatar
Rob Pike committed
536 537

<p>
538 539 540
A string literal represents a <a href="#Constants">string constant</a>
obtained from concatenating a sequence of characters. There are two forms:
raw string literals and interpreted string literals.
Rob Pike's avatar
Rob Pike committed
541
</p>
542

Rob Pike's avatar
Rob Pike committed
543
<p>
544 545
Raw string literals are character sequences between back quotes, as in
<code>`foo`</code>.  Within the quotes, any character may appear except
546
back quote. The value of a raw string literal is the
547 548
string composed of the uninterpreted (implicitly UTF-8-encoded) characters
between the quotes;
549
in particular, backslashes have no special meaning and the string may
550
contain newlines.
551
Carriage return characters ('\r') inside raw string literals
552
are discarded from the raw string value.
Rob Pike's avatar
Rob Pike committed
553
</p>
554

Rob Pike's avatar
Rob Pike committed
555 556
<p>
Interpreted string literals are character sequences between double
557 558 559
quotes, as in <code>&quot;bar&quot;</code>.
Within the quotes, any character may appear except newline and unescaped double quote.
The text between the quotes forms the
Rob Pike's avatar
Rob Pike committed
560
value of the literal, with backslash escapes interpreted as they
561
are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and
562 563
<code>\"</code> is legal), with the same restrictions.
The three-digit octal (<code>\</code><i>nnn</i>)
564
and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
Rob Pike's avatar
Rob Pike committed
565 566
<i>bytes</i> of the resulting string; all other escapes represent
the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
567 568 569
Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent
a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>,
<code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent
570
the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
Rob Pike's avatar
Rob Pike committed
571 572 573
U+00FF.
</p>

574
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
575
string_lit             = raw_string_lit | interpreted_string_lit .
576
raw_string_lit         = "`" { unicode_char | newline } "`" .
577
interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
578
</pre>
579

580
<pre>
581
`abc`                // same as "abc"
582
`\n
583
\n`                  // same as "\\n\n\\n"
584
"\n"
585
"\""                 // same as `"`
586 587 588 589
"Hello, world!\n"
"日本語"
"\u65e5本\U00008a9e"
"\xff\u00FF"
590 591
"\uD800"             // illegal: surrogate half
"\U00110000"         // illegal: invalid Unicode code point
592
</pre>
593

Rob Pike's avatar
Rob Pike committed
594
<p>
595
These examples all represent the same string:
Rob Pike's avatar
Rob Pike committed
596
</p>
597

598
<pre>
Rob Pike's avatar
Rob Pike committed
599 600
"日本語"                                 // UTF-8 input text
`日本語`                                 // UTF-8 input text as a raw literal
601 602 603
"\u65e5\u672c\u8a9e"                    // the explicit Unicode code points
"\U000065e5\U0000672c\U00008a9e"        // the explicit Unicode code points
"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e"  // the explicit UTF-8 bytes
604
</pre>
605

606
<p>
607 608
If the source code represents a character as two code points, such as
a combining form involving an accent and a letter, the result will be
609
an error if placed in a rune literal (it is not a single code
610 611
point), and will appear as two code points if placed in a string
literal.
Rob Pike's avatar
Rob Pike committed
612
</p>
613

614 615 616

<h2 id="Constants">Constants</h2>

617
<p>There are <i>boolean constants</i>,
618
<i>rune constants</i>,
619
<i>integer constants</i>,
Rob Pike's avatar
Rob Pike committed
620
<i>floating-point constants</i>, <i>complex constants</i>,
621
and <i>string constants</i>. Rune, integer, floating-point,
Rob Pike's avatar
Rob Pike committed
622
and complex constants are
623 624 625 626
collectively called <i>numeric constants</i>.
</p>

<p>
627
A constant value is represented by a
628
<a href="#Rune_literals">rune</a>,
629 630
<a href="#Integer_literals">integer</a>,
<a href="#Floating-point_literals">floating-point</a>,
Rob Pike's avatar
Rob Pike committed
631
<a href="#Imaginary_literals">imaginary</a>,
632
or
633 634
<a href="#String_literals">string</a> literal,
an identifier denoting a constant,
635 636
a <a href="#Constant_expressions">constant expression</a>,
a <a href="#Conversions">conversion</a> with a result that is a constant, or
637 638 639 640
the result value of some built-in functions such as
<code>unsafe.Sizeof</code> applied to any value,
<code>cap</code> or <code>len</code> applied to
<a href="#Length_and_capacity">some expressions</a>,
Rob Pike's avatar
Rob Pike committed
641
<code>real</code> and <code>imag</code> applied to a complex constant
642
and <code>complex</code> applied to numeric constants.
643 644 645 646
The boolean truth values are represented by the predeclared constants
<code>true</code> and <code>false</code>. The predeclared identifier
<a href="#Iota">iota</a> denotes an integer constant.
</p>
Rob Pike's avatar
Rob Pike committed
647

Rob Pike's avatar
Rob Pike committed
648 649 650 651 652 653
<p>
In general, complex constants are a form of
<a href="#Constant_expressions">constant expression</a>
and are discussed in that section.
</p>

Rob Pike's avatar
Rob Pike committed
654
<p>
655 656 657
Numeric constants represent exact values of arbitrary precision and do not overflow.
Consequently, there are no constants denoting the IEEE-754 negative zero, infinity,
and not-a-number values.
Rob Pike's avatar
Rob Pike committed
658 659
</p>

660
<p>
661
Constants may be <a href="#Types">typed</a> or <i>untyped</i>.
662 663 664 665 666 667 668 669 670 671 672 673
Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>,
and certain <a href="#Constant_expressions">constant expressions</a>
containing only untyped constant operands are untyped.
</p>

<p>
A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a>
or <a href="#Conversions">conversion</a>, or implicitly when used in a
<a href="#Variable_declarations">variable declaration</a> or an
<a href="#Assignments">assignment</a> or as an
operand in an <a href="#Expressions">expression</a>.
It is an error if the constant value
674
cannot be <a href="#Representability">represented</a> as a value of the respective type.
675 676
</p>

677 678 679 680 681 682 683 684 685 686 687
<p>
An untyped constant has a <i>default type</i> which is the type to which the
constant is implicitly converted in contexts where a typed value is required,
for instance, in a <a href="#Short_variable_declarations">short variable declaration</a>
such as <code>i := 0</code> where there is no explicit type.
The default type of an untyped constant is <code>bool</code>, <code>rune</code>,
<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code>
respectively, depending on whether it is a boolean, rune, integer, floating-point,
complex, or string constant.
</p>

688
<p>
689 690 691 692
Implementation restriction: Although numeric constants have arbitrary
precision in the language, a compiler may implement them using an
internal representation with limited precision.  That said, every
implementation must:
693
</p>
694

695 696 697 698 699
<ul>
	<li>Represent integer constants with at least 256 bits.</li>

	<li>Represent floating-point constants, including the parts of
	    a complex constant, with a mantissa of at least 256 bits
700
	    and a signed binary exponent of at least 16 bits.</li>
701 702 703

	<li>Give an error if unable to represent an integer constant
	    precisely.</li>
704

705 706 707 708 709 710 711
	<li>Give an error if unable to represent a floating-point or
	    complex constant due to overflow.</li>

	<li>Round to the nearest representable constant if unable to
	    represent a floating-point or complex constant due to limits
	    on precision.</li>
</ul>
712

713 714 715 716 717
<p>
These requirements apply both to literal constants and to the result
of evaluating <a href="#Constant_expressions">constant
expressions</a>.
</p>
718

719

Robert Griesemer's avatar
Robert Griesemer committed
720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749
<h2 id="Variables">Variables</h2>

<p>
A variable is a storage location for holding a <i>value</i>.
The set of permissible values is determined by the
variable's <i><a href="#Types">type</a></i>.
</p>

<p>
A <a href="#Variable_declarations">variable declaration</a>
or, for function parameters and results, the signature
of a <a href="#Function_declarations">function declaration</a>
or <a href="#Function_literals">function literal</a> reserves
storage for a named variable.

Calling the built-in function <a href="#Allocation"><code>new</code></a>
or taking the address of a <a href="#Composite_literals">composite literal</a>
allocates storage for a variable at run time.
Such an anonymous variable is referred to via a (possibly implicit)
<a href="#Address_operators">pointer indirection</a>.
</p>

<p>
<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>,
and <a href="#Struct_types">struct</a> types have elements and fields that may
be <a href="#Address_operators">addressed</a> individually. Each such element
acts like a variable.
</p>

<p>
750
The <i>static type</i> (or just <i>type</i>) of a variable is the
Robert Griesemer's avatar
Robert Griesemer committed
751 752 753 754 755 756 757 758 759
type given in its declaration, the type provided in the
<code>new</code> call or composite literal, or the type of
an element of a structured variable.
Variables of interface type also have a distinct <i>dynamic type</i>,
which is the concrete type of the value assigned to the variable at run time
(unless the value is the predeclared identifier <code>nil</code>,
which has no type).
The dynamic type may vary during execution but values stored in interface
variables are always <a href="#Assignability">assignable</a>
760 761
to the static type of the variable.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778

<pre>
var x interface{}  // x is nil and has static type interface{}
var v *T           // v has value nil, static type *T
x = 42             // x has value 42 and dynamic type int
x = v              // x has value (*T)(nil) and dynamic type *T
</pre>

<p>
A variable's value is retrieved by referring to the variable in an
<a href="#Expressions">expression</a>; it is the most recent value
<a href="#Assignments">assigned</a> to the variable.
If a variable has not yet been assigned a value, its value is the
<a href="#The_zero_value">zero value</a> for its type.
</p>


779
<h2 id="Types">Types</h2>
780

781
<p>
782 783 784
A type determines a set of values together with operations and methods specific
to those values. A type may be denoted by a <i>type name</i>, if it has one,
or specified using a <i>type literal</i>, which composes a type from existing types.
Rob Pike's avatar
Rob Pike committed
785
</p>
786

787
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
788
Type      = TypeName | TypeLit | "(" Type ")" .
789
TypeName  = identifier | QualifiedIdent .
Rob Pike's avatar
Rob Pike committed
790 791
TypeLit   = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
	    SliceType | MapType | ChannelType .
792
</pre>
793

794
<p>
795 796
The language <a href="#Predeclared_identifiers">predeclares</a> certain type names.
Others are introduced with <a href="#Type_declarations">type declarations</a>.
797 798 799
<i>Composite types</i>&mdash;array, struct, pointer, function,
interface, slice, map, and channel types&mdash;may be constructed using
type literals.
Rob Pike's avatar
Rob Pike committed
800
</p>
801

802 803
<p>
Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
804 805
is one of the predeclared boolean, numeric, or string types, or a type literal,
the corresponding underlying
806 807 808 809 810 811
type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type
is the underlying type of the type to which <code>T</code> refers in its
<a href="#Type_declarations">type declaration</a>.
</p>

<pre>
812 813 814 815 816 817 818 819 820 821 822
type (
	A1 = string
	A2 = A1
)

type (
	B1 string
	B2 B1
	B3 []B1
	B4 B3
)
823 824 825
</pre>

<p>
826 827 828
The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>,
and <code>B2</code> is <code>string</code>.
The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>.
829 830
</p>

831
<h3 id="Method_sets">Method sets</h3>
Rob Pike's avatar
Rob Pike committed
832
<p>
833
A type may have a <i>method set</i> associated with it.
834
The method set of an <a href="#Interface_types">interface type</a> is its interface.
835 836 837 838
The method set of any other type <code>T</code> consists of all
<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>.
The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code>
is the set of all methods declared with receiver <code>*T</code> or <code>T</code>
Robert Griesemer's avatar
Robert Griesemer committed
839
(that is, it also contains the method set of <code>T</code>).
840
Further rules apply to structs containing embedded fields, as described
841
in the section on <a href="#Struct_types">struct types</a>.
Robert Griesemer's avatar
Robert Griesemer committed
842
Any other type has an empty method set.
843
In a method set, each method must have a
844 845
<a href="#Uniqueness_of_identifiers">unique</a>
non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>.
Rob Pike's avatar
Rob Pike committed
846
</p>
Robert Griesemer's avatar
Robert Griesemer committed
847

848 849 850 851 852 853
<p>
The method set of a type determines the interfaces that the
type <a href="#Interface_types">implements</a>
and the methods that can be <a href="#Calls">called</a>
using a receiver of that type.
</p>
854

855 856
<h3 id="Boolean_types">Boolean types</h3>

857
<p>
858 859
A <i>boolean type</i> represents the set of Boolean truth values
denoted by the predeclared constants <code>true</code>
860 861
and <code>false</code>. The predeclared boolean type is <code>bool</code>;
it is a <a href="#Type_definitions">defined type</a>.
862
</p>
863

864
<h3 id="Numeric_types">Numeric types</h3>
865

Rob Pike's avatar
Rob Pike committed
866
<p>
867 868
A <i>numeric type</i> represents sets of integer or floating-point values.
The predeclared architecture-independent numeric types are:
Rob Pike's avatar
Rob Pike committed
869
</p>
870

Rob Pike's avatar
Rob Pike committed
871
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
872 873 874 875 876 877 878 879 880
uint8       the set of all unsigned  8-bit integers (0 to 255)
uint16      the set of all unsigned 16-bit integers (0 to 65535)
uint32      the set of all unsigned 32-bit integers (0 to 4294967295)
uint64      the set of all unsigned 64-bit integers (0 to 18446744073709551615)

int8        the set of all signed  8-bit integers (-128 to 127)
int16       the set of all signed 16-bit integers (-32768 to 32767)
int32       the set of all signed 32-bit integers (-2147483648 to 2147483647)
int64       the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
881

Rob Pike's avatar
Rob Pike committed
882 883
float32     the set of all IEEE-754 32-bit floating-point numbers
float64     the set of all IEEE-754 64-bit floating-point numbers
884

Rob Pike's avatar
Rob Pike committed
885 886
complex64   the set of all complex numbers with float32 real and imaginary parts
complex128  the set of all complex numbers with float64 real and imaginary parts
Rob Pike's avatar
Rob Pike committed
887

888
byte        alias for uint8
889
rune        alias for int32
890
</pre>
891

Rob Pike's avatar
Rob Pike committed
892
<p>
893
The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
894
<a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
Rob Pike's avatar
Rob Pike committed
895
</p>
896

Rob Pike's avatar
Rob Pike committed
897
<p>
898
There is also a set of predeclared numeric types with implementation-specific sizes:
Rob Pike's avatar
Rob Pike committed
899
</p>
900

901
<pre class="grammar">
902
uint     either 32 or 64 bits
903
int      same size as uint
904
uintptr  an unsigned integer large enough to store the uninterpreted bits of a pointer value
905
</pre>
906

907
<p>
908 909 910
To avoid portability issues all numeric types are <a href="#Type_definitions">defined
types</a> and thus distinct except
<code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and
911
<code>rune</code>, which is an alias for <code>int32</code>.
912
Explicit conversions
913
are required when different numeric types are mixed in an expression
Rob Pike's avatar
Rob Pike committed
914
or assignment. For instance, <code>int32</code> and <code>int</code>
915
are not the same type even though they may have the same size on a
Rob Pike's avatar
Rob Pike committed
916
particular architecture.
917

918

919
<h3 id="String_types">String types</h3>
920

921
<p>
922
A <i>string type</i> represents the set of string values.
923
A string value is a (possibly empty) sequence of bytes.
924
The number of bytes is called the length of the string and is never negative.
925
Strings are immutable: once created,
Rob Pike's avatar
Rob Pike committed
926
it is impossible to change the contents of a string.
927 928
The predeclared string type is <code>string</code>;
it is a <a href="#Type_definitions">defined type</a>.
929
</p>
Rob Pike's avatar
Rob Pike committed
930 931

<p>
932
The length of a string <code>s</code> can be discovered using
933 934
the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
The length is a compile-time constant if the string is a constant.
935 936
A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a>
0 through <code>len(s)-1</code>.
937 938 939
It is illegal to take the address of such an element; if
<code>s[i]</code> is the <code>i</code>'th byte of a
string, <code>&amp;s[i]</code> is invalid.
Rob Pike's avatar
Rob Pike committed
940
</p>
941 942


943
<h3 id="Array_types">Array types</h3>
944 945 946

<p>
An array is a numbered sequence of elements of a single
947
type, called the element type.
948
The number of elements is called the length of the array and is never negative.
949 950
</p>

951
<pre class="ebnf">
952 953
ArrayType   = "[" ArrayLength "]" ElementType .
ArrayLength = Expression .
954
ElementType = Type .
955 956 957
</pre>

<p>
958
The length is part of the array's type; it must evaluate to a
959 960
non-negative <a href="#Constants">constant</a>
<a href="#Representability">representable</a> by a value
961 962
of type <code>int</code>.
The length of array <code>a</code> can be discovered
963
using the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
964
The elements can be addressed by integer <a href="#Index_expressions">indices</a>
965
0 through <code>len(a)-1</code>.
966 967
Array types are always one-dimensional but may be composed to form
multi-dimensional types.
968 969 970 971 972 973
</p>

<pre>
[32]byte
[2*N] struct { x, y int32 }
[1000]*float64
974 975
[3][5]int
[2][2][2]float64  // same as [2]([2]([2]float64))
976 977
</pre>

978
<h3 id="Slice_types">Slice types</h3>
979 980

<p>
981
A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
982 983
provides access to a numbered sequence of elements from that array.
A slice type denotes the set of all slices of arrays of its element type.
984
The number of elements is called the length of the slice and is never negative.
985
The value of an uninitialized slice is <code>nil</code>.
986 987
</p>

988
<pre class="ebnf">
989 990 991 992
SliceType = "[" "]" ElementType .
</pre>

<p>
993
The length of a slice <code>s</code> can be discovered by the built-in function
994
<a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during
995 996
execution.  The elements can be addressed by integer <a href="#Index_expressions">indices</a>
0 through <code>len(s)-1</code>.  The slice index of a
997 998 999 1000 1001
given element may be less than the index of the same element in the
underlying array.
</p>
<p>
A slice, once initialized, is always associated with an underlying
Rob Pike's avatar
Rob Pike committed
1002
array that holds its elements.  A slice therefore shares storage
1003 1004 1005 1006 1007
with its array and with other slices of the same array; by contrast,
distinct arrays always represent distinct storage.
</p>
<p>
The array underlying a slice may extend past the end of the slice.
1008
The <i>capacity</i> is a measure of that extent: it is the sum of
1009
the length of the slice and the length of the array beyond the slice;
1010
a slice of length up to that capacity can be created by
Robert Griesemer's avatar
Robert Griesemer committed
1011
<a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
1012
The capacity of a slice <code>a</code> can be discovered using the
1013
built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
1014 1015 1016
</p>

<p>
1017 1018 1019 1020
A new, initialized slice value for a given element type <code>T</code> is
made using the built-in function
<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
which takes a slice type
1021 1022 1023
and parameters specifying the length and optionally the capacity.
A slice created with <code>make</code> always allocates a new, hidden array
to which the returned slice value refers. That is, executing
1024 1025 1026 1027 1028
</p>

<pre>
make([]T, length, capacity)
</pre>
1029

1030
<p>
1031 1032
produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
it, so these two expressions are equivalent:
1033 1034 1035 1036 1037 1038 1039
</p>

<pre>
make([]int, 50, 100)
new([100]int)[0:50]
</pre>

1040 1041 1042 1043
<p>
Like arrays, slices are always one-dimensional but may be composed to construct
higher-dimensional objects.
With arrays of arrays, the inner arrays are, by construction, always the same length;
1044 1045
however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
Moreover, the inner slices must be initialized individually.
1046
</p>
1047

1048
<h3 id="Struct_types">Struct types</h3>
1049

Rob Pike's avatar
Rob Pike committed
1050
<p>
1051 1052
A struct is a sequence of named elements, called fields, each of which has a
name and a type. Field names may be specified explicitly (IdentifierList) or
1053
implicitly (EmbeddedField).
1054
Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
1055
be <a href="#Uniqueness_of_identifiers">unique</a>.
Rob Pike's avatar
Rob Pike committed
1056
</p>
1057

1058
<pre class="ebnf">
1059 1060 1061 1062
StructType    = "struct" "{" { FieldDecl ";" } "}" .
FieldDecl     = (IdentifierList Type | EmbeddedField) [ Tag ] .
EmbeddedField = [ "*" ] TypeName .
Tag           = string_lit .
1063
</pre>
1064

1065
<pre>
1066 1067
// An empty struct.
struct {}
1068

Robert Griesemer's avatar
Robert Griesemer committed
1069
// A struct with 6 fields.
1070
struct {
1071
	x, y int
1072 1073
	u float32
	_ float32  // padding
1074 1075
	A *[]int
	F func()
1076 1077
}
</pre>
1078

Rob Pike's avatar
Rob Pike committed
1079
<p>
1080 1081
A field declared with a type but no explicit field name is called an <i>embedded field</i>.
An embedded field must be specified as
1082
a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
1083
and <code>T</code> itself may not be
1084
a pointer type. The unqualified type name acts as the field name.
Rob Pike's avatar
Rob Pike committed
1085
</p>
1086

1087
<pre>
1088
// A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4
1089
struct {
1090 1091 1092 1093 1094
	T1        // field name is T1
	*T2       // field name is T2
	P.T3      // field name is T3
	*P.T4     // field name is T4
	x, y int  // field names are x and y
1095
}
1096 1097
</pre>

Rob Pike's avatar
Rob Pike committed
1098
<p>
1099 1100
The following declaration is illegal because field names must be unique
in a struct type:
Rob Pike's avatar
Rob Pike committed
1101
</p>
1102

1103
<pre>
1104
struct {
1105 1106 1107
	T     // conflicts with embedded field *T and *P.T
	*T    // conflicts with embedded field T and *P.T
	*P.T  // conflicts with embedded field T and *T
1108
}
1109
</pre>
1110

1111
<p>
1112
A field or <a href="#Method_declarations">method</a> <code>f</code> of an
1113
embedded field in a struct <code>x</code> is called <i>promoted</i> if
1114 1115
<code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes
that field or method <code>f</code>.
Rob Pike's avatar
Rob Pike committed
1116
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1117

1118 1119 1120 1121 1122
<p>
Promoted fields act like ordinary fields
of a struct except that they cannot be used as field names in
<a href="#Composite_literals">composite literals</a> of the struct.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1123

1124
<p>
1125 1126
Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a>
<code>T</code>, promoted methods are included in the method set of the struct as follows:
1127 1128 1129
</p>
<ul>
	<li>
1130
	If <code>S</code> contains an embedded field <code>T</code>,
1131 1132 1133 1134 1135
	the <a href="#Method_sets">method sets</a> of <code>S</code>
	and <code>*S</code> both include promoted methods with receiver
	<code>T</code>. The method set of <code>*S</code> also
	includes promoted methods with receiver <code>*T</code>.
	</li>
1136

1137
	<li>
1138
	If <code>S</code> contains an embedded field <code>*T</code>,
1139 1140 1141
	the method sets of <code>S</code> and <code>*S</code> both
	include promoted methods with receiver <code>T</code> or
	<code>*T</code>.
Robert Griesemer's avatar
Robert Griesemer committed
1142 1143
	</li>
</ul>
1144

Rob Pike's avatar
Rob Pike committed
1145
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1146
A field declaration may be followed by an optional string literal <i>tag</i>,
1147
which becomes an attribute for all the fields in the corresponding
1148 1149
field declaration. An empty tag string is equivalent to an absent tag.
The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a>
1150
and take part in <a href="#Type_identity">type identity</a> for structs
Rob Pike's avatar
Rob Pike committed
1151 1152
but are otherwise ignored.
</p>
1153

1154
<pre>
1155
struct {
1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166
	x, y float64 ""  // an empty tag string is like an absent tag
	name string  "any string is permitted as a tag"
	_    [4]byte "ceci n'est pas un champ de structure"
}

// A struct corresponding to a TimeStamp protocol buffer.
// The tag strings define the protocol buffer field numbers;
// they follow the convention outlined by the reflect package.
struct {
	microsec  uint64 `protobuf:"1"`
	serverIP6 uint64 `protobuf:"2"`
1167
}
1168
</pre>
1169

1170
<h3 id="Pointer_types">Pointer types</h3>
1171

Rob Pike's avatar
Rob Pike committed
1172
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1173
A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given
1174
type, called the <i>base type</i> of the pointer.
1175
The value of an uninitialized pointer is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1176
</p>
1177

1178
<pre class="ebnf">
1179
PointerType = "*" BaseType .
1180
BaseType    = Type .
1181
</pre>
1182

1183
<pre>
Robert Griesemer's avatar
Robert Griesemer committed
1184 1185
*Point
*[4]int
1186
</pre>
1187

1188
<h3 id="Function_types">Function types</h3>
1189

Rob Pike's avatar
Rob Pike committed
1190
<p>
1191
A function type denotes the set of all functions with the same parameter
1192
and result types. The value of an uninitialized variable of function type
1193
is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1194
</p>
1195

1196
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
1197 1198
FunctionType   = "func" Signature .
Signature      = Parameters [ Result ] .
1199
Result         = Parameters | Type .
1200
Parameters     = "(" [ ParameterList [ "," ] ] ")" .
Rob Pike's avatar
Rob Pike committed
1201
ParameterList  = ParameterDecl { "," ParameterDecl } .
Russ Cox's avatar
Russ Cox committed
1202
ParameterDecl  = [ IdentifierList ] [ "..." ] Type .
1203 1204 1205
</pre>

<p>
Rob Pike's avatar
Rob Pike committed
1206 1207
Within a list of parameters or results, the names (IdentifierList)
must either all be present or all be absent. If present, each name
1208 1209 1210 1211 1212
stands for one item (parameter or result) of the specified type and
all non-<a href="#Blank_identifier">blank</a> names in the signature
must be <a href="#Uniqueness_of_identifiers">unique</a>.
If absent, each type stands for one item of that type.
Parameter and result
Rob Pike's avatar
Rob Pike committed
1213
lists are always parenthesized except that if there is exactly
Robert Griesemer's avatar
Robert Griesemer committed
1214
one unnamed result it may be written as an unparenthesized type.
Rob Pike's avatar
Rob Pike committed
1215
</p>
Russ Cox's avatar
Russ Cox committed
1216

Robert Griesemer's avatar
Robert Griesemer committed
1217
<p>
1218
The final incoming parameter in a function signature may have
Robert Griesemer's avatar
Robert Griesemer committed
1219 1220 1221
a type prefixed with <code>...</code>.
A function with such a parameter is called <i>variadic</i> and
may be invoked with zero or more arguments for that parameter.
Rob Pike's avatar
Rob Pike committed
1222
</p>
1223 1224

<pre>
Russ Cox's avatar
Russ Cox committed
1225
func()
Robert Griesemer's avatar
Robert Griesemer committed
1226 1227
func(x int) int
func(a, _ int, z float32) bool
1228
func(a, b int, z float32) (bool)
Robert Griesemer's avatar
Robert Griesemer committed
1229
func(prefix string, values ...int)
1230 1231
func(a, b int, z float64, opt ...interface{}) (success bool)
func(int, int, float64) (float64, *[]int)
Russ Cox's avatar
Russ Cox committed
1232
func(n int) func(p *T)
1233 1234 1235
</pre>


1236
<h3 id="Interface_types">Interface types</h3>
1237

Rob Pike's avatar
Rob Pike committed
1238
<p>
1239
An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>.
Robert Griesemer's avatar
Robert Griesemer committed
1240 1241
A variable of interface type can store a value of any type with a method set
that is any superset of the interface. Such a type is said to
1242
<i>implement the interface</i>.
1243
The value of an uninitialized variable of interface type is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1244
</p>
1245

1246
<pre class="ebnf">
1247
InterfaceType      = "interface" "{" { MethodSpec ";" } "}" .
1248 1249
MethodSpec         = MethodName Signature | InterfaceTypeName .
MethodName         = identifier .
Rob Pike's avatar
Rob Pike committed
1250
InterfaceTypeName  = TypeName .
1251
</pre>
1252

1253
<p>
1254
As with all method sets, in an interface type, each method must have a
1255 1256
<a href="#Uniqueness_of_identifiers">unique</a>
non-<a href="#Blank_identifier">blank</a> name.
1257 1258
</p>

1259
<pre>
1260
// A simple File interface.
1261
interface {
1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272
	Read([]byte) (int, error)
	Write([]byte) (int, error)
	Close() error
}
</pre>

<pre>
interface {
	String() string
	String() string  // illegal: String not unique
	_(x int)         // illegal: method must have non-blank name
1273 1274
}
</pre>
1275

Rob Pike's avatar
Rob Pike committed
1276
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1277
More than one type may implement an interface.
Rob Pike's avatar
Rob Pike committed
1278
For instance, if two types <code>S1</code> and <code>S2</code>
Robert Griesemer's avatar
Robert Griesemer committed
1279
have the method set
Rob Pike's avatar
Rob Pike committed
1280
</p>
1281

1282
<pre>
1283 1284 1285
func (p T) Read(p []byte) (n int, err error)   { return … }
func (p T) Write(p []byte) (n int, err error)  { return … }
func (p T) Close() error                       { return … }
1286
</pre>
1287

Rob Pike's avatar
Rob Pike committed
1288 1289 1290 1291 1292 1293
<p>
(where <code>T</code> stands for either <code>S1</code> or <code>S2</code>)
then the <code>File</code> interface is implemented by both <code>S1</code> and
<code>S2</code>, regardless of what other methods
<code>S1</code> and <code>S2</code> may have or share.
</p>
1294

Rob Pike's avatar
Rob Pike committed
1295 1296 1297 1298 1299
<p>
A type implements any interface comprising any subset of its methods
and may therefore implement several distinct interfaces. For
instance, all types implement the <i>empty interface</i>:
</p>
1300

1301
<pre>
1302
interface{}
1303
</pre>
1304

Rob Pike's avatar
Rob Pike committed
1305 1306
<p>
Similarly, consider this interface specification,
1307
which appears within a <a href="#Type_declarations">type declaration</a>
1308
to define an interface called <code>Locker</code>:
Rob Pike's avatar
Rob Pike committed
1309
</p>
1310 1311

<pre>
1312
type Locker interface {
1313 1314
	Lock()
	Unlock()
1315
}
1316
</pre>
1317

Rob Pike's avatar
Rob Pike committed
1318 1319 1320
<p>
If <code>S1</code> and <code>S2</code> also implement
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1321

1322
<pre>
1323 1324
func (p T) Lock() { … }
func (p T) Unlock() { … }
1325 1326
</pre>

1327
<p>
1328
they implement the <code>Locker</code> interface as well
Rob Pike's avatar
Rob Pike committed
1329 1330
as the <code>File</code> interface.
</p>
1331

Rob Pike's avatar
Rob Pike committed
1332
<p>
1333 1334 1335 1336 1337
An interface <code>T</code> may use a (possibly qualified) interface type
name <code>E</code> in place of a method specification. This is called
<i>embedding</i> interface <code>E</code> in <code>T</code>; it adds
all (exported and non-exported) methods of <code>E</code> to the interface
<code>T</code>.
Rob Pike's avatar
Rob Pike committed
1338
</p>
1339

1340
<pre>
1341
type ReadWriter interface {
1342 1343
	Read(b Buffer) bool
	Write(b Buffer) bool
1344
}
1345

1346
type File interface {
1347 1348
	ReadWriter  // same as adding the methods of ReadWriter
	Locker      // same as adding the methods of Locker
1349
	Close()
1350
}
1351 1352 1353 1354 1355 1356

type LockedFile interface {
	Locker
	File        // illegal: Lock, Unlock not unique
	Lock()      // illegal: Lock not unique
}
1357
</pre>
1358

1359
<p>
Russ Cox's avatar
Russ Cox committed
1360 1361
An interface type <code>T</code> may not embed itself
or any interface type that embeds <code>T</code>, recursively.
1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378
</p>

<pre>
// illegal: Bad cannot embed itself
type Bad interface {
	Bad
}

// illegal: Bad1 cannot embed itself using Bad2
type Bad1 interface {
	Bad2
}
type Bad2 interface {
	Bad1
}
</pre>

1379
<h3 id="Map_types">Map types</h3>
1380

Rob Pike's avatar
Rob Pike committed
1381 1382
<p>
A map is an unordered group of elements of one type, called the
1383
element type, indexed by a set of unique <i>keys</i> of another type,
1384
called the key type.
1385
The value of an uninitialized map is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1386
</p>
1387

1388
<pre class="ebnf">
1389
MapType     = "map" "[" KeyType "]" ElementType .
1390
KeyType     = Type .
1391
</pre>
1392

1393
<p>
1394 1395
The <a href="#Comparison_operators">comparison operators</a>
<code>==</code> and <code>!=</code> must be fully defined
1396 1397
for operands of the key type; thus the key type must not be a function, map, or
slice.
1398
If the key type is an interface type, these
Rob Pike's avatar
Rob Pike committed
1399
comparison operators must be defined for the dynamic key values;
1400
failure will cause a <a href="#Run_time_panics">run-time panic</a>.
Rob Pike's avatar
Rob Pike committed
1401 1402

</p>
1403

1404
<pre>
1405 1406 1407
map[string]int
map[*T]struct{ x, y float64 }
map[string]interface{}
1408
</pre>
1409

Rob Pike's avatar
Rob Pike committed
1410
<p>
1411 1412
The number of map elements is called its length.
For a map <code>m</code>, it can be discovered using the
1413
built-in function <a href="#Length_and_capacity"><code>len</code></a>
1414 1415
and may change during execution. Elements may be added during execution
using <a href="#Assignments">assignments</a> and retrieved with
1416
<a href="#Index_expressions">index expressions</a>; they may be removed with the
1417
<a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function.
Rob Pike's avatar
Rob Pike committed
1418 1419 1420
</p>
<p>
A new, empty map value is made using the built-in
1421 1422
function <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
which takes the map type and an optional capacity hint as arguments:
Rob Pike's avatar
Rob Pike committed
1423
</p>
1424

1425
<pre>
1426 1427
make(map[string]int)
make(map[string]int, 100)
1428
</pre>
1429

1430 1431 1432
<p>
The initial capacity does not bound its size:
maps grow to accommodate the number of items
1433 1434 1435
stored in them, with the exception of <code>nil</code> maps.
A <code>nil</code> map is equivalent to an empty map except that no elements
may be added.
1436

1437
<h3 id="Channel_types">Channel types</h3>
1438

Rob Pike's avatar
Rob Pike committed
1439
<p>
1440 1441 1442 1443 1444 1445
A channel provides a mechanism for
<a href="#Go_statements">concurrently executing functions</a>
to communicate by
<a href="#Send_statements">sending</a> and
<a href="#Receive_operator">receiving</a>
values of a specified element type.
1446
The value of an uninitialized channel is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1447
</p>
1448

1449
<pre class="ebnf">
1450
ChannelType = ( "chan" | "chan" "&lt;-" | "&lt;-" "chan" ) ElementType .
1451
</pre>
1452

1453
<p>
1454
The optional <code>&lt;-</code> operator specifies the channel <i>direction</i>,
1455
<i>send</i> or <i>receive</i>. If no direction is given, the channel is
1456
<i>bidirectional</i>.
1457 1458 1459
A channel may be constrained only to send or only to receive by
<a href="#Assignments">assignment</a> or
explicit <a href="#Conversions">conversion</a>.
1460 1461 1462
</p>

<pre>
1463 1464 1465
chan T          // can be used to send and receive values of type T
chan&lt;- float64  // can only be used to send float64s
&lt;-chan int      // can only be used to receive ints
1466 1467
</pre>

Rob Pike's avatar
Rob Pike committed
1468
<p>
1469 1470
The <code>&lt;-</code> operator associates with the leftmost <code>chan</code>
possible:
Rob Pike's avatar
Rob Pike committed
1471
</p>
1472

1473
<pre>
1474 1475 1476
chan&lt;- chan int    // same as chan&lt;- (chan int)
chan&lt;- &lt;-chan int  // same as chan&lt;- (&lt;-chan int)
&lt;-chan &lt;-chan int  // same as &lt;-chan (&lt;-chan int)
1477
chan (&lt;-chan int)
1478
</pre>
1479

Rob Pike's avatar
Rob Pike committed
1480
<p>
1481
A new, initialized channel
1482 1483
value can be made using the built-in function
<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
1484
which takes the channel type and an optional <i>capacity</i> as arguments:
Rob Pike's avatar
Rob Pike committed
1485
</p>
1486

1487
<pre>
1488
make(chan int, 100)
1489
</pre>
1490

Rob Pike's avatar
Rob Pike committed
1491
<p>
1492 1493
The capacity, in number of elements, sets the size of the buffer in the channel.
If the capacity is zero or absent, the channel is unbuffered and communication
1494 1495
succeeds only when both a sender and receiver are ready. Otherwise, the channel
is buffered and communication succeeds without blocking if the buffer
1496
is not full (sends) or not empty (receives).
1497
A <code>nil</code> channel is never ready for communication.
Rob Pike's avatar
Rob Pike committed
1498
</p>
1499

1500
<p>
1501
A channel may be closed with the built-in function
1502 1503
<a href="#Close"><code>close</code></a>.
The multi-valued assignment form of the
1504
<a href="#Receive_operator">receive operator</a>
1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520
reports whether a received value was sent before
the channel was closed.
</p>

<p>
A single channel may be used in
<a href="#Send_statements">send statements</a>,
<a href="#Receive_operator">receive operations</a>,
and calls to the built-in functions
<a href="#Length_and_capacity"><code>cap</code></a> and
<a href="#Length_and_capacity"><code>len</code></a>
by any number of goroutines without further synchronization.
Channels act as first-in-first-out queues.
For example, if one goroutine sends values on a channel
and a second goroutine receives them, the values are
received in the order sent.
1521 1522
</p>

1523
<h2 id="Properties_of_types_and_values">Properties of types and values</h2>
1524

1525 1526
<h3 id="Type_identity">Type identity</h3>

1527
<p>
1528
Two types are either <i>identical</i> or <i>different</i>.
1529
</p>
1530

1531
<p>
1532 1533 1534 1535
A <a href="#Type_definitions">defined type</a> is always different from any other type.
Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are
structurally equivalent; that is, they have the same literal structure and corresponding
components have identical types. In detail:
1536
</p>
Rob Pike's avatar
Rob Pike committed
1537

1538
<ul>
1539 1540
	<li>Two array types are identical if they have identical element types and
	    the same array length.</li>
1541

1542
	<li>Two slice types are identical if they have identical element types.</li>
1543

1544
	<li>Two struct types are identical if they have the same sequence of fields,
1545 1546
	    and if corresponding fields have the same names, and identical types,
	    and identical tags.
1547 1548
	    <a href="#Exported_identifiers">Non-exported</a> field names from different
	    packages are always different.</li>
1549

1550
	<li>Two pointer types are identical if they have identical base types.</li>
1551

1552
	<li>Two function types are identical if they have the same number of parameters
Russ Cox's avatar
Russ Cox committed
1553 1554
	    and result values, corresponding parameter and result types are
	    identical, and either both functions are variadic or neither is.
1555
	    Parameter and result names are not required to match.</li>
1556

1557
	<li>Two interface types are identical if they have the same set of methods
1558 1559 1560
	    with the same names and identical function types.
	    <a href="#Exported_identifiers">Non-exported</a> method names from different
	    packages are always different. The order of the methods is irrelevant.</li>
1561

1562
	<li>Two map types are identical if they have identical key and element types.</li>
1563

1564
	<li>Two channel types are identical if they have identical element types and
1565
	    the same direction.</li>
1566 1567 1568
</ul>

<p>
Rob Pike's avatar
Rob Pike committed
1569 1570
Given the declarations
</p>
1571 1572 1573

<pre>
type (
1574 1575 1576 1577 1578 1579
	A0 = []string
	A1 = A0
	A2 = struct{ a, b int }
	A3 = int
	A4 = func(A3, float64) *A0
	A5 = func(x int, _ float64) *[]string
1580
)
1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591

type (
	B0 A0
	B1 []string
	B2 struct{ a, b int }
	B3 struct{ a, c int }
	B4 func(int, float64) *B0
	B5 func(x int, y float64) *A1
)

type	C0 = B0
1592
</pre>
1593

Rob Pike's avatar
Rob Pike committed
1594
<p>
1595
these types are identical:
Rob Pike's avatar
Rob Pike committed
1596
</p>
1597

1598
<pre>
1599 1600 1601 1602 1603
A0, A1, and []string
A2 and struct{ a, b int }
A3 and int
A4, func(int, float64) *[]string, and A5

1604
B0 and C0
1605
[]int and []int
1606
struct{ a, b *T5 } and struct{ a, b *T5 }
1607
func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5
1608
</pre>
1609

Rob Pike's avatar
Rob Pike committed
1610
<p>
1611 1612 1613 1614
<code>B0</code> and <code>B1</code> are different because they are new types
created by distinct <a href="#Type_definitions">type definitions</a>;
<code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code>
are different because <code>B0</code> is different from <code>[]string</code>.
Rob Pike's avatar
Rob Pike committed
1615
</p>
1616 1617


1618
<h3 id="Assignability">Assignability</h3>
Rob Pike's avatar
Rob Pike committed
1619 1620

<p>
Robert Griesemer's avatar
Robert Griesemer committed
1621
A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code>
1622
("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies:
Rob Pike's avatar
Rob Pike committed
1623
</p>
1624

Rob Pike's avatar
Rob Pike committed
1625 1626
<ul>
<li>
1627 1628 1629
<code>x</code>'s type is identical to <code>T</code>.
</li>
<li>
1630 1631
<code>x</code>'s type <code>V</code> and <code>T</code> have identical
<a href="#Types">underlying types</a> and at least one of <code>V</code>
1632
or <code>T</code> is not a <a href="#Type_definitions">defined</a> type.
Robert Griesemer's avatar
Robert Griesemer committed
1633 1634
</li>
<li>
1635
<code>T</code> is an interface type and
1636 1637 1638 1639 1640
<code>x</code> <a href="#Interface_types">implements</a> <code>T</code>.
</li>
<li>
<code>x</code> is a bidirectional channel value, <code>T</code> is a channel type,
<code>x</code>'s type <code>V</code> and <code>T</code> have identical element types,
1641
and at least one of <code>V</code> or <code>T</code> is not a defined type.
Rob Pike's avatar
Rob Pike committed
1642 1643
</li>
<li>
1644 1645 1646 1647
<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
is a pointer, function, slice, map, channel, or interface type.
</li>
<li>
1648 1649
<code>x</code> is an untyped <a href="#Constants">constant</a>
<a href="#Representability">representable</a>
1650
by a value of type <code>T</code>.
Robert Griesemer's avatar
Robert Griesemer committed
1651
</li>
Rob Pike's avatar
Rob Pike committed
1652 1653
</ul>

1654

1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709
<h3 id="Representability">Representability</h3>

<p>
A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i>
by a value of type <code>T</code> if one of the following conditions applies:
</p>

<ul>
<li>
<code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>.
</li>

<li>
<code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s
precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE
negative zero further simplified to an unsigned zero. Note that constant values never result
in an IEEE negative zero, NaN, or infinity.
</li>

<li>
<code>T</code> is a complex type, and <code>x</code>'s
<a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code>
are representable by values of <code>T</code>'s component type (<code>float32</code> or
<code>float64</code>).
</li>
</ul>

<pre>
x                   T           x is representable by a value of T because

'a'                 byte        97 is in the set of byte values
97                  rune        rune is an alias for int32, and 97 is in the set of 32-bit integers
"foo"               string      "foo" is in the set of string values
1024                int16       1024 is in the set of 16-bit integers
42.0                byte        42 is in the set of unsigned 8-bit integers
1e10                uint64      10000000000 is in the set of unsigned 64-bit integers
2.718281828459045   float32     2.718281828459045 rounds to 2.7182817 which is in the set of float32 values
-1e-1000            float64     -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0
0i                  int         0 is an integer value
(42 + 0i)           float32     42.0 (with zero imaginary part) is in the set of float32 values
</pre>

<pre>
x                   T           x is not representable by a value of T because

0                   bool        0 is not in the set of boolean values
'a'                 string      'a' is a rune, it is not in the set of string values
1024                byte        1024 is not in the set of unsigned 8-bit integers
-1                  uint16      -1 is not in the set of unsigned 16-bit integers
1.1                 int         1.1 is not an integer value
42i                 float32     (0 + 42i) is not in the set of float32 values
1e1000              float64     1e1000 overflows to IEEE +Inf after rounding
</pre>


1710
<h2 id="Blocks">Blocks</h2>
Robert Griesemer's avatar
Robert Griesemer committed
1711 1712

<p>
1713 1714
A <i>block</i> is a possibly empty sequence of declarations and statements
within matching brace brackets.
Robert Griesemer's avatar
Robert Griesemer committed
1715 1716 1717
</p>

<pre class="ebnf">
1718 1719
Block = "{" StatementList "}" .
StatementList = { Statement ";" } .
Robert Griesemer's avatar
Robert Griesemer committed
1720 1721 1722 1723 1724 1725 1726 1727 1728
</pre>

<p>
In addition to explicit blocks in the source code, there are implicit blocks:
</p>

<ol>
	<li>The <i>universe block</i> encompasses all Go source text.</li>

Robert Griesemer's avatar
Robert Griesemer committed
1729
	<li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
Robert Griesemer's avatar
Robert Griesemer committed
1730 1731 1732 1733 1734
	    Go source text for that package.</li>

	<li>Each file has a <i>file block</i> containing all Go source text
	    in that file.</li>

1735 1736 1737
	<li>Each <a href="#If_statements">"if"</a>,
	    <a href="#For_statements">"for"</a>, and
	    <a href="#Switch_statements">"switch"</a>
Robert Griesemer's avatar
Robert Griesemer committed
1738 1739
	    statement is considered to be in its own implicit block.</li>

1740 1741
	<li>Each clause in a <a href="#Switch_statements">"switch"</a>
	    or <a href="#Select_statements">"select"</a> statement
Robert Griesemer's avatar
Robert Griesemer committed
1742 1743 1744 1745
	    acts as an implicit block.</li>
</ol>

<p>
Robert Griesemer's avatar
Robert Griesemer committed
1746
Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
Robert Griesemer's avatar
Robert Griesemer committed
1747 1748 1749
</p>


1750
<h2 id="Declarations_and_scope">Declarations and scope</h2>
1751 1752

<p>
1753 1754 1755 1756 1757 1758 1759
A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a
<a href="#Constant_declarations">constant</a>,
<a href="#Type_declarations">type</a>,
<a href="#Variable_declarations">variable</a>,
<a href="#Function_declarations">function</a>,
<a href="#Labeled_statements">label</a>, or
<a href="#Import_declarations">package</a>.
1760
Every identifier in a program must be declared.
Robert Griesemer's avatar
Robert Griesemer committed
1761 1762
No identifier may be declared twice in the same block, and
no identifier may be declared in both the file and package block.
1763
</p>
1764

1765 1766 1767
<p>
The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
in a declaration, but it does not introduce a binding and thus is not declared.
1768 1769 1770
In the package block, the identifier <code>init</code> may only be used for
<a href="#Package_initialization"><code>init</code> function</a> declarations,
and like the blank identifier it does not introduce a new binding.
1771 1772
</p>

1773
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
1774 1775
Declaration   = ConstDecl | TypeDecl | VarDecl .
TopLevelDecl  = Declaration | FunctionDecl | MethodDecl .
1776
</pre>
1777

1778
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1779
The <i>scope</i> of a declared identifier is the extent of source text in which
1780
the identifier denotes the specified constant, type, variable, function, label, or package.
1781
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1782

1783
<p>
1784
Go is lexically scoped using <a href="#Blocks">blocks</a>:
1785
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1786

1787
<ol>
1788
	<li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li>
Robert Griesemer's avatar
Robert Griesemer committed
1789 1790

	<li>The scope of an identifier denoting a constant, type, variable,
1791 1792
	    or function (but not method) declared at top level (outside any
	    function) is the package block.</li>
Robert Griesemer's avatar
Robert Griesemer committed
1793

1794
	<li>The scope of the package name of an imported package is the file block
Robert Griesemer's avatar
Robert Griesemer committed
1795 1796
	    of the file containing the import declaration.</li>

1797 1798
	<li>The scope of an identifier denoting a method receiver, function parameter,
	    or result variable is the function body.</li>
Robert Griesemer's avatar
Robert Griesemer committed
1799 1800 1801

	<li>The scope of a constant or variable identifier declared
	    inside a function begins at the end of the ConstSpec or VarSpec
1802
	    (ShortVarDecl for short variable declarations)
Robert Griesemer's avatar
Robert Griesemer committed
1803 1804 1805
	    and ends at the end of the innermost containing block.</li>

	<li>The scope of a type identifier declared inside a function
Russ Cox's avatar
Russ Cox committed
1806
	    begins at the identifier in the TypeSpec
Robert Griesemer's avatar
Robert Griesemer committed
1807
	    and ends at the end of the innermost containing block.</li>
1808
</ol>
1809

1810
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1811 1812 1813
An identifier declared in a block may be redeclared in an inner block.
While the identifier of the inner declaration is in scope, it denotes
the entity declared by the inner declaration.
1814
</p>
1815

Robert Griesemer's avatar
Robert Griesemer committed
1816
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1817
The <a href="#Package_clause">package clause</a> is not a declaration; the package name
Robert Griesemer's avatar
Robert Griesemer committed
1818
does not appear in any scope. Its purpose is to identify the files belonging
1819
to the same <a href="#Packages">package</a> and to specify the default package name for import
Robert Griesemer's avatar
Robert Griesemer committed
1820 1821
declarations.
</p>
1822 1823


1824
<h3 id="Label_scopes">Label scopes</h3>
1825

Robert Griesemer's avatar
Robert Griesemer committed
1826
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1827
Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
1828 1829 1830
used in the <a href="#Break_statements">"break"</a>,
<a href="#Continue_statements">"continue"</a>, and
<a href="#Goto_statements">"goto"</a> statements.
Russ Cox's avatar
Russ Cox committed
1831
It is illegal to define a label that is never used.
Robert Griesemer's avatar
Robert Griesemer committed
1832 1833 1834 1835 1836
In contrast to other identifiers, labels are not block scoped and do
not conflict with identifiers that are not labels. The scope of a label
is the body of the function in which it is declared and excludes
the body of any nested function.
</p>
1837 1838


1839 1840 1841
<h3 id="Blank_identifier">Blank identifier</h3>

<p>
1842 1843 1844 1845
The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
It serves as an anonymous placeholder instead of a regular (non-blank)
identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>.
1846 1847 1848
</p>


1849
<h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
1850

1851
<p>
1852 1853
The following identifiers are implicitly declared in the
<a href="#Blocks">universe block</a>:
1854 1855
</p>
<pre class="grammar">
Russ Cox's avatar
Russ Cox committed
1856 1857 1858 1859
Types:
	bool byte complex64 complex128 error float32 float64
	int int8 int16 int32 int64 rune string
	uint uint8 uint16 uint32 uint64 uintptr
1860

1861
Constants:
1862 1863 1864 1865
	true false iota

Zero value:
	nil
1866

1867
Functions:
1868
	append cap close complex copy delete imag len
Robert Griesemer's avatar
Robert Griesemer committed
1869
	make new panic print println real recover
1870
</pre>
1871

1872

1873
<h3 id="Exported_identifiers">Exported identifiers</h3>
Robert Griesemer's avatar
Robert Griesemer committed
1874

1875
<p>
1876 1877
An identifier may be <i>exported</i> to permit access to it from another package.
An identifier is exported if both:
1878 1879
</p>
<ol>
1880 1881 1882 1883 1884
	<li>the first character of the identifier's name is a Unicode upper case
	letter (Unicode class "Lu"); and</li>
	<li>the identifier is declared in the <a href="#Blocks">package block</a>
	or it is a <a href="#Struct_types">field name</a> or
	<a href="#MethodName">method name</a>.</li>
1885
</ol>
1886
<p>
1887
All other identifiers are not exported.
1888
</p>
1889

1890

1891
<h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3>
Robert Griesemer's avatar
Robert Griesemer committed
1892 1893

<p>
1894 1895 1896 1897
Given a set of identifiers, an identifier is called <i>unique</i> if it is
<i>different</i> from every other in the set.
Two identifiers are different if they are spelled differently, or if they
appear in different <a href="#Packages">packages</a> and are not
Shenghou Ma's avatar
Shenghou Ma committed
1898
<a href="#Exported_identifiers">exported</a>. Otherwise, they are the same.
Robert Griesemer's avatar
Robert Griesemer committed
1899 1900
</p>

1901
<h3 id="Constant_declarations">Constant declarations</h3>
1902

1903 1904
<p>
A constant declaration binds a list of identifiers (the names of
Robert Griesemer's avatar
Robert Griesemer committed
1905 1906 1907 1908
the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>.
The number of identifiers must be equal
to the number of expressions, and the <i>n</i>th identifier on
the left is bound to the value of the <i>n</i>th expression on the
1909 1910
right.
</p>
1911

1912
<pre class="ebnf">
1913
ConstDecl      = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
1914
ConstSpec      = IdentifierList [ [ Type ] "=" ExpressionList ] .
1915

1916 1917
IdentifierList = identifier { "," identifier } .
ExpressionList = Expression { "," Expression } .
1918
</pre>
1919

1920
<p>
1921
If the type is present, all constants take the type specified, and
1922
the expressions must be <a href="#Assignability">assignable</a> to that type.
1923
If the type is omitted, the constants take the
1924 1925 1926 1927 1928 1929
individual types of the corresponding expressions.
If the expression values are untyped <a href="#Constants">constants</a>,
the declared constants remain untyped and the constant identifiers
denote the constant values. For instance, if the expression is a
floating-point literal, the constant identifier denotes a floating-point
constant, even if the literal's fractional part is zero.
1930
</p>
1931

1932
<pre>
1933
const Pi float64 = 3.14159265358979323846
1934
const zero = 0.0         // untyped floating-point constant
1935
const (
1936
	size int64 = 1024
1937
	eof        = -1  // untyped integer constant
1938
)
1939
const a, b, c = 3, 4, "foo"  // a = 3, b = 4, c = "foo", untyped integer and string constants
1940
const u, v float32 = 0, 3    // u = 0.0, v = 3.0
1941
</pre>
1942

1943 1944
<p>
Within a parenthesized <code>const</code> declaration list the
1945
expression list may be omitted from any but the first ConstSpec.
1946
Such an empty list is equivalent to the textual substitution of the
Rob Pike's avatar
Rob Pike committed
1947
first preceding non-empty expression list and its type if any.
1948 1949 1950
Omitting the list of expressions is therefore equivalent to
repeating the previous list.  The number of identifiers must be equal
to the number of expressions in the previous list.
Robert Griesemer's avatar
Robert Griesemer committed
1951 1952
Together with the <a href="#Iota"><code>iota</code> constant generator</a>
this mechanism permits light-weight declaration of sequential values:
1953
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1954

1955
<pre>
1956
const (
1957 1958 1959 1960 1961 1962 1963 1964
	Sunday = iota
	Monday
	Tuesday
	Wednesday
	Thursday
	Friday
	Partyday
	numberOfDays  // this constant is not exported
1965
)
1966
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
1967 1968


1969
<h3 id="Iota">Iota</h3>
1970

1971
<p>
1972
Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
1973
<code>iota</code> represents successive untyped integer <a href="#Constants">
1974 1975
constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a>
in that constant declaration, starting at zero.
1976
It can be used to construct a set of related constants:
1977
</p>
1978

1979
<pre>
1980
const (
1981 1982 1983
	c0 = iota  // c0 == 0
	c1 = iota  // c1 == 1
	c2 = iota  // c2 == 2
1984 1985
)

1986 1987 1988 1989 1990
const (
	a = 1 &lt;&lt; iota  // a == 1  (iota == 0)
	b = 1 &lt;&lt; iota  // b == 2  (iota == 1)
	c = 3          // c == 3  (iota == 2, unused)
	d = 1 &lt;&lt; iota  // d == 8  (iota == 3)
1991 1992
)

1993
const (
1994 1995 1996
	u         = iota * 42  // u == 0     (untyped integer constant)
	v float64 = iota * 42  // v == 42.0  (float64 constant)
	w         = iota * 42  // w == 84    (untyped integer constant)
1997 1998
)

1999 2000
const x = iota  // x == 0
const y = iota  // y == 0
2001
</pre>
2002

2003
<p>
2004
By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value:
2005
</p>
2006

2007
<pre>
2008
const (
2009 2010 2011 2012
	bit0, mask0 = 1 &lt;&lt; iota, 1&lt;&lt;iota - 1  // bit0 == 1, mask0 == 0  (iota == 0)
	bit1, mask1                           // bit1 == 2, mask1 == 1  (iota == 1)
	_, _                                  //                        (iota == 2, unused)
	bit3, mask3                           // bit3 == 8, mask3 == 7  (iota == 3)
2013
)
2014
</pre>
2015

2016
<p>
2017 2018
This last example exploits the <a href="#Constant_declarations">implicit repetition</a>
of the last non-empty expression list.
2019
</p>
2020 2021


2022
<h3 id="Type_declarations">Type declarations</h3>
2023

2024
<p>
2025
A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>.
2026
Type declarations come in two forms: alias declarations and type definitions.
2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037
<p>

<pre class="ebnf">
TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
TypeSpec = AliasDecl | TypeDef .
</pre>

<h4 id="Alias_declarations">Alias declarations</h4>

<p>
An alias declaration binds an identifier to the given type.
2038
</p>
2039

2040
<pre class="ebnf">
2041
AliasDecl = identifier "=" Type .
2042
</pre>
2043

2044 2045 2046 2047 2048
<p>
Within the <a href="#Declarations_and_scope">scope</a> of
the identifier, it serves as an <i>alias</i> for the type.
</p>

2049
<pre>
2050 2051 2052 2053 2054
type (
	nodeList = []*Node  // nodeList and []*Node are identical types
	Polar    = polar    // Polar and polar denote identical types
)
</pre>
2055

2056 2057 2058 2059

<h4 id="Type_definitions">Type definitions</h4>

<p>
2060 2061 2062
A type definition creates a new, distinct type with the same
<a href="#Types">underlying type</a> and operations as the given type,
and binds an identifier to it.
2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075
</p>

<pre class="ebnf">
TypeDef = identifier Type .
</pre>

<p>
The new type is called a <i>defined type</i>.
It is <a href="#Type_identity">different</a> from any other type,
including the type it is created from.
</p>

<pre>
2076
type (
2077 2078
	Point struct{ x, y float64 }  // Point and struct{ x, y float64 } are different types
	polar Point                   // polar and Point denote different types
2079
)
2080

2081
type TreeNode struct {
2082 2083
	left, right *TreeNode
	value *Comparable
2084 2085
}

2086
type Block interface {
2087 2088 2089
	BlockSize() int
	Encrypt(src, dst []byte)
	Decrypt(src, dst []byte)
2090
}
2091
</pre>
2092

2093
<p>
2094 2095 2096
A defined type may have <a href="#Method_declarations">methods</a> associated with it.
It does not inherit any methods bound to the given type,
but the <a href="#Method_sets">method set</a>
2097
of an interface type or of elements of a composite type remains unchanged:
2098 2099 2100
</p>

<pre>
Rob Pike's avatar
Rob Pike committed
2101
// A Mutex is a data type with two methods, Lock and Unlock.
2102 2103 2104 2105 2106 2107 2108
type Mutex struct         { /* Mutex fields */ }
func (m *Mutex) Lock()    { /* Lock implementation */ }
func (m *Mutex) Unlock()  { /* Unlock implementation */ }

// NewMutex has the same composition as Mutex but its method set is empty.
type NewMutex Mutex

2109
// The method set of PtrMutex's underlying type *Mutex remains unchanged,
2110 2111 2112
// but the method set of PtrMutex is empty.
type PtrMutex *Mutex

2113
// The method set of *PrintableMutex contains the methods
2114
// Lock and Unlock bound to its embedded field Mutex.
2115
type PrintableMutex struct {
2116
	Mutex
2117
}
2118

2119 2120
// MyBlock is an interface type that has the same method set as Block.
type MyBlock Block
2121 2122 2123
</pre>

<p>
2124 2125
Type definitions may be used to define different boolean, numeric,
or string types and associate methods with them:
2126 2127 2128 2129 2130 2131
</p>

<pre>
type TimeZone int

const (
2132 2133 2134 2135
	EST TimeZone = -(5 + iota)
	CST
	MST
	PST
2136 2137 2138
)

func (tz TimeZone) String() string {
2139
	return fmt.Sprintf("GMT%+dh", tz)
2140 2141 2142 2143
}
</pre>


2144
<h3 id="Variable_declarations">Variable declarations</h3>
2145 2146

<p>
2147 2148
A variable declaration creates one or more <a href="#Variables">variables</a>,
binds corresponding identifiers to them, and gives each a type and an initial value.
2149
</p>
2150

2151
<pre class="ebnf">
2152
VarDecl     = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
2153
VarSpec     = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
2154
</pre>
2155

2156
<pre>
2157
var i int
2158
var U, V, W float64
2159
var k = 0
2160
var x, y float32 = -1, -2
2161
var (
2162
	i       int
2163 2164
	u, v, s = 2.0, 3.0, "bar"
)
Robert Griesemer's avatar
Robert Griesemer committed
2165
var re, im = complexSqrt(-1)
2166
var _, found = entries[name]  // map lookup; only interested in "found"
2167
</pre>
2168

2169
<p>
2170
If a list of expressions is given, the variables are initialized
2171
with the expressions following the rules for <a href="#Assignments">assignments</a>.
2172
Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
2173
</p>
2174

2175
<p>
2176 2177 2178
If a type is present, each variable is given that type.
Otherwise, each variable is given the type of the corresponding
initialization value in the assignment.
2179
If that value is an untyped constant, it is first implicitly
2180
<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
2181
if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
2182 2183
The predeclared value <code>nil</code> cannot be used to initialize a variable
with no explicit type.
2184
</p>
2185

2186
<pre>
2187
var d = math.Sin(0.5)  // d is float64
2188 2189 2190 2191
var i = 42             // i is int
var t, ok = x.(T)      // t is T, ok is bool
var n = nil            // illegal
</pre>
2192 2193 2194 2195 2196 2197

<p>
Implementation restriction: A compiler may make it illegal to declare a variable
inside a <a href="#Function_declarations">function body</a> if the variable is
never used.
</p>
2198

2199
<h3 id="Short_variable_declarations">Short variable declarations</h3>
2200

2201
<p>
2202
A <i>short variable declaration</i> uses the syntax:
2203
</p>
2204

2205
<pre class="ebnf">
2206
ShortVarDecl = IdentifierList ":=" ExpressionList .
2207
</pre>
2208

2209
<p>
2210
It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
2211
with initializer expressions but no types:
2212
</p>
2213

2214 2215
<pre class="grammar">
"var" IdentifierList = ExpressionList .
2216
</pre>
2217

2218
<pre>
2219 2220 2221
i, j := 0, 10
f := func() int { return 7 }
ch := make(chan int)
2222 2223
r, w, _ := os.Pipe()  // os.Pipe() returns a connected pair of Files and an error, if any
_, y, _ := coord(p)   // coord() returns three values; only interested in y coordinate
2224
</pre>
2225

Rob Pike's avatar
Rob Pike committed
2226
<p>
2227 2228
Unlike regular variable declarations, a short variable declaration may <i>redeclare</i>
variables provided they were originally declared earlier in the same block
2229
(or the parameter lists if the block is the function body) with the same type,
2230 2231 2232
and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new.
As a consequence, redeclaration can only appear in a multi-variable short declaration.
Redeclaration does not introduce a new variable; it just assigns a new value to the original.
Rob Pike's avatar
Rob Pike committed
2233 2234 2235
</p>

<pre>
2236 2237
field1, offset := nextField(str, 0)
field2, offset := nextField(str, offset)  // redeclares offset
2238
a, a := 1, 2                              // illegal: double declaration of a or no new variable if a was declared elsewhere
Rob Pike's avatar
Rob Pike committed
2239 2240
</pre>

Rob Pike's avatar
Rob Pike committed
2241
<p>
2242
Short variable declarations may appear only inside functions.
2243 2244 2245 2246 2247
In some contexts such as the initializers for
<a href="#If_statements">"if"</a>,
<a href="#For_statements">"for"</a>, or
<a href="#Switch_statements">"switch"</a> statements,
they can be used to declare local temporary variables.
Rob Pike's avatar
Rob Pike committed
2248
</p>
2249

2250
<h3 id="Function_declarations">Function declarations</h3>
2251

2252
<p>
2253 2254
A function declaration binds an identifier, the <i>function name</i>,
to a function.
2255
</p>
2256

2257
<pre class="ebnf">
2258
FunctionDecl = "func" FunctionName Signature [ FunctionBody ] .
2259
FunctionName = identifier .
2260
FunctionBody = Block .
2261
</pre>
2262

2263 2264 2265 2266 2267 2268
<p>
If the function's <a href="#Function_types">signature</a> declares
result parameters, the function body's statement list must end in
a <a href="#Terminating_statements">terminating statement</a>.
</p>

2269
<pre>
2270 2271 2272 2273
func IndexRune(s string, r rune) int {
	for i, c := range s {
		if c == r {
			return i
2274 2275
		}
	}
2276
	// invalid: missing return statement
2277 2278 2279
}
</pre>

2280 2281 2282 2283 2284
<p>
A function declaration may omit the body. Such a declaration provides the
signature for a function implemented outside Go, such as an assembly routine.
</p>

2285 2286 2287
<pre>
func min(x int, y int) int {
	if x &lt; y {
2288
		return x
2289
	}
2290
	return y
2291
}
2292 2293

func flushICache(begin, end uintptr)  // implemented externally
2294
</pre>
2295

2296
<h3 id="Method_declarations">Method declarations</h3>
2297

2298
<p>
2299 2300 2301
A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
A method declaration binds an identifier, the <i>method name</i>, to a method,
and associates the method with the receiver's <i>base type</i>.
Rob Pike's avatar
Rob Pike committed
2302
</p>
2303

2304
<pre class="ebnf">
2305
MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] .
2306
Receiver   = Parameters .
2307 2308
</pre>

2309
<p>
Paolo Martini's avatar
Paolo Martini committed
2310
The receiver is specified via an extra parameter section preceding the method
2311
name. That parameter section must declare a single non-variadic parameter, the receiver.
2312 2313 2314 2315 2316
Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a
pointer to a defined type <code>T</code>. <code>T</code> is called the receiver
<i>base type</i>. A receiver base type cannot be a pointer or interface type and
it must be defined in the same package as the method.
The method is said to be <i>bound</i> to its receiver base type and the method name
2317 2318
is visible only within <a href="#Selectors">selectors</a> for type <code>T</code>
or <code>*T</code>.
2319 2320 2321
</p>

<p>
2322 2323 2324 2325 2326 2327 2328 2329 2330
A non-<a href="#Blank_identifier">blank</a> receiver identifier must be
<a href="#Uniqueness_of_identifiers">unique</a> in the method signature.
If the receiver's value is not referenced inside the body of the method,
its identifier may be omitted in the declaration. The same applies in
general to parameters of functions and methods.
</p>

<p>
For a base type, the non-blank names of methods bound to it must be unique.
2331 2332
If the base type is a <a href="#Struct_types">struct type</a>,
the non-blank method and field names must be distinct.
Rob Pike's avatar
Rob Pike committed
2333
</p>
2334

2335
<p>
2336
Given defined type <code>Point</code>, the declarations
2337
</p>
2338

2339
<pre>
2340 2341
func (p *Point) Length() float64 {
	return math.Sqrt(p.x * p.x + p.y * p.y)
2342
}
2343

2344 2345 2346
func (p *Point) Scale(factor float64) {
	p.x *= factor
	p.y *= factor
2347 2348
}
</pre>
2349

2350
<p>
Rob Pike's avatar
Rob Pike committed
2351 2352
bind the methods <code>Length</code> and <code>Scale</code>,
with receiver type <code>*Point</code>,
2353 2354
to the base type <code>Point</code>.
</p>
2355

Rob Pike's avatar
Rob Pike committed
2356 2357 2358 2359 2360 2361
<p>
The type of a method is the type of a function with the receiver as first
argument.  For instance, the method <code>Scale</code> has type
</p>

<pre>
2362
func(p *Point, factor float64)
Rob Pike's avatar
Rob Pike committed
2363 2364 2365 2366 2367 2368
</pre>

<p>
However, a function declared this way is not a method.
</p>

2369

2370
<h2 id="Expressions">Expressions</h2>
2371

2372
<p>
Rob Pike's avatar
Rob Pike committed
2373
An expression specifies the computation of a value by applying
2374
operators and functions to operands.
Rob Pike's avatar
Rob Pike committed
2375
</p>
2376

2377
<h3 id="Operands">Operands</h3>
2378

2379
<p>
2380
Operands denote the elementary values in an expression. An operand may be a
2381 2382
literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
non-<a href="#Blank_identifier">blank</a> identifier denoting a
2383 2384 2385 2386
<a href="#Constant_declarations">constant</a>,
<a href="#Variable_declarations">variable</a>, or
<a href="#Function_declarations">function</a>,
or a parenthesized expression.
2387
</p>
2388

2389 2390 2391 2392 2393
<p>
The <a href="#Blank_identifier">blank identifier</a> may appear as an
operand only on the left-hand side of an <a href="#Assignments">assignment</a>.
</p>

2394
<pre class="ebnf">
2395
Operand     = Literal | OperandName | "(" Expression ")" .
2396 2397
Literal     = BasicLit | CompositeLit | FunctionLit .
BasicLit    = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
2398
OperandName = identifier | QualifiedIdent.
2399
</pre>
2400

2401
<h3 id="Qualified_identifiers">Qualified identifiers</h3>
2402

2403
<p>
2404 2405 2406
A qualified identifier is an identifier qualified with a package name prefix.
Both the package name and the identifier must not be
<a href="#Blank_identifier">blank</a>.
Rob Pike's avatar
Rob Pike committed
2407
</p>
2408

2409
<pre class="ebnf">
2410
QualifiedIdent = PackageName "." identifier .
2411
</pre>
2412

Rob Pike's avatar
Rob Pike committed
2413
<p>
Robert Griesemer's avatar
Robert Griesemer committed
2414 2415
A qualified identifier accesses an identifier in a different package, which
must be <a href="#Import_declarations">imported</a>.
2416 2417
The identifier must be <a href="#Exported_identifiers">exported</a> and
declared in the <a href="#Blocks">package block</a> of that package.
Rob Pike's avatar
Rob Pike committed
2418 2419 2420
</p>

<pre>
2421
math.Sin	// denotes the Sin function in package math
Rob Pike's avatar
Rob Pike committed
2422
</pre>
2423

2424
<h3 id="Composite_literals">Composite literals</h3>
2425

Rob Pike's avatar
Rob Pike committed
2426 2427 2428
<p>
Composite literals construct values for structs, arrays, slices, and maps
and create a new value each time they are evaluated.
2429
They consist of the type of the literal followed by a brace-bound list of elements.
2430
Each element may optionally be preceded by a corresponding key.
Rob Pike's avatar
Rob Pike committed
2431
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2432

2433
<pre class="ebnf">
2434
CompositeLit  = LiteralType LiteralValue .
Rob Pike's avatar
Rob Pike committed
2435
LiteralType   = StructType | ArrayType | "[" "..." "]" ElementType |
2436
                SliceType | MapType | TypeName .
2437
LiteralValue  = "{" [ ElementList [ "," ] ] "}" .
2438 2439
ElementList   = KeyedElement { "," KeyedElement } .
KeyedElement  = [ Key ":" ] Element .
2440
Key           = FieldName | Expression | LiteralValue .
Rob Pike's avatar
Rob Pike committed
2441
FieldName     = identifier .
2442
Element       = Expression | LiteralValue .
2443
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2444

Rob Pike's avatar
Rob Pike committed
2445
<p>
2446
The LiteralType's underlying type must be a struct, array, slice, or map type
2447 2448
(the grammar enforces this constraint except when the type is given
as a TypeName).
2449
The types of the elements and keys must be <a href="#Assignability">assignable</a>
2450
to the respective field, element, and key types of the literal type;
2451
there is no additional conversion.
2452
The key is interpreted as a field name for struct literals,
2453
an index for array and slice literals, and a key for map literals.
2454 2455
For map literals, all elements must have a key. It is an error
to specify multiple elements with the same field name or
2456 2457
constant key value. For non-constant map keys, see the section on
<a href="#Order_of_evaluation">evaluation order</a>.
Rob Pike's avatar
Rob Pike committed
2458
</p>
2459

2460 2461
<p>
For struct literals the following rules apply:
2462
</p>
2463
<ul>
2464
	<li>A key must be a field name declared in the struct type.
2465
	</li>
2466
	<li>An element list that does not contain any keys must
2467 2468 2469 2470 2471
	    list an element for each struct field in the
	    order in which the fields are declared.
	</li>
	<li>If any element has a key, every element must have a key.
	</li>
2472
	<li>An element list that contains keys does not need to
2473 2474 2475 2476
	    have an element for each struct field. Omitted fields
	    get the zero value for that field.
	</li>
	<li>A literal may omit the element list; such a literal evaluates
2477
	    to the zero value for its type.
2478 2479 2480 2481 2482 2483 2484 2485 2486
	</li>
	<li>It is an error to specify an element for a non-exported
	    field of a struct belonging to a different package.
	</li>
</ul>

<p>
Given the declarations
</p>
2487
<pre>
2488 2489
type Point3D struct { x, y, z float64 }
type Line struct { p, q Point3D }
2490
</pre>
2491

Rob Pike's avatar
Rob Pike committed
2492 2493 2494
<p>
one may write
</p>
2495

2496
<pre>
2497 2498
origin := Point3D{}                            // zero value for Point3D
line := Line{origin, Point3D{y: -4, z: 12.3}}  // zero value for line.q.x
2499 2500
</pre>

2501 2502 2503
<p>
For array and slice literals the following rules apply:
</p>
2504 2505 2506 2507
<ul>
	<li>Each element has an associated integer index marking
	    its position in the array.
	</li>
2508
	<li>An element with a key uses the key as its index. The
2509 2510
	    key must be a non-negative constant
	    <a href="#Representability">representable</a> by
2511 2512
	    a value of type <code>int</code>; and if it is typed
	    it must be of integer type.
2513 2514 2515 2516 2517 2518
	</li>
	<li>An element without a key uses the previous element's index plus one.
	    If the first element has no key, its index is zero.
	</li>
</ul>

2519
<p>
2520
<a href="#Address_operators">Taking the address</a> of a composite literal
Robert Griesemer's avatar
Robert Griesemer committed
2521 2522
generates a pointer to a unique <a href="#Variables">variable</a> initialized
with the literal's value.
2523
</p>
2524

2525
<pre>
2526
var pointer *Point3D = &amp;Point3D{y: 1000}
2527
</pre>
2528

2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541
<p>
Note that the <a href="#The_zero_value">zero value</a> for a slice or map
type is not the same as an initialized but empty value of the same type.
Consequently, taking the address of an empty slice or map composite literal
does not have the same effect as allocating a new slice or map value with
<a href="#Allocation">new</a>.
</p>

<pre>
p1 := &[]int{}    // p1 points to an initialized, empty slice with value []int{} and length 0
p2 := new([]int)  // p2 points to an uninitialized slice with value nil and length 0
</pre>

Rob Pike's avatar
Rob Pike committed
2542
<p>
2543
The length of an array literal is the length specified in the literal type.
2544
If fewer elements than the length are provided in the literal, the missing
Rob Pike's avatar
Rob Pike committed
2545
elements are set to the zero value for the array element type.
2546 2547 2548
It is an error to provide elements with index values outside the index range
of the array. The notation <code>...</code> specifies an array length equal
to the maximum element index plus one.
Rob Pike's avatar
Rob Pike committed
2549
</p>
2550

2551
<pre>
2552 2553 2554
buffer := [10]string{}             // len(buffer) == 10
intSet := [6]int{1, 2, 3, 5}       // len(intSet) == 6
days := [...]string{"Sat", "Sun"}  // len(days) == 2
2555
</pre>
2556

Rob Pike's avatar
Rob Pike committed
2557 2558
<p>
A slice literal describes the entire underlying array literal.
2559
Thus the length and capacity of a slice literal are the maximum
2560
element index plus one. A slice literal has the form
Rob Pike's avatar
Rob Pike committed
2561
</p>
2562

2563
<pre>
2564
[]T{x1, x2, … xn}
2565
</pre>
2566

Rob Pike's avatar
Rob Pike committed
2567
<p>
2568
and is shorthand for a slice operation applied to an array:
Rob Pike's avatar
Rob Pike committed
2569
</p>
2570

2571
<pre>
2572 2573
tmp := [n]T{x1, x2, … xn}
tmp[0 : n]
2574
</pre>
2575

2576 2577
<p>
Within a composite literal of array, slice, or map type <code>T</code>,
2578 2579 2580 2581
elements or map keys that are themselves composite literals may elide the respective
literal type if it is identical to the element or key type of <code>T</code>.
Similarly, elements or keys that are addresses of composite literals may elide
the <code>&amp;T</code> when the element or key type is <code>*T</code>.
2582 2583 2584
</p>

<pre>
2585 2586 2587 2588 2589
[...]Point{{1.5, -3.5}, {0, 0}}     // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
[][]int{{1, 2, 3}, {4, 5}}          // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
[][]Point{{{0, 1}, {1, 2}}}         // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}}
map[string]Point{"orig": {0, 0}}    // same as map[string]Point{"orig": Point{0, 0}}
map[Point]string{{0, 0}: "orig"}    // same as map[Point]string{Point{0, 0}: "orig"}
2590 2591 2592 2593

type PPoint *Point
[2]*Point{{1.5, -3.5}, {}}          // same as [2]*Point{&amp;Point{1.5, -3.5}, &amp;Point{}}
[2]PPoint{{1.5, -3.5}, {}}          // same as [2]PPoint{PPoint(&amp;Point{1.5, -3.5}), PPoint(&amp;Point{})}
2594 2595
</pre>

2596 2597
<p>
A parsing ambiguity arises when a composite literal using the
2598 2599 2600 2601 2602 2603 2604
TypeName form of the LiteralType appears as an operand between the
<a href="#Keywords">keyword</a> and the opening brace of the block
of an "if", "for", or "switch" statement, and the composite literal
is not enclosed in parentheses, square brackets, or curly braces.
In this rare case, the opening brace of the literal is erroneously parsed
as the one introducing the block of statements. To resolve the ambiguity,
the composite literal must appear within parentheses.
2605 2606 2607
</p>

<pre>
2608 2609
if x == (T{a,b,c}[i]) { … }
if (x == T{a,b,c}[i]) { … }
2610 2611
</pre>

2612 2613 2614 2615 2616 2617
<p>
Examples of valid array, slice, and map literals:
</p>

<pre>
// list of prime numbers
2618
primes := []int{2, 3, 5, 7, 9, 2147483647}
2619 2620

// vowels[ch] is true if ch is a vowel
2621
vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
2622

2623 2624
// the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1}
filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}
2625 2626

// frequencies in Hz for equal-tempered scale (A4 = 440Hz)
2627
noteFrequency := map[string]float32{
2628 2629 2630 2631 2632 2633
	"C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
	"G0": 24.50, "A0": 27.50, "B0": 30.87,
}
</pre>


2634
<h3 id="Function_literals">Function literals</h3>
2635

Rob Pike's avatar
Rob Pike committed
2636
<p>
2637
A function literal represents an anonymous <a href="#Function_declarations">function</a>.
Rob Pike's avatar
Rob Pike committed
2638
</p>
2639

2640
<pre class="ebnf">
2641
FunctionLit = "func" Signature FunctionBody .
2642
</pre>
2643

2644
<pre>
2645
func(a, b int, z float64) bool { return a*b &lt; int(z) }
2646
</pre>
2647

Rob Pike's avatar
Rob Pike committed
2648 2649 2650
<p>
A function literal can be assigned to a variable or invoked directly.
</p>
2651

2652
<pre>
Rob Pike's avatar
Rob Pike committed
2653
f := func(x, y int) int { return x + y }
2654
func(ch chan int) { ch &lt;- ACK }(replyChan)
2655
</pre>
2656

Rob Pike's avatar
Rob Pike committed
2657 2658
<p>
Function literals are <i>closures</i>: they may refer to variables
2659 2660
defined in a surrounding function. Those variables are then shared between
the surrounding function and the function literal, and they survive as long
Rob Pike's avatar
Rob Pike committed
2661 2662
as they are accessible.
</p>
2663

2664

2665
<h3 id="Primary_expressions">Primary expressions</h3>
2666

2667 2668 2669 2670
<p>
Primary expressions are the operands for unary and binary expressions.
</p>

2671
<pre class="ebnf">
2672 2673
PrimaryExpr =
	Operand |
2674
	Conversion |
2675
	MethodExpr |
2676 2677 2678
	PrimaryExpr Selector |
	PrimaryExpr Index |
	PrimaryExpr Slice |
2679
	PrimaryExpr TypeAssertion |
2680
	PrimaryExpr Arguments .
2681

2682 2683
Selector       = "." identifier .
Index          = "[" Expression "]" .
2684 2685
Slice          = "[" [ Expression ] ":" [ Expression ] "]" |
                 "[" [ Expression ] ":" Expression ":" Expression "]" .
2686
TypeAssertion  = "." "(" Type ")" .
2687
Arguments      = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
2688 2689 2690 2691 2692 2693 2694 2695
</pre>


<pre>
x
2
(s + ".txt")
f(3.1415, true)
2696
Point{1, 2}
2697 2698 2699 2700 2701 2702 2703
m["foo"]
s[i : j + 1]
obj.color
f.p[i].x()
</pre>


2704
<h3 id="Selectors">Selectors</h3>
2705

Rob Pike's avatar
Rob Pike committed
2706
<p>
2707 2708 2709
For a <a href="#Primary_expressions">primary expression</a> <code>x</code>
that is not a <a href="#Package_clause">package name</a>, the
<i>selector expression</i>
Rob Pike's avatar
Rob Pike committed
2710
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2711

2712 2713 2714
<pre>
x.f
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2715

2716
<p>
2717 2718 2719 2720 2721 2722 2723
denotes the field or method <code>f</code> of the value <code>x</code>
(or sometimes <code>*x</code>; see below).
The identifier <code>f</code> is called the (field or method) <i>selector</i>;
it must not be the <a href="#Blank_identifier">blank identifier</a>.
The type of the selector expression is the type of <code>f</code>.
If <code>x</code> is a package name, see the section on
<a href="#Qualified_identifiers">qualified identifiers</a>.
Rob Pike's avatar
Rob Pike committed
2724
</p>
2725

2726
<p>
Rob Pike's avatar
Rob Pike committed
2727 2728
A selector <code>f</code> may denote a field or method <code>f</code> of
a type <code>T</code>, or it may refer
2729
to a field or method <code>f</code> of a nested
2730 2731
<a href="#Struct_types">embedded field</a> of <code>T</code>.
The number of embedded fields traversed
Rob Pike's avatar
Rob Pike committed
2732 2733 2734 2735
to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
The depth of a field or method <code>f</code>
declared in <code>T</code> is zero.
The depth of a field or method <code>f</code> declared in
2736
an embedded field <code>A</code> in <code>T</code> is the
Rob Pike's avatar
Rob Pike committed
2737 2738
depth of <code>f</code> in <code>A</code> plus one.
</p>
2739

2740
<p>
2741
The following rules apply to selectors:
Rob Pike's avatar
Rob Pike committed
2742
</p>
2743

Rob Pike's avatar
Rob Pike committed
2744 2745 2746
<ol>
<li>
For a value <code>x</code> of type <code>T</code> or <code>*T</code>
2747
where <code>T</code> is not a pointer or interface type,
Rob Pike's avatar
Rob Pike committed
2748 2749 2750
<code>x.f</code> denotes the field or method at the shallowest depth
in <code>T</code> where there
is such an <code>f</code>.
2751 2752
If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a>
with shallowest depth, the selector expression is illegal.
Rob Pike's avatar
Rob Pike committed
2753
</li>
2754

Rob Pike's avatar
Rob Pike committed
2755
<li>
2756
For a value <code>x</code> of type <code>I</code> where <code>I</code>
2757
is an interface type, <code>x.f</code> denotes the actual method with name
2758
<code>f</code> of the dynamic value of <code>x</code>.
2759 2760 2761
If there is no method with name <code>f</code> in the
<a href="#Method_sets">method set</a> of <code>I</code>, the selector
expression is illegal.
Rob Pike's avatar
Rob Pike committed
2762
</li>
2763 2764

<li>
2765 2766
As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a>
pointer type and <code>(*x).f</code> is a valid selector expression denoting a field
2767 2768 2769
(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>.
</li>

Rob Pike's avatar
Rob Pike committed
2770 2771
<li>
In all other cases, <code>x.f</code> is illegal.
2772
</li>
2773

2774
<li>
Russ Cox's avatar
Russ Cox committed
2775 2776 2777 2778 2779
If <code>x</code> is of pointer type and has the value
<code>nil</code> and <code>x.f</code> denotes a struct field,
assigning to or evaluating <code>x.f</code>
causes a <a href="#Run_time_panics">run-time panic</a>.
</li>
2780

Russ Cox's avatar
Russ Cox committed
2781 2782 2783 2784
<li>
If <code>x</code> is of interface type and has the value
<code>nil</code>, <a href="#Calls">calling</a> or
<a href="#Method_values">evaluating</a> the method <code>x.f</code>
2785
causes a <a href="#Run_time_panics">run-time panic</a>.
2786
</li>
Rob Pike's avatar
Rob Pike committed
2787
</ol>
2788

2789
<p>
Rob Pike's avatar
Rob Pike committed
2790 2791
For example, given the declarations:
</p>
2792

2793 2794
<pre>
type T0 struct {
2795
	x int
2796
}
2797

2798
func (*T0) M0()
2799

2800
type T1 struct {
2801
	y int
2802
}
2803

2804
func (T1) M1()
2805

2806
type T2 struct {
2807 2808 2809
	z int
	T1
	*T0
2810
}
Robert Griesemer's avatar
Robert Griesemer committed
2811

2812
func (*T2) M2()
Robert Griesemer's avatar
Robert Griesemer committed
2813

2814 2815 2816 2817 2818
type Q *T2

var t T2     // with t.T0 != nil
var p *T2    // with p != nil and (*p).T0 != nil
var q Q = p
2819
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2820

Rob Pike's avatar
Rob Pike committed
2821 2822 2823
<p>
one may write:
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2824

2825
<pre>
2826 2827
t.z          // t.z
t.y          // t.T1.y
Robert Griesemer's avatar
Robert Griesemer committed
2828
t.x          // (*t.T0).x
2829 2830 2831 2832 2833 2834 2835

p.z          // (*p).z
p.y          // (*p).T1.y
p.x          // (*(*p).T0).x

q.x          // (*(*q).T0).x        (*q).x is a valid field selector

2836
p.M0()       // ((*p).T0).M0()      M0 expects *T0 receiver
2837
p.M1()       // ((*p).T1).M1()      M1 expects T1 receiver
2838 2839
p.M2()       // p.M2()              M2 expects *T2 receiver
t.M2()       // (&amp;t).M2()           M2 expects *T2 receiver, see section on Calls
2840
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2841

2842 2843 2844 2845 2846 2847
<p>
but the following is invalid:
</p>

<pre>
q.M0()       // (*q).M0 is valid but not a field selector
2848
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2849 2850


2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861
<h3 id="Method_expressions">Method expressions</h3>

<p>
If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
<code>T.M</code> is a function that is callable as a regular function
with the same arguments as <code>M</code> prefixed by an additional
argument that is the receiver of the method.
</p>

<pre class="ebnf">
MethodExpr    = ReceiverType "." MethodName .
2862
ReceiverType  = Type .
2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077
</pre>

<p>
Consider a struct type <code>T</code> with two methods,
<code>Mv</code>, whose receiver is of type <code>T</code>, and
<code>Mp</code>, whose receiver is of type <code>*T</code>.
</p>

<pre>
type T struct {
	a int
}
func (tv  T) Mv(a int) int         { return 0 }  // value receiver
func (tp *T) Mp(f float32) float32 { return 1 }  // pointer receiver

var t T
</pre>

<p>
The expression
</p>

<pre>
T.Mv
</pre>

<p>
yields a function equivalent to <code>Mv</code> but
with an explicit receiver as its first argument; it has signature
</p>

<pre>
func(tv T, a int) int
</pre>

<p>
That function may be called normally with an explicit receiver, so
these five invocations are equivalent:
</p>

<pre>
t.Mv(7)
T.Mv(t, 7)
(T).Mv(t, 7)
f1 := T.Mv; f1(t, 7)
f2 := (T).Mv; f2(t, 7)
</pre>

<p>
Similarly, the expression
</p>

<pre>
(*T).Mp
</pre>

<p>
yields a function value representing <code>Mp</code> with signature
</p>

<pre>
func(tp *T, f float32) float32
</pre>

<p>
For a method with a value receiver, one can derive a function
with an explicit pointer receiver, so
</p>

<pre>
(*T).Mv
</pre>

<p>
yields a function value representing <code>Mv</code> with signature
</p>

<pre>
func(tv *T, a int) int
</pre>

<p>
Such a function indirects through the receiver to create a value
to pass as the receiver to the underlying method;
the method does not overwrite the value whose address is passed in
the function call.
</p>

<p>
The final case, a value-receiver function for a pointer-receiver method,
is illegal because pointer-receiver methods are not in the method set
of the value type.
</p>

<p>
Function values derived from methods are called with function call syntax;
the receiver is provided as the first argument to the call.
That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
as <code>f(t, 7)</code> not <code>t.f(7)</code>.
To construct a function that binds the receiver, use a
<a href="#Function_literals">function literal</a> or
<a href="#Method_values">method value</a>.
</p>

<p>
It is legal to derive a function value from a method of an interface type.
The resulting function takes an explicit receiver of that interface type.
</p>

<h3 id="Method_values">Method values</h3>

<p>
If the expression <code>x</code> has static type <code>T</code> and
<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
<code>x.M</code> is called a <i>method value</i>.
The method value <code>x.M</code> is a function value that is callable
with the same arguments as a method call of <code>x.M</code>.
The expression <code>x</code> is evaluated and saved during the evaluation of the
method value; the saved copy is then used as the receiver in any calls,
which may be executed later.
</p>

<p>
The type <code>T</code> may be an interface or non-interface type.
</p>

<p>
As in the discussion of <a href="#Method_expressions">method expressions</a> above,
consider a struct type <code>T</code> with two methods,
<code>Mv</code>, whose receiver is of type <code>T</code>, and
<code>Mp</code>, whose receiver is of type <code>*T</code>.
</p>

<pre>
type T struct {
	a int
}
func (tv  T) Mv(a int) int         { return 0 }  // value receiver
func (tp *T) Mp(f float32) float32 { return 1 }  // pointer receiver

var t T
var pt *T
func makeT() T
</pre>

<p>
The expression
</p>

<pre>
t.Mv
</pre>

<p>
yields a function value of type
</p>

<pre>
func(int) int
</pre>

<p>
These two invocations are equivalent:
</p>

<pre>
t.Mv(7)
f := t.Mv; f(7)
</pre>

<p>
Similarly, the expression
</p>

<pre>
pt.Mp
</pre>

<p>
yields a function value of type
</p>

<pre>
func(float32) float32
</pre>

<p>
As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
</p>

<p>
As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&amp;t).Mp</code>.
</p>

<pre>
f := t.Mv; f(7)   // like t.Mv(7)
f := pt.Mp; f(7)  // like pt.Mp(7)
f := pt.Mv; f(7)  // like (*pt).Mv(7)
f := t.Mp; f(7)   // like (&amp;t).Mp(7)
f := makeT().Mp   // invalid: result of makeT() is not addressable
</pre>

<p>
Although the examples above use non-interface types, it is also legal to create a method value
from a value of interface type.
</p>

<pre>
var i interface { M(int) } = myVal
f := i.M; f(7)  // like i.M(7)
</pre>


3078
<h3 id="Index_expressions">Index expressions</h3>
3079

Rob Pike's avatar
Rob Pike committed
3080
<p>
Robert Griesemer's avatar
Robert Griesemer committed
3081
A primary expression of the form
Rob Pike's avatar
Rob Pike committed
3082
</p>
Robert Griesemer's avatar
Robert Griesemer committed
3083

3084 3085 3086
<pre>
a[x]
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
3087

Rob Pike's avatar
Rob Pike committed
3088
<p>
3089 3090 3091
denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
The following rules apply:
Rob Pike's avatar
Rob Pike committed
3092
</p>
3093

3094 3095 3096 3097
<p>
If <code>a</code> is not a map:
</p>
<ul>
3098 3099 3100 3101 3102
	<li>the index <code>x</code> must be of integer type or an untyped constant</li>
	<li>a constant index must be non-negative and
	    <a href="#Representability">representable</a> by a value of type <code>int</code></li>
	<li>a constant index that is untyped is given type <code>int</code></li>
	<li>the index <code>x</code> is <i>in range</i> if <code>0 &lt;= x &lt; len(a)</code>,
3103 3104 3105
	    otherwise it is <i>out of range</i></li>
</ul>

3106
<p>
3107
For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
Rob Pike's avatar
Rob Pike committed
3108
</p>
3109
<ul>
3110
	<li>a <a href="#Constants">constant</a> index must be in range</li>
3111
	<li>if <code>x</code> is out of range at run time,
3112
	    a <a href="#Run_time_panics">run-time panic</a> occurs</li>
Rob Pike's avatar
Rob Pike committed
3113
	<li><code>a[x]</code> is the array element at index <code>x</code> and the type of
3114
	    <code>a[x]</code> is the element type of <code>A</code></li>
3115 3116 3117
</ul>

<p>
3118 3119 3120 3121 3122 3123 3124 3125
For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
</p>
<ul>
	<li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
</ul>

<p>
For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
3126 3127
</p>
<ul>
3128
	<li>if <code>x</code> is out of range at run time,
3129 3130
	    a <a href="#Run_time_panics">run-time panic</a> occurs</li>
	<li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
3131
	    <code>a[x]</code> is the element type of <code>S</code></li>
3132
</ul>
3133 3134

<p>
3135
For <code>a</code> of <a href="#String_types">string type</a>:
3136 3137
</p>
<ul>
3138
	<li>a <a href="#Constants">constant</a> index must be in range
3139 3140 3141
	    if the string <code>a</code> is also constant</li>
	<li>if <code>x</code> is out of range at run time,
	    a <a href="#Run_time_panics">run-time panic</a> occurs</li>
3142
	<li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
3143
	    <code>a[x]</code> is <code>byte</code></li>
3144
	<li><code>a[x]</code> may not be assigned to</li>
3145 3146
</ul>

3147
<p>
3148
For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
Rob Pike's avatar
Rob Pike committed
3149
</p>
3150
<ul>
3151
	<li><code>x</code>'s type must be
3152 3153
	    <a href="#Assignability">assignable</a>
	    to the key type of <code>M</code></li>
3154
	<li>if the map contains an entry with key <code>x</code>,
3155 3156
	    <code>a[x]</code> is the map element with key <code>x</code>
	    and the type of <code>a[x]</code> is the element type of <code>M</code></li>
3157
	<li>if the map is <code>nil</code> or does not contain such an entry,
3158
	    <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
3159
	    for the element type of <code>M</code></li>
3160
</ul>
Robert Griesemer's avatar
Robert Griesemer committed
3161

3162
<p>
3163
Otherwise <code>a[x]</code> is illegal.
Rob Pike's avatar
Rob Pike committed
3164 3165 3166
</p>

<p>
3167
An index expression on a map <code>a</code> of type <code>map[K]V</code>
3168
used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pike's avatar
Rob Pike committed
3169 3170 3171
</p>

<pre>
3172 3173 3174
v, ok = a[x]
v, ok := a[x]
var v, ok = a[x]
Rob Pike's avatar
Rob Pike committed
3175 3176 3177
</pre>

<p>
3178
yields an additional untyped boolean value. The value of <code>ok</code> is
3179
<code>true</code> if the key <code>x</code> is present in the map, and
3180
<code>false</code> otherwise.
Rob Pike's avatar
Rob Pike committed
3181 3182
</p>

3183 3184 3185 3186 3187
<p>
Assigning to an element of a <code>nil</code> map causes a
<a href="#Run_time_panics">run-time panic</a>.
</p>

3188

Robert Griesemer's avatar
Robert Griesemer committed
3189 3190 3191 3192 3193 3194 3195 3196 3197
<h3 id="Slice_expressions">Slice expressions</h3>

<p>
Slice expressions construct a substring or slice from a string, array, pointer
to array, or slice. There are two variants: a simple form that specifies a low
and high bound, and a full form that also specifies a bound on the capacity.
</p>

<h4>Simple slice expressions</h4>
3198

Rob Pike's avatar
Rob Pike committed
3199
<p>
3200
For a string, array, pointer to array, or slice <code>a</code>, the primary expression
Rob Pike's avatar
Rob Pike committed
3201
</p>
3202

3203
<pre>
3204
a[low : high]
3205
</pre>
3206

Rob Pike's avatar
Rob Pike committed
3207
<p>
3208 3209 3210
constructs a substring or slice. The <i>indices</i> <code>low</code> and
<code>high</code> select which elements of operand <code>a</code> appear
in the result. The result has indices starting at 0 and length equal to
3211
<code>high</code>&nbsp;-&nbsp;<code>low</code>.
3212 3213 3214 3215
After slicing the array <code>a</code>
</p>

<pre>
3216 3217
a := [5]int{1, 2, 3, 4, 5}
s := a[1:4]
3218 3219 3220 3221
</pre>

<p>
the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements
Rob Pike's avatar
Rob Pike committed
3222
</p>
3223

3224 3225 3226
<pre>
s[0] == 2
s[1] == 3
3227
s[2] == 4
3228
</pre>
3229

Rob Pike's avatar
Rob Pike committed
3230
<p>
3231
For convenience, any of the indices may be omitted. A missing <code>low</code>
3232 3233
index defaults to zero; a missing <code>high</code> index defaults to the length of the
sliced operand:
3234 3235
</p>

3236
<pre>
3237
a[2:]  // same as a[2 : len(a)]
3238 3239
a[:3]  // same as a[0 : 3]
a[:]   // same as a[0 : len(a)]
3240 3241
</pre>

3242
<p>
3243 3244 3245 3246 3247 3248 3249
If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
<code>(*a)[low : high]</code>.
</p>

<p>
For arrays or strings, the indices are <i>in range</i> if
<code>0</code> &lt;= <code>low</code> &lt;= <code>high</code> &lt;= <code>len(a)</code>,
3250 3251
otherwise they are <i>out of range</i>.
For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
3252 3253
A <a href="#Constants">constant</a> index must be non-negative and
<a href="#Representability">representable</a> by a value of type
3254
<code>int</code>; for arrays or constant strings, constant indices must also be in range.
3255 3256
If both indices are constant, they must satisfy <code>low &lt;= high</code>.
If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
3257 3258
</p>

3259
<p>
3260 3261 3262
Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
the result of the slice operation is a non-constant value of the same type as the operand.
For untyped string operands the result is a non-constant value of type <code>string</code>.
3263 3264
If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
and the result of the slice operation is a slice with the same element type as the array.
Rob Pike's avatar
Rob Pike committed
3265
</p>
3266

3267 3268
<p>
If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
3269 3270
is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying
array with the operand.
3271
</p>
3272

3273 3274 3275 3276 3277 3278 3279 3280
<pre>
var a [10]int
s1 := a[3:7]   // underlying array of s1 is array a; &s1[2] == &a[5]
s2 := s1[1:4]  // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5]
s2[1] = 42     // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element
</pre>


Robert Griesemer's avatar
Robert Griesemer committed
3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320
<h4>Full slice expressions</h4>

<p>
For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression
</p>

<pre>
a[low : high : max]
</pre>

<p>
constructs a slice of the same type, and with the same length and elements as the simple slice
expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity
by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0.
After slicing the array <code>a</code>
</p>

<pre>
a := [5]int{1, 2, 3, 4, 5}
t := a[1:3:5]
</pre>

<p>
the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements
</p>

<pre>
t[0] == 2
t[1] == 3
</pre>

<p>
As for simple slice expressions, if <code>a</code> is a pointer to an array,
<code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>.
If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>.
</p>

<p>
The indices are <i>in range</i> if <code>0 &lt;= low &lt;= high &lt;= max &lt;= cap(a)</code>,
otherwise they are <i>out of range</i>.
3321 3322
A <a href="#Constants">constant</a> index must be non-negative and
<a href="#Representability">representable</a> by a value of type
3323
<code>int</code>; for arrays, constant indices must also be in range.
Robert Griesemer's avatar
Robert Griesemer committed
3324 3325 3326 3327 3328
If multiple indices are constant, the constants that are present must be in range relative to each
other.
If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
</p>

3329
<h3 id="Type_assertions">Type assertions</h3>
3330

Rob Pike's avatar
Rob Pike committed
3331
<p>
3332 3333
For an expression <code>x</code> of <a href="#Interface_types">interface type</a>
and a type <code>T</code>, the primary expression
Rob Pike's avatar
Rob Pike committed
3334
</p>
3335

3336 3337 3338
<pre>
x.(T)
</pre>
3339

3340
<p>
3341
asserts that <code>x</code> is not <code>nil</code>
Russ Cox's avatar
Russ Cox committed
3342
and that the value stored in <code>x</code> is of type <code>T</code>.
3343
The notation <code>x.(T)</code> is called a <i>type assertion</i>.
Rob Pike's avatar
Rob Pike committed
3344 3345
</p>
<p>
3346
More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
3347 3348
that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
to the type <code>T</code>.
3349 3350 3351
In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>;
otherwise the type assertion is invalid since it is not possible for <code>x</code>
to store a value of type <code>T</code>.
3352
If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
3353
of <code>x</code> implements the interface <code>T</code>.
Rob Pike's avatar
Rob Pike committed
3354
</p>
3355
<p>
3356
If the type assertion holds, the value of the expression is the value
3357 3358 3359
stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false,
a <a href="#Run_time_panics">run-time panic</a> occurs.
In other words, even though the dynamic type of <code>x</code>
3360
is known only at run time, the type of <code>x.(T)</code> is
Rob Pike's avatar
Rob Pike committed
3361 3362
known to be <code>T</code> in a correct program.
</p>
3363 3364

<pre>
3365 3366
var x interface{} = 7          // x has dynamic type int and value 7
i := x.(int)                   // i has type int and value 7
3367 3368

type I interface { m() }
3369 3370 3371 3372 3373 3374

func f(y I) {
	s := y.(string)        // illegal: string does not implement I (missing method m)
	r := y.(io.Reader)     // r has type io.Reader and the dynamic type of y must implement both I and io.Reader

}
3375 3376
</pre>

3377
<p>
3378
A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pike's avatar
Rob Pike committed
3379
</p>
3380

3381 3382 3383
<pre>
v, ok = x.(T)
v, ok := x.(T)
Rob Pike's avatar
Rob Pike committed
3384
var v, ok = x.(T)
3385
var v, ok T1 = x.(T)
3386
</pre>
3387

3388
<p>
3389 3390 3391
yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code>
if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is
the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
3392
No <a href="#Run_time_panics">run-time panic</a> occurs in this case.
Rob Pike's avatar
Rob Pike committed
3393
</p>
3394

3395

3396
<h3 id="Calls">Calls</h3>
3397

3398
<p>
Rob Pike's avatar
Rob Pike committed
3399 3400
Given an expression <code>f</code> of function type
<code>F</code>,
Rob Pike's avatar
Rob Pike committed
3401
</p>
3402

3403
<pre>
3404
f(a1, a2, … an)
3405
</pre>
3406

3407
<p>
3408
calls <code>f</code> with arguments <code>a1, a2, … an</code>.
3409
Except for one special case, arguments must be single-valued expressions
3410
<a href="#Assignability">assignable</a> to the parameter types of
Rob Pike's avatar
Rob Pike committed
3411 3412 3413 3414 3415 3416 3417
<code>F</code> and are evaluated before the function is called.
The type of the expression is the result type
of <code>F</code>.
A method invocation is similar but the method itself
is specified as a selector upon a value of the receiver type for
the method.
</p>
3418

3419
<pre>
3420
math.Atan2(x, y)  // function call
3421
var pt *Point
3422
pt.Scale(3.5)     // method call with receiver pt
3423
</pre>
3424

3425 3426 3427 3428 3429 3430 3431 3432 3433 3434
<p>
In a function call, the function value and arguments are evaluated in
<a href="#Order_of_evaluation">the usual order</a>.
After they are evaluated, the parameters of the call are passed by value to the function
and the called function begins execution.
The return parameters of the function are passed by value
back to the calling function when the function returns.
</p>

<p>
Hong Ruiqi's avatar
Hong Ruiqi committed
3435
Calling a <code>nil</code> function value
3436 3437 3438
causes a <a href="#Run_time_panics">run-time panic</a>.
</p>

3439
<p>
3440
As a special case, if the return values of a function or method
3441 3442
<code>g</code> are equal in number and individually
assignable to the parameters of another function or method
3443 3444 3445
<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
will invoke <code>f</code> after binding the return values of
<code>g</code> to the parameters of <code>f</code> in order.  The call
3446 3447
of <code>f</code> must contain no parameters other than the call of <code>g</code>,
and <code>g</code> must have at least one return value.
3448 3449 3450 3451 3452 3453 3454
If <code>f</code> has a final <code>...</code> parameter, it is
assigned the return values of <code>g</code> that remain after
assignment of regular parameters.
</p>

<pre>
func Split(s string, pos int) (string, string) {
3455
	return s[0:pos], s[pos:]
3456 3457 3458 3459 3460 3461 3462
}

func Join(s, t string) string {
	return s + t
}

if Join(Split(value, len(value)/2)) != value {
3463
	log.Panic("test fails")
3464 3465 3466
}
</pre>

Rob Pike's avatar
Rob Pike committed
3467
<p>
3468 3469
A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a>
of (the type of) <code>x</code> contains <code>m</code> and the
3470
argument list can be assigned to the parameter list of <code>m</code>.
Rob Pike's avatar
Rob Pike committed
3471
If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&amp;x</code>'s method
Robert Griesemer's avatar
Robert Griesemer committed
3472 3473
set contains <code>m</code>, <code>x.m()</code> is shorthand
for <code>(&amp;x).m()</code>:
Rob Pike's avatar
Rob Pike committed
3474
</p>
3475

3476
<pre>
3477
var p Point
Rob Pike's avatar
Rob Pike committed
3478
p.Scale(3.5)
3479
</pre>
3480

3481
<p>
3482
There is no distinct method type and there are no method literals.
Rob Pike's avatar
Rob Pike committed
3483
</p>
3484

3485
<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
3486

Rob Pike's avatar
Rob Pike committed
3487
<p>
3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498
If <code>f</code> is <a href="#Function_types">variadic</a> with a final
parameter <code>p</code> of type <code>...T</code>, then within <code>f</code>
the type of <code>p</code> is equivalent to type <code>[]T</code>.
If <code>f</code> is invoked with no actual arguments for <code>p</code>,
the value passed to <code>p</code> is <code>nil</code>.
Otherwise, the value passed is a new slice
of type <code>[]T</code> with a new underlying array whose successive elements
are the actual arguments, which all must be <a href="#Assignability">assignable</a>
to <code>T</code>. The length and capacity of the slice is therefore
the number of arguments bound to <code>p</code> and may differ for each
call site.
3499
</p>
3500

Rob Pike's avatar
Rob Pike committed
3501
<p>
3502
Given the function and calls
3503 3504
</p>
<pre>
3505
func Greeting(prefix string, who ...string)
3506
Greeting("nobody")
3507 3508 3509 3510
Greeting("hello:", "Joe", "Anna", "Eileen")
</pre>

<p>
Robert Griesemer's avatar
Robert Griesemer committed
3511
within <code>Greeting</code>, <code>who</code> will have the value
3512 3513
<code>nil</code> in the first call, and
<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second.
3514 3515
</p>

Robert Griesemer's avatar
Robert Griesemer committed
3516
<p>
3517
If the final argument is assignable to a slice type <code>[]T</code>, it is
3518 3519
passed unchanged as the value for a <code>...T</code> parameter if the argument
is followed by <code>...</code>. In this case no new slice is created.
Robert Griesemer's avatar
Robert Griesemer committed
3520
</p>
3521 3522

<p>
Robert Griesemer's avatar
Robert Griesemer committed
3523
Given the slice <code>s</code> and call
3524
</p>
3525

Robert Griesemer's avatar
Robert Griesemer committed
3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536
<pre>
s := []string{"James", "Jasmine"}
Greeting("goodbye:", s...)
</pre>

<p>
within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code>
with the same underlying array.
</p>


3537
<h3 id="Operators">Operators</h3>
3538

Rob Pike's avatar
Rob Pike committed
3539
<p>
3540
Operators combine operands into expressions.
Rob Pike's avatar
Rob Pike committed
3541
</p>
3542

3543
<pre class="ebnf">
3544
Expression = UnaryExpr | Expression binary_op Expression .
Rob Pike's avatar
Rob Pike committed
3545
UnaryExpr  = PrimaryExpr | unary_op UnaryExpr .
3546

3547
binary_op  = "||" | "&amp;&amp;" | rel_op | add_op | mul_op .
Rob Pike's avatar
Rob Pike committed
3548 3549
rel_op     = "==" | "!=" | "&lt;" | "&lt;=" | ">" | ">=" .
add_op     = "+" | "-" | "|" | "^" .
3550
mul_op     = "*" | "/" | "%" | "&lt;&lt;" | "&gt;&gt;" | "&amp;" | "&amp;^" .
3551

Rob Pike's avatar
Rob Pike committed
3552
unary_op   = "+" | "-" | "!" | "^" | "*" | "&amp;" | "&lt;-" .
3553
</pre>
3554

3555
<p>
3556
Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
3557
For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
3558
unless the operation involves shifts or untyped <a href="#Constants">constants</a>.
3559 3560
For operations involving constants only, see the section on
<a href="#Constant_expressions">constant expressions</a>.
Rob Pike's avatar
Rob Pike committed
3561
</p>
3562

3563
<p>
3564
Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a>
3565
and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a>
3566
to the type of the other operand.
3567
</p>
3568

3569
<p>
3570
The right operand in a shift expression must have integer type
3571 3572
or be an untyped constant <a href="#Representability">representable</a> by a
value of type <code>uint</code>.
3573
If the left operand of a non-constant shift expression is an untyped constant,
3574
it is first implicitly converted to the type it would assume if the shift expression were
3575
replaced by its left operand alone.
3576
</p>
3577

3578
<pre>
3579
var s uint = 33
3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593
var i = 1&lt;&lt;s                  // 1 has type int
var j int32 = 1&lt;&lt;s            // 1 has type int32; j == 0
var k = uint64(1&lt;&lt;s)          // 1 has type uint64; k == 1&lt;&lt;33
var m int = 1.0&lt;&lt;s            // 1.0 has type int; m == 0 if ints are 32bits in size
var n = 1.0&lt;&lt;s == j           // 1.0 has type int32; n == true
var o = 1&lt;&lt;s == 2&lt;&lt;s          // 1 and 2 have type int; o == true if ints are 32bits in size
var p = 1&lt;&lt;s == 1&lt;&lt;33         // illegal if ints are 32bits in size: 1 has type int, but 1&lt;&lt;33 overflows int
var u = 1.0&lt;&lt;s                // illegal: 1.0 has type float64, cannot shift
var u1 = 1.0&lt;&lt;s != 0          // illegal: 1.0 has type float64, cannot shift
var u2 = 1&lt;&lt;s != 1.0          // illegal: 1 has type float64, cannot shift
var v float32 = 1&lt;&lt;s          // illegal: 1 has type float32, cannot shift
var w int64 = 1.0&lt;&lt;33         // 1.0&lt;&lt;33 is a constant shift expression
var x = a[1.0&lt;&lt;s]             // 1.0 has type int; x == a[0] if ints are 32bits in size
var a = make([]byte, 1.0&lt;&lt;s)  // 1.0 has type int; len(a) == 0 if ints are 32bits in size
3594
</pre>
3595

3596 3597

<h4 id="Operator_precedence">Operator precedence</h4>
3598
<p>
Russ Cox's avatar
Russ Cox committed
3599 3600
Unary operators have the highest precedence.
As the  <code>++</code> and <code>--</code> operators form
Rob Pike's avatar
Rob Pike committed
3601
statements, not expressions, they fall
Russ Cox's avatar
Russ Cox committed
3602
outside the operator hierarchy.
Rob Pike's avatar
Rob Pike committed
3603 3604
As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
<p>
3605
There are five precedence levels for binary operators.
Rob Pike's avatar
Rob Pike committed
3606
Multiplication operators bind strongest, followed by addition
3607 3608
operators, comparison operators, <code>&amp;&amp;</code> (logical AND),
and finally <code>||</code> (logical OR):
Rob Pike's avatar
Rob Pike committed
3609
</p>
3610

Rob Pike's avatar
Rob Pike committed
3611
<pre class="grammar">
3612
Precedence    Operator
3613 3614
    5             *  /  %  &lt;&lt;  &gt;&gt;  &amp;  &amp;^
    4             +  -  |  ^
3615
    3             ==  !=  &lt;  &lt;=  &gt;  &gt;=
3616 3617 3618
    2             &amp;&amp;
    1             ||
</pre>
3619

Rob Pike's avatar
Rob Pike committed
3620
<p>
3621
Binary operators of the same precedence associate from left to right.
3622
For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
Rob Pike's avatar
Rob Pike committed
3623
</p>
3624

3625 3626 3627 3628
<pre>
+x
23 + 3*x[i]
x &lt;= f()
3629
^a &gt;&gt; b
3630
f() || g()
3631
x == y+1 &amp;&amp; &lt;-chanPtr &gt; 0
3632
</pre>
3633 3634


3635
<h3 id="Arithmetic_operators">Arithmetic operators</h3>
3636
<p>
3637
Arithmetic operators apply to numeric values and yield a result of the same
Rob Pike's avatar
Rob Pike committed
3638
type as the first operand. The four standard arithmetic operators (<code>+</code>,
3639 3640 3641
<code>-</code>, <code>*</code>, <code>/</code>) apply to integer,
floating-point, and complex types; <code>+</code> also applies to strings.
The bitwise logical and shift operators apply to integers only.
Rob Pike's avatar
Rob Pike committed
3642
</p>
3643

Rob Pike's avatar
Rob Pike committed
3644
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
3645 3646 3647 3648
+    sum                    integers, floats, complex values, strings
-    difference             integers, floats, complex values
*    product                integers, floats, complex values
/    quotient               integers, floats, complex values
3649
%    remainder              integers
3650

3651 3652 3653 3654
&amp;    bitwise AND            integers
|    bitwise OR             integers
^    bitwise XOR            integers
&amp;^   bit clear (AND NOT)    integers
3655

3656 3657
&lt;&lt;   left shift             integer &lt;&lt; unsigned integer
&gt;&gt;   right shift            integer &gt;&gt; unsigned integer
3658
</pre>
3659 3660


3661
<h4 id="Integer_operators">Integer operators</h4>
3662

Rob Pike's avatar
Rob Pike committed
3663
<p>
3664 3665 3666
For two integer values <code>x</code> and <code>y</code>, the integer quotient
<code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following
relationships:
Rob Pike's avatar
Rob Pike committed
3667
</p>
3668

3669
<pre>
3670
x = q*y + r  and  |r| &lt; |y|
3671
</pre>
3672

Rob Pike's avatar
Rob Pike committed
3673
<p>
3674
with <code>x / y</code> truncated towards zero
3675
(<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
Rob Pike's avatar
Rob Pike committed
3676
</p>
3677

3678 3679 3680 3681 3682 3683 3684
<pre>
 x     y     x / y     x % y
 5     3       1         2
-5     3      -1        -2
 5    -3      -1         2
-5    -3       1        -2
</pre>
3685

3686
<p>
3687 3688 3689 3690
The one exception to this rule is that if the dividend <code>x</code> is
the most negative value for the int type of <code>x</code>, the quotient
<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>)
due to two's-complement <a href="#Integer_overflow">integer overflow</a>:
3691 3692 3693 3694 3695 3696 3697 3698 3699 3700
</p>

<pre>
			 x, q
int8                     -128
int16                  -32768
int32             -2147483648
int64    -9223372036854775808
</pre>

Rob Pike's avatar
Rob Pike committed
3701
<p>
3702 3703
If the divisor is a <a href="#Constants">constant</a>, it must not be zero.
If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
3704
If the dividend is non-negative and the divisor is a constant power of 2,
3705
the division may be replaced by a right shift, and computing the remainder may
3706
be replaced by a bitwise AND operation:
Rob Pike's avatar
Rob Pike committed
3707
</p>
3708

3709
<pre>
3710
 x     x / 4     x % 4     x &gt;&gt; 2     x &amp; 3
3711 3712 3713
 11      2         3         2          3
-11     -2        -3        -3          1
</pre>
3714

Rob Pike's avatar
Rob Pike committed
3715
<p>
3716
The shift operators shift the left operand by the shift count specified by the
3717 3718 3719
right operand, which must be positive. If the shift count is negative at run time,
a <a href="#Run_time_panics">run-time panic</a> occurs.
The shift operators implement arithmetic shifts if the left operand is a signed
3720 3721
integer and logical shifts if it is an unsigned integer.
There is no upper limit on the shift count. Shifts behave
Rob Pike's avatar
Rob Pike committed
3722 3723
as if the left operand is shifted <code>n</code> times by 1 for a shift
count of <code>n</code>.
3724 3725
As a result, <code>x &lt;&lt; 1</code> is the same as <code>x*2</code>
and <code>x &gt;&gt; 1</code> is the same as
3726
<code>x/2</code> but truncated towards negative infinity.
Rob Pike's avatar
Rob Pike committed
3727
</p>
3728

Rob Pike's avatar
Rob Pike committed
3729 3730 3731
<p>
For integer operands, the unary operators
<code>+</code>, <code>-</code>, and <code>^</code> are defined as
Robert Griesemer's avatar
Robert Griesemer committed
3732
follows:
Rob Pike's avatar
Rob Pike committed
3733
</p>
3734

Rob Pike's avatar
Rob Pike committed
3735
<pre class="grammar">
3736 3737
+x                          is 0 + x
-x    negation              is 0 - x
Russ Cox's avatar
Russ Cox committed
3738 3739
^x    bitwise complement    is m ^ x  with m = "all bits set to 1" for unsigned x
                                      and  m = -1 for signed x
3740
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
3741 3742


3743
<h4 id="Integer_overflow">Integer overflow</h4>
Robert Griesemer's avatar
Robert Griesemer committed
3744

Rob Pike's avatar
Rob Pike committed
3745 3746 3747 3748
<p>
For unsigned integer values, the operations <code>+</code>,
<code>-</code>, <code>*</code>, and <code>&lt;&lt;</code> are
computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
3749 3750
the <a href="#Numeric_types">unsigned integer</a>'s type.
Loosely speaking, these unsigned integer operations
3751
discard high bits upon overflow, and programs may rely on "wrap around".
Rob Pike's avatar
Rob Pike committed
3752
</p>
3753
<p>
Rob Pike's avatar
Rob Pike committed
3754
For signed integers, the operations <code>+</code>,
3755
<code>-</code>, <code>*</code>, <code>/</code>, and <code>&lt;&lt;</code> may legally
Robert Griesemer's avatar
Robert Griesemer committed
3756 3757
overflow and the resulting value exists and is deterministically defined
by the signed integer representation, the operation, and its operands.
3758
Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>.
3759
A compiler may not optimize code under the assumption that overflow does
Rob Pike's avatar
Rob Pike committed
3760 3761
not occur. For instance, it may not assume that <code>x &lt; x + 1</code> is always true.
</p>
3762 3763


3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774
<h4 id="Floating_point_operators">Floating-point operators</h4>

<p>
For floating-point and complex numbers,
<code>+x</code> is the same as <code>x</code>,
while <code>-x</code> is the negation of <code>x</code>.
The result of a floating-point or complex division by zero is not specified beyond the
IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a>
occurs is implementation-specific.
</p>

3775 3776 3777 3778
<p>
An implementation may combine multiple floating-point operations into a single
fused operation, possibly across statements, and produce a result that differs
from the value obtained by executing and rounding the instructions individually.
3779
An explicit floating-point type <a href="#Conversions">conversion</a> rounds to
3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801
the precision of the target type, preventing fusion that would discard that rounding.
</p>

<p>
For instance, some architectures provide a "fused multiply and add" (FMA) instruction
that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>.
These examples show when a Go implementation can use that instruction:
</p>

<pre>
// FMA allowed for computing r, because x*y is not explicitly rounded:
r  = x*y + z
r  = z;   r += x*y
t  = x*y; r = t + z
*p = x*y; r = *p + z
r  = x*y + float64(z)

// FMA disallowed for computing r, because it would omit rounding of x*y:
r  = float64(x*y) + z
r  = z; r += float64(x*y)
t  = float64(x*y); r = t + z
</pre>
3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819

<h4 id="String_concatenation">String concatenation</h4>

<p>
Strings can be concatenated using the <code>+</code> operator
or the <code>+=</code> assignment operator:
</p>

<pre>
s := "hi" + string(c)
s += " and good bye"
</pre>

<p>
String addition creates a new string by concatenating the operands.
</p>


3820
<h3 id="Comparison_operators">Comparison operators</h3>
3821

Rob Pike's avatar
Rob Pike committed
3822
<p>
3823
Comparison operators compare two operands and yield an untyped boolean value.
Rob Pike's avatar
Rob Pike committed
3824
</p>
3825

Rob Pike's avatar
Rob Pike committed
3826
<pre class="grammar">
3827 3828
==    equal
!=    not equal
Anthony Martin's avatar
Anthony Martin committed
3829 3830
&lt;     less
&lt;=    less or equal
3831 3832
&gt;     greater
&gt;=    greater or equal
3833
</pre>
3834

Rob Pike's avatar
Rob Pike committed
3835
<p>
3836
In any comparison, the first operand
3837 3838
must be <a href="#Assignability">assignable</a>
to the type of the second operand, or vice versa.
Rob Pike's avatar
Rob Pike committed
3839
</p>
3840
<p>
3841 3842 3843 3844 3845
The equality operators <code>==</code> and <code>!=</code> apply
to operands that are <i>comparable</i>.
The ordering operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code>
apply to operands that are <i>ordered</i>.
These terms and the result of the comparisons are defined as follows:
Rob Pike's avatar
Rob Pike committed
3846
</p>
3847

3848 3849
<ul>
	<li>
3850 3851 3852
	Boolean values are comparable.
	Two boolean values are equal if they are either both
	<code>true</code> or both <code>false</code>.
3853
	</li>
3854

3855
	<li>
3856
	Integer values are comparable and ordered, in the usual way.
3857
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3858

3859
	<li>
3860
	Floating-point values are comparable and ordered,
3861
	as defined by the IEEE-754 standard.
3862
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3863

3864
	<li>
3865 3866 3867 3868
	Complex values are comparable.
	Two complex values <code>u</code> and <code>v</code> are
	equal if both <code>real(u) == real(v)</code> and
	<code>imag(u) == imag(v)</code>.
3869
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3870

3871
	<li>
3872
	String values are comparable and ordered, lexically byte-wise.
3873
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3874

3875
	<li>
3876
	Pointer values are comparable.
3877 3878
	Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>.
	Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal.
3879
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3880

3881
	<li>
3882
	Channel values are comparable.
3883 3884
	Two channel values are equal if they were created by the same call to
	<a href="#Making_slices_maps_and_channels"><code>make</code></a>
3885
	or if both have value <code>nil</code>.
3886
	</li>
3887

3888
	<li>
3889 3890 3891
	Interface values are comparable.
	Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types
	and equal dynamic values or if both have value <code>nil</code>.
3892
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3893

3894
	<li>
3895 3896 3897 3898 3899 3900
	A value <code>x</code> of non-interface type <code>X</code> and
	a value <code>t</code> of interface type <code>T</code> are comparable when values
	of type <code>X</code> are comparable and
	<code>X</code> implements <code>T</code>.
	They are equal if <code>t</code>'s dynamic type is identical to <code>X</code>
	and <code>t</code>'s dynamic value is equal to <code>x</code>.
3901
	</li>
3902

3903
	<li>
3904 3905 3906
	Struct values are comparable if all their fields are comparable.
	Two struct values are equal if their corresponding
	non-<a href="#Blank_identifier">blank</a> fields are equal.
3907
	</li>
Hong Ruiqi's avatar
Hong Ruiqi committed
3908

3909
	<li>
3910 3911
	Array values are comparable if values of the array element type are comparable.
	Two array values are equal if their corresponding elements are equal.
3912 3913 3914
	</li>
</ul>

3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929
<p>
A comparison of two interface values with identical dynamic types
causes a <a href="#Run_time_panics">run-time panic</a> if values
of that type are not comparable.  This behavior applies not only to direct interface
value comparisons but also when comparing arrays of interface values
or structs with interface-valued fields.
</p>

<p>
Slice, map, and function values are not comparable.
However, as a special case, a slice, map, or function value may
be compared to the predeclared identifier <code>nil</code>.
Comparison of pointer, channel, and interface values to <code>nil</code>
is also allowed and follows from the general rules above.
</p>
3930

3931
<pre>
3932
const c = 3 &lt; 4            // c is the untyped boolean constant true
3933

3934
type MyBool bool
3935 3936
var x, y int
var (
3937
	// The result of a comparison is an untyped boolean.
3938 3939 3940 3941
	// The usual assignment rules apply.
	b3        = x == y // b3 has type bool
	b4 bool   = x == y // b4 has type bool
	b5 MyBool = x == y // b5 has type MyBool
3942 3943 3944
)
</pre>

3945
<h3 id="Logical_operators">Logical operators</h3>
3946

Rob Pike's avatar
Rob Pike committed
3947
<p>
3948 3949
Logical operators apply to <a href="#Boolean_types">boolean</a> values
and yield a result of the same type as the operands.
3950
The right operand is evaluated conditionally.
Rob Pike's avatar
Rob Pike committed
3951
</p>
3952

Rob Pike's avatar
Rob Pike committed
3953
<pre class="grammar">
3954 3955 3956
&amp;&amp;    conditional AND    p &amp;&amp; q  is  "if p then q else false"
||    conditional OR     p || q  is  "if p then true else q"
!     NOT                !p      is  "not p"
3957
</pre>
3958 3959


3960
<h3 id="Address_operators">Address operators</h3>
3961

Rob Pike's avatar
Rob Pike committed
3962
<p>
3963 3964 3965
For an operand <code>x</code> of type <code>T</code>, the address operation
<code>&amp;x</code> generates a pointer of type <code>*T</code> to <code>x</code>.
The operand must be <i>addressable</i>,
3966
that is, either a variable, pointer indirection, or slice indexing
3967
operation; or a field selector of an addressable struct operand;
3968
or an array indexing operation of an addressable array.
3969
As an exception to the addressability requirement, <code>x</code> may also be a
3970
(possibly parenthesized)
3971
<a href="#Composite_literals">composite literal</a>.
3972
If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>,
3973
then the evaluation of <code>&amp;x</code> does too.
3974
</p>
Russ Cox's avatar
Russ Cox committed
3975

3976 3977
<p>
For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
Robert Griesemer's avatar
Robert Griesemer committed
3978
indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed
3979
to by <code>x</code>.
3980 3981
If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code>
will cause a <a href="#Run_time_panics">run-time panic</a>.
Rob Pike's avatar
Rob Pike committed
3982 3983 3984 3985 3986
</p>

<pre>
&amp;x
&amp;a[f(2)]
3987
&amp;Point{2, 3}
Rob Pike's avatar
Rob Pike committed
3988 3989
*p
*pf(x)
Russ Cox's avatar
Russ Cox committed
3990 3991 3992

var x *int = nil
*x   // causes a run-time panic
3993
&amp;*x  // causes a run-time panic
Rob Pike's avatar
Rob Pike committed
3994 3995
</pre>

Rob Pike's avatar
Rob Pike committed
3996

3997
<h3 id="Receive_operator">Receive operator</h3>
3998

Rob Pike's avatar
Rob Pike committed
3999
<p>
4000 4001
For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>,
the value of the receive operation <code>&lt;-ch</code> is the value received
4002 4003 4004
from the channel <code>ch</code>. The channel direction must permit receive operations,
and the type of the receive operation is the element type of the channel.
The expression blocks until a value is available.
4005
Receiving from a <code>nil</code> channel blocks forever.
4006
A receive operation on a <a href="#Close">closed</a> channel can always proceed
4007 4008
immediately, yielding the element type's <a href="#The_zero_value">zero value</a>
after any previously sent values have been received.
Rob Pike's avatar
Rob Pike committed
4009
</p>
4010

4011
<pre>
4012 4013 4014
v1 := &lt;-ch
v2 = &lt;-ch
f(&lt;-ch)
4015
&lt;-strobe  // wait until clock pulse and discard received value
4016
</pre>
4017

Rob Pike's avatar
Rob Pike committed
4018
<p>
4019
A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pike's avatar
Rob Pike committed
4020
</p>
4021

4022
<pre>
4023 4024 4025
x, ok = &lt;-ch
x, ok := &lt;-ch
var x, ok = &lt;-ch
4026
var x, ok T = &lt;-ch
4027
</pre>
4028

Rob Pike's avatar
Rob Pike committed
4029
<p>
4030
yields an additional untyped boolean result reporting whether the
4031 4032 4033 4034
communication succeeded. The value of <code>ok</code> is <code>true</code>
if the value received was delivered by a successful send operation to the
channel, or <code>false</code> if it is a zero value generated because the
channel is closed and empty.
Rob Pike's avatar
Rob Pike committed
4035
</p>
4036

4037

4038 4039 4040
<h3 id="Conversions">Conversions</h3>

<p>
4041 4042 4043 4044 4045 4046 4047 4048
A conversion changes the <a href="#Types">type</a> of an expression
to the type specified by the conversion.
A conversion may appear literally in the source, or it may be <i>implied</i>
by the context in which an expression appears.
</p>

<p>
An <i>explicit</i> conversion is an expression of the form <code>T(x)</code>
4049 4050 4051 4052 4053
where <code>T</code> is a type and <code>x</code> is an expression
that can be converted to type <code>T</code>.
</p>

<pre class="ebnf">
4054
Conversion = Type "(" Expression [ "," ] ")" .
4055 4056 4057
</pre>

<p>
4058
If the type starts with the operator <code>*</code> or <code>&lt;-</code>,
4059 4060 4061
or if the type starts with the keyword <code>func</code>
and has no result list, it must be parenthesized when
necessary to avoid ambiguity:
4062 4063 4064 4065
</p>

<pre>
*Point(p)        // same as *(Point(p))
4066
(*Point)(p)      // p is converted to *Point
4067
&lt;-chan int(c)    // same as &lt;-(chan int(c))
4068
(&lt;-chan int)(c)  // c is converted to &lt;-chan int
4069
func()(x)        // function signature func() x
4070 4071 4072
(func())(x)      // x is converted to func()
(func() int)(x)  // x is converted to func() int
func() int(x)    // x is converted to func() int (unambiguous)
4073 4074 4075
</pre>

<p>
4076
A <a href="#Constants">constant</a> value <code>x</code> can be converted to
4077 4078
type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a>
by a value of <code>T</code>.
4079
As a special case, an integer constant <code>x</code> can be explicitly converted to a
4080 4081 4082
<a href="#String_types">string type</a> using the
<a href="#Conversions_to_and_from_a_string_type">same rule</a>
as for non-constant <code>x</code>.
4083 4084 4085 4086 4087 4088 4089 4090 4091 4092
</p>

<p>
Converting a constant yields a typed constant as result.
</p>

<pre>
uint(iota)               // iota value of type uint
float32(2.718281828)     // 2.718281828 of type float32
complex128(1)            // 1.0 + 0.0i of type complex128
4093
float32(0.49999999)      // 0.5 of type float32
4094
float64(-1e-1000)        // 0.0 of type float64
4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106
string('x')              // "x" of type string
string(0x266c)           // "♬" of type string
MyString("foo" + "bar")  // "foobar" of type MyString
string([]byte{'a'})      // not a constant: []byte{'a'} is not a constant
(*int)(nil)              // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
int(1.2)                 // illegal: 1.2 cannot be represented as an int
string(65.0)             // illegal: 65.0 is not an integer constant
</pre>

<p>
A non-constant value <code>x</code> can be converted to type <code>T</code>
in any of these cases:
4107
</p>
4108

4109 4110
<ul>
	<li>
4111
	<code>x</code> is <a href="#Assignability">assignable</a>
4112 4113 4114
	to <code>T</code>.
	</li>
	<li>
4115 4116
	ignoring struct tags (see below),
	<code>x</code>'s type and <code>T</code> have <a href="#Type_identity">identical</a>
4117 4118 4119
	<a href="#Types">underlying types</a>.
	</li>
	<li>
4120
	ignoring struct tags (see below),
4121 4122
	<code>x</code>'s type and <code>T</code> are pointer types
	that are not <a href="#Type_definitions">defined types</a>,
4123 4124 4125 4126 4127 4128 4129 4130 4131 4132
	and their pointer base types have identical underlying types.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> are both integer or floating
	point types.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> are both complex types.
	</li>
	<li>
4133 4134
	<code>x</code> is an integer or a slice of bytes or runes
	and <code>T</code> is a string type.
4135 4136
	</li>
	<li>
4137
	<code>x</code> is a string and <code>T</code> is a slice of bytes or runes.
4138 4139
	</li>
</ul>
4140

4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165
<p>
<a href="#Struct_types">Struct tags</a> are ignored when comparing struct types
for identity for the purpose of conversion:
</p>

<pre>
type Person struct {
	Name    string
	Address *struct {
		Street string
		City   string
	}
}

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

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

4166
<p>
4167 4168
Specific rules apply to (non-constant) conversions between numeric types or
to and from a string type.
4169 4170 4171 4172
These conversions may change the representation of <code>x</code>
and incur a run-time cost.
All other conversions only change the type but not the representation
of <code>x</code>.
4173 4174
</p>

4175 4176 4177 4178 4179 4180 4181
<p>
There is no linguistic mechanism to convert between pointers and integers.
The package <a href="#Package_unsafe"><code>unsafe</code></a>
implements this functionality under
restricted circumstances.
</p>

4182
<h4>Conversions between numeric types</h4>
4183 4184 4185 4186 4187

<p>
For the conversion of non-constant numeric values, the following rules apply:
</p>

4188
<ol>
4189
<li>
4190 4191 4192 4193 4194
When converting between integer types, if the value is a signed integer, it is
sign extended to implicit infinite precision; otherwise it is zero extended.
It is then truncated to fit in the result type's size.
For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>.
The conversion always yields a valid value; there is no indication of overflow.
4195 4196
</li>
<li>
4197 4198
When converting a floating-point number to an integer, the fraction is discarded
(truncation towards zero).
4199
</li>
Rob Pike's avatar
Rob Pike committed
4200
<li>
4201 4202
When converting an integer or floating-point number to a floating-point type,
or a complex number to another complex type, the result value is rounded
Rob Pike's avatar
Rob Pike committed
4203
to the precision specified by the destination type.
4204 4205 4206 4207
For instance, the value of a variable <code>x</code> of type <code>float32</code>
may be stored using additional precision beyond that of an IEEE-754 32-bit number,
but float32(x) represents the result of rounding <code>x</code>'s value to
32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits
Evan Shaw's avatar
Evan Shaw committed
4208
of precision, but <code>float32(x + 0.1)</code> does not.
4209
</li>
4210 4211 4212
</ol>

<p>
4213
In all non-constant conversions involving floating-point or complex values,
Rob Pike's avatar
Rob Pike committed
4214
if the result type cannot represent the value the conversion
4215
succeeds but the result value is implementation-dependent.
4216 4217
</p>

4218
<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
4219

4220
<ol>
4221
<li>
4222
Converting a signed or unsigned integer value to a string type yields a
4223 4224
string containing the UTF-8 representation of the integer. Values outside
the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
4225 4226

<pre>
4227
string('a')       // "a"
4228
string(-1)        // "\ufffd" == "\xef\xbf\xbd"
4229
string(0xf8)      // "\u00f8" == "ø" == "\xc3\xb8"
4230
type MyString string
4231
MyString(0x65e5)  // "\u65e5" == "日" == "\xe6\x97\xa5"
4232 4233 4234 4235
</pre>
</li>

<li>
4236
Converting a slice of bytes to a string type yields
4237
a string whose successive bytes are the elements of the slice.
4238 4239

<pre>
4240 4241 4242
string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'})   // "hellø"
string([]byte{})                                     // ""
string([]byte(nil))                                  // ""
4243 4244 4245

type MyBytes []byte
string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'})  // "hellø"
4246 4247
</pre>
</li>
4248

4249
<li>
4250
Converting a slice of runes to a string type yields
4251
a string that is the concatenation of the individual rune values
4252
converted to strings.
4253

4254
<pre>
4255 4256 4257
string([]rune{0x767d, 0x9d6c, 0x7fd4})   // "\u767d\u9d6c\u7fd4" == "白鵬翔"
string([]rune{})                         // ""
string([]rune(nil))                      // ""
4258 4259 4260

type MyRunes []rune
string(MyRunes{0x767d, 0x9d6c, 0x7fd4})  // "\u767d\u9d6c\u7fd4" == "白鵬翔"
4261
</pre>
4262 4263 4264
</li>

<li>
4265
Converting a value of a string type to a slice of bytes type
4266 4267 4268
yields a slice whose successive elements are the bytes of the string.

<pre>
4269
[]byte("hellø")   // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
4270 4271
[]byte("")        // []byte{}

4272
MyBytes("hellø")  // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
4273 4274
</pre>
</li>
4275

4276
<li>
4277 4278
Converting a value of a string type to a slice of runes type
yields a slice containing the individual Unicode code points of the string.
4279

4280
<pre>
4281
[]rune(MyString("白鵬翔"))  // []rune{0x767d, 0x9d6c, 0x7fd4}
4282 4283
[]rune("")                 // []rune{}

4284
MyRunes("白鵬翔")           // []rune{0x767d, 0x9d6c, 0x7fd4}
4285 4286
</pre>
</li>
4287
</ol>
4288 4289


4290
<h3 id="Constant_expressions">Constant expressions</h3>
Robert Griesemer's avatar
Robert Griesemer committed
4291

4292
<p>
4293
Constant expressions may contain only <a href="#Constants">constant</a>
4294
operands and are evaluated at compile time.
4295
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4296

4297
<p>
4298 4299
Untyped boolean, numeric, and string constants may be used as operands
wherever it is legal to use an operand of boolean, numeric, or string type,
4300
respectively.
4301
</p>
4302 4303

<p>
4304
A constant <a href="#Comparison_operators">comparison</a> always yields
4305
an untyped boolean constant.  If the left operand of a constant
4306 4307
<a href="#Operators">shift expression</a> is an untyped constant, the
result is an integer constant; otherwise it is a constant of the same
4308 4309
type as the left operand, which must be of
<a href="#Numeric_types">integer type</a>.
4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320
</p>

<p>
Any other operation on untyped constants results in an untyped constant of the
same kind; that is, a boolean, integer, floating-point, complex, or string
constant.
If the untyped operands of a binary operation (other than a shift) are of
different kinds, the result is of the operand's kind that appears later in this
list: integer, rune, floating-point, complex.
For example, an untyped integer constant divided by an
untyped complex constant yields an untyped complex constant.
4321 4322
</p>

4323
<pre>
4324 4325 4326
const a = 2 + 3.0          // a == 5.0   (untyped floating-point constant)
const b = 15 / 4           // b == 3     (untyped integer constant)
const c = 15 / 4.0         // c == 3.75  (untyped floating-point constant)
4327 4328
const Θ float64 = 3/2      // Θ == 1.0   (type float64, 3/2 is integer division)
const Π float64 = 3/2.     // Π == 1.5   (type float64, 3/2. is float division)
4329 4330
const d = 1 &lt;&lt; 3.0         // d == 8     (untyped integer constant)
const e = 1.0 &lt;&lt; 3         // e == 8     (untyped integer constant)
4331
const f = int32(1) &lt;&lt; 33   // illegal    (constant 8589934592 overflows int32)
4332
const g = float64(2) &gt;&gt; 1  // illegal    (float64(2) is a typed floating-point constant)
4333 4334
const h = "foo" &gt; "bar"    // h == true  (untyped boolean constant)
const j = true             // j == true  (untyped boolean constant)
4335
const k = 'w' + 1          // k == 'x'   (untyped rune constant)
4336 4337
const l = "hi"             // l == "hi"  (untyped string constant)
const m = string(k)        // m == "x"   (type string)
4338
const Σ = 1 - 0.707i       //            (untyped complex constant)
4339 4340
const Δ = Σ + 2.0e-4       //            (untyped complex constant)
const Φ = iota*1i - 1/1i   //            (untyped complex constant)
4341 4342
</pre>

Rob Pike's avatar
Rob Pike committed
4343
<p>
4344
Applying the built-in function <code>complex</code> to untyped
4345
integer, rune, or floating-point constants yields
4346
an untyped complex constant.
Rob Pike's avatar
Rob Pike committed
4347 4348 4349
</p>

<pre>
4350
const ic = complex(0, c)   // ic == 3.75i  (untyped complex constant)
4351
const iΘ = complex(0, Θ)   // iΘ == 1i     (type complex128)
Rob Pike's avatar
Rob Pike committed
4352 4353
</pre>

4354
<p>
4355 4356 4357
Constant expressions are always evaluated exactly; intermediate values and the
constants themselves may require precision significantly larger than supported
by any predeclared type in the language. The following are legal declarations:
4358 4359 4360
</p>

<pre>
4361 4362
const Huge = 1 &lt;&lt; 100         // Huge == 1267650600228229401496703205376  (untyped integer constant)
const Four int8 = Huge &gt;&gt; 98  // Four == 4                                (type int8)
4363
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
4364

4365 4366 4367 4368 4369 4370 4371 4372
<p>
The divisor of a constant division or remainder operation must not be zero:
</p>

<pre>
3.14 / 0.0   // illegal: division by zero
</pre>

4373
<p>
4374 4375
The values of <i>typed</i> constants must always be accurately
<a href="#Representability">representable</a> by values
4376
of the constant type. The following constant expressions are illegal:
4377 4378 4379
</p>

<pre>
4380 4381
uint(-1)     // -1 cannot be represented as a uint
int(3.14)    // 3.14 cannot be represented as an int
4382 4383 4384
int64(Huge)  // 1267650600228229401496703205376 cannot be represented as an int64
Four * 300   // operand 300 cannot be represented as an int8 (type of Four)
Four * 100   // product 400 cannot be represented as an int8 (type of Four)
4385 4386 4387
</pre>

<p>
4388
The mask used by the unary bitwise complement operator <code>^</code> matches
Rob Pike's avatar
Rob Pike committed
4389
the rule for non-constants: the mask is all 1s for unsigned constants
4390
and -1 for signed and untyped constants.
4391 4392 4393
</p>

<pre>
4394
^1         // untyped integer constant, equal to -2
4395
uint8(^1)  // illegal: same as uint8(-2), -2 cannot be represented as a uint8
4396 4397 4398
^uint8(1)  // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
int8(^1)   // same as int8(-2)
^int8(1)   // same as -1 ^ int8(1) = -2
4399 4400
</pre>

4401 4402 4403 4404 4405 4406 4407
<p>
Implementation restriction: A compiler may use rounding while
computing untyped floating-point or complex constant expressions; see
the implementation restriction in the section
on <a href="#Constants">constants</a>.  This rounding may cause a
floating-point constant expression to be invalid in an integer
context, even if it would be integral when calculated using infinite
4408
precision, and vice versa.
4409 4410
</p>

4411

4412
<h3 id="Order_of_evaluation">Order of evaluation</h3>
4413 4414

<p>
4415
At package level, <a href="#Package_initialization">initialization dependencies</a>
4416 4417 4418 4419
determine the evaluation order of individual initialization expressions in
<a href="#Variable_declarations">variable declarations</a>.
Otherwise, when evaluating the <a href="#Operands">operands</a> of an
expression, assignment, or
4420 4421
<a href="#Return_statements">return statement</a>,
all function calls, method calls, and
4422
communication operations are evaluated in lexical left-to-right
4423 4424 4425
order.
</p>

4426
<p>
4427
For example, in the (function-local) assignment
4428 4429
</p>
<pre>
4430
y[f()], ok = g(h(), i()+x[j()], &lt;-c), k()
4431 4432
</pre>
<p>
4433 4434
the function calls and communication happen in the order
<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>,
4435
<code>&lt;-c</code>, <code>g()</code>, and <code>k()</code>.
4436 4437 4438
However, the order of those events compared to the evaluation
and indexing of <code>x</code> and the evaluation
of <code>y</code> is not specified.
4439 4440
</p>

4441 4442
<pre>
a := 1
4443
f := func() int { a++; return a }
4444 4445 4446
x := []int{a, f()}            // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
m := map[int]int{a: 1, a: 2}  // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
n := map[int]int{a: f()}      // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
4447 4448
</pre>

4449 4450 4451
<p>
At package level, initialization dependencies override the left-to-right rule
for individual initialization expressions, but not for operands within each
4452
expression:
4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470
</p>

<pre>
var a, b, c = f() + v(), g(), sqr(u()) + v()

func f() int        { return c }
func g() int        { return a }
func sqr(x int) int { return x*x }

// functions u and v are independent of all other variables and functions
</pre>

<p>
The function calls happen in the order
<code>u()</code>, <code>sqr()</code>, <code>v()</code>,
<code>f()</code>, <code>v()</code>, and <code>g()</code>.
</p>

4471 4472 4473 4474 4475 4476 4477 4478
<p>
Floating-point operations within a single expression are evaluated according to
the associativity of the operators.  Explicit parentheses affect the evaluation
by overriding the default associativity.
In the expression <code>x + (y + z)</code> the addition <code>y + z</code>
is performed before adding <code>x</code>.
</p>

4479
<h2 id="Statements">Statements</h2>
4480

Rob Pike's avatar
Rob Pike committed
4481
<p>
4482
Statements control execution.
Rob Pike's avatar
Rob Pike committed
4483
</p>
4484

4485
<pre class="ebnf">
4486
Statement =
4487 4488
	Declaration | LabeledStmt | SimpleStmt |
	GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
4489 4490
	FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
	DeferStmt .
Robert Griesemer's avatar
Robert Griesemer committed
4491

4492
SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
4493
</pre>
4494

4495 4496 4497
<h3 id="Terminating_statements">Terminating statements</h3>

<p>
4498 4499 4500
A <i>terminating statement</i> prevents execution of all statements that lexically
appear after it in the same <a href="#Blocks">block</a>. The following statements
are terminating:
4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571
</p>

<ol>
<li>
	A <a href="#Return_statements">"return"</a> or
    	<a href="#Goto_statements">"goto"</a> statement.
	<!-- ul below only for regular layout -->
	<ul> </ul>
</li>

<li>
	A call to the built-in function
	<a href="#Handling_panics"><code>panic</code></a>.
	<!-- ul below only for regular layout -->
	<ul> </ul>
</li>

<li>
	A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
	<!-- ul below only for regular layout -->
	<ul> </ul>
</li>

<li>
	An <a href="#If_statements">"if" statement</a> in which:
	<ul>
	<li>the "else" branch is present, and</li>
	<li>both branches are terminating statements.</li>
	</ul>
</li>

<li>
	A <a href="#For_statements">"for" statement</a> in which:
	<ul>
	<li>there are no "break" statements referring to the "for" statement, and</li>
	<li>the loop condition is absent.</li>
	</ul>
</li>

<li>
	A <a href="#Switch_statements">"switch" statement</a> in which:
	<ul>
	<li>there are no "break" statements referring to the "switch" statement,</li>
	<li>there is a default case, and</li>
	<li>the statement lists in each case, including the default, end in a terminating
	    statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
	    statement</a>.</li>
	</ul>
</li>

<li>
	A <a href="#Select_statements">"select" statement</a> in which:
	<ul>
	<li>there are no "break" statements referring to the "select" statement, and</li>
	<li>the statement lists in each case, including the default if present,
	    end in a terminating statement.</li>
	</ul>
</li>

<li>
	A <a href="#Labeled_statements">labeled statement</a> labeling
	a terminating statement.
</li>
</ol>

<p>
All other statements are not terminating.
</p>

<p>
A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
4572
is not empty and its final non-empty statement is terminating.
4573 4574
</p>

4575

4576
<h3 id="Empty_statements">Empty statements</h3>
4577

Rob Pike's avatar
Rob Pike committed
4578
<p>
4579
The empty statement does nothing.
Rob Pike's avatar
Rob Pike committed
4580
</p>
4581

4582
<pre class="ebnf">
4583
EmptyStmt = .
4584
</pre>
4585 4586


4587
<h3 id="Labeled_statements">Labeled statements</h3>
4588 4589 4590 4591 4592 4593

<p>
A labeled statement may be the target of a <code>goto</code>,
<code>break</code> or <code>continue</code> statement.
</p>

4594
<pre class="ebnf">
4595
LabeledStmt = Label ":" Statement .
4596 4597 4598 4599
Label       = identifier .
</pre>

<pre>
4600
Error: log.Panic("error encountered")
4601 4602 4603
</pre>


4604
<h3 id="Expression_statements">Expression statements</h3>
4605

Rob Pike's avatar
Rob Pike committed
4606
<p>
4607 4608 4609
With the exception of specific built-in functions,
function and method <a href="#Calls">calls</a> and
<a href="#Receive_operator">receive operations</a>
4610
can appear in statement context. Such statements may be parenthesized.
Rob Pike's avatar
Rob Pike committed
4611 4612
</p>

4613
<pre class="ebnf">
4614
ExpressionStmt = Expression .
4615
</pre>
4616

4617 4618 4619 4620 4621 4622 4623 4624 4625
<p>
The following built-in functions are not permitted in statement context:
</p>

<pre>
append cap complex imag len make new real
unsafe.Alignof unsafe.Offsetof unsafe.Sizeof
</pre>

4626
<pre>
4627 4628
h(x+y)
f.Close()
4629
&lt;-ch
4630
(&lt;-ch)
4631
len("foo")  // illegal if len is the built-in function
4632
</pre>
4633 4634


4635 4636 4637 4638
<h3 id="Send_statements">Send statements</h3>

<p>
A send statement sends a value on a channel.
4639 4640 4641
The channel expression must be of <a href="#Channel_types">channel type</a>,
the channel direction must permit send operations,
and the type of the value to be sent must be <a href="#Assignability">assignable</a>
4642 4643 4644 4645 4646 4647 4648 4649 4650 4651
to the channel's element type.
</p>

<pre class="ebnf">
SendStmt = Channel "&lt;-" Expression .
Channel  = Expression .
</pre>

<p>
Both the channel and the value expression are evaluated before communication
4652
begins. Communication blocks until the send can proceed.
4653 4654
A send on an unbuffered channel can proceed if a receiver is ready.
A send on a buffered channel can proceed if there is room in the buffer.
4655
A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>.
4656
A send on a <code>nil</code> channel blocks forever.
4657 4658 4659
</p>

<pre>
4660
ch &lt;- 3  // send value 3 to channel ch
4661 4662 4663
</pre>


4664
<h3 id="IncDec_statements">IncDec statements</h3>
4665

Rob Pike's avatar
Rob Pike committed
4666
<p>
4667
The "++" and "--" statements increment or decrement their operands
4668
by the untyped <a href="#Constants">constant</a> <code>1</code>.
4669 4670
As with an assignment, the operand must be <a href="#Address_operators">addressable</a>
or a map index expression.
Rob Pike's avatar
Rob Pike committed
4671
</p>
4672

4673
<pre class="ebnf">
4674
IncDecStmt = Expression ( "++" | "--" ) .
4675
</pre>
4676

Rob Pike's avatar
Rob Pike committed
4677
<p>
Robert Griesemer's avatar
Robert Griesemer committed
4678
The following <a href="#Assignments">assignment statements</a> are semantically
4679
equivalent:
Rob Pike's avatar
Rob Pike committed
4680
</p>
4681

Rob Pike's avatar
Rob Pike committed
4682
<pre class="grammar">
4683 4684 4685 4686
IncDec statement    Assignment
x++                 x += 1
x--                 x -= 1
</pre>
4687

4688

4689
<h3 id="Assignments">Assignments</h3>
4690

4691
<pre class="ebnf">
4692
Assignment = ExpressionList assign_op ExpressionList .
Rob Pike's avatar
Rob Pike committed
4693

4694 4695
assign_op = [ add_op | mul_op ] "=" .
</pre>
4696

Rob Pike's avatar
Rob Pike committed
4697
<p>
Rob Pike's avatar
Rob Pike committed
4698
Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
4699 4700
a map index expression, or (for <code>=</code> assignments only) the
<a href="#Blank_identifier">blank identifier</a>.
4701
Operands may be parenthesized.
Rob Pike's avatar
Rob Pike committed
4702
</p>
4703

4704 4705 4706 4707
<pre>
x = 1
*p = f()
a[i] = 23
4708
(k) = &lt;-ch  // same as: k = &lt;-ch
4709
</pre>
4710

Rob Pike's avatar
Rob Pike committed
4711 4712
<p>
An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
4713 4714
<code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a>
is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
4715
<code>(y)</code> but evaluates <code>x</code>
Rob Pike's avatar
Rob Pike committed
4716
only once.  The <i>op</i><code>=</code> construct is a single token.
Rob Pike's avatar
Rob Pike committed
4717
In assignment operations, both the left- and right-hand expression lists
4718 4719
must contain exactly one single-valued expression, and the left-hand
expression must not be the blank identifier.
Rob Pike's avatar
Rob Pike committed
4720
</p>
4721

4722
<pre>
4723
a[i] &lt;&lt;= 2
Rob Pike's avatar
Rob Pike committed
4724
i &amp;^= 1&lt;&lt;n
4725
</pre>
4726

Rob Pike's avatar
Rob Pike committed
4727 4728 4729 4730
<p>
A tuple assignment assigns the individual elements of a multi-valued
operation to a list of variables.  There are two forms.  In the
first, the right hand operand is a single multi-valued expression
4731 4732
such as a function call, a <a href="#Channel_types">channel</a> or
<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>.
4733
The number of operands on the left
Robert Griesemer's avatar
Robert Griesemer committed
4734
hand side must match the number of values.  For instance, if
Rob Pike's avatar
Rob Pike committed
4735 4736
<code>f</code> is a function returning two values,
</p>
4737

4738 4739 4740
<pre>
x, y = f()
</pre>
4741

Rob Pike's avatar
Rob Pike committed
4742 4743
<p>
assigns the first value to <code>x</code> and the second to <code>y</code>.
4744 4745 4746 4747
In the second form, the number of operands on the left must equal the number
of expressions on the right, each of which must be single-valued, and the
<i>n</i>th expression on the right is assigned to the <i>n</i>th
operand on the left:
Rob Pike's avatar
Rob Pike committed
4748
</p>
4749

Robert Griesemer's avatar
Robert Griesemer committed
4750
<pre>
4751
one, two, three = '一', '二', '三'
Robert Griesemer's avatar
Robert Griesemer committed
4752 4753
</pre>

Rob Pike's avatar
Rob Pike committed
4754
<p>
4755 4756
The <a href="#Blank_identifier">blank identifier</a> provides a way to
ignore right-hand side values in an assignment:
4757 4758
</p>

4759 4760 4761 4762 4763
<pre>
_ = x       // evaluate x but ignore it
x, _ = f()  // evaluate f() but ignore second result value
</pre>

4764 4765
<p>
The assignment proceeds in two phases.
4766
First, the operands of <a href="#Index_expressions">index expressions</a>
4767 4768 4769 4770 4771
and <a href="#Address_operators">pointer indirections</a>
(including implicit pointer indirections in <a href="#Selectors">selectors</a>)
on the left and the expressions on the right are all
<a href="#Order_of_evaluation">evaluated in the usual order</a>.
Second, the assignments are carried out in left-to-right order.
Rob Pike's avatar
Rob Pike committed
4772
</p>
4773

4774
<pre>
Rob Pike's avatar
Rob Pike committed
4775
a, b = b, a  // exchange a and b
4776 4777 4778

x := []int{1, 2, 3}
i := 0
4779
i, x[i] = 1, 2  // set i = 1, x[0] = 2
4780 4781 4782 4783

i = 0
x[i], i = 2, 1  // set x[0] = 2, i = 1

4784
x[0], x[0] = 1, 2  // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end)
4785

4786
x[1], x[3] = 4, 5  // set x[1] = 4, then panic setting x[3] = 5.
4787 4788 4789 4790

type Point struct { x, y int }
var p *Point
x[2], p.x = 6, 7  // set x[2] = 6, then panic setting p.x = 7
4791 4792 4793 4794 4795 4796 4797

i = 2
x = []int{3, 5, 7}
for i, x[i] = range x {  // set i, x[2] = 0, x[0]
	break
}
// after this loop, i == 0 and x == []int{3, 5, 3}
4798
</pre>
Rob Pike's avatar
Rob Pike committed
4799 4800

<p>
4801 4802
In assignments, each value must be <a href="#Assignability">assignable</a>
to the type of the operand to which it is assigned, with the following special cases:
Rob Pike's avatar
Rob Pike committed
4803
</p>
4804

4805
<ol>
4806 4807 4808 4809 4810 4811
<li>
	Any typed value may be assigned to the blank identifier.
</li>

<li>
	If an untyped constant
4812
	is assigned to a variable of interface type or the blank identifier,
4813
	the constant is first implicitly <a href="#Conversions">converted</a> to its
4814 4815 4816 4817 4818
	 <a href="#Constants">default type</a>.
</li>

<li>
	If an untyped boolean value is assigned to a variable of interface type or
4819
	the blank identifier, it is first implicitly converted to type <code>bool</code>.
4820
</li>
4821
</ol>
4822

4823
<h3 id="If_statements">If statements</h3>
4824

Rob Pike's avatar
Rob Pike committed
4825 4826 4827 4828
<p>
"If" statements specify the conditional execution of two branches
according to the value of a boolean expression.  If the expression
evaluates to true, the "if" branch is executed, otherwise, if
4829
present, the "else" branch is executed.
Rob Pike's avatar
Rob Pike committed
4830
</p>
4831

4832
<pre class="ebnf">
Russ Cox's avatar
Russ Cox committed
4833
IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
4834
</pre>
4835

4836
<pre>
4837 4838
if x &gt; max {
	x = max
4839 4840
}
</pre>
4841

4842
<p>
Russ Cox's avatar
Russ Cox committed
4843 4844
The expression may be preceded by a simple statement, which
executes before the expression is evaluated.
4845
</p>
4846

4847
<pre>
4848 4849
if x := f(); x &lt; y {
	return x
4850
} else if x &gt; z {
4851
	return z
4852
} else {
4853
	return y
4854 4855
}
</pre>
4856 4857


4858
<h3 id="Switch_statements">Switch statements</h3>
4859

Rob Pike's avatar
Rob Pike committed
4860 4861
<p>
"Switch" statements provide multi-way execution.
Rob Pike's avatar
Rob Pike committed
4862 4863 4864
An expression or type specifier is compared to the "cases"
inside the "switch" to determine which branch
to execute.
Rob Pike's avatar
Rob Pike committed
4865
</p>
4866

4867
<pre class="ebnf">
4868
SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
4869 4870
</pre>

Rob Pike's avatar
Rob Pike committed
4871
<p>
Rob Pike's avatar
Rob Pike committed
4872 4873 4874 4875 4876
There are two forms: expression switches and type switches.
In an expression switch, the cases contain expressions that are compared
against the value of the switch expression.
In a type switch, the cases contain types that are compared against the
type of a specially annotated switch expression.
4877
The switch expression is evaluated exactly once in a switch statement.
Rob Pike's avatar
Rob Pike committed
4878 4879
</p>

4880
<h4 id="Expression_switches">Expression switches</h4>
Rob Pike's avatar
Rob Pike committed
4881 4882 4883 4884 4885

<p>
In an expression switch,
the switch expression is evaluated and
the case expressions, which need not be constants,
4886
are evaluated left-to-right and top-to-bottom; the first one that equals the
Rob Pike's avatar
Rob Pike committed
4887
switch expression
Rob Pike's avatar
Rob Pike committed
4888 4889
triggers execution of the statements of the associated case;
the other cases are skipped.
Rob Pike's avatar
Rob Pike committed
4890 4891
If no case matches and there is a "default" case,
its statements are executed.
Rob Pike's avatar
Rob Pike committed
4892 4893
There can be at most one default case and it may appear anywhere in the
"switch" statement.
4894 4895
A missing switch expression is equivalent to the boolean value
<code>true</code>.
Rob Pike's avatar
Rob Pike committed
4896
</p>
4897

4898
<pre class="ebnf">
4899
ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
4900
ExprCaseClause = ExprSwitchCase ":" StatementList .
4901
ExprSwitchCase = "case" ExpressionList | "default" .
4902 4903
</pre>

4904
<p>
4905
If the switch expression evaluates to an untyped constant, it is first implicitly
4906
<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
4907
if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
4908 4909 4910 4911
The predeclared untyped value <code>nil</code> cannot be used as a switch expression.
</p>

<p>
4912
If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a>
4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924
to the type of the switch expression.
For each (possibly converted) case expression <code>x</code> and the value <code>t</code>
of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>.
</p>

<p>
In other words, the switch expression is treated as if it were used to declare and
initialize a temporary variable <code>t</code> without explicit type; it is that
value of <code>t</code> against which each case expression <code>x</code> is tested
for equality.
</p>

Rob Pike's avatar
Rob Pike committed
4925
<p>
4926 4927 4928
In a case or default clause, the last non-empty statement
may be a (possibly <a href="#Labeled_statements">labeled</a>)
<a href="#Fallthrough_statements">"fallthrough" statement</a> to
Rob Pike's avatar
Rob Pike committed
4929
indicate that control should flow from the end of this clause to
4930
the first statement of the next clause.
Rob Pike's avatar
Rob Pike committed
4931
Otherwise control flows to the end of the "switch" statement.
4932 4933
A "fallthrough" statement may appear as the last statement of all
but the last clause of an expression switch.
Rob Pike's avatar
Rob Pike committed
4934
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4935

4936
<p>
4937
The switch expression may be preceded by a simple statement, which
Russ Cox's avatar
Russ Cox committed
4938
executes before the expression is evaluated.
Rob Pike's avatar
Rob Pike committed
4939
</p>
4940

4941 4942
<pre>
switch tag {
4943 4944 4945
default: s3()
case 0, 1, 2, 3: s1()
case 4, 5, 6, 7: s2()
4946
}
4947

4948
switch x := f(); {  // missing switch expression means "true"
4949 4950
case x &lt; 0: return -x
default: return x
4951
}
4952

4953
switch {
4954 4955 4956
case x &lt; y: f1()
case x &lt; z: f2()
case x == 4: f3()
4957 4958
}
</pre>
4959

4960 4961 4962 4963 4964 4965 4966
<p>
Implementation restriction: A compiler may disallow multiple case
expressions evaluating to the same constant.
For instance, the current compilers disallow duplicate integer,
floating point, or string constants in case expressions.
</p>

4967
<h4 id="Type_switches">Type switches</h4>
Rob Pike's avatar
Rob Pike committed
4968 4969

<p>
4970
A type switch compares types rather than values. It is otherwise similar
Robert Griesemer's avatar
Robert Griesemer committed
4971
to an expression switch. It is marked by a special switch expression that
4972
has the form of a <a href="#Type_assertions">type assertion</a>
4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986
using the reserved word <code>type</code> rather than an actual type:
</p>

<pre>
switch x.(type) {
// cases
}
</pre>

<p>
Cases then match actual types <code>T</code> against the dynamic type of the
expression <code>x</code>. As with type assertions, <code>x</code> must be of
<a href="#Interface_types">interface type</a>, and each non-interface type
<code>T</code> listed in a case must implement the type of <code>x</code>.
4987 4988
The types listed in the cases of a type switch must all be
<a href="#Type_identity">different</a>.
Rob Pike's avatar
Rob Pike committed
4989 4990
</p>

4991
<pre class="ebnf">
4992
TypeSwitchStmt  = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
4993
TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
4994
TypeCaseClause  = TypeSwitchCase ":" StatementList .
Rob Pike's avatar
Rob Pike committed
4995 4996
TypeSwitchCase  = "case" TypeList | "default" .
TypeList        = Type { "," Type } .
Rob Pike's avatar
Rob Pike committed
4997 4998
</pre>

4999
<p>
5000 5001
The TypeSwitchGuard may include a
<a href="#Short_variable_declarations">short variable declaration</a>.
5002 5003
When that form is used, the variable is declared at the end of the
TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause.
5004 5005 5006
In clauses with a case listing exactly one type, the variable
has that type; otherwise, the variable has the type of the expression
in the TypeSwitchGuard.
5007 5008
</p>

Rob Pike's avatar
Rob Pike committed
5009
<p>
5010 5011 5012
Instead of a type, a case may use the predeclared identifier
<a href="#Predeclared_identifiers"><code>nil</code></a>;
that case is selected when the expression in the TypeSwitchGuard
Robert Griesemer's avatar
Robert Griesemer committed
5013
is a <code>nil</code> interface value.
5014
There may be at most one <code>nil</code> case.
5015 5016 5017
</p>

<p>
5018
Given an expression <code>x</code> of type <code>interface{}</code>,
5019
the following type switch:
Rob Pike's avatar
Rob Pike committed
5020 5021 5022
</p>

<pre>
5023
switch i := x.(type) {
5024
case nil:
5025
	printString("x is nil")                // type of i is type of x (interface{})
Rob Pike's avatar
Rob Pike committed
5026
case int:
5027
	printInt(i)                            // type of i is int
5028
case float64:
5029
	printFloat64(i)                        // type of i is float64
5030
case func(int) float64:
5031
	printFunction(i)                       // type of i is func(int) float64
5032
case bool, string:
5033
	printString("type is bool or string")  // type of i is type of x (interface{})
Rob Pike's avatar
Rob Pike committed
5034
default:
5035
	printString("don't know the type")     // type of i is type of x (interface{})
Rob Pike's avatar
Rob Pike committed
5036
}
5037
</pre>
Rob Pike's avatar
Rob Pike committed
5038

5039 5040 5041 5042 5043
<p>
could be rewritten:
</p>

<pre>
5044
v := x  // x is evaluated exactly once
5045
if v == nil {
5046
	i := v                                 // type of i is type of x (interface{})
5047
	printString("x is nil")
5048
} else if i, isInt := v.(int); isInt {
5049
	printInt(i)                            // type of i is int
5050
} else if i, isFloat64 := v.(float64); isFloat64 {
5051
	printFloat64(i)                        // type of i is float64
5052
} else if i, isFunc := v.(func(int) float64); isFunc {
5053
	printFunction(i)                       // type of i is func(int) float64
5054
} else {
5055 5056
	_, isBool := v.(bool)
	_, isString := v.(string)
5057
	if isBool || isString {
5058 5059
		i := v                         // type of i is type of x (interface{})
		printString("type is bool or string")
5060
	} else {
5061 5062
		i := v                         // type of i is type of x (interface{})
		printString("don't know the type")
5063
	}
Rob Pike's avatar
Rob Pike committed
5064 5065
}
</pre>
5066

5067
<p>
Russ Cox's avatar
Russ Cox committed
5068 5069
The type switch guard may be preceded by a simple statement, which
executes before the guard is evaluated.
Robert Griesemer's avatar
Robert Griesemer committed
5070
</p>
5071 5072 5073

<p>
The "fallthrough" statement is not permitted in a type switch.
Russ Cox's avatar
Russ Cox committed
5074 5075
</p>

5076
<h3 id="For_statements">For statements</h3>
5077

Rob Pike's avatar
Rob Pike committed
5078
<p>
5079 5080
A "for" statement specifies repeated execution of a block. There are three forms:
The iteration may be controlled by a single condition, a "for" clause, or a "range" clause.
Rob Pike's avatar
Rob Pike committed
5081
</p>
5082

5083
<pre class="ebnf">
5084
ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
5085 5086
Condition = Expression .
</pre>
5087

5088 5089
<h4 id="For_condition">For statements with single condition</h4>

Rob Pike's avatar
Rob Pike committed
5090 5091 5092 5093
<p>
In its simplest form, a "for" statement specifies the repeated execution of
a block as long as a boolean condition evaluates to true.
The condition is evaluated before each iteration.
5094 5095
If the condition is absent, it is equivalent to the boolean value
<code>true</code>.
Rob Pike's avatar
Rob Pike committed
5096
</p>
5097

5098 5099 5100 5101 5102
<pre>
for a &lt; b {
	a *= 2
}
</pre>
5103

5104 5105
<h4 id="For_clause">For statements with <code>for</code> clause</h4>

Rob Pike's avatar
Rob Pike committed
5106
<p>
Rob Pike's avatar
Rob Pike committed
5107
A "for" statement with a ForClause is also controlled by its condition, but
Rob Pike's avatar
Rob Pike committed
5108 5109
additionally it may specify an <i>init</i>
and a <i>post</i> statement, such as an assignment,
Russ Cox's avatar
Russ Cox committed
5110
an increment or decrement statement. The init statement may be a
5111
<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
5112
Variables declared by the init statement are re-used in each iteration.
Rob Pike's avatar
Rob Pike committed
5113
</p>
5114

5115
<pre class="ebnf">
5116
ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
5117 5118
InitStmt = SimpleStmt .
PostStmt = SimpleStmt .
5119
</pre>
5120

5121
<pre>
5122
for i := 0; i &lt; 10; i++ {
5123 5124 5125
	f(i)
}
</pre>
5126

5127
<p>
Rob Pike's avatar
Rob Pike committed
5128 5129 5130 5131
If non-empty, the init statement is executed once before evaluating the
condition for the first iteration;
the post statement is executed after each execution of the block (and
only if the block was executed).
5132 5133
Any element of the ForClause may be empty but the
<a href="#Semicolons">semicolons</a> are
Rob Pike's avatar
Rob Pike committed
5134
required unless there is only a condition.
5135 5136
If the condition is absent, it is equivalent to the boolean value
<code>true</code>.
Rob Pike's avatar
Rob Pike committed
5137
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5138

5139
<pre>
Rob Pike's avatar
Rob Pike committed
5140 5141
for cond { S() }    is the same as    for ; cond ; { S() }
for      { S() }    is the same as    for true     { S() }
5142
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
5143

5144 5145
<h4 id="For_range">For statements with <code>range</code> clause</h4>

Rob Pike's avatar
Rob Pike committed
5146 5147
<p>
A "for" statement with a "range" clause
Rob Pike's avatar
Rob Pike committed
5148
iterates through all entries of an array, slice, string or map,
5149
or values received on a channel. For each entry it assigns <i>iteration values</i>
5150
to corresponding <i>iteration variables</i> if present and then executes the block.
Rob Pike's avatar
Rob Pike committed
5151
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5152

5153
<pre class="ebnf">
5154
RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
5155 5156 5157 5158
</pre>

<p>
The expression on the right in the "range" clause is called the <i>range expression</i>,
5159 5160
which may be an array, pointer to an array, slice, string, map, or channel permitting
<a href="#Receive_operator">receive operations</a>.
5161
As with an assignment, if present the operands on the left must be
5162
<a href="#Address_operators">addressable</a> or map index expressions; they
5163 5164 5165 5166
denote the iteration variables. If the range expression is a channel, at most
one iteration variable is permitted, otherwise there may be up to two.
If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
the range clause is equivalent to the same clause without that identifier.
5167
</p>
5168 5169

<p>
5170 5171 5172 5173
The range expression <code>x</code> is evaluated once before beginning the loop,
with one exception: if at most one iteration variable is present and
<code>len(x)</code> is <a href="#Length_and_capacity">constant</a>,
the range expression is not evaluated.
5174 5175 5176
</p>

<p>
5177
Function calls on the left are evaluated once per iteration.
5178 5179
For each iteration, iteration values are produced as follows
if the respective iteration variables are present:
5180 5181 5182
</p>

<pre class="grammar">
5183
Range expression                          1st value          2nd value
5184 5185

array or slice  a  [n]E, *[n]E, or []E    index    i  int    a[i]       E
5186
string          s  string type            index    i  int    see below  rune
5187
map             m  map[K]V                key      k  K      m[k]       V
5188
channel         c  chan E, &lt;-chan E       element  e  E
5189 5190 5191 5192
</pre>

<ol>
<li>
5193
For an array, pointer to array, or slice value <code>a</code>, the index iteration
5194
values are produced in increasing order, starting at element index 0.
5195
If at most one iteration variable is present, the range loop produces
5196
iteration values from 0 up to <code>len(a)-1</code> and does not index into the array
5197
or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
5198 5199 5200 5201 5202 5203
</li>

<li>
For a string value, the "range" clause iterates over the Unicode code points
in the string starting at byte index 0.  On successive iterations, the index value will be the
index of the first byte of successive UTF-8-encoded code points in the string,
5204
and the second value, of type <code>rune</code>, will be the value of
Rob Pike's avatar
Rob Pike committed
5205
the corresponding code point.  If the iteration encounters an invalid
5206
UTF-8 sequence, the second value will be <code>0xFFFD</code>,
Rob Pike's avatar
Rob Pike committed
5207 5208
the Unicode replacement character, and the next iteration will advance
a single byte in the string.
5209 5210 5211
</li>

<li>
5212 5213
The iteration order over maps is not specified
and is not guaranteed to be the same from one iteration to the next.
Robert Griesemer's avatar
Robert Griesemer committed
5214 5215
If a map entry that has not yet been reached is removed during iteration,
the corresponding iteration value will not be produced. If a map entry is
5216 5217 5218 5219
created during iteration, that entry may be produced during the iteration or
may be skipped. The choice may vary for each entry created and from one
iteration to the next.
If the map is <code>nil</code>, the number of iterations is 0.
5220 5221 5222 5223
</li>

<li>
For channels, the iteration values produced are the successive values sent on
5224 5225
the channel until the channel is <a href="#Close">closed</a>. If the channel
is <code>nil</code>, the range expression blocks forever.
5226
</li>
Anthony Martin's avatar
Anthony Martin committed
5227
</ol>
5228

Rob Pike's avatar
Rob Pike committed
5229
<p>
5230 5231
The iteration values are assigned to the respective
iteration variables as in an <a href="#Assignments">assignment statement</a>.
5232
</p>
5233

5234
<p>
Robert Griesemer's avatar
Robert Griesemer committed
5235
The iteration variables may be declared by the "range" clause using a form of
5236 5237
<a href="#Short_variable_declarations">short variable declaration</a>
(<code>:=</code>).
5238
In this case their types are set to the types of the respective iteration values
5239
and their <a href="#Declarations_and_scope">scope</a> is the block of the "for"
5240
statement; they are re-used in each iteration.
Rob Pike's avatar
Rob Pike committed
5241 5242 5243
If the iteration variables are declared outside the "for" statement,
after execution their values will be those of the last iteration.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5244

5245
<pre>
5246 5247 5248 5249 5250 5251 5252 5253 5254
var testdata *struct {
	a *[7]int
}
for i, _ := range testdata.a {
	// testdata.a is never evaluated; len(testdata.a) is constant
	// i ranges from 0 to 6
	f(i)
}

5255
var a [10]string
5256 5257 5258 5259 5260 5261 5262
for i, s := range a {
	// type of i is int
	// type of s is string
	// s == a[i]
	g(i, s)
}

5263
var key string
5264
var val interface {}  // element type of m is assignable to val
5265
m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
Rob Pike's avatar
Rob Pike committed
5266 5267
for key, val = range m {
	h(key, val)
5268 5269 5270
}
// key == last map key encountered in iteration
// val == map[key]
5271 5272 5273 5274 5275

var ch chan Work = producer()
for w := range ch {
	doWork(w)
}
5276 5277 5278

// empty a channel
for range ch {}
5279
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
5280

5281

5282
<h3 id="Go_statements">Go statements</h3>
5283

Rob Pike's avatar
Rob Pike committed
5284
<p>
5285
A "go" statement starts the execution of a function call
Rob Pike's avatar
Rob Pike committed
5286 5287 5288
as an independent concurrent thread of control, or <i>goroutine</i>,
within the same address space.
</p>
5289

5290
<pre class="ebnf">
5291
GoStmt = "go" Expression .
5292
</pre>
5293

Rob Pike's avatar
Rob Pike committed
5294
<p>
5295 5296 5297 5298 5299 5300
The expression must be a function or method call; it cannot be parenthesized.
Calls of built-in functions are restricted as for
<a href="#Expression_statements">expression statements</a>.
</p>

<p>
5301 5302 5303
The function value and parameters are
<a href="#Calls">evaluated as usual</a>
in the calling goroutine, but
Rob Pike's avatar
Rob Pike committed
5304
unlike with a regular call, program execution does not wait
5305
for the invoked function to complete.
5306 5307 5308 5309 5310
Instead, the function begins executing independently
in a new goroutine.
When the function terminates, its goroutine also terminates.
If the function has any return values, they are discarded when the
function completes.
Rob Pike's avatar
Rob Pike committed
5311
</p>
5312

5313 5314
<pre>
go Server()
5315
go func(ch chan&lt;- bool) { for { sleep(10); ch &lt;- true }} (c)
5316
</pre>
5317 5318


5319
<h3 id="Select_statements">Select statements</h3>
5320

Rob Pike's avatar
Rob Pike committed
5321
<p>
5322 5323 5324 5325 5326 5327
A "select" statement chooses which of a set of possible
<a href="#Send_statements">send</a> or
<a href="#Receive_operator">receive</a>
operations will proceed.
It looks similar to a
<a href="#Switch_statements">"switch"</a> statement but with the
5328
cases all referring to communication operations.
Rob Pike's avatar
Rob Pike committed
5329
</p>
5330

5331
<pre class="ebnf">
5332
SelectStmt = "select" "{" { CommClause } "}" .
5333
CommClause = CommCase ":" StatementList .
5334
CommCase   = "case" ( SendStmt | RecvStmt ) | "default" .
5335
RecvStmt   = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
5336
RecvExpr   = Expression .
5337
</pre>
5338

5339
<p>
5340 5341 5342 5343 5344 5345
A case with a RecvStmt may assign the result of a RecvExpr to one or
two variables, which may be declared using a
<a href="#Short_variable_declarations">short variable declaration</a>.
The RecvExpr must be a (possibly parenthesized) receive operation.
There can be at most one default case and it may appear anywhere
in the list of cases.
Rob Pike's avatar
Rob Pike committed
5346
</p>
5347

5348
<p>
5349
Execution of a "select" statement proceeds in several steps:
Rob Pike's avatar
Rob Pike committed
5350
</p>
5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388

<ol>
<li>
For all the cases in the statement, the channel operands of receive operations
and the channel and right-hand-side expressions of send statements are
evaluated exactly once, in source order, upon entering the "select" statement.
The result is a set of channels to receive from or send to,
and the corresponding values to send.
Any side effects in that evaluation will occur irrespective of which (if any)
communication operation is selected to proceed.
Expressions on the left-hand side of a RecvStmt with a short variable declaration
or assignment are not yet evaluated.
</li>

<li>
If one or more of the communications can proceed,
a single one that can proceed is chosen via a uniform pseudo-random selection.
Otherwise, if there is a default case, that case is chosen.
If there is no default case, the "select" statement blocks until
at least one of the communications can proceed.
</li>

<li>
Unless the selected case is the default case, the respective communication
operation is executed.
</li>

<li>
If the selected case is a RecvStmt with a short variable declaration or
an assignment, the left-hand side expressions are evaluated and the
received value (or values) are assigned.
</li>

<li>
The statement list of the selected case is executed.
</li>
</ol>

5389
<p>
5390 5391
Since communication on <code>nil</code> channels can never proceed,
a select with only <code>nil</code> channels and no default case blocks forever.
Rob Pike's avatar
Rob Pike committed
5392
</p>
5393

5394
<pre>
5395 5396
var a []int
var c, c1, c2, c3, c4 chan int
5397
var i1, i2 int
5398 5399
select {
case i1 = &lt;-c1:
5400
	print("received ", i1, " from c1\n")
5401
case c2 &lt;- i2:
5402
	print("sent ", i2, " to c2\n")
5403
case i3, ok := (&lt;-c3):  // same as: i3, ok := &lt;-c3
5404 5405 5406 5407 5408
	if ok {
		print("received ", i3, " from c3\n")
	} else {
		print("c3 is closed\n")
	}
5409 5410 5411 5412
case a[f()] = &lt;-c4:
	// same as:
	// case t := &lt;-c4
	//	a[f()] = t
5413
default:
5414
	print("no communication\n")
5415 5416 5417
}

for {  // send random sequence of bits to c
5418
	select {
5419 5420
	case c &lt;- 0:  // note: no statement, no fallthrough, no folding of cases
	case c &lt;- 1:
5421
	}
5422
}
5423

5424
select {}  // block forever
5425
</pre>
5426 5427


5428
<h3 id="Return_statements">Return statements</h3>
5429

Rob Pike's avatar
Rob Pike committed
5430
<p>
5431 5432 5433 5434
A "return" statement in a function <code>F</code> terminates the execution
of <code>F</code>, and optionally provides one or more result values.
Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
are executed before <code>F</code> returns to its caller.
Rob Pike's avatar
Rob Pike committed
5435
</p>
5436

5437
<pre class="ebnf">
5438
ReturnStmt = "return" [ ExpressionList ] .
5439
</pre>
5440

5441 5442 5443 5444
<p>
In a function without a result type, a "return" statement must not
specify any result values.
</p>
Rob Pike's avatar
Rob Pike committed
5445
<pre>
5446
func noResult() {
Rob Pike's avatar
Rob Pike committed
5447 5448 5449
	return
}
</pre>
5450

Rob Pike's avatar
Rob Pike committed
5451
<p>
5452 5453
There are three ways to return values from a function with a result
type:
Rob Pike's avatar
Rob Pike committed
5454
</p>
5455

5456 5457 5458
<ol>
	<li>The return value or values may be explicitly listed
		in the "return" statement. Each expression must be single-valued
5459 5460
		and <a href="#Assignability">assignable</a>
		to the corresponding element of the function's result type.
5461
<pre>
5462
func simpleF() int {
Rob Pike's avatar
Rob Pike committed
5463 5464 5465
	return 2
}

5466
func complexF1() (re float64, im float64) {
Rob Pike's avatar
Rob Pike committed
5467
	return -7.0, -4.0
5468 5469
}
</pre>
5470 5471 5472 5473 5474 5475 5476
	</li>
	<li>The expression list in the "return" statement may be a single
		call to a multi-valued function. The effect is as if each value
		returned from that function were assigned to a temporary
		variable with the type of the respective value, followed by a
		"return" statement listing these variables, at which point the
		rules of the previous case apply.
5477
<pre>
5478 5479
func complexF2() (re float64, im float64) {
	return complexF1()
5480 5481
}
</pre>
5482
	</li>
5483
	<li>The expression list may be empty if the function's result
5484
		type specifies names for its <a href="#Function_types">result parameters</a>.
5485
		The result parameters act as ordinary local variables
5486 5487
		and the function may assign values to them as necessary.
		The "return" statement returns the values of these variables.
5488
<pre>
5489
func complexF3() (re float64, im float64) {
5490 5491 5492
	re = 7.0
	im = 4.0
	return
5493
}
5494

Russ Cox's avatar
Russ Cox committed
5495
func (devnull) Write(p []byte) (n int, _ error) {
5496 5497
	n = len(p)
	return
5498
}
5499
</pre>
5500 5501
	</li>
</ol>
5502

5503
<p>
5504 5505
Regardless of how they are declared, all the result values are initialized to
the <a href="#The_zero_value">zero values</a> for their type upon entry to the
5506 5507
function. A "return" statement that specifies results sets the result parameters before
any deferred functions are executed.
5508 5509
</p>

5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524
<p>
Implementation restriction: A compiler may disallow an empty expression list
in a "return" statement if a different entity (constant, type, or variable)
with the same name as a result parameter is in
<a href="#Declarations_and_scope">scope</a> at the place of the return.
</p>

<pre>
func f(n int) (res int, err error) {
	if _, err := f(n-1); err != nil {
		return  // invalid return statement: err is shadowed
	}
	return
}
</pre>
5525

5526
<h3 id="Break_statements">Break statements</h3>
5527

Rob Pike's avatar
Rob Pike committed
5528 5529
<p>
A "break" statement terminates execution of the innermost
5530 5531
<a href="#For_statements">"for"</a>,
<a href="#Switch_statements">"switch"</a>, or
5532 5533
<a href="#Select_statements">"select"</a> statement
within the same function.
Rob Pike's avatar
Rob Pike committed
5534
</p>
5535

5536
<pre class="ebnf">
5537
BreakStmt = "break" [ Label ] .
5538
</pre>
5539

Rob Pike's avatar
Rob Pike committed
5540 5541
<p>
If there is a label, it must be that of an enclosing
5542 5543
"for", "switch", or "select" statement,
and that is the one whose execution terminates.
Rob Pike's avatar
Rob Pike committed
5544
</p>
5545

5546
<pre>
5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557
OuterLoop:
	for i = 0; i &lt; n; i++ {
		for j = 0; j &lt; m; j++ {
			switch a[i][j] {
			case nil:
				state = Error
				break OuterLoop
			case item:
				state = Found
				break OuterLoop
			}
Russ Cox's avatar
Russ Cox committed
5558
		}
5559
	}
5560
</pre>
5561

5562
<h3 id="Continue_statements">Continue statements</h3>
5563

Rob Pike's avatar
Rob Pike committed
5564 5565
<p>
A "continue" statement begins the next iteration of the
5566
innermost <a href="#For_statements">"for" loop</a> at its post statement.
5567
The "for" loop must be within the same function.
Rob Pike's avatar
Rob Pike committed
5568
</p>
5569

5570
<pre class="ebnf">
5571
ContinueStmt = "continue" [ Label ] .
5572
</pre>
5573

Rob Pike's avatar
Rob Pike committed
5574
<p>
5575 5576
If there is a label, it must be that of an enclosing
"for" statement, and that is the one whose execution
5577
advances.
Rob Pike's avatar
Rob Pike committed
5578
</p>
5579

5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591
<pre>
RowLoop:
	for y, row := range rows {
		for x, data := range row {
			if data == endOfRow {
				continue RowLoop
			}
			row[x] = data + bias(x, y)
		}
	}
</pre>

5592
<h3 id="Goto_statements">Goto statements</h3>
5593

Rob Pike's avatar
Rob Pike committed
5594
<p>
5595 5596
A "goto" statement transfers control to the statement with the corresponding label
within the same function.
Rob Pike's avatar
Rob Pike committed
5597
</p>
5598

5599
<pre class="ebnf">
5600
GotoStmt = "goto" Label .
5601
</pre>
5602

5603 5604 5605
<pre>
goto Error
</pre>
5606

Rob Pike's avatar
Rob Pike committed
5607 5608
<p>
Executing the "goto" statement must not cause any variables to come into
Russ Cox's avatar
Russ Cox committed
5609 5610
<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
For instance, this example:
Rob Pike's avatar
Rob Pike committed
5611
</p>
5612

5613
<pre>
Russ Cox's avatar
Russ Cox committed
5614 5615
	goto L  // BAD
	v := 3
5616 5617
L:
</pre>
5618

Rob Pike's avatar
Rob Pike committed
5619 5620 5621
<p>
is erroneous because the jump to label <code>L</code> skips
the creation of <code>v</code>.
Russ Cox's avatar
Russ Cox committed
5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642
</p>

<p>
A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
For instance, this example:
</p>

<pre>
if n%2 == 1 {
	goto L1
}
for n &gt; 0 {
	f()
	n--
L1:
	f()
	n--
}
</pre>

<p>
5643
is erroneous because the label <code>L1</code> is inside
Russ Cox's avatar
Russ Cox committed
5644
the "for" statement's block but the <code>goto</code> is not.
Rob Pike's avatar
Rob Pike committed
5645
</p>
5646

5647
<h3 id="Fallthrough_statements">Fallthrough statements</h3>
5648

Rob Pike's avatar
Rob Pike committed
5649 5650
<p>
A "fallthrough" statement transfers control to the first statement of the
Shenghou Ma's avatar
Shenghou Ma committed
5651
next case clause in an <a href="#Expression_switches">expression "switch" statement</a>.
5652
It may be used only as the final non-empty statement in such a clause.
Rob Pike's avatar
Rob Pike committed
5653
</p>
5654

5655
<pre class="ebnf">
5656
FallthroughStmt = "fallthrough" .
5657
</pre>
5658 5659


5660
<h3 id="Defer_statements">Defer statements</h3>
Robert Griesemer's avatar
Robert Griesemer committed
5661

Rob Pike's avatar
Rob Pike committed
5662
<p>
5663 5664 5665 5666 5667
A "defer" statement invokes a function whose execution is deferred
to the moment the surrounding function returns, either because the
surrounding function executed a <a href="#Return_statements">return statement</a>,
reached the end of its <a href="#Function_declarations">function body</a>,
or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>.
Rob Pike's avatar
Rob Pike committed
5668
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5669

5670
<pre class="ebnf">
5671
DeferStmt = "defer" Expression .
5672
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
5673

Rob Pike's avatar
Rob Pike committed
5674
<p>
5675 5676 5677 5678 5679 5680
The expression must be a function or method call; it cannot be parenthesized.
Calls of built-in functions are restricted as for
<a href="#Expression_statements">expression statements</a>.
</p>

<p>
5681
Each time a "defer" statement
5682 5683
executes, the function value and parameters to the call are
<a href="#Calls">evaluated as usual</a>
5684 5685
and saved anew but the actual function is not invoked.
Instead, deferred functions are invoked immediately before
5686
the surrounding function returns, in the reverse order
5687 5688 5689 5690
they were deferred. That is, if the surrounding function
returns through an explicit <a href="#Return_statements">return statement</a>,
deferred functions are executed <i>after</i> any result parameters are set
by that return statement but <i>before</i> the function returns to its caller.
5691 5692
If a deferred function value evaluates
to <code>nil</code>, execution <a href="#Handling_panics">panics</a>
Rob Pike's avatar
Rob Pike committed
5693
when the function is invoked, not when the "defer" statement is executed.
5694 5695 5696 5697
</p>

<p>
For instance, if the deferred function is
5698
a <a href="#Function_literals">function literal</a> and the surrounding
5699 5700 5701
function has <a href="#Function_types">named result parameters</a> that
are in scope within the literal, the deferred function may access and modify
the result parameters before they are returned.
5702 5703
If the deferred function has any return values, they are discarded when
the function completes.
5704 5705 5706
(See also the section on <a href="#Handling_panics">handling panics</a>.)
</p>

5707
<pre>
5708 5709
lock(l)
defer unlock(l)  // unlocking happens before surrounding function returns
Robert Griesemer's avatar
Robert Griesemer committed
5710

5711 5712
// prints 3 2 1 0 before surrounding function returns
for i := 0; i &lt;= 3; i++ {
5713
	defer fmt.Print(i)
5714
}
5715

5716
// f returns 42
5717 5718
func f() (result int) {
	defer func() {
5719 5720
		// result is accessed after it was set to 6 by the return statement
		result *= 7
5721
	}()
5722
	return 6
5723
}
5724
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
5725

5726
<h2 id="Built-in_functions">Built-in functions</h2>
5727 5728

<p>
Rob Pike's avatar
Rob Pike committed
5729
Built-in functions are
5730 5731 5732 5733
<a href="#Predeclared_identifiers">predeclared</a>.
They are called like any other function but some of them
accept a type instead of an expression as the first argument.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5734

5735 5736 5737 5738 5739 5740
<p>
The built-in functions do not have standard Go types,
so they can only appear in <a href="#Calls">call expressions</a>;
they cannot be used as function values.
</p>

5741
<h3 id="Close">Close</h3>
5742

Rob Pike's avatar
Rob Pike committed
5743
<p>
5744
For a channel <code>c</code>, the built-in function <code>close(c)</code>
5745 5746 5747 5748
records that no more values will be sent on the channel.
It is an error if <code>c</code> is a receive-only channel.
Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>.
5749
After calling <code>close</code>, and after any previously
5750
sent values have been received, receive operations will return
5751
the zero value for the channel's type without blocking.
5752 5753
The multi-valued <a href="#Receive_operator">receive operation</a>
returns a received value along with an indication of whether the channel is closed.
Rob Pike's avatar
Rob Pike committed
5754
</p>
5755

5756

5757
<h3 id="Length_and_capacity">Length and capacity</h3>
5758

Rob Pike's avatar
Rob Pike committed
5759
<p>
5760 5761 5762
The built-in functions <code>len</code> and <code>cap</code> take arguments
of various types and return a result of type <code>int</code>.
The implementation guarantees that the result always fits into an <code>int</code>.
5763 5764
</p>

5765
<pre class="grammar">
5766
Call      Argument type    Result
5767

5768 5769 5770 5771 5772
len(s)    string type      string length in bytes
          [n]T, *[n]T      array length (== n)
          []T              slice length
          map[K]T          map length (number of defined keys)
          chan T           number of elements queued in channel buffer
5773

5774 5775 5776
cap(s)    [n]T, *[n]T      array length (== n)
          []T              slice capacity
          chan T           channel buffer capacity
5777
</pre>
5778

5779 5780 5781 5782 5783
<p>
The capacity of a slice is the number of elements for which there is
space allocated in the underlying array.
At any time the following relationship holds:
</p>
5784

5785
<pre>
Anthony Martin's avatar
Anthony Martin committed
5786
0 &lt;= len(s) &lt;= cap(s)
5787
</pre>
5788

5789
<p>
5790
The length of a <code>nil</code> slice, map or channel is 0.
5791
The capacity of a <code>nil</code> slice or channel is 0.
5792 5793
</p>

5794
<p>
5795 5796 5797 5798
The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
<code>s</code> is a string constant. The expressions <code>len(s)</code> and
<code>cap(s)</code> are constants if the type of <code>s</code> is an array
or pointer to an array and the expression <code>s</code> does not contain
5799
<a href="#Receive_operator">channel receives</a> or (non-constant)
5800 5801 5802
<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated.
Otherwise, invocations of <code>len</code> and <code>cap</code> are not
constant and <code>s</code> is evaluated.
5803
</p>
5804

5805 5806 5807 5808 5809 5810
<pre>
const (
	c1 = imag(2i)                    // imag(2i) = 2.0 is a constant
	c2 = len([10]float64{2})         // [10]float64{2} contains no function calls
	c3 = len([10]float64{c1})        // [10]float64{c1} contains no function calls
	c4 = len([10]float64{imag(2i)})  // imag(2i) is a constant and no function call is issued
Shenghou Ma's avatar
Shenghou Ma committed
5811
	c5 = len([10]float64{imag(z)})   // invalid: imag(z) is a (non-constant) function call
5812 5813 5814
)
var z complex128
</pre>
5815

5816
<h3 id="Allocation">Allocation</h3>
5817

Rob Pike's avatar
Rob Pike committed
5818
<p>
Robert Griesemer's avatar
Robert Griesemer committed
5819 5820 5821 5822 5823
The built-in function <code>new</code> takes a type <code>T</code>,
allocates storage for a <a href="#Variables">variable</a> of that type
at run time, and returns a value of type <code>*T</code>
<a href="#Pointer_types">pointing</a> to it.
The variable is initialized as described in the section on
5824
<a href="#The_zero_value">initial values</a>.
Rob Pike's avatar
Rob Pike committed
5825
</p>
5826

5827
<pre class="grammar">
5828 5829
new(T)
</pre>
5830

Rob Pike's avatar
Rob Pike committed
5831
<p>
5832
For instance
Rob Pike's avatar
Rob Pike committed
5833
</p>
5834

5835
<pre>
5836
type S struct { a int; b float64 }
5837 5838
new(S)
</pre>
5839

5840
<p>
Robert Griesemer's avatar
Robert Griesemer committed
5841
allocates storage for a variable of type <code>S</code>,
Rob Pike's avatar
Rob Pike committed
5842 5843
initializes it (<code>a=0</code>, <code>b=0.0</code>),
and returns a value of type <code>*S</code> containing the address
Robert Griesemer's avatar
Robert Griesemer committed
5844
of the location.
Rob Pike's avatar
Rob Pike committed
5845
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5846

5847
<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
Robert Griesemer's avatar
Robert Griesemer committed
5848

Rob Pike's avatar
Rob Pike committed
5849 5850 5851 5852 5853
<p>
The built-in function <code>make</code> takes a type <code>T</code>,
which must be a slice, map or channel type,
optionally followed by a type-specific list of expressions.
It returns a value of type <code>T</code> (not <code>*T</code>).
5854 5855
The memory is initialized as described in the section on
<a href="#The_zero_value">initial values</a>.
Rob Pike's avatar
Rob Pike committed
5856
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5857

5858
<pre class="grammar">
5859
Call             Type T     Result
Robert Griesemer's avatar
Robert Griesemer committed
5860

5861 5862
make(T, n)       slice      slice of type T with length n and capacity n
make(T, n, m)    slice      slice of type T with length n and capacity m
Robert Griesemer's avatar
Robert Griesemer committed
5863

5864
make(T)          map        map of type T
5865
make(T, n)       map        map of type T with initial space for approximately n elements
5866

5867 5868
make(T)          channel    unbuffered channel of type T
make(T, n)       channel    buffered channel of type T, buffer size n
5869
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
5870 5871


Rob Pike's avatar
Rob Pike committed
5872
<p>
5873 5874 5875 5876
Each of the size arguments <code>n</code> and <code>m</code> must be of integer type
or an untyped <a href="#Constants">constant</a>.
A constant size argument must be non-negative and <a href="#Representability">representable</a>
by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>.
5877
If both <code>n</code> and <code>m</code> are provided and are constant, then
5878 5879 5880
<code>n</code> must be no larger than <code>m</code>.
If <code>n</code> is negative or larger than <code>m</code> at run time,
a <a href="#Run_time_panics">run-time panic</a> occurs.
Rob Pike's avatar
Rob Pike committed
5881
</p>
Robert Griesemer's avatar
Robert Griesemer committed
5882

5883
<pre>
5884
s := make([]int, 10, 100)       // slice with len(s) == 10, cap(s) == 100
5885
s := make([]int, 1e3)           // slice with len(s) == cap(s) == 1000
5886
s := make([]int, 1&lt;&lt;63)         // illegal: len(s) is not representable by a value of type int
5887
s := make([]int, 10, 0)         // illegal: len(s) > cap(s)
5888
c := make(chan int, 10)         // channel with a buffer size of 10
5889
m := make(map[string]int, 100)  // map with initial space for approximately 100 elements
5890
</pre>
5891

5892 5893 5894 5895 5896 5897
<p>
Calling <code>make</code> with a map type and size hint <code>n</code> will
create a map with initial space to hold <code>n</code> map elements.
The precise behavior is implementation-dependent.
</p>

5898

Robert Griesemer's avatar
Robert Griesemer committed
5899
<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
5900 5901

<p>
5902 5903 5904 5905
The built-in functions <code>append</code> and <code>copy</code> assist in
common slice operations.
For both functions, the result is independent of whether the memory referenced
by the arguments overlaps.
Robert Griesemer's avatar
Robert Griesemer committed
5906 5907 5908
</p>

<p>
5909 5910
The <a href="#Function_types">variadic</a> function <code>append</code>
appends zero or more values <code>x</code>
5911 5912
to <code>s</code> of type <code>S</code>, which must be a slice type, and
returns the resulting slice, also of type <code>S</code>.
5913 5914 5915 5916
The values <code>x</code> are passed to a parameter of type <code>...T</code>
where <code>T</code> is the <a href="#Slice_types">element type</a> of
<code>S</code> and the respective
<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply.
5917 5918 5919 5920
As a special case, <code>append</code> also accepts a first argument
assignable to type <code>[]byte</code> with a second argument of
string type followed by <code>...</code>. This form appends the
bytes of the string.
Robert Griesemer's avatar
Robert Griesemer committed
5921 5922 5923
</p>

<pre class="grammar">
5924
append(s S, x ...T) S  // T is the element type of S
Robert Griesemer's avatar
Robert Griesemer committed
5925 5926 5927 5928
</pre>

<p>
If the capacity of <code>s</code> is not large enough to fit the additional
5929 5930 5931
values, <code>append</code> allocates a new, sufficiently large underlying
array that fits both the existing slice elements and the additional values.
Otherwise, <code>append</code> re-uses the underlying array.
Robert Griesemer's avatar
Robert Griesemer committed
5932 5933 5934 5935
</p>

<pre>
s0 := []int{0, 0}
5936 5937 5938 5939
s1 := append(s0, 2)                // append a single element     s1 == []int{0, 0, 2}
s2 := append(s1, 3, 5, 7)          // append multiple elements    s2 == []int{0, 0, 2, 3, 5, 7}
s3 := append(s2, s0...)            // append a slice              s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
s4 := append(s3[3:6], s3[2:]...)   // append overlapping slice    s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
5940 5941

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

var b []byte
5945
b = append(b, "bar"...)            // append string contents      b == []byte{'b', 'a', 'r' }
Robert Griesemer's avatar
Robert Griesemer committed
5946 5947 5948 5949
</pre>

<p>
The function <code>copy</code> copies slice elements from
5950
a source <code>src</code> to a destination <code>dst</code> and returns the
5951
number of elements copied.
5952
Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be
5953
<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>.
5954
The number of elements copied is the minimum of
5955
<code>len(src)</code> and <code>len(dst)</code>.
5956 5957 5958
As a special case, <code>copy</code> also accepts a destination argument assignable
to type <code>[]byte</code> with a source argument of a string type.
This form copies the bytes from the string into the byte slice.
5959 5960 5961 5962
</p>

<pre class="grammar">
copy(dst, src []T) int
5963
copy(dst []byte, src string) int
5964 5965 5966 5967 5968 5969 5970
</pre>

<p>
Examples:
</p>

<pre>
5971 5972
var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
var s = make([]int, 6)
5973 5974 5975 5976
var b = make([]byte, 5)
n1 := copy(s, a[0:])            // n1 == 6, s == []int{0, 1, 2, 3, 4, 5}
n2 := copy(s, s[2:])            // n2 == 4, s == []int{2, 3, 4, 5, 4, 5}
n3 := copy(b, "Hello, World!")  // n3 == 5, b == []byte("Hello")
5977 5978
</pre>

5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993

<h3 id="Deletion_of_map_elements">Deletion of map elements</h3>

<p>
The built-in function <code>delete</code> removes the element with key
<code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The
type of <code>k</code> must be <a href="#Assignability">assignable</a>
to the key type of <code>m</code>.
</p>

<pre class="grammar">
delete(m, k)  // remove element m[k] from map m
</pre>

<p>
5994 5995
If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code>
does not exist, <code>delete</code> is a no-op.
5996 5997 5998
</p>


5999
<h3 id="Complex_numbers">Manipulating complex numbers</h3>
Rob Pike's avatar
Rob Pike committed
6000 6001 6002

<p>
Three functions assemble and disassemble complex numbers.
6003
The built-in function <code>complex</code> constructs a complex
Rob Pike's avatar
Rob Pike committed
6004 6005 6006 6007 6008 6009
value from a floating-point real and imaginary part, while
<code>real</code> and <code>imag</code>
extract the real and imaginary parts of a complex value.
</p>

<pre class="grammar">
6010
complex(realPart, imaginaryPart floatT) complexT
Rob Pike's avatar
Rob Pike committed
6011 6012 6013 6014 6015 6016
real(complexT) floatT
imag(complexT) floatT
</pre>

<p>
The type of the arguments and return value correspond.
6017
For <code>complex</code>, the two arguments must be of the same
Rob Pike's avatar
Rob Pike committed
6018 6019
floating-point type and the return type is the complex type
with the corresponding floating-point constituents:
6020 6021
<code>complex64</code> for <code>float32</code> arguments, and
<code>complex128</code> for <code>float64</code> arguments.
6022
If one of the arguments evaluates to an untyped constant, it is first implicitly
6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041
<a href="#Conversions">converted</a> to the type of the other argument.
If both arguments evaluate to untyped constants, they must be non-complex
numbers or their imaginary parts must be zero, and the return value of
the function is an untyped complex constant.
</p>

<p>
For <code>real</code> and <code>imag</code>, the argument must be
of complex type, and the return type is the corresponding floating-point
type: <code>float32</code> for a <code>complex64</code> argument, and
<code>float64</code> for a <code>complex128</code> argument.
If the argument evaluates to an untyped constant, it must be a number,
and the return value of the function is an untyped floating-point constant.
</p>

<p>
The <code>real</code> and <code>imag</code> functions together form the inverse of
<code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>,
<code>z&nbsp;==&nbsp;Z(complex(real(z),&nbsp;imag(z)))</code>.
Rob Pike's avatar
Rob Pike committed
6042 6043 6044 6045 6046 6047 6048 6049
</p>

<p>
If the operands of these functions are all constants, the return
value is a constant.
</p>

<pre>
6050
var a = complex(2, -2)             // complex128
6051
const b = complex(1.0, -1.4)       // untyped complex constant 1 - 1.4i
6052 6053
x := float32(math.Cos(math.Pi/2))  // float32
var c64 = complex(5, -x)           // complex64
6054
var s int = complex(1, 0)          // untyped complex constant 1 + 0i can be converted to int
6055
_ = complex(1, 2&lt;&lt;s)               // illegal: 2 assumes floating-point type, cannot shift
6056
var rl = real(c64)                 // float32
6057 6058
var im = imag(a)                   // float64
const c = imag(b)                  // untyped constant -1.4
6059
_ = imag(3 &lt;&lt; s)                   // illegal: 3 assumes complex type, cannot shift
Rob Pike's avatar
Rob Pike committed
6060 6061
</pre>

6062 6063 6064 6065
<h3 id="Handling_panics">Handling panics</h3>

<p> Two built-in functions, <code>panic</code> and <code>recover</code>,
assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
6066
and program-defined error conditions.
6067 6068 6069 6070 6071 6072 6073 6074
</p>

<pre class="grammar">
func panic(interface{})
func recover() interface{}
</pre>

<p>
6075 6076 6077
While executing a function <code>F</code>,
an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
terminates the execution of <code>F</code>.
6078
Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
6079 6080 6081 6082
are then executed as usual.
Next, any deferred functions run by <code>F's</code> caller are run,
and so on up to any deferred by the top-level function in the executing goroutine.
At that point, the program is terminated and the error
6083 6084
condition is reported, including the value of the argument to <code>panic</code>.
This termination sequence is called <i>panicking</i>.
6085 6086
</p>

6087 6088 6089 6090 6091 6092
<pre>
panic(42)
panic("unreachable")
panic(Error("cannot parse"))
</pre>

6093 6094
<p>
The <code>recover</code> function allows a program to manage behavior
6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110
of a panicking goroutine.
Suppose a function <code>G</code> defers a function <code>D</code> that calls
<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
is executing.
When the running of deferred functions reaches <code>D</code>,
the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>.
If <code>D</code> returns normally, without starting a new
<code>panic</code>, the panicking sequence stops. In that case,
the state of functions called between <code>G</code> and the call to <code>panic</code>
is discarded, and normal execution resumes.
Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
execution terminates by returning to its caller.
</p>

<p>
The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds:
6111
</p>
6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122
<ul>
<li>
<code>panic</code>'s argument was <code>nil</code>;
</li>
<li>
the goroutine is not panicking;
</li>
<li>
<code>recover</code> was not called directly by a deferred function.
</li>
</ul>
6123 6124

<p>
6125 6126 6127
The <code>protect</code> function in the example below invokes
the function argument <code>g</code> and protects callers from
run-time panics raised by <code>g</code>.
6128 6129 6130
</p>

<pre>
6131
func protect(g func()) {
6132
	defer func() {
6133
		log.Println("done")  // Println executes normally even if there is a panic
6134
		if x := recover(); x != nil {
6135
			log.Printf("run time panic: %v", x)
6136
		}
6137
	}()
6138 6139
	log.Println("start")
	g()
6140 6141 6142
}
</pre>

6143

6144 6145
<h3 id="Bootstrapping">Bootstrapping</h3>

6146
<p>
6147 6148 6149
Current implementations provide several built-in functions useful during
bootstrapping. These functions are documented for completeness but are not
guaranteed to stay in the language. They do not return a result.
6150 6151
</p>

6152
<pre class="grammar">
6153
Function   Behavior
6154 6155 6156 6157 6158

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

6159 6160 6161
<p>
Implementation restriction: <code>print</code> and <code>println</code> need not
accept arbitrary argument types, but printing of boolean, numeric, and string
6162
<a href="#Types">types</a> must be supported.
6163
</p>
6164

6165
<h2 id="Packages">Packages</h2>
6166

Rob Pike's avatar
Rob Pike committed
6167 6168
<p>
Go programs are constructed by linking together <i>packages</i>.
6169 6170 6171 6172 6173
A package in turn is constructed from one or more source files
that together declare constants, types, variables and functions
belonging to the package and which are accessible in all files
of the same package. Those elements may be
<a href="#Exported_identifiers">exported</a> and used in another package.
Rob Pike's avatar
Rob Pike committed
6174 6175
</p>

6176
<h3 id="Source_file_organization">Source file organization</h3>
Rob Pike's avatar
Rob Pike committed
6177 6178 6179 6180 6181 6182

<p>
Each source file consists of a package clause defining the package
to which it belongs, followed by a possibly empty set of import
declarations that declare packages whose contents it wishes to use,
followed by a possibly empty set of declarations of functions,
Robert Griesemer's avatar
Robert Griesemer committed
6183
types, variables, and constants.
Rob Pike's avatar
Rob Pike committed
6184
</p>
6185

6186
<pre class="ebnf">
6187
SourceFile       = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
6188
</pre>
6189

6190
<h3 id="Package_clause">Package clause</h3>
Rob Pike's avatar
Rob Pike committed
6191

6192
<p>
Rob Pike's avatar
Rob Pike committed
6193 6194 6195
A package clause begins each source file and defines the package
to which the file belongs.
</p>
6196

6197
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
6198 6199
PackageClause  = "package" PackageName .
PackageName    = identifier .
Rob Pike's avatar
Rob Pike committed
6200
</pre>
6201

Robert Griesemer's avatar
Robert Griesemer committed
6202 6203 6204 6205
<p>
The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
</p>

Rob Pike's avatar
Rob Pike committed
6206 6207
<pre>
package math
6208
</pre>
6209

Rob Pike's avatar
Rob Pike committed
6210 6211 6212 6213
<p>
A set of files sharing the same PackageName form the implementation of a package.
An implementation may require that all source files for a package inhabit the same directory.
</p>
6214

6215
<h3 id="Import_declarations">Import declarations</h3>
Rob Pike's avatar
Rob Pike committed
6216 6217

<p>
6218 6219 6220
An import declaration states that the source file containing the declaration
depends on functionality of the <i>imported</i> package
(<a href="#Program_initialization_and_execution">§Program initialization and execution</a>)
6221
and enables access to <a href="#Exported_identifiers">exported</a> identifiers
6222 6223
of that package.
The import names an identifier (PackageName) to be used for access and an ImportPath
Rob Pike's avatar
Rob Pike committed
6224
that specifies the package to be imported.
Rob Pike's avatar
Rob Pike committed
6225
</p>
6226

6227
<pre class="ebnf">
6228
ImportDecl       = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
6229
ImportSpec       = [ "." | PackageName ] ImportPath .
6230
ImportPath       = string_lit .
6231
</pre>
6232

6233
<p>
Rob Pike's avatar
Rob Pike committed
6234
The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
6235
to access exported identifiers of the package within the importing source file.
Rob Pike's avatar
Rob Pike committed
6236 6237
It is declared in the <a href="#Blocks">file block</a>.
If the PackageName is omitted, it defaults to the identifier specified in the
Robert Griesemer's avatar
Robert Griesemer committed
6238
<a href="#Package_clause">package clause</a> of the imported package.
Rob Pike's avatar
Rob Pike committed
6239
If an explicit period (<code>.</code>) appears instead of a name, all the
6240 6241
package's exported identifiers declared in that package's
<a href="#Blocks">package block</a> will be declared in the importing source
6242
file's file block and must be accessed without a qualifier.
Rob Pike's avatar
Rob Pike committed
6243 6244 6245 6246 6247 6248
</p>

<p>
The interpretation of the ImportPath is implementation-dependent but
it is typically a substring of the full file name of the compiled
package and may be relative to a repository of installed packages.
Rob Pike's avatar
Rob Pike committed
6249
</p>
Russ Cox's avatar
Russ Cox committed
6250

6251 6252 6253
<p>
Implementation restriction: A compiler may restrict ImportPaths to
non-empty strings using only characters belonging to
6254
<a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a>
6255
L, M, N, P, and S general categories (the Graphic characters without
6256 6257 6258
spaces) and may also exclude the characters
<code>!"#$%&amp;'()*,:;&lt;=&gt;?[\]^`{|}</code>
and the Unicode replacement character U+FFFD.
6259 6260
</p>

6261
<p>
Rob Pike's avatar
Rob Pike committed
6262 6263 6264
Assume we have compiled a package containing the package clause
<code>package math</code>, which exports function <code>Sin</code>, and
installed the compiled package in the file identified by
Rob Pike's avatar
Rob Pike committed
6265
<code>"lib/math"</code>.
6266
This table illustrates how <code>Sin</code> is accessed in files
Rob Pike's avatar
Rob Pike committed
6267 6268
that import the package after the
various types of import declaration.
Rob Pike's avatar
Rob Pike committed
6269
</p>
6270

Rob Pike's avatar
Rob Pike committed
6271
<pre class="grammar">
6272
Import declaration          Local name of Sin
Rob Pike's avatar
Rob Pike committed
6273 6274

import   "lib/math"         math.Sin
6275
import m "lib/math"         m.Sin
Rob Pike's avatar
Rob Pike committed
6276
import . "lib/math"         Sin
6277
</pre>
6278

6279
<p>
Rob Pike's avatar
Rob Pike committed
6280 6281
An import declaration declares a dependency relation between
the importing and imported package.
6282 6283
It is illegal for a package to import itself, directly or indirectly,
or to directly import a package without
6284 6285 6286 6287 6288 6289 6290 6291 6292 6293
referring to any of its exported identifiers. To import a package solely for
its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
identifier as explicit package name:
</p>

<pre>
import _ "lib/math"
</pre>


6294
<h3 id="An_example_package">An example package</h3>
Rob Pike's avatar
Rob Pike committed
6295 6296 6297 6298

<p>
Here is a complete Go package that implements a concurrent prime sieve.
</p>
6299

6300 6301 6302
<pre>
package main

Rob Pike's avatar
Rob Pike committed
6303 6304
import "fmt"

6305
// Send the sequence 2, 3, 4, … to channel 'ch'.
6306
func generate(ch chan&lt;- int) {
6307
	for i := 2; ; i++ {
6308
		ch &lt;- i  // Send 'i' to channel 'ch'.
6309
	}
6310 6311
}

Fazlul Shahriar's avatar
Fazlul Shahriar committed
6312
// Copy the values from channel 'src' to channel 'dst',
6313
// removing those divisible by 'prime'.
6314
func filter(src &lt;-chan int, dst chan&lt;- int, prime int) {
6315
	for i := range src {  // Loop over values received from 'src'.
6316
		if i%prime != 0 {
6317
			dst &lt;- i  // Send 'i' to channel 'dst'.
6318 6319
		}
	}
6320 6321 6322 6323
}

// The prime sieve: Daisy-chain filter processes together.
func sieve() {
6324 6325
	ch := make(chan int)  // Create a new channel.
	go generate(ch)       // Start generate() as a subprocess.
6326
	for {
6327 6328 6329 6330 6331
		prime := &lt;-ch
		fmt.Print(prime, "\n")
		ch1 := make(chan int)
		go filter(ch, ch1, prime)
		ch = ch1
6332
	}
6333
}
6334

6335
func main() {
6336
	sieve()
6337 6338
}
</pre>
6339

6340
<h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
6341

6342
<h3 id="The_zero_value">The zero value</h3>
Rob Pike's avatar
Rob Pike committed
6343
<p>
Robert Griesemer's avatar
Robert Griesemer committed
6344 6345 6346 6347 6348 6349
When storage is allocated for a <a href="#Variables">variable</a>,
either through a declaration or a call of <code>new</code>, or when
a new value is created, either through a composite literal or a call
of <code>make</code>,
and no explicit initialization is provided, the variable or value is
given a default value.  Each element of such a variable or value is
6350
set to the <i>zero value</i> for its type: <code>false</code> for booleans,
6351
<code>0</code> for numeric types, <code>""</code>
6352
for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
Rob Pike's avatar
Rob Pike committed
6353
This initialization is done recursively, so for instance each element of an
Rob Pike's avatar
Rob Pike committed
6354 6355
array of structs will have its fields zeroed if no value is specified.
</p>
6356
<p>
6357
These two simple declarations are equivalent:
Rob Pike's avatar
Rob Pike committed
6358
</p>
6359

6360
<pre>
6361 6362
var i int
var i int = 0
6363
</pre>
6364

Rob Pike's avatar
Rob Pike committed
6365
<p>
6366
After
Rob Pike's avatar
Rob Pike committed
6367
</p>
6368

6369
<pre>
6370
type T struct { i int; f float64; next *T }
6371
t := new(T)
6372
</pre>
6373

Rob Pike's avatar
Rob Pike committed
6374
<p>
6375
the following holds:
Rob Pike's avatar
Rob Pike committed
6376
</p>
6377

6378 6379 6380 6381 6382
<pre>
t.i == 0
t.f == 0.0
t.next == nil
</pre>
6383

Rob Pike's avatar
Rob Pike committed
6384 6385 6386 6387 6388 6389 6390 6391
<p>
The same would also be true after
</p>

<pre>
var t T
</pre>

6392
<h3 id="Package_initialization">Package initialization</h3>
6393 6394

<p>
6395 6396 6397
Within a package, package-level variable initialization proceeds stepwise,
with each step selecting the variable earliest in <i>declaration order</i>
which has no dependencies on uninitialized variables.
6398 6399 6400 6401 6402 6403
</p>

<p>
More precisely, a package-level variable is considered <i>ready for
initialization</i> if it is not yet initialized and either has
no <a href="#Variable_declarations">initialization expression</a> or
6404
its initialization expression has no <i>dependencies</i> on uninitialized variables.
6405 6406 6407 6408 6409
Initialization proceeds by repeatedly initializing the next package-level
variable that is earliest in declaration order and ready for initialization,
until there are no variables ready for initialization.
</p>

6410
<p>
6411 6412 6413 6414 6415
If any variables are still uninitialized when this
process ends, those variables are part of one or more initialization cycles,
and the program is not valid.
</p>

6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432
<p>
Multiple variables on the left-hand side of a variable declaration initialized
by single (multi-valued) expression on the right-hand side are initialized
together: If any of the variables on the left-hand side is initialized, all
those variables are initialized in the same step.
</p>

<pre>
var x = a
var a, b = f() // a and b are initialized together, before x is initialized
</pre>

<p>
For the purpose of package initialization, <a href="#Blank_identifier">blank</a>
variables are treated like any other variables in declarations.
</p>

6433 6434 6435 6436 6437
<p>
The declaration order of variables declared in multiple files is determined
by the order in which the files are presented to the compiler: Variables
declared in the first file are declared before any of the variables declared
in the second file, and so on.
6438 6439 6440 6441 6442
</p>

<p>
Dependency analysis does not rely on the actual values of the
variables, only on lexical <i>references</i> to them in the source,
6443 6444 6445
analyzed transitively. For instance, if a variable <code>x</code>'s
initialization expression refers to a function whose body refers to
variable <code>y</code> then <code>x</code> depends on <code>y</code>.
6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457
Specifically:
</p>

<ul>
<li>
A reference to a variable or function is an identifier denoting that
variable or function.
</li>

<li>
A reference to a method <code>m</code> is a
<a href="#Method_values">method value</a> or
6458
<a href="#Method_expressions">method expression</a> of the form
6459 6460 6461 6462 6463 6464 6465 6466
<code>t.m</code>, where the (static) type of <code>t</code> is
not an interface type, and the method <code>m</code> is in the
<a href="#Method_sets">method set</a> of <code>t</code>.
It is immaterial whether the resulting function value
<code>t.m</code> is invoked.
</li>

<li>
6467
A variable, function, or method <code>x</code> depends on a variable
6468 6469 6470 6471 6472 6473 6474 6475 6476 6477
<code>y</code> if <code>x</code>'s initialization expression or body
(for functions and methods) contains a reference to <code>y</code>
or to a function or method that depends on <code>y</code>.
</li>
</ul>

<p>
For example, given the declarations
</p>

Rob Pike's avatar
Rob Pike committed
6478
<pre>
6479
var (
6480 6481 6482 6483
	a = c + b  // == 9
	b = f()    // == 4
	c = f()    // == 5
	d = 3      // == 5 after initialization has finished
6484 6485 6486 6487 6488 6489
)

func f() int {
	d++
	return d
}
Rob Pike's avatar
Rob Pike committed
6490
</pre>
6491

Rob Pike's avatar
Rob Pike committed
6492
<p>
6493
the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>.
6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526
Note that the order of subexpressions in initialization expressions is irrelevant:
<code>a = c + b</code> and <code>a = b + c</code> result in the same initialization
order in this example.
</p>

<p>
Dependency analysis is performed per package; only references referring
to variables, functions, and (non-interface) methods declared in the current
package are considered. If other, hidden, data dependencies exists between
variables, the initialization order between those variables is unspecified.
</p>

<p>
For instance, given the declarations
</p>

<pre>
var x = I(T{}).ab()   // x has an undetected, hidden dependency on a and b
var _ = sideEffect()  // unrelated to x, a, or b
var a = b
var b = 42

type I interface      { ab() []int }
type T struct{}
func (T) ab() []int   { return []int{a, b} }
</pre>

<p>
the variable <code>a</code> will be initialized after <code>b</code> but
whether <code>x</code> is initialized before <code>b</code>, between
<code>b</code> and <code>a</code>, or after <code>a</code>, and
thus also the moment at which <code>sideEffect()</code> is called (before
or after <code>x</code> is initialized) is not specified.
Rob Pike's avatar
Rob Pike committed
6527
</p>
6528

6529
<p>
6530 6531
Variables may also be initialized using functions named <code>init</code>
declared in the package block, with no arguments and no result parameters.
6532
</p>
6533 6534 6535 6536 6537

<pre>
func init() { … }
</pre>

6538
<p>
6539 6540 6541 6542
Multiple such functions may be defined per package, even within a single
source file. In the package block, the <code>init</code> identifier can
be used only to declare <code>init</code> functions, yet the identifier
itself is not <a href="#Declarations_and_scope">declared</a>. Thus
6543 6544
<code>init</code> functions cannot be referred to from anywhere
in a program.
Rob Pike's avatar
Rob Pike committed
6545
</p>
6546

6547
<p>
6548 6549
A package with no imports is initialized by assigning initial values
to all its package-level variables followed by calling all <code>init</code>
6550 6551
functions in the order they appear in the source, possibly in multiple files,
as presented to the compiler.
6552
If a package has imports, the imported packages are initialized
6553
before initializing the package itself. If multiple packages import
6554 6555 6556
a package, the imported package will be initialized only once.
The importing of packages, by construction, guarantees that there
can be no cyclic initialization dependencies.
Rob Pike's avatar
Rob Pike committed
6557
</p>
6558

6559
<p>
6560 6561 6562 6563 6564 6565 6566 6567
Package initialization&mdash;variable initialization and the invocation of
<code>init</code> functions&mdash;happens in a single goroutine,
sequentially, one package at a time.
An <code>init</code> function may launch other goroutines, which can run
concurrently with the initialization code. However, initialization
always sequences
the <code>init</code> functions: it will not invoke the next one
until the previous one has returned.
Rob Pike's avatar
Rob Pike committed
6568
</p>
6569

6570 6571 6572 6573 6574 6575
<p>
To ensure reproducible initialization behavior, build systems are encouraged
to present multiple files belonging to the same package in lexical file name
order to a compiler.
</p>

6576 6577

<h3 id="Program_execution">Program execution</h3>
6578
<p>
6579 6580 6581 6582
A complete program is created by linking a single, unimported package
called the <i>main package</i> with all the packages it imports, transitively.
The main package must
have package name <code>main</code> and
6583
declare a function <code>main</code> that takes no
6584
arguments and returns no value.
Rob Pike's avatar
Rob Pike committed
6585
</p>
6586

6587
<pre>
6588
func main() { … }
6589
</pre>
6590

Rob Pike's avatar
Rob Pike committed
6591
<p>
6592 6593
Program execution begins by initializing the main package and then
invoking the function <code>main</code>.
6594
When that function invocation returns, the program exits.
6595
It does not wait for other (non-<code>main</code>) goroutines to complete.
Rob Pike's avatar
Rob Pike committed
6596
</p>
6597

Russ Cox's avatar
Russ Cox committed
6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619
<h2 id="Errors">Errors</h2>

<p>
The predeclared type <code>error</code> is defined as
</p>

<pre>
type error interface {
	Error() string
}
</pre>

<p>
It is the conventional interface for representing an error condition,
with the nil value representing no error.
For instance, a function to read data from a file might be defined:
</p>

<pre>
func Read(f *File, b []byte) (n int, err error)
</pre>

6620
<h2 id="Run_time_panics">Run-time panics</h2>
6621 6622 6623 6624 6625 6626

<p>
Execution errors such as attempting to index an array out
of bounds trigger a <i>run-time panic</i> equivalent to a call of
the built-in function <a href="#Handling_panics"><code>panic</code></a>
with a value of the implementation-defined interface type <code>runtime.Error</code>.
6627
That type satisfies the predeclared interface type
Russ Cox's avatar
Russ Cox committed
6628 6629 6630
<a href="#Errors"><code>error</code></a>.
The exact error values that
represent distinct run-time error conditions are unspecified.
6631 6632 6633 6634 6635 6636
</p>

<pre>
package runtime

type Error interface {
Russ Cox's avatar
Russ Cox committed
6637 6638
	error
	// and perhaps other methods
6639 6640 6641
}
</pre>

6642
<h2 id="System_considerations">System considerations</h2>
6643

6644
<h3 id="Package_unsafe">Package <code>unsafe</code></h3>
6645

6646
<p>
6647 6648
The built-in package <code>unsafe</code>, known to the compiler
and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>,
Rob Pike's avatar
Rob Pike committed
6649 6650
provides facilities for low-level programming including operations
that violate the type system. A package using <code>unsafe</code>
6651 6652
must be vetted manually for type safety and may not be portable.
The package provides the following interface:
6653
</p>
6654

Rob Pike's avatar
Rob Pike committed
6655
<pre class="grammar">
6656
package unsafe
6657

6658 6659
type ArbitraryType int  // shorthand for an arbitrary Go type; it is not a real type
type Pointer *ArbitraryType
6660

6661
func Alignof(variable ArbitraryType) uintptr
Hong Ruiqi's avatar
Hong Ruiqi committed
6662
func Offsetof(selector ArbitraryType) uintptr
6663
func Sizeof(variable ArbitraryType) uintptr
6664
</pre>
6665

6666
<p>
6667 6668
A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
value may not be <a href="#Address_operators">dereferenced</a>.
6669
Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to
6670
a type of underlying type <code>Pointer</code> and vice versa.
6671
The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined.
6672
</p>
6673 6674 6675 6676 6677 6678 6679

<pre>
var f float64
bits = *(*uint64)(unsafe.Pointer(&amp;f))

type ptr unsafe.Pointer
bits = *(*uint64)(ptr(&amp;f))
6680 6681

var p ptr = nil
6682 6683
</pre>

6684
<p>
6685 6686 6687
The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
as if <code>v</code> was declared via <code>var v = x</code>.
6688
</p>
6689
<p>
6690
The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
6691 6692 6693 6694
<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
without pointer indirections through fields of the struct.
Rob Pike's avatar
Rob Pike committed
6695
For a struct <code>s</code> with field <code>f</code>:
6696
</p>
6697

6698
<pre>
6699
uintptr(unsafe.Pointer(&amp;s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&amp;s.f))
6700
</pre>
6701

6702
<p>
6703 6704 6705 6706 6707 6708 6709
Computer architectures may require memory addresses to be <i>aligned</i>;
that is, for addresses of a variable to be a multiple of a factor,
the variable's type's <i>alignment</i>.  The function <code>Alignof</code>
takes an expression denoting a variable of any type and returns the
alignment of the (type of the) variable in bytes.  For a variable
<code>x</code>:
</p>
6710

6711
<pre>
6712
uintptr(unsafe.Pointer(&amp;x)) % unsafe.Alignof(x) == 0
6713
</pre>
6714

6715 6716
<p>
Calls to <code>Alignof</code>, <code>Offsetof</code>, and
6717
<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
Rob Pike's avatar
Rob Pike committed
6718
</p>
6719

6720
<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
6721

6722
<p>
6723
For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
6724
</p>
6725

Rob Pike's avatar
Rob Pike committed
6726
<pre class="grammar">
6727
type                                 size in bytes
6728

6729 6730 6731 6732 6733
byte, uint8, int8                     1
uint16, int16                         2
uint32, int32, float32                4
uint64, int64, float64, complex64     8
complex128                           16
6734
</pre>
6735

6736
<p>
6737
The following minimal alignment properties are guaranteed:
Rob Pike's avatar
Rob Pike committed
6738
</p>
6739
<ol>
6740
<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
6741
</li>
6742

6743
<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
6744
   all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
6745
</li>
6746

6747
<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
6748
	the alignment of a variable of the array's element type.
6749
</li>
6750
</ol>
6751

6752 6753 6754
<p>
A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
</p>