go_spec.html 153 KB
Newer Older
1
<!-- title The Go Programming Language Specification -->
2
<!-- subtitle Version of May 13, 2011 -->
3

4
<!--
5
TODO
6
[ ] need language about function/method calls and parameter passing rules
Rob Pike's avatar
Rob Pike committed
7 8
[ ] last paragraph of #Assignments (constant promotion) should be elsewhere
    and mention assignment to empty interface.
Robert Griesemer's avatar
Robert Griesemer committed
9
[ ] need to say something about "scope" of selectors?
10 11
[ ] clarify what a field name is in struct declarations
    (struct{T} vs struct {T T} vs struct {t T})
12 13
[ ] need explicit language about the result type of operations
[ ] may want to have some examples for the types of shift operations
14
[ ] should string(1<<s) and float32(1<<s) be valid?
15 16
[ ] should probably write something about evaluation order of statements even
	though obvious
17
[ ] review language on implicit dereferencing
18
[ ] clarify what it means for two functions to be "the same" when comparing them
19 20
-->

21

22
<h2 id="Introduction">Introduction</h2>
23

24
<p>
Rob Pike's avatar
Rob Pike committed
25
This is a reference manual for the Go programming language. For
26
more information and other documents, see <a href="http://golang.org/">http://golang.org</a>.
Rob Pike's avatar
Rob Pike committed
27
</p>
28

29
<p>
Rob Pike's avatar
Rob Pike committed
30
Go is a general-purpose language designed with systems programming
Rob Pike's avatar
Rob Pike committed
31
in mind. It is strongly typed and garbage-collected and has explicit
Rob Pike's avatar
Rob Pike committed
32 33 34 35 36
support for concurrent programming.  Programs are constructed from
<i>packages</i>, whose properties allow efficient management of
dependencies. The existing implementations use a traditional
compile/link model to generate executable binaries.
</p>
37

38
<p>
Rob Pike's avatar
Rob Pike committed
39 40 41
The grammar is compact and regular, allowing for easy analysis by
automatic tools such as integrated development environments.
</p>
42

43
<h2 id="Notation">Notation</h2>
Rob Pike's avatar
Rob Pike committed
44
<p>
45
The syntax is specified using Extended Backus-Naur Form (EBNF):
Rob Pike's avatar
Rob Pike committed
46
</p>
47

Rob Pike's avatar
Rob Pike committed
48
<pre class="grammar">
49
Production  = production_name "=" [ Expression ] "." .
Rob Pike's avatar
Rob Pike committed
50
Expression  = Alternative { "|" Alternative } .
51
Alternative = Term { Term } .
Rob Pike's avatar
Rob Pike committed
52 53
Term        = production_name | token [ "..." token ] | Group | Option | Repetition .
Group       = "(" Expression ")" .
54
Option      = "[" Expression "]" .
Rob Pike's avatar
Rob Pike committed
55
Repetition  = "{" Expression "}" .
56
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
57

Rob Pike's avatar
Rob Pike committed
58 59 60 61
<p>
Productions are expressions constructed from terms and the following
operators, in increasing precedence:
</p>
Rob Pike's avatar
Rob Pike committed
62
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
63 64 65 66
|   alternation
()  grouping
[]  option (0 or 1 times)
{}  repetition (0 to n times)
67
</pre>
68

69
<p>
Rob Pike's avatar
Rob Pike committed
70 71
Lower-case production names are used to identify lexical tokens.
Non-terminals are in CamelCase. Lexical symbols are enclosed in
Rob Pike's avatar
Rob Pike committed
72
double quotes <code>""</code> or back quotes <code>``</code>.
Rob Pike's avatar
Rob Pike committed
73 74
</p>

75
<p>
76
The form <code>a ... b</code> represents the set of characters from
77
<code>a</code> through <code>b</code> as alternatives.
Rob Pike's avatar
Rob Pike committed
78 79
</p>

80
<h2 id="Source_code_representation">Source code representation</h2>
81

82
<p>
83 84
Source code is Unicode text encoded in
<a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
Rob Pike's avatar
Rob Pike committed
85 86 87 88 89
canonicalized, so a single accented code point is distinct from the
same character constructed from combining an accent and a letter;
those are treated as two code points.  For simplicity, this document
will use the term <i>character</i> to refer to a Unicode code point.
</p>
90
<p>
Rob Pike's avatar
Rob Pike committed
91 92 93
Each code point is distinct; for instance, upper and lower case letters
are different characters.
</p>
94
<p>
95 96
Implementation restriction: For compatibility with other tools, a
compiler may disallow the NUL character (U+0000) in the source text.
97
</p>
98

99
<h3 id="Characters">Characters</h3>
100

101
<p>
Rob Pike's avatar
Rob Pike committed
102 103
The following terms are used to denote specific Unicode character classes:
</p>
104
<pre class="ebnf">
105 106
newline        = /* the Unicode code point U+000A */ .
unicode_char   = /* an arbitrary Unicode code point except newline */ .
107
unicode_letter = /* a Unicode code point classified as "Letter" */ .
108
unicode_digit  = /* a Unicode code point classified as "Decimal Digit" */ .
109
</pre>
110

Rob Pike's avatar
Rob Pike committed
111
<p>
112 113
In <a href="http://www.unicode.org/versions/Unicode6.0.0/">The Unicode Standard 6.0</a>,
Section 4.5 "General Category"
Rob Pike's avatar
Rob Pike committed
114 115 116 117
defines a set of character categories.  Go treats
those characters in category Lu, Ll, Lt, Lm, or Lo as Unicode letters,
and those in category Nd as Unicode digits.
</p>
118

119
<h3 id="Letters_and_digits">Letters and digits</h3>
Rob Pike's avatar
Rob Pike committed
120 121

<p>
122
The underscore character <code>_</code> (U+005F) is considered a letter.
123 124
</p>
<pre class="ebnf">
125 126 127 128 129
letter        = unicode_letter | "_" .
decimal_digit = "0" ... "9" .
octal_digit   = "0" ... "7" .
hex_digit     = "0" ... "9" | "A" ... "F" | "a" ... "f" .
</pre>
Rob Pike's avatar
Rob Pike committed
130

131
<h2 id="Lexical_elements">Lexical elements</h2>
132

133
<h3 id="Comments">Comments</h3>
134

Rob Pike's avatar
Rob Pike committed
135
<p>
136
There are two forms of comments:
Rob Pike's avatar
Rob Pike committed
137 138
</p>

139 140 141
<ol>
<li>
<i>Line comments</i> start with the character sequence <code>//</code>
142
and stop at the end of the line. A line comment acts like a newline.
143 144 145 146 147 148 149 150 151 152 153 154 155 156
</li>
<li>
<i>General comments</i> start with the character sequence <code>/*</code>
and continue through the character sequence <code>*/</code>. A general
comment that spans multiple lines acts like a newline, otherwise it acts
like a space.
</li>
</ol>

<p>
Comments do not nest.
</p>


157
<h3 id="Tokens">Tokens</h3>
158

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

173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
<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>
<p>
When the input is broken into tokens, a semicolon is automatically inserted
into the token stream at the end of a non-blank line if the line's final
token is
</p>
<ul>
189 190
	<li>an
	    <a href="#Identifiers">identifier</a>
191
	</li>
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
	
	<li>an
	    <a href="#Integer_literals">integer</a>,
	    <a href="#Floating-point_literals">floating-point</a>,
	    <a href="#Imaginary_literals">imaginary</a>,
	    <a href="#Character_literals">character</a>, or
	    <a href="#String_literals">string</a> literal
	</li>
	
	<li>one of the <a href="#Keywords">keywords</a>
	    <code>break</code>,
	    <code>continue</code>,
	    <code>fallthrough</code>, or
	    <code>return</code>
	</li>
	
	<li>one of the <a href="#Operators_and_Delimiters">operators and delimiters</a>
	    <code>++</code>,
	    <code>--</code>,
	    <code>)</code>,
	    <code>]</code>, or
	    <code>}</code>
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
	</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>


230
<h3 id="Identifiers">Identifiers</h3>
231

Rob Pike's avatar
Rob Pike committed
232 233 234 235 236
<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>
237
<pre class="ebnf">
238
identifier = letter { letter | unicode_digit } .
239 240 241 242 243 244 245
</pre>
<pre>
a
_x9
ThisVariableIsExported
αβ
</pre>
246 247

<p>
Robert Griesemer's avatar
Robert Griesemer committed
248
Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
249 250
</p>

251

252
<h3 id="Keywords">Keywords</h3>
253

Rob Pike's avatar
Rob Pike committed
254 255 256 257 258 259 260 261 262 263
<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>
264

265
<h3 id="Operators_and_Delimiters">Operators and Delimiters</h3>
Rob Pike's avatar
Rob Pike committed
266 267

<p>
268
The following character sequences represent <a href="#Operators">operators</a>, delimiters, and other special tokens:
Rob Pike's avatar
Rob Pike committed
269 270 271 272 273
</p>
<pre class="grammar">
+    &amp;     +=    &amp;=     &amp;&amp;    ==    !=    (    )
-    |     -=    |=     ||    &lt;     &lt;=    [    ]
*    ^     *=    ^=     &lt;-    &gt;     &gt;=    {    }
274 275
/    &lt;&lt;    /=    &lt;&lt;=    ++    =     :=    ,    ;
%    &gt;&gt;    %=    &gt;&gt;=    --    !     ...   .    :
Rob Pike's avatar
Rob Pike committed
276
     &amp;^          &amp;^=
Rob Pike's avatar
Rob Pike committed
277 278
</pre>

279
<h3 id="Integer_literals">Integer literals</h3>
Rob Pike's avatar
Rob Pike committed
280 281

<p>
282 283 284
An integer literal is a sequence of digits representing an
<a href="#Constants">integer constant</a>.
An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</code> or
285 286
<code>0X</code> for hexadecimal.  In hexadecimal literals, letters
<code>a-f</code> and <code>A-F</code> represent values 10 through 15.
Rob Pike's avatar
Rob Pike committed
287
</p>
288
<pre class="ebnf">
289 290 291 292
int_lit     = decimal_lit | octal_lit | hex_lit .
decimal_lit = ( "1" ... "9" ) { decimal_digit } .
octal_lit   = "0" { octal_digit } .
hex_lit     = "0" ( "x" | "X" ) hex_digit { hex_digit } .
293 294 295 296 297 298 299 300
</pre>

<pre>
42
0600
0xBadFace
170141183460469231731687303715884105727
</pre>
301

302
<h3 id="Floating-point_literals">Floating-point literals</h3>
Rob Pike's avatar
Rob Pike committed
303
<p>
304 305 306
A floating-point literal is a decimal representation of a
<a href="#Constants">floating-point constant</a>.
It has an integer part, a decimal point, a fractional part,
Rob Pike's avatar
Rob Pike committed
307
and an exponent part.  The integer and fractional part comprise
308
decimal digits; the exponent part is an <code>e</code> or <code>E</code>
Rob Pike's avatar
Rob Pike committed
309 310 311 312
followed by an optionally signed decimal exponent.  One of the
integer part or the fractional part may be elided; one of the decimal
point or the exponent may be elided.
</p>
313
<pre class="ebnf">
314 315 316 317 318
float_lit = decimals "." [ decimals ] [ exponent ] |
            decimals exponent |
            "." decimals [ exponent ] .
decimals  = decimal_digit { decimal_digit } .
exponent  = ( "e" | "E" ) [ "+" | "-" ] decimals .
319 320 321 322
</pre>

<pre>
0.
Rob Pike's avatar
Rob Pike committed
323 324
72.40
072.40  // == 72.40
325 326 327 328 329 330 331
2.71828
1.e+0
6.67428e-11
1E6
.25
.12345E+5
</pre>
332

Rob Pike's avatar
Rob Pike committed
333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357
<h3 id="Imaginary_literals">Imaginary literals</h3>
<p>
An imaginary literal is a decimal representation of the imaginary part of a
<a href="#Constants">complex constant</a>.
It consists of a
<a href="#Floating-point_literals">floating-point literal</a>
or decimal integer followed
by the lower-case letter <code>i</code>.
</p>
<pre class="ebnf">
imaginary_lit = (decimals | float_lit) "i" .
</pre>

<pre>
0i
011i  // == 11i
0.i
2.71828i
1.e+0i
6.67428e-11i
1E6i
.25i
.12345E+5i
</pre>

358

359
<h3 id="Character_literals">Character literals</h3>
360

Rob Pike's avatar
Rob Pike committed
361
<p>
362 363
A character literal represents an <a href="#Constants">integer constant</a>,
typically a Unicode code point, as one or more characters enclosed in single
Rob Pike's avatar
Rob Pike committed
364 365 366 367
quotes.  Within the quotes, any character may appear except single
quote and newline. A single quoted character represents itself,
while multi-character sequences beginning with a backslash encode
values in various formats.
Rob Pike's avatar
Rob Pike committed
368
</p>
369
<p>
Rob Pike's avatar
Rob Pike committed
370 371 372
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
373 374 375 376
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
377
</p>
378
<p>
Rob Pike's avatar
Rob Pike committed
379 380
Several backslash escapes allow arbitrary values to be represented
as ASCII text.  There are four ways to represent the integer value
381 382 383 384
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
385 386 387
In each case the value of the literal is the value represented by
the digits in the corresponding base.
</p>
388
<p>
Rob Pike's avatar
Rob Pike committed
389 390
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
391 392
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
393
represent Unicode code points so within them some values are illegal,
394
in particular those above <code>0x10FFFF</code> and surrogate halves.
Rob Pike's avatar
Rob Pike committed
395
</p>
396
<p>
Rob Pike's avatar
Rob Pike committed
397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
After a backslash, certain single-character escapes represent special values:
</p>
<pre class="grammar">
\a   U+0007 alert or bell
\b   U+0008 backspace
\f   U+000C form feed
\n   U+000A line feed or newline
\r   U+000D carriage return
\t   U+0009 horizontal tab
\v   U+000b vertical tab
\\   U+005c backslash
\'   U+0027 single quote  (valid escape only within character literals)
\"   U+0022 double quote  (valid escape only within string literals)
</pre>
<p>
412
All other sequences starting with a backslash are illegal inside character literals.
Rob Pike's avatar
Rob Pike committed
413
</p>
414
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
415 416 417
char_lit         = "'" ( unicode_value | byte_value ) "'" .
unicode_value    = unicode_char | little_u_value | big_u_value | escaped_char .
byte_value       = octal_byte_value | hex_byte_value .
418 419 420 421
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
422
                           hex_digit hex_digit hex_digit hex_digit .
423
escaped_char     = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
Rob Pike's avatar
Rob Pike committed
424
</pre>
425

426 427 428 429 430 431 432 433 434 435 436 437 438
<pre>
'a'
'ä'
'本'
'\t'
'\000'
'\007'
'\377'
'\x07'
'\xff'
'\u12e4'
'\U00101234'
</pre>
439 440


441
<h3 id="String_literals">String literals</h3>
Rob Pike's avatar
Rob Pike committed
442 443

<p>
444 445 446
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
447 448 449
</p>
<p>
Raw string literals are character sequences between back quotes
450
<code>``</code>.  Within the quotes, any character is legal except
451 452 453 454
back quote. The value of a raw string literal is the
string composed of the uninterpreted characters between the quotes;
in particular, backslashes have no special meaning and the string may
span multiple lines.
Rob Pike's avatar
Rob Pike committed
455 456 457
</p>
<p>
Interpreted string literals are character sequences between double
458 459
quotes <code>&quot;&quot;</code>. The text between the quotes,
which may not span multiple lines, forms the
Rob Pike's avatar
Rob Pike committed
460
value of the literal, with backslash escapes interpreted as they
461
are in character literals (except that <code>\'</code> is illegal and
462 463
<code>\"</code> is legal).  The three-digit octal (<code>\</code><i>nnn</i>)
and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
Rob Pike's avatar
Rob Pike committed
464 465
<i>bytes</i> of the resulting string; all other escapes represent
the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
466 467 468
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
469
the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
Rob Pike's avatar
Rob Pike committed
470 471 472
U+00FF.
</p>

473
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
474
string_lit             = raw_string_lit | interpreted_string_lit .
475
raw_string_lit         = "`" { unicode_char | newline } "`" .
476
interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
477
</pre>
478

479
<pre>
480 481 482
`abc`  // same as "abc"
`\n
\n`    // same as "\\n\n\\n"
483 484 485 486 487 488 489
"\n"
""
"Hello, world!\n"
"日本語"
"\u65e5本\U00008a9e"
"\xff\u00FF"
</pre>
490

Rob Pike's avatar
Rob Pike committed
491
<p>
492
These examples all represent the same string:
Rob Pike's avatar
Rob Pike committed
493
</p>
494

495
<pre>
Rob Pike's avatar
Rob Pike committed
496 497 498 499
"日本語"                                 // UTF-8 input text
`日本語`                                 // UTF-8 input text as a raw literal
"\u65e5\u672c\u8a9e"                    // The explicit Unicode code points
"\U000065e5\U0000672c\U00008a9e"        // The explicit Unicode code points
500 501
"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e"  // The explicit UTF-8 bytes
</pre>
502

503
<p>
504 505 506 507 508
If the source code represents a character as two code points, such as
a combining form involving an accent and a letter, the result will be
an error if placed in a character literal (it is not a single code
point), and will appear as two code points if placed in a string
literal.
Rob Pike's avatar
Rob Pike committed
509
</p>
510

511 512 513

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

Rob Pike's avatar
Rob Pike committed
514 515 516 517
<p>There are <i>boolean constants</i>, <i>integer constants</i>,
<i>floating-point constants</i>, <i>complex constants</i>,
and <i>string constants</i>. Integer, floating-point,
and complex constants are
518 519 520 521 522 523 524
collectively called <i>numeric constants</i>.
</p>

<p>
A constant value is represented by an
<a href="#Integer_literals">integer</a>,
<a href="#Floating-point_literals">floating-point</a>,
Rob Pike's avatar
Rob Pike committed
525
<a href="#Imaginary_literals">imaginary</a>,
526 527 528 529
<a href="#Character_literals">character</a>, or
<a href="#String_literals">string</a> literal,
an identifier denoting a constant,
a <a href="#Constant_expressions">constant expression</a>, or
530 531 532 533
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
534
<code>real</code> and <code>imag</code> applied to a complex constant
535
and <code>complex</code> applied to numeric constants.
536 537 538 539
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
540

Rob Pike's avatar
Rob Pike committed
541 542 543 544 545 546
<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
547
<p>
548
Numeric constants represent values of arbitrary precision and do not overflow.
Rob Pike's avatar
Rob Pike committed
549 550
</p>

551 552 553 554 555 556 557 558 559 560 561 562 563 564
<p>
Constants may be <a href="#Types">typed</a> or untyped.
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
565
cannot be represented as a value of the respective type.
566
For instance, <code>3.0</code> can be given any integer or any
567 568 569
floating-point type, while <code>2147483648.0</code> (equal to <code>1&lt;&lt;31</code>)
can be given the types <code>float32</code>, <code>float64</code>, or <code>uint32</code> but
not <code>int32</code> or <code>string</code>.
570 571
</p>

572 573 574 575 576 577 578 579 580 581
<p>
There are no constants denoting the IEEE-754 infinity and not-a-number values,
but the <a href="/pkg/math/"><code>math</code> package</a>'s
<a href="/pkg/math/#Inf">Inf</a>,
<a href="/pkg/math/#NaN">NaN</a>,
<a href="/pkg/math/#IsInf">IsInf</a>, and
<a href="/pkg/math/#IsNaN">IsNaN</a>
functions return and test for those values at run time.
</p>

582 583 584 585 586 587 588
<p>
Implementation restriction: A compiler may implement numeric constants by choosing
an internal representation with at least twice as many bits as any machine type;
for floating-point values, both the mantissa and exponent must be twice as large.
</p>


589
<h2 id="Types">Types</h2>
590

591
<p>
Robert Griesemer's avatar
Robert Griesemer committed
592 593
A type determines the set of values and operations specific to values of that
type.  A type may be specified by a (possibly qualified) <i>type name</i>
594
<a href="#Qualified_identifiers">Qualified identifier</a>, §<a href="#Type_declarations">Type declarations</a>) or a <i>type literal</i>,
Robert Griesemer's avatar
Robert Griesemer committed
595
which composes a new type from previously declared types.
Rob Pike's avatar
Rob Pike committed
596
</p>
597

598
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
599
Type      = TypeName | TypeLit | "(" Type ")" .
600
TypeName  = QualifiedIdent .
Rob Pike's avatar
Rob Pike committed
601 602
TypeLit   = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
	    SliceType | MapType | ChannelType .
603
</pre>
604

605
<p>
606 607 608 609 610
Named instances of the boolean, numeric, and string types are
<a href="#Predeclared_identifiers">predeclared</a>.
<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
611
</p>
612

613 614 615 616 617 618 619 620 621 622 623
<p>
The <i>static type</i> (or just <i>type</i>) of a variable is the
type defined by its declaration.  Variables of interface type
also have a distinct <i>dynamic type</i>, which
is the actual type of the value stored in the variable at run-time.
The dynamic type may vary during execution but is always
<a href="#Assignability">assignable</a>
to the static type of the interface variable.  For non-interface
types, the dynamic type is always the static type.
</p>

624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644
<p>
Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
is a predeclared type or a type literal, the corresponding underlying
type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type
is the underlying type of the type to which <code>T</code> refers in its
<a href="#Type_declarations">type declaration</a>.
</p>

<pre>
   type T1 string
   type T2 T1
   type T3 []T1
   type T4 T3
</pre>

<p>
The underlying type of <code>string</code>, <code>T1</code>, and <code>T2</code>
is <code>string</code>. The underlying type of <code>[]T1</code>, <code>T3</code>,
and <code>T4</code> is <code>[]T1</code>.
</p>

645
<h3 id="Method_sets">Method sets</h3>
Rob Pike's avatar
Rob Pike committed
646
<p>
647
A type may have a <i>method set</i> associated with it
648
<a href="#Interface_types">Interface types</a>, §<a href="#Method_declarations">Method declarations</a>).
649
The method set of an <a href="#Interface_types">interface type</a> is its interface.
Robert Griesemer's avatar
Robert Griesemer committed
650
The method set of any other named type <code>T</code>
651
consists of all methods with receiver type <code>T</code>.
Robert Griesemer's avatar
Robert Griesemer committed
652 653 654 655
The method set of the corresponding pointer type <code>*T</code>
is the set of all methods with receiver <code>*T</code> or <code>T</code>
(that is, it also contains the method set of <code>T</code>).
Any other type has an empty method set.
656
In a method set, each method must have a unique name.
Rob Pike's avatar
Rob Pike committed
657
</p>
Robert Griesemer's avatar
Robert Griesemer committed
658

659

660 661 662 663 664 665
<h3 id="Boolean_types">Boolean types</h3>

A <i>boolean type</i> represents the set of Boolean truth values
denoted by the predeclared constants <code>true</code>
and <code>false</code>. The predeclared boolean type is <code>bool</code>.

666

667
<h3 id="Numeric_types">Numeric types</h3>
668

Rob Pike's avatar
Rob Pike committed
669
<p>
670 671
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
672
</p>
673

Rob Pike's avatar
Rob Pike committed
674
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
675 676 677 678 679 680 681 682 683
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)
684

Rob Pike's avatar
Rob Pike committed
685 686
float32     the set of all IEEE-754 32-bit floating-point numbers
float64     the set of all IEEE-754 64-bit floating-point numbers
687

Rob Pike's avatar
Rob Pike committed
688 689
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
690

691
byte        familiar alias for uint8
692
</pre>
693

Rob Pike's avatar
Rob Pike committed
694
<p>
695 696
The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
<a href="http://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
Rob Pike's avatar
Rob Pike committed
697
</p>
698

Rob Pike's avatar
Rob Pike committed
699
<p>
700
There is also a set of predeclared numeric types with implementation-specific sizes:
Rob Pike's avatar
Rob Pike committed
701
</p>
702

703
<pre class="grammar">
704
uint     either 32 or 64 bits
705
int      same size as uint
706
uintptr  an unsigned integer large enough to store the uninterpreted bits of a pointer value
707
</pre>
708

709
<p>
710 711 712
To avoid portability issues all numeric types are distinct except
<code>byte</code>, which is an alias for <code>uint8</code>.
Conversions
713
are required when different numeric types are mixed in an expression
Rob Pike's avatar
Rob Pike committed
714
or assignment. For instance, <code>int32</code> and <code>int</code>
715
are not the same type even though they may have the same size on a
Rob Pike's avatar
Rob Pike committed
716
particular architecture.
717

718

719
<h3 id="String_types">String types</h3>
720

721
<p>
722
A <i>string type</i> represents the set of string values.
Rob Pike's avatar
Rob Pike committed
723 724
Strings behave like arrays of bytes but are immutable: once created,
it is impossible to change the contents of a string.
725
The predeclared string type is <code>string</code>.
Rob Pike's avatar
Rob Pike committed
726 727 728

<p>
The elements of strings have type <code>byte</code> and may be
729
accessed using the usual <a href="#Indexes">indexing operations</a>.  It is
Rob Pike's avatar
Rob Pike committed
730 731
illegal to take the address of such an element; if
<code>s[i]</code> is the <i>i</i>th byte of a
732 733
string, <code>&amp;s[i]</code> is invalid.  The length of string
<code>s</code> can be discovered using the built-in function
734
<code>len</code>. The length is a compile-time constant if <code>s</code>
735
is a string literal.
Rob Pike's avatar
Rob Pike committed
736
</p>
737 738


739
<h3 id="Array_types">Array types</h3>
740 741 742

<p>
An array is a numbered sequence of elements of a single
743 744
type, called the element type.
The number of elements is called the length and is never
745 746 747
negative.
</p>

748
<pre class="ebnf">
749 750
ArrayType   = "[" ArrayLength "]" ElementType .
ArrayLength = Expression .
751
ElementType = Type .
752 753 754
</pre>

<p>
755
The length is part of the array's type and must be a
756
<a href="#Constant_expressions">constant expression</a> that evaluates to a non-negative
757
integer value.  The length of array <code>a</code> can be discovered
758 759
using the built-in function <a href="#Length_and_capacity"><code>len(a)</code></a>.
The elements can be indexed by integer
760
indices 0 through the <code>len(a)-1</code><a href="#Indexes">Indexes</a>).
761 762
Array types are always one-dimensional but may be composed to form
multi-dimensional types.
763 764 765 766 767 768
</p>

<pre>
[32]byte
[2*N] struct { x, y int32 }
[1000]*float64
769 770
[3][5]int
[2][2][2]float64  // same as [2]([2]([2]float64))
771 772
</pre>

773
<h3 id="Slice_types">Slice types</h3>
774 775 776 777 778

<p>
A slice is a reference to a contiguous segment of an array and
contains a numbered sequence of elements from that array.  A slice
type denotes the set of all slices of arrays of its element type.
779
The value of an uninitialized slice is <code>nil</code>.
780 781
</p>

782
<pre class="ebnf">
783 784 785 786 787 788
SliceType = "[" "]" ElementType .
</pre>

<p>
Like arrays, slices are indexable and have a length.  The length of a
slice <code>s</code> can be discovered by the built-in function
789
<a href="#Length_and_capacity"><code>len(s)</code></a>; unlike with arrays it may change during
790
execution.  The elements can be addressed by integer indices 0
791
through <code>len(s)-1</code><a href="#Indexes">Indexes</a>).  The slice index of a
792 793 794 795 796
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
797
array that holds its elements.  A slice therefore shares storage
798 799 800 801 802
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.
803
The <i>capacity</i> is a measure of that extent: it is the sum of
804 805
the length of the slice and the length of the array beyond the slice;
a slice of length up to that capacity can be created by `slicing' a new
806
one from the original slice (§<a href="#Slices">Slices</a>).
807
The capacity of a slice <code>a</code> can be discovered using the
808
built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
809 810 811
</p>

<p>
812 813 814 815
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
816 817 818 819 820 821 822
and parameters specifying the length and optionally the capacity:
</p>

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

824 825
<p>
The <code>make()</code> call allocates a new, hidden array to which the returned
Rob Pike's avatar
Rob Pike committed
826
slice value refers. That is, executing
827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842
</p>

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

<p>
produces the same slice as allocating an array and slicing it, so these two examples
result in the same slice:
</p>

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

843 844 845 846 847 848 849
<p>
Like arrays, slices are always one-dimensional but may be composed to construct
higher-dimensional objects.
With arrays of arrays, the inner arrays are, by construction, always the same length;
however with slices of slices (or arrays of slices), the lengths may vary dynamically.
Moreover, the inner slices must be allocated individually (with <code>make</code>).
</p>
850

851
<h3 id="Struct_types">Struct types</h3>
852

Rob Pike's avatar
Rob Pike committed
853
<p>
854 855 856 857 858
A struct is a sequence of named elements, called fields, each of which has a
name and a type. Field names may be specified explicitly (IdentifierList) or
implicitly (AnonymousField).
Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
be unique.
Rob Pike's avatar
Rob Pike committed
859
</p>
860

861
<pre class="ebnf">
862
StructType     = "struct" "{" { FieldDecl ";" } "}" .
863 864
FieldDecl      = (IdentifierList Type | AnonymousField) [ Tag ] .
AnonymousField = [ "*" ] TypeName .
865
Tag            = string_lit .
866
</pre>
867

868
<pre>
869 870
// An empty struct.
struct {}
871

Robert Griesemer's avatar
Robert Griesemer committed
872
// A struct with 6 fields.
873
struct {
874
	x, y int
875 876
	u float32
	_ float32  // padding
877 878
	A *[]int
	F func()
879 880
}
</pre>
881

Rob Pike's avatar
Rob Pike committed
882
<p>
883 884
A field declared with a type but no explicit field name is an <i>anonymous field</i>
(colloquially called an embedded field).
Rob Pike's avatar
Rob Pike committed
885
Such a field type must be specified as
886
a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
887
and <code>T</code> itself may not be
888
a pointer type. The unqualified type name acts as the field name.
Rob Pike's avatar
Rob Pike committed
889
</p>
890

891 892 893
<pre>
// A struct with four anonymous fields of type T1, *T2, P.T3 and *P.T4
struct {
894 895 896 897 898
	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
899
}
900 901
</pre>

Rob Pike's avatar
Rob Pike committed
902
<p>
903 904
The following declaration is illegal because field names must be unique
in a struct type:
Rob Pike's avatar
Rob Pike committed
905
</p>
906

907
<pre>
908
struct {
909 910 911
	T         // conflicts with anonymous field *T and *P.T
	*T        // conflicts with anonymous field T and *P.T
	*P.T      // conflicts with anonymous field T and *T
912
}
913
</pre>
914

915
<p>
916 917
Fields and methods (§<a href="#Method_declarations">Method declarations</a>) of an anonymous field are
promoted to be ordinary fields and methods of the struct (§<a href="#Selectors">Selectors</a>).
Robert Griesemer's avatar
Robert Griesemer committed
918 919
The following rules apply for a struct type named <code>S</code> and
a type named <code>T</code>:
Rob Pike's avatar
Rob Pike committed
920
</p>
Robert Griesemer's avatar
Robert Griesemer committed
921 922
<ul>
	<li>If <code>S</code> contains an anonymous field <code>T</code>, the
923 924
	    <a href="#Method_sets">method set</a> of <code>S</code> includes the
	    method set of <code>T</code>.
Robert Griesemer's avatar
Robert Griesemer committed
925 926 927 928 929 930 931 932 933 934 935 936 937
	</li>

	<li>If <code>S</code> contains an anonymous field <code>*T</code>, the
	    method set of <code>S</code> includes the method set of <code>*T</code>
	    (which itself includes the method set of <code>T</code>).
	</li>

	<li>If <code>S</code> contains an anonymous field <code>T</code> or
	    <code>*T</code>, the method set of <code>*S</code> includes the
	    method set of <code>*T</code> (which itself includes the method
	    set of <code>T</code>).
	</li>
</ul>
Rob Pike's avatar
Rob Pike committed
938
<p>
Robert Griesemer's avatar
Robert Griesemer committed
939
A field declaration may be followed by an optional string literal <i>tag</i>,
940
which becomes an attribute for all the fields in the corresponding
Rob Pike's avatar
Rob Pike committed
941
field declaration. The tags are made
942
visible through a <a href="#Package_unsafe">reflection interface</a>
Rob Pike's avatar
Rob Pike committed
943 944
but are otherwise ignored.
</p>
945

946
<pre>
Rob Pike's avatar
Rob Pike committed
947
// A struct corresponding to the TimeStamp protocol buffer.
Rob Pike's avatar
Rob Pike committed
948
// The tag strings define the protocol buffer field numbers.
949
struct {
950 951 952
	microsec  uint64 "field 1"
	serverIP6 uint64 "field 2"
	process   string "field 3"
953
}
954
</pre>
955

956
<h3 id="Pointer_types">Pointer types</h3>
957

Rob Pike's avatar
Rob Pike committed
958
<p>
959
A pointer type denotes the set of all pointers to variables of a given
960
type, called the <i>base type</i> of the pointer.
961
The value of an uninitialized pointer is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
962
</p>
963

964
<pre class="ebnf">
965 966
PointerType = "*" BaseType .
BaseType = Type .
967
</pre>
968

969
<pre>
970
*int
Rob Pike's avatar
Rob Pike committed
971
*map[string] *chan int
972
</pre>
973

974
<h3 id="Function_types">Function types</h3>
975

Rob Pike's avatar
Rob Pike committed
976
<p>
977
A function type denotes the set of all functions with the same parameter
978
and result types. The value of an uninitialized variable of function type
979
is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
980
</p>
981

982
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
983 984
FunctionType   = "func" Signature .
Signature      = Parameters [ Result ] .
985
Result         = Parameters | Type .
986
Parameters     = "(" [ ParameterList [ "," ] ] ")" .
Rob Pike's avatar
Rob Pike committed
987
ParameterList  = ParameterDecl { "," ParameterDecl } .
Russ Cox's avatar
Russ Cox committed
988
ParameterDecl  = [ IdentifierList ] [ "..." ] Type .
989 990 991
</pre>

<p>
Rob Pike's avatar
Rob Pike committed
992 993 994 995 996
Within a list of parameters or results, the names (IdentifierList)
must either all be present or all be absent. If present, each name
stands for one item (parameter or result) of the specified type; if absent, each
type stands for one item of that type.  Parameter and result
lists are always parenthesized except that if there is exactly
Robert Griesemer's avatar
Robert Griesemer committed
997
one unnamed result it may be written as an unparenthesized type.
Rob Pike's avatar
Rob Pike committed
998
</p>
Russ Cox's avatar
Russ Cox committed
999

Robert Griesemer's avatar
Robert Griesemer committed
1000 1001 1002 1003 1004
<p>
The final parameter in a function signature may have
a type prefixed with <code>...</code>.
A function with such a parameter is called <i>variadic</i> and
may be invoked with zero or more arguments for that parameter.
Rob Pike's avatar
Rob Pike committed
1005
</p>
1006 1007

<pre>
Russ Cox's avatar
Russ Cox committed
1008 1009 1010
func()
func(x int)
func() int
Russ Cox's avatar
Russ Cox committed
1011
func(prefix string, values ...int)
1012 1013 1014 1015
func(a, b int, z float32) bool
func(a, b int, z float32) (bool)
func(a, b int, z float64, opt ...interface{}) (success bool)
func(int, int, float64) (float64, *[]int)
Russ Cox's avatar
Russ Cox committed
1016
func(n int) func(p *T)
1017 1018 1019
</pre>


1020
<h3 id="Interface_types">Interface types</h3>
1021

Rob Pike's avatar
Rob Pike committed
1022
<p>
1023
An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>.
Robert Griesemer's avatar
Robert Griesemer committed
1024 1025
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
1026
<i>implement the interface</i>.
1027
The value of an uninitialized variable of interface type is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1028
</p>
1029

1030
<pre class="ebnf">
1031
InterfaceType      = "interface" "{" { MethodSpec ";" } "}" .
1032 1033
MethodSpec         = MethodName Signature | InterfaceTypeName .
MethodName         = identifier .
Rob Pike's avatar
Rob Pike committed
1034
InterfaceTypeName  = TypeName .
1035
</pre>
1036

1037 1038 1039 1040
<p>
As with all method sets, in an interface type, each method must have a unique name.
</p>

1041
<pre>
Rob Pike's avatar
Rob Pike committed
1042
// A simple File interface
1043
interface {
1044 1045 1046
	Read(b Buffer) bool
	Write(b Buffer) bool
	Close()
1047 1048
}
</pre>
1049

Rob Pike's avatar
Rob Pike committed
1050
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1051
More than one type may implement an interface.
Rob Pike's avatar
Rob Pike committed
1052
For instance, if two types <code>S1</code> and <code>S2</code>
Robert Griesemer's avatar
Robert Griesemer committed
1053
have the method set
Rob Pike's avatar
Rob Pike committed
1054
</p>
1055

1056
<pre>
1057 1058 1059
func (p T) Read(b Buffer) bool { return ... }
func (p T) Write(b Buffer) bool { return ... }
func (p T) Close() { ... }
1060
</pre>
1061

Rob Pike's avatar
Rob Pike committed
1062 1063 1064 1065 1066 1067
<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>
1068

Rob Pike's avatar
Rob Pike committed
1069 1070 1071 1072 1073
<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>
1074

1075
<pre>
1076
interface{}
1077
</pre>
1078

Rob Pike's avatar
Rob Pike committed
1079 1080
<p>
Similarly, consider this interface specification,
1081
which appears within a <a href="#Type_declarations">type declaration</a>
Rob Pike's avatar
Rob Pike committed
1082 1083
to define an interface called <code>Lock</code>:
</p>
1084 1085 1086

<pre>
type Lock interface {
1087 1088
	Lock()
	Unlock()
1089
}
1090
</pre>
1091

Rob Pike's avatar
Rob Pike committed
1092 1093 1094
<p>
If <code>S1</code> and <code>S2</code> also implement
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1095

1096 1097 1098 1099 1100
<pre>
func (p T) Lock() { ... }
func (p T) Unlock() { ... }
</pre>

1101
<p>
Rob Pike's avatar
Rob Pike committed
1102 1103 1104 1105 1106 1107
they implement the <code>Lock</code> interface as well
as the <code>File</code> interface.
</p>
<p>
An interface may contain an interface type name <code>T</code>
in place of a method specification.
1108
The effect is equivalent to enumerating the methods of <code>T</code> explicitly
Rob Pike's avatar
Rob Pike committed
1109 1110
in the interface.
</p>
1111

1112 1113
<pre>
type ReadWrite interface {
1114 1115
	Read(b Buffer) bool
	Write(b Buffer) bool
1116
}
1117

1118
type File interface {
1119 1120 1121
	ReadWrite  // same as enumerating the methods in ReadWrite
	Lock       // same as enumerating the methods in Lock
	Close()
1122 1123
}
</pre>
1124

1125
<h3 id="Map_types">Map types</h3>
1126

Rob Pike's avatar
Rob Pike committed
1127 1128
<p>
A map is an unordered group of elements of one type, called the
1129
element type, indexed by a set of unique <i>keys</i> of another type,
1130
called the key type.
1131
The value of an uninitialized map is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1132
</p>
1133

1134
<pre class="ebnf">
1135
MapType     = "map" "[" KeyType "]" ElementType .
1136
KeyType     = Type .
1137
</pre>
1138

1139
<p>
Rob Pike's avatar
Rob Pike committed
1140
The comparison operators <code>==</code> and <code>!=</code>
1141 1142 1143
<a href="#Comparison_operators">Comparison operators</a>) must be fully defined
for operands of the key type; thus the key type must not be a struct, array or slice.
If the key type is an interface type, these
Rob Pike's avatar
Rob Pike committed
1144
comparison operators must be defined for the dynamic key values;
1145
failure will cause a <a href="#Run_time_panics">run-time panic</a>.
Rob Pike's avatar
Rob Pike committed
1146 1147

</p>
1148

1149
<pre>
1150
map [string] int
1151
map [*T] struct { x, y float64 }
1152
map [string] interface {}
1153
</pre>
1154

Rob Pike's avatar
Rob Pike committed
1155
<p>
1156 1157 1158
The number of map elements is called its length.
For a map <code>m</code>, it can be discovered using the
built-in function <a href="#Length_and_capacity"><code>len(m)</code></a>
1159 1160 1161
and may change during execution. Elements may be added and removed
during execution using special forms of <a href="#Assignments">assignment</a>;
and they may be accessed with <a href="#Indexes">index</a> expressions.
Rob Pike's avatar
Rob Pike committed
1162 1163 1164
</p>
<p>
A new, empty map value is made using the built-in
1165 1166
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
1167
</p>
1168

1169
<pre>
1170 1171
make(map[string] int)
make(map[string] int, 100)
1172
</pre>
1173

1174 1175 1176
<p>
The initial capacity does not bound its size:
maps grow to accommodate the number of items
1177 1178 1179 1180
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.
</code>
1181

1182
<h3 id="Channel_types">Channel types</h3>
1183

Rob Pike's avatar
Rob Pike committed
1184
<p>
1185
A channel provides a mechanism for two concurrently executing functions
Rob Pike's avatar
Rob Pike committed
1186
to synchronize execution and communicate by passing a value of a
1187
specified element type.
1188
The value of an uninitialized channel is <code>nil</code>.
Rob Pike's avatar
Rob Pike committed
1189
</p>
1190

1191
<pre class="ebnf">
1192
ChannelType = ( "chan" [ "&lt;-" ] | "&lt;-" "chan" ) ElementType .
1193
</pre>
1194

1195
<p>
1196 1197 1198 1199 1200
The <code>&lt;-</code> operator specifies the channel <i>direction</i>,
<i>send</i> or <i>receive</i>. If no direction is given, the channel is
<i>bi-directional</i>.
A channel may be constrained only to send or only to receive by
<a href="#Conversions">conversion</a> or <a href="#Assignments">assignment</a>.
1201 1202 1203
</p>

<pre>
1204
chan T         // can be used to send and receive values of type T
1205
chan&lt;- float64 // can only be used to send float64s
1206
&lt;-chan int     // can only be used to receive ints
1207 1208
</pre>

Rob Pike's avatar
Rob Pike committed
1209
<p>
1210 1211
The <code>&lt;-</code> operator associates with the leftmost <code>chan</code>
possible:
Rob Pike's avatar
Rob Pike committed
1212
</p>
1213

1214
<pre>
1215 1216 1217 1218
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)
chan (&lt;-chan int)
1219
</pre>
1220

Rob Pike's avatar
Rob Pike committed
1221
<p>
1222
A new, initialized channel
1223 1224
value can be made using the built-in function
<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
1225
which takes the channel type and an optional capacity as arguments:
Rob Pike's avatar
Rob Pike committed
1226
</p>
1227

1228
<pre>
1229
make(chan int, 100)
1230
</pre>
1231

Rob Pike's avatar
Rob Pike committed
1232 1233
<p>
The capacity, in number of elements, sets the size of the buffer in the channel. If the
1234 1235 1236 1237 1238
capacity is greater than zero, the channel is asynchronous: communication operations 
succeed without blocking if the buffer is not full (sends) or not empty (receives),
and elements are received in the order they are sent.
If the capacity is zero or absent, the communication succeeds only when both a sender and
receiver are ready.
1239
A <code>nil</code> channel is never ready for communication.
Rob Pike's avatar
Rob Pike committed
1240
</p>
1241

1242
<p>
1243 1244 1245 1246 1247
A channel may be closed with the built-in function
<a href="#Close"><code>close</code></a>; the
multi-valued assignment form of the
<a href="#Receive_operator">receive operator</a>
tests whether a channel has been closed.
1248 1249
</p>

1250
<h2 id="Properties_of_types_and_values">Properties of types and values</h2>
1251

1252 1253
<h3 id="Type_identity">Type identity</h3>

1254
<p>
1255
Two types are either <i>identical</i> or <i>different</i>.
1256
</p>
1257

1258
<p>
1259
Two named types are identical if their type names originate in the same
1260
type <a href="#Declarations_and_scope">declaration</a>.
1261
A named and an unnamed type are always different. Two unnamed types are identical
1262
if the corresponding type literals are identical, that is, if they have the same
1263
literal structure and corresponding components have identical types. In detail:
1264
</p>
Rob Pike's avatar
Rob Pike committed
1265

1266
<ul>
1267 1268
	<li>Two array types are identical if they have identical element types and
	    the same array length.</li>
1269

1270
	<li>Two slice types are identical if they have identical element types.</li>
1271

1272
	<li>Two struct types are identical if they have the same sequence of fields,
1273 1274
	    and if corresponding fields have the same names, and identical types,
	    and identical tags.
1275 1276
	    Two anonymous fields are considered to have the same name. Lower-case field
	    names from different packages are always different.</li>
1277

1278
	<li>Two pointer types are identical if they have identical base types.</li>
1279

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

1285
	<li>Two interface types are identical if they have the same set of methods
1286 1287
	    with the same names and identical function types. Lower-case method names from
	    different packages are always different. The order of the methods is irrelevant.</li>
1288

1289
	<li>Two map types are identical if they have identical key and value types.</li>
1290

1291 1292
	<li>Two channel types are identical if they have identical value types and
	    the same direction.</li>
1293 1294 1295
</ul>

<p>
Rob Pike's avatar
Rob Pike committed
1296 1297
Given the declarations
</p>
1298 1299 1300

<pre>
type (
1301 1302 1303 1304
	T0 []string
	T1 []string
	T2 struct { a, b int }
	T3 struct { a, c int }
1305 1306
	T4 func(int, float64) *T0
	T5 func(x int, y float64) *[]string
1307
)
1308
</pre>
1309

Rob Pike's avatar
Rob Pike committed
1310
<p>
1311
these types are identical:
Rob Pike's avatar
Rob Pike committed
1312
</p>
1313

1314
<pre>
1315
T0 and T0
1316 1317
[]int and []int
struct { a, b *T5 } and struct { a, b *T5 }
1318
func(x int, y float64) *[]string and func(int, float64) (result *[]string)
1319
</pre>
1320

Rob Pike's avatar
Rob Pike committed
1321
<p>
1322
<code>T0</code> and <code>T1</code> are different because they are named types
1323 1324
with distinct declarations; <code>func(int, float64) *T0</code> and
<code>func(x int, y float64) *[]string</code> are different because <code>T0</code>
1325
is different from <code>[]string</code>.
Rob Pike's avatar
Rob Pike committed
1326
</p>
1327 1328


1329
<h3 id="Assignability">Assignability</h3>
Rob Pike's avatar
Rob Pike committed
1330 1331

<p>
1332 1333
A value <code>x</code> is <i>assignable</i> to a variable of type <code>T</code>
("<code>x</code> is assignable to <code>T</code>") in any of these cases:
Rob Pike's avatar
Rob Pike committed
1334
</p>
1335

Rob Pike's avatar
Rob Pike committed
1336 1337
<ul>
<li>
1338 1339 1340
<code>x</code>'s type is identical to <code>T</code>.
</li>
<li>
1341 1342 1343
<code>x</code>'s type <code>V</code> and <code>T</code> have identical
<a href="#Types">underlying types</a> and at least one of <code>V</code>
or <code>T</code> is not a named type.
Robert Griesemer's avatar
Robert Griesemer committed
1344 1345
</li>
<li>
1346
<code>T</code> is an interface type and
1347 1348 1349 1350 1351
<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,
1352
and at least one of <code>V</code> or <code>T</code> is not a named type.
Rob Pike's avatar
Rob Pike committed
1353 1354
</li>
<li>
1355 1356 1357 1358 1359 1360
<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
is a pointer, function, slice, map, channel, or interface type.
</li>
<li>
<code>x</code> is an untyped <a href="#Constants">constant</a> representable
by a value of type <code>T</code>.
Robert Griesemer's avatar
Robert Griesemer committed
1361
</li>
Rob Pike's avatar
Rob Pike committed
1362 1363
</ul>

1364
<p>
1365 1366 1367
If <code>T</code> is a struct type with non-<a href="#Exported_identifiers">exported</a>
fields, the assignment must be in the same package in which <code>T</code> is declared,
or <code>x</code> must be the receiver of a method call.
1368
In other words, a struct value can be assigned to a struct variable only if
1369 1370
every field of the struct may be legally assigned individually by the program,
or if the assignment is initializing the receiver of a method of the struct type.
1371 1372
</p>

1373 1374 1375 1376
<p>
Any value may be assigned to the <a href="#Blank_identifier">blank identifier</a>.
</p>

1377

1378
<h2 id="Blocks">Blocks</h2>
Robert Griesemer's avatar
Robert Griesemer committed
1379 1380 1381 1382 1383 1384 1385

<p>
A <i>block</i> is a sequence of declarations and statements within matching
brace brackets.
</p>

<pre class="ebnf">
1386
Block = "{" { Statement ";" } "}" .
Robert Griesemer's avatar
Robert Griesemer committed
1387 1388 1389 1390 1391 1392 1393 1394 1395
</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
1396
	<li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
Robert Griesemer's avatar
Robert Griesemer committed
1397 1398 1399 1400 1401 1402 1403 1404
	    Go source text for that package.</li>

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

	<li>Each <code>if</code>, <code>for</code>, and <code>switch</code>
	    statement is considered to be in its own implicit block.</li>

Russ Cox's avatar
Russ Cox committed
1405
	<li>Each clause in a <code>switch</code> or <code>select</code> statement
Robert Griesemer's avatar
Robert Griesemer committed
1406 1407 1408 1409
	    acts as an implicit block.</li>
</ol>

<p>
Robert Griesemer's avatar
Robert Griesemer committed
1410
Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
Robert Griesemer's avatar
Robert Griesemer committed
1411 1412 1413
</p>


1414
<h2 id="Declarations_and_scope">Declarations and scope</h2>
1415 1416

<p>
Robert Griesemer's avatar
Robert Griesemer committed
1417 1418
A declaration binds a non-<a href="#Blank_identifier">blank</a>
identifier to a constant, type, variable, function, or package.
1419
Every identifier in a program must be declared.
Robert Griesemer's avatar
Robert Griesemer committed
1420 1421
No identifier may be declared twice in the same block, and
no identifier may be declared in both the file and package block.
1422
</p>
1423

1424
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
1425 1426
Declaration   = ConstDecl | TypeDecl | VarDecl .
TopLevelDecl  = Declaration | FunctionDecl | MethodDecl .
1427
</pre>
1428

1429
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1430 1431
The <i>scope</i> of a declared identifier is the extent of source text in which
the identifier denotes the specified constant, type, variable, function, or package.
1432
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1433

1434
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1435
Go is lexically scoped using blocks:
1436
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1437

1438
<ol>
Robert Griesemer's avatar
Robert Griesemer committed
1439 1440 1441
	<li>The scope of a predeclared identifier is the universe block.</li>

	<li>The scope of an identifier denoting a constant, type, variable,
1442 1443
	    or function (but not method) declared at top level (outside any
	    function) is the package block.</li>
Robert Griesemer's avatar
Robert Griesemer committed
1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455

	<li>The scope of an imported package identifier is the file block
	    of the file containing the import declaration.</li>

	<li>The scope of an identifier denoting a function parameter or
	    result variable is the function body.</li>

	<li>The scope of a constant or variable identifier declared
	    inside a function begins at the end of the ConstSpec or VarSpec
	    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
1456
	    begins at the identifier in the TypeSpec
Robert Griesemer's avatar
Robert Griesemer committed
1457
	    and ends at the end of the innermost containing block.</li>
1458
</ol>
1459

1460
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1461 1462 1463
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.
1464
</p>
1465

Robert Griesemer's avatar
Robert Griesemer committed
1466
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1467
The <a href="#Package_clause">package clause</a> is not a declaration; the package name
Robert Griesemer's avatar
Robert Griesemer committed
1468
does not appear in any scope. Its purpose is to identify the files belonging
1469
to the same <a href="#Packages">package</a> and to specify the default package name for import
Robert Griesemer's avatar
Robert Griesemer committed
1470 1471
declarations.
</p>
1472 1473


1474
<h3 id="Label_scopes">Label scopes</h3>
1475

Robert Griesemer's avatar
Robert Griesemer committed
1476
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1477
Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
Robert Griesemer's avatar
Robert Griesemer committed
1478
used in the <code>break</code>, <code>continue</code>, and <code>goto</code>
1479
statements (§<a href="#Break_statements">Break statements</a>, §<a href="#Continue_statements">Continue statements</a>, §<a href="#Goto_statements">Goto statements</a>).
Russ Cox's avatar
Russ Cox committed
1480
It is illegal to define a label that is never used.
Robert Griesemer's avatar
Robert Griesemer committed
1481 1482 1483 1484 1485
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>
1486 1487


1488
<h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
1489

1490
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1491
The following identifiers are implicitly declared in the universe block:
1492 1493 1494
</p>
<pre class="grammar">
Basic types:
1495 1496
	bool byte complex64 complex128 float32 float64
	int8 int16 int32 int64 string uint8 uint16 uint32 uint64
1497

Rob Pike's avatar
Rob Pike committed
1498
Architecture-specific convenience types:
1499
	int uint uintptr
1500

1501
Constants:
1502 1503 1504 1505
	true false iota

Zero value:
	nil
1506

1507
Functions:
1508
	append cap close complex copy imag len
Robert Griesemer's avatar
Robert Griesemer committed
1509
	make new panic print println real recover
1510
</pre>
1511

1512

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

1515
<p>
1516 1517 1518
An identifier may be <i>exported</i> to permit access to it from another package
using a <a href="#Qualified_identifiers">qualified identifier</a>. An identifier
is exported if both:
1519 1520
</p>
<ol>
1521
	<li>the first character of the identifier's name is a Unicode upper case letter (Unicode class "Lu"); and</li>
Rob Pike's avatar
Rob Pike committed
1522
	<li>the identifier is declared in the <a href="#Blocks">package block</a> or denotes a field or method of a type
1523
	    declared in that block.</li>
1524
</ol>
1525
<p>
1526
All other identifiers are not exported.
1527
</p>
1528

1529

Robert Griesemer's avatar
Robert Griesemer committed
1530 1531 1532 1533 1534 1535 1536 1537
<h3 id="Blank_identifier">Blank identifier</h3>

<p>
The <i>blank identifier</i>, represented by the underscore character <code>_</code>, may be used in a declaration like
any other identifier but the declaration does not introduce a new binding.
</p>


1538
<h3 id="Constant_declarations">Constant declarations</h3>
1539

1540 1541
<p>
A constant declaration binds a list of identifiers (the names of
Robert Griesemer's avatar
Robert Griesemer committed
1542 1543 1544 1545
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
1546 1547
right.
</p>
1548

1549
<pre class="ebnf">
1550
ConstDecl      = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
1551
ConstSpec      = IdentifierList [ [ Type ] "=" ExpressionList ] .
1552

1553 1554
IdentifierList = identifier { "," identifier } .
ExpressionList = Expression { "," Expression } .
1555
</pre>
1556

1557
<p>
1558
If the type is present, all constants take the type specified, and
1559
the expressions must be <a href="#Assignability">assignable</a> to that type.
1560
If the type is omitted, the constants take the
1561 1562 1563 1564 1565 1566
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.
1567
</p>
1568

1569
<pre>
1570
const Pi float64 = 3.14159265358979323846
1571
const zero = 0.0             // untyped floating-point constant
1572
const (
1573 1574
	size int64 = 1024
	eof = -1             // untyped integer constant
1575
)
1576
const a, b, c = 3, 4, "foo"  // a = 3, b = 4, c = "foo", untyped integer and string constants
1577
const u, v float32 = 0, 3    // u = 0.0, v = 3.0
1578
</pre>
1579

1580 1581 1582 1583
<p>
Within a parenthesized <code>const</code> declaration list the
expression list may be omitted from any but the first declaration.
Such an empty list is equivalent to the textual substitution of the
Rob Pike's avatar
Rob Pike committed
1584
first preceding non-empty expression list and its type if any.
1585 1586 1587
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
1588 1589
Together with the <a href="#Iota"><code>iota</code> constant generator</a>
this mechanism permits light-weight declaration of sequential values:
1590
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1591

1592
<pre>
1593
const (
1594 1595 1596 1597 1598 1599 1600 1601
	Sunday = iota
	Monday
	Tuesday
	Wednesday
	Thursday
	Friday
	Partyday
	numberOfDays  // this constant is not exported
1602
)
1603
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
1604 1605


1606
<h3 id="Iota">Iota</h3>
1607

1608
<p>
1609
Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
1610 1611
<code>iota</code> represents successive untyped integer <a href="#Constants">
constants</a>. It is reset to 0 whenever the reserved word <code>const</code>
1612 1613
appears in the source and increments after each <a href="#ConstSpec">ConstSpec</a>.
It can be used to construct a set of related constants:
1614
</p>
1615

1616
<pre>
Robert Griesemer's avatar
Robert Griesemer committed
1617
const (  // iota is reset to 0
1618 1619 1620
	c0 = iota  // c0 == 0
	c1 = iota  // c1 == 1
	c2 = iota  // c2 == 2
1621 1622 1623
)

const (
1624 1625 1626
	a = 1 &lt;&lt; iota  // a == 1 (iota has been reset)
	b = 1 &lt;&lt; iota  // b == 2
	c = 1 &lt;&lt; iota  // c == 4
1627 1628 1629
)

const (
1630 1631 1632
	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)
1633 1634
)

1635 1636
const x = iota  // x == 0 (iota has been reset)
const y = iota  // y == 0 (iota has been reset)
1637
</pre>
1638

1639
<p>
1640
Within an ExpressionList, the value of each <code>iota</code> is the same because
1641
it is only incremented after each ConstSpec:
1642
</p>
1643

1644
<pre>
1645
const (
1646 1647 1648 1649
	bit0, mask0 = 1 &lt;&lt; iota, 1 &lt;&lt; iota - 1  // bit0 == 1, mask0 == 0
	bit1, mask1                             // bit1 == 2, mask1 == 1
	_, _                                    // skips iota == 2
	bit3, mask3                             // bit3 == 8, mask3 == 7
1650
)
1651
</pre>
1652

1653
<p>
1654 1655 1656
This last example exploits the implicit repetition of the
last non-empty expression list.
</p>
1657 1658


1659
<h3 id="Type_declarations">Type declarations</h3>
1660

1661
<p>
1662
A type declaration binds an identifier, the <i>type name</i>, to a new type
1663 1664 1665
that has the same <a href="#Types">underlying type</a> as
an existing type.  The new type is <a href="#Type_identity">different</a> from
the existing type.
1666
</p>
1667

1668
<pre class="ebnf">
1669
TypeDecl     = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
1670
TypeSpec     = identifier Type .
1671
</pre>
1672

1673
<pre>
1674
type IntArray [16]int
1675

1676
type (
1677
	Point struct { x, y float64 }
1678 1679
	Polar Point
)
1680

1681
type TreeNode struct {
1682 1683
	left, right *TreeNode
	value *Comparable
1684 1685
}

Rob Pike's avatar
Rob Pike committed
1686
type Cipher interface {
1687 1688 1689
	BlockSize() int
	Encrypt(src, dst []byte)
	Decrypt(src, dst []byte)
1690
}
1691
</pre>
1692

1693 1694
<p>
The declared type does not inherit any <a href="#Method_declarations">methods</a>
1695
bound to the existing type, but the <a href="#Method_sets">method set</a>
1696
of an interface type or of elements of a composite type remains unchanged:
1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707
</p>

<pre>
// A Mutex is a data type with two methods Lock and Unlock.
type Mutex struct         { /* Mutex fields */ }
func (m *Mutex) Lock()    { /* Lock implementation */ }
func (m *Mutex) Unlock()  { /* Unlock implementation */ }

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

1708 1709 1710 1711
// The method set of the <a href="#Pointer_types">base type</a> of PtrMutex remains unchanged,
// but the method set of PtrMutex is empty.
type PtrMutex *Mutex

1712
// The method set of *PrintableMutex contains the methods
1713
// Lock and Unlock bound to its anonymous field Mutex.
1714
type PrintableMutex struct {
1715
	Mutex
1716
}
1717

1718
// MyCipher is an interface type that has the same method set as Cipher.
1719
type MyCipher Cipher
1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730
</pre>

<p>
A type declaration may be used to define a different boolean, numeric, or string
type and attach methods to it:
</p>

<pre>
type TimeZone int

const (
1731 1732 1733 1734
	EST TimeZone = -(5 + iota)
	CST
	MST
	PST
1735 1736 1737
)

func (tz TimeZone) String() string {
1738
	return fmt.Sprintf("GMT+%dh", tz)
1739 1740 1741 1742
}
</pre>


1743
<h3 id="Variable_declarations">Variable declarations</h3>
1744 1745 1746 1747 1748

<p>
A variable declaration creates a variable, binds an identifier to it and
gives it a type and optionally an initial value.
</p>
1749
<pre class="ebnf">
1750
VarDecl     = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
1751
VarSpec     = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
1752
</pre>
1753

1754
<pre>
1755
var i int
1756
var U, V, W float64
1757
var k = 0
1758
var x, y float32 = -1, -2
1759
var (
1760
	i int
1761 1762
	u, v, s = 2.0, 3.0, "bar"
)
Robert Griesemer's avatar
Robert Griesemer committed
1763
var re, im = complexSqrt(-1)
1764
var _, found = entries[name]  // map lookup; only interested in "found"
1765
</pre>
1766

1767
<p>
1768
If a list of expressions is given, the variables are initialized
Rob Pike's avatar
Rob Pike committed
1769 1770
by assigning the expressions to the variables (§<a href="#Assignments">Assignments</a>)
in order; all expressions must be consumed and all variables initialized from them.
1771
Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
1772
</p>
1773

1774
<p>
1775 1776 1777
If the type is present, each variable is given that type.
Otherwise, the types are deduced from the assignment
of the expression list.
1778
</p>
1779

1780
<p>
1781 1782
If the type is absent and the corresponding expression evaluates to an
untyped <a href="#Constants">constant</a>, the type of the declared variable
1783
is <code>bool</code>, <code>int</code>, <code>float64</code>, or <code>string</code>
1784 1785
respectively, depending on whether the value is a boolean, integer,
floating-point, or string constant:
1786
</p>
1787

1788
<pre>
1789
var b = true    // t has type bool
1790
var i = 0       // i has type int
1791
var f = 3.0     // f has type float64
1792
var s = "OMDB"  // s has type string
1793
</pre>
1794

1795
<h3 id="Short_variable_declarations">Short variable declarations</h3>
1796

1797
<p>
1798
A <i>short variable declaration</i> uses the syntax:
1799
</p>
1800

1801
<pre class="ebnf">
1802
ShortVarDecl = IdentifierList ":=" ExpressionList .
1803
</pre>
1804

1805
<p>
1806 1807
It is a shorthand for a regular variable declaration with
initializer expressions but no types:
1808
</p>
1809

1810 1811
<pre class="grammar">
"var" IdentifierList = ExpressionList .
1812
</pre>
1813

1814
<pre>
1815 1816 1817 1818 1819
i, j := 0, 10
f := func() int { return 7 }
ch := make(chan int)
r, w := os.Pipe(fd)  // os.Pipe() returns two values
_, y, _ := coord(p)  // coord() returns three values; only interested in y coordinate
1820
</pre>
1821

Rob Pike's avatar
Rob Pike committed
1822
<p>
1823
Unlike regular variable declarations, a short variable declaration may redeclare variables provided they
Rob Pike's avatar
Rob Pike committed
1824
were originally declared in the same block with the same type, and at
Robert Griesemer's avatar
Robert Griesemer committed
1825
least one of the non-<a href="#Blank_identifier">blank</a> variables is new.  As a consequence, redeclaration
Rob Pike's avatar
Rob Pike committed
1826 1827 1828 1829 1830 1831
can only appear in a multi-variable short declaration.
Redeclaration does not introduce a new
variable; it just assigns a new value to the original.
</p>

<pre>
1832 1833
field1, offset := nextField(str, 0)
field2, offset := nextField(str, offset)  // redeclares offset
Rob Pike's avatar
Rob Pike committed
1834 1835
</pre>

Rob Pike's avatar
Rob Pike committed
1836
<p>
1837 1838 1839
Short variable declarations may appear only inside functions.
In some contexts such as the initializers for <code>if</code>,
<code>for</code>, or <code>switch</code> statements,
1840
they can be used to declare local temporary variables (§<a href="#Statements">Statements</a>).
Rob Pike's avatar
Rob Pike committed
1841
</p>
1842

1843
<h3 id="Function_declarations">Function declarations</h3>
1844

1845
<p>
1846
A function declaration binds an identifier to a function (§<a href="#Function_types">Function types</a>).
1847
</p>
1848

1849
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
1850
FunctionDecl = "func" identifier Signature [ Body ] .
1851
Body         = Block .
1852
</pre>
1853

1854 1855 1856 1857 1858
<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>

1859 1860 1861
<pre>
func min(x int, y int) int {
	if x &lt; y {
1862
		return x
1863
	}
1864
	return y
1865
}
1866 1867

func flushICache(begin, end uintptr)  // implemented externally
1868
</pre>
1869

1870
<h3 id="Method_declarations">Method declarations</h3>
1871

1872
<p>
1873 1874
A method is a function with a <i>receiver</i>.
A method declaration binds an identifier to a method.
Rob Pike's avatar
Rob Pike committed
1875
</p>
1876
<pre class="ebnf">
1877 1878
MethodDecl   = "func" Receiver MethodName Signature [ Body ] .
Receiver     = "(" [ identifier ] [ "*" ] BaseTypeName ")" .
1879
BaseTypeName = identifier .
1880 1881
</pre>

1882
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1883 1884 1885 1886
The receiver type must be of the form <code>T</code> or <code>*T</code> where
<code>T</code> is a type name. <code>T</code> is called the
<i>receiver base type</i> or just <i>base type</i>.
The base type must not be a pointer or interface type and must be
1887
declared in the same package as the method.
1888 1889
The method is said to be <i>bound</i> to the base type
and is visible only within selectors for that type
1890
<a href="#Type_declarations">Type declarations</a>, §<a href="#Selectors">Selectors</a>).
Rob Pike's avatar
Rob Pike committed
1891
</p>
1892

1893 1894 1895
<p>
Given type <code>Point</code>, the declarations
</p>
1896

1897
<pre>
1898 1899
func (p *Point) Length() float64 {
	return math.Sqrt(p.x * p.x + p.y * p.y)
1900
}
1901

1902 1903 1904
func (p *Point) Scale(factor float64) {
	p.x *= factor
	p.y *= factor
1905 1906
}
</pre>
1907

1908
<p>
Rob Pike's avatar
Rob Pike committed
1909 1910
bind the methods <code>Length</code> and <code>Scale</code>,
with receiver type <code>*Point</code>,
1911 1912
to the base type <code>Point</code>.
</p>
1913

1914
<p>
1915
If the receiver's value is not referenced inside the body of the method,
1916 1917 1918
its identifier may be omitted in the declaration. The same applies in
general to parameters of functions and methods.
</p>
1919

Rob Pike's avatar
Rob Pike committed
1920 1921 1922 1923 1924 1925
<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>
1926
func(p *Point, factor float64)
Rob Pike's avatar
Rob Pike committed
1927 1928 1929 1930 1931 1932
</pre>

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

1933

1934
<h2 id="Expressions">Expressions</h2>
1935

1936
<p>
Rob Pike's avatar
Rob Pike committed
1937
An expression specifies the computation of a value by applying
1938
operators and functions to operands.
Rob Pike's avatar
Rob Pike committed
1939
</p>
1940

1941
<h3 id="Operands">Operands</h3>
1942

1943
<p>
1944
Operands denote the elementary values in an expression.
1945
</p>
1946

1947
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
1948
Operand    = Literal | QualifiedIdent | MethodExpr | "(" Expression ")" .
Rob Pike's avatar
Rob Pike committed
1949
Literal    = BasicLit | CompositeLit | FunctionLit .
Rob Pike's avatar
Rob Pike committed
1950
BasicLit   = int_lit | float_lit | imaginary_lit | char_lit | string_lit .
1951
</pre>
1952 1953


1954
<h3 id="Qualified_identifiers">Qualified identifiers</h3>
1955

1956
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1957
A qualified identifier is a non-<a href="#Blank_identifier">blank</a> identifier qualified by a package name prefix.
Rob Pike's avatar
Rob Pike committed
1958
</p>
1959

1960
<pre class="ebnf">
Russ Cox's avatar
Russ Cox committed
1961
QualifiedIdent = [ PackageName "." ] identifier .
1962
</pre>
1963

Rob Pike's avatar
Rob Pike committed
1964
<p>
1965 1966 1967
A qualified identifier accesses an identifier in a separate package.
The identifier must be <a href="#Exported_identifiers">exported</a> by that
package, which means that it must begin with a Unicode upper case letter.
Rob Pike's avatar
Rob Pike committed
1968 1969 1970
</p>

<pre>
Rob Pike's avatar
Rob Pike committed
1971
math.Sin
Rob Pike's avatar
Rob Pike committed
1972
</pre>
1973

1974
<!--
Robert Griesemer's avatar
Robert Griesemer committed
1975
<p>
Robert Griesemer's avatar
Robert Griesemer committed
1976
<span class="alert">TODO: Unify this section with Selectors - it's the same syntax.</span>
Robert Griesemer's avatar
Robert Griesemer committed
1977
</p>
Rob Pike's avatar
Rob Pike committed
1978
-->
Robert Griesemer's avatar
Robert Griesemer committed
1979

1980
<h3 id="Composite_literals">Composite literals</h3>
1981

Rob Pike's avatar
Rob Pike committed
1982 1983 1984 1985
<p>
Composite literals construct values for structs, arrays, slices, and maps
and create a new value each time they are evaluated.
They consist of the type of the value
1986 1987
followed by a brace-bound list of composite elements. An element may be
a single expression or a key-value pair.
Rob Pike's avatar
Rob Pike committed
1988
</p>
Robert Griesemer's avatar
Robert Griesemer committed
1989

1990
<pre class="ebnf">
1991
CompositeLit  = LiteralType LiteralValue .
Rob Pike's avatar
Rob Pike committed
1992
LiteralType   = StructType | ArrayType | "[" "..." "]" ElementType |
1993
                SliceType | MapType | TypeName .
1994
LiteralValue  = "{" [ ElementList [ "," ] ] "}" .
1995
ElementList   = Element { "," Element } .
1996
Element       = [ Key ":" ] Value .
1997
Key           = FieldName | ElementIndex .
Rob Pike's avatar
Rob Pike committed
1998
FieldName     = identifier .
1999
ElementIndex  = Expression .
2000
Value         = Expression | LiteralValue .
2001
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2002

Rob Pike's avatar
Rob Pike committed
2003
<p>
2004 2005 2006
The LiteralType must be a struct, array, slice, or map type
(the grammar enforces this constraint except when the type is given
as a TypeName).
2007 2008
The types of the expressions must be <a href="#Assignability">assignable</a>
to the respective field, element, and key types of the LiteralType;
2009
there is no additional conversion.
2010
The key is interpreted as a field name for struct literals,
Rob Pike's avatar
Rob Pike committed
2011
an index expression for array and slice literals, and a key for map literals.
2012 2013 2014
For map literals, all elements must have a key. It is an error
to specify multiple elements with the same field name or
constant key value.
Rob Pike's avatar
Rob Pike committed
2015
</p>
2016

2017 2018
<p>
For struct literals the following rules apply:
2019
</p>
2020
<ul>
2021 2022
	<li>A key must be a field name declared in the LiteralType.
	</li>
Rob Pike's avatar
Rob Pike committed
2023
	<li>A literal that does not contain any keys must
2024 2025 2026 2027 2028
	    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>
Rob Pike's avatar
Rob Pike committed
2029
	<li>A literal that contains keys does not need to
2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043
	    have an element for each struct field. Omitted fields
	    get the zero value for that field.
	</li>
	<li>A literal may omit the element list; such a literal evaluates
		to the zero value for its type.
	</li>
	<li>It is an error to specify an element for a non-exported
	    field of a struct belonging to a different package.
	</li>
</ul>

<p>
Given the declarations
</p>
2044
<pre>
2045 2046
type Point3D struct { x, y, z float64 }
type Line struct { p, q Point3D }
2047
</pre>
2048

Rob Pike's avatar
Rob Pike committed
2049 2050 2051
<p>
one may write
</p>
2052

2053
<pre>
2054 2055
origin := Point3D{}                            // zero value for Point3D
line := Line{origin, Point3D{y: -4, z: 12.3}}  // zero value for line.q.x
2056 2057
</pre>

2058 2059 2060
<p>
For array and slice literals the following rules apply:
</p>
2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072
<ul>
	<li>Each element has an associated integer index marking
	    its position in the array.
	</li>
	<li>An element with a key uses the key as its index; the
	    key must be a constant integer expression.
	</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>

2073
<p>
2074
Taking the address of a composite literal (§<a href="#Address_operators">Address operators</a>)
2075
generates a pointer to a unique instance of the literal's value.
2076 2077
</p>
<pre>
2078
var pointer *Point3D = &amp;Point3D{y: 1000}
2079
</pre>
2080

Rob Pike's avatar
Rob Pike committed
2081
<p>
2082 2083
The length of an array literal is the length specified in the LiteralType.
If fewer elements than the length are provided in the literal, the missing
Rob Pike's avatar
Rob Pike committed
2084
elements are set to the zero value for the array element type.
2085 2086 2087
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
2088
</p>
2089

2090
<pre>
2091 2092 2093
buffer := [10]string{}               // len(buffer) == 10
intSet := [6]int{1, 2, 3, 5}         // len(intSet) == 6
days := [...]string{"Sat", "Sun"}    // len(days) == 2
2094
</pre>
2095

Rob Pike's avatar
Rob Pike committed
2096 2097
<p>
A slice literal describes the entire underlying array literal.
Rob Pike's avatar
Rob Pike committed
2098
Thus, the length and capacity of a slice literal are the maximum
2099
element index plus one. A slice literal has the form
Rob Pike's avatar
Rob Pike committed
2100
</p>
2101

2102
<pre>
2103
[]T{x1, x2, ... xn}
2104
</pre>
2105

Rob Pike's avatar
Rob Pike committed
2106 2107 2108
<p>
and is a shortcut for a slice operation applied to an array literal:
</p>
2109

2110
<pre>
2111
[n]T{x1, x2, ... xn}[0 : n]
2112
</pre>
2113

2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124
<p>
Within a composite literal of array, slice, or map type <code>T</code>,
elements that are themselves composite literals may elide the respective
literal type if it is identical to the element type of <code>T</code>.
</p>

<pre>
[...]Point{{1.5, -3.5}, {0, 0}}  // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
[][]int{{1, 2, 3}, {4, 5}}       // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
</pre>

2125 2126
<p>
A parsing ambiguity arises when a composite literal using the
2127 2128
TypeName form of the LiteralType appears between the
<a href="#Keywords">keyword</a> and the opening brace of the block of an
2129 2130
"if", "for", or "switch" statement, because the braces surrounding
the expressions in the literal are confused with those introducing
2131
the block of statements. To resolve the ambiguity in this rare case,
2132 2133 2134 2135 2136 2137 2138 2139 2140
the composite literal must appear within
parentheses.
</p>

<pre>
if x == (T{a,b,c}[i]) { ... }
if (x == T{a,b,c}[i]) { ... }
</pre>

2141 2142 2143 2144 2145 2146
<p>
Examples of valid array, slice, and map literals:
</p>

<pre>
// list of prime numbers
2147
primes := []int{2, 3, 5, 7, 9, 11, 13, 17, 19, 991}
2148 2149

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

2152 2153
// 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}
2154 2155

// frequencies in Hz for equal-tempered scale (A4 = 440Hz)
2156
noteFrequency := map[string]float32{
2157 2158 2159 2160 2161 2162
	"C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
	"G0": 24.50, "A0": 27.50, "B0": 30.87,
}
</pre>


2163
<h3 id="Function_literals">Function literals</h3>
2164

Rob Pike's avatar
Rob Pike committed
2165 2166 2167 2168
<p>
A function literal represents an anonymous function.
It consists of a specification of the function type and a function body.
</p>
2169

2170
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
2171
FunctionLit = FunctionType Body .
2172
</pre>
2173

2174
<pre>
2175
func(a, b int, z float64) bool { return a*b &lt; int(z) }
2176
</pre>
2177

Rob Pike's avatar
Rob Pike committed
2178 2179 2180
<p>
A function literal can be assigned to a variable or invoked directly.
</p>
2181

2182
<pre>
Rob Pike's avatar
Rob Pike committed
2183 2184
f := func(x, y int) int { return x + y }
func(ch chan int) { ch &lt;- ACK } (reply_chan)
2185
</pre>
2186

Rob Pike's avatar
Rob Pike committed
2187 2188
<p>
Function literals are <i>closures</i>: they may refer to variables
2189 2190
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
2191 2192
as they are accessible.
</p>
2193

2194

2195
<h3 id="Primary_expressions">Primary expressions</h3>
2196

2197 2198 2199 2200
<p>
Primary expressions are the operands for unary and binary expressions.
</p>

2201
<pre class="ebnf">
2202 2203
PrimaryExpr =
	Operand |
2204
	Conversion |
2205
	BuiltinCall |
2206 2207 2208
	PrimaryExpr Selector |
	PrimaryExpr Index |
	PrimaryExpr Slice |
2209
	PrimaryExpr TypeAssertion |
2210 2211
	PrimaryExpr Call .

2212 2213
Selector       = "." identifier .
Index          = "[" Expression "]" .
2214
Slice          = "[" [ Expression ] ":" [ Expression ] "]" .
2215
TypeAssertion  = "." "(" Type ")" .
Robert Griesemer's avatar
Robert Griesemer committed
2216 2217
Call           = "(" [ ArgumentList [ "," ] ] ")" .
ArgumentList   = ExpressionList [ "..." ] .
2218 2219 2220 2221 2222 2223 2224 2225
</pre>


<pre>
x
2
(s + ".txt")
f(3.1415, true)
2226
Point{1, 2}
2227 2228 2229
m["foo"]
s[i : j + 1]
obj.color
2230
math.Sin
2231 2232 2233 2234
f.p[i].x()
</pre>


2235
<h3 id="Selectors">Selectors</h3>
2236

Rob Pike's avatar
Rob Pike committed
2237
<p>
Robert Griesemer's avatar
Robert Griesemer committed
2238
A primary expression of the form
Rob Pike's avatar
Rob Pike committed
2239
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2240

2241 2242 2243
<pre>
x.f
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2244

2245
<p>
Rob Pike's avatar
Rob Pike committed
2246
denotes the field or method <code>f</code> of the value denoted by <code>x</code>
2247
(or sometimes <code>*x</code>; see below). The identifier <code>f</code>
Rob Pike's avatar
Rob Pike committed
2248
is called the (field or method)
Robert Griesemer's avatar
Robert Griesemer committed
2249
<i>selector</i>; it must not be the <a href="#Blank_identifier">blank identifier</a>.
Rob Pike's avatar
Rob Pike committed
2250 2251
The type of the expression is the type of <code>f</code>.
</p>
2252
<p>
Rob Pike's avatar
Rob Pike committed
2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264
A selector <code>f</code> may denote a field or method <code>f</code> of
a type <code>T</code>, or it may refer
to a field or method <code>f</code> of a nested anonymous field of
<code>T</code>.
The number of anonymous fields traversed
to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
The depth of a field or method <code>f</code>
declared in <code>T</code> is zero.
The depth of a field or method <code>f</code> declared in
an anonymous field <code>A</code> in <code>T</code> is the
depth of <code>f</code> in <code>A</code> plus one.
</p>
2265
<p>
2266
The following rules apply to selectors:
Rob Pike's avatar
Rob Pike committed
2267 2268 2269 2270 2271 2272 2273 2274 2275
</p>
<ol>
<li>
For a value <code>x</code> of type <code>T</code> or <code>*T</code>
where <code>T</code> is not an interface type,
<code>x.f</code> denotes the field or method at the shallowest depth
in <code>T</code> where there
is such an <code>f</code>.
If there is not exactly one <code>f</code> with shallowest depth, the selector
2276
expression is illegal.
Rob Pike's avatar
Rob Pike committed
2277 2278
</li>
<li>
2279
For a variable <code>x</code> of type <code>I</code>
Rob Pike's avatar
Rob Pike committed
2280 2281 2282 2283 2284 2285 2286
where <code>I</code> is an interface type,
<code>x.f</code> denotes the actual method with name <code>f</code> of the value assigned
to <code>x</code> if there is such a method.
If no value or <code>nil</code> was assigned to <code>x</code>, <code>x.f</code> is illegal.
</li>
<li>
In all other cases, <code>x.f</code> is illegal.
2287
</li>
Rob Pike's avatar
Rob Pike committed
2288
</ol>
2289
<p>
2290 2291 2292 2293
Selectors automatically dereference pointers to structs.
If <code>x</code> is a pointer to a struct, <code>x.y</code>
is shorthand for <code>(*x).y</code>; if the field <code>y</code>
is also a pointer to a struct, <code>x.y.z</code> is shorthand
Rob Pike's avatar
Rob Pike committed
2294
for <code>(*(*x).y).z</code>, and so on.
2295 2296
If <code>x</code> contains an anonymous field of type <code>*A</code>,
where <code>A</code> is also a struct type,
Rob Pike's avatar
Rob Pike committed
2297 2298
<code>x.f</code> is a shortcut for <code>(*x.A).f</code>.
</p>
2299
<p>
Rob Pike's avatar
Rob Pike committed
2300 2301
For example, given the declarations:
</p>
2302

2303 2304
<pre>
type T0 struct {
2305
	x int
2306
}
2307

2308
func (recv *T0) M0()
2309

2310
type T1 struct {
2311
	y int
2312
}
2313

2314
func (recv T1) M1()
2315

2316
type T2 struct {
2317 2318 2319
	z int
	T1
	*T0
2320
}
Robert Griesemer's avatar
Robert Griesemer committed
2321

2322
func (recv *T2) M2()
Robert Griesemer's avatar
Robert Griesemer committed
2323

2324
var p *T2  // with p != nil and p.T1 != nil
2325
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2326

Rob Pike's avatar
Rob Pike committed
2327 2328 2329
<p>
one may write:
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2330

2331 2332 2333 2334
<pre>
p.z         // (*p).z
p.y         // ((*p).T1).y
p.x         // (*(*p).T0).x
Robert Griesemer's avatar
Robert Griesemer committed
2335

2336 2337 2338 2339
p.M2        // (*p).M2
p.M1        // ((*p).T1).M1
p.M0        // ((*p).T0).M0
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2340 2341


2342
<!--
Robert Griesemer's avatar
Robert Griesemer committed
2343
<span class="alert">
2344
TODO: Specify what happens to receivers.
Robert Griesemer's avatar
Robert Griesemer committed
2345
</span>
Rob Pike's avatar
Rob Pike committed
2346
-->
Robert Griesemer's avatar
Robert Griesemer committed
2347

2348

2349
<h3 id="Indexes">Indexes</h3>
2350

Rob Pike's avatar
Rob Pike committed
2351
<p>
Robert Griesemer's avatar
Robert Griesemer committed
2352
A primary expression of the form
Rob Pike's avatar
Rob Pike committed
2353
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2354

2355 2356 2357
<pre>
a[x]
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2358

Rob Pike's avatar
Rob Pike committed
2359
<p>
Rob Pike's avatar
Rob Pike committed
2360
denotes the element of the array, slice, string or map <code>a</code> indexed by <code>x</code>.
Rob Pike's avatar
Rob Pike committed
2361
The value <code>x</code> is called the
Rob Pike's avatar
Rob Pike committed
2362
<i>index</i> or <i>map key</i>, respectively. The following
Robert Griesemer's avatar
Robert Griesemer committed
2363
rules apply:
Rob Pike's avatar
Rob Pike committed
2364
</p>
2365

2366
<p>
Rob Pike's avatar
Rob Pike committed
2367
For <code>a</code> of type <code>A</code> or <code>*A</code>
Robert Griesemer's avatar
Robert Griesemer committed
2368 2369
where <code>A</code> is an <a href="#Array_types">array type</a>,
or for <code>a</code> of type <code>S</code> where <code>S</code> is a <a href="#Slice_types">slice type</a>:
Rob Pike's avatar
Rob Pike committed
2370
</p>
2371
<ul>
2372
	<li><code>x</code> must be an integer value and <code>0 &lt;= x &lt; len(a)</code></li>
Rob Pike's avatar
Rob Pike committed
2373
	<li><code>a[x]</code> is the array element at index <code>x</code> and the type of
2374
	  <code>a[x]</code> is the element type of <code>A</code></li>
2375
	<li>if <code>a</code> is <code>nil</code> or if the index <code>x</code> is out of range,
2376
	a <a href="#Run_time_panics">run-time panic</a> occurs</li>
2377
</ul>
2378 2379 2380

<p>
For <code>a</code> of type <code>T</code>
2381
where <code>T</code> is a <a href="#String_types">string type</a>:
2382 2383
</p>
<ul>
2384
	<li><code>x</code> must be an integer value and <code>0 &lt;= x &lt; len(a)</code></li>
2385
	<li><code>a[x]</code> is the byte at index <code>x</code> and the type of
2386
	  <code>a[x]</code> is <code>byte</code></li>
2387
	<li><code>a[x]</code> may not be assigned to</li>
2388 2389
	<li>if the index <code>x</code> is out of range,
	a <a href="#Run_time_panics">run-time panic</a> occurs</li>
2390 2391
</ul>

2392
<p>
2393
For <code>a</code> of type <code>M</code>
Robert Griesemer's avatar
Robert Griesemer committed
2394
where <code>M</code> is a <a href="#Map_types">map type</a>:
Rob Pike's avatar
Rob Pike committed
2395
</p>
2396
<ul>
2397
	<li><code>x</code>'s type must be
2398 2399
	<a href="#Assignability">assignable</a>
	to the key type of <code>M</code></li>
2400 2401 2402
	<li>if the map contains an entry with key <code>x</code>,
	  <code>a[x]</code> is the map value with key <code>x</code>
	  and the type of <code>a[x]</code> is the value type of <code>M</code></li>
2403
	<li>if the map is <code>nil</code> or does not contain such an entry,
2404 2405
	  <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
	  for the value type of <code>M</code></li>
2406
</ul>
Robert Griesemer's avatar
Robert Griesemer committed
2407

2408
<p>
2409
Otherwise <code>a[x]</code> is illegal.
Rob Pike's avatar
Rob Pike committed
2410 2411 2412
</p>

<p>
2413 2414
An index expression on a map <code>a</code> of type <code>map[K]V</code>
may be used in an assignment or initialization of the special form
Rob Pike's avatar
Rob Pike committed
2415 2416 2417
</p>

<pre>
2418 2419 2420
v, ok = a[x]
v, ok := a[x]
var v, ok = a[x]
Rob Pike's avatar
Rob Pike committed
2421 2422 2423
</pre>

<p>
2424 2425 2426 2427 2428
where the result of the index expression is a pair of values with types
<code>(V, bool)</code>. In this form, the value of <code>ok</code> is
<code>true</code> if the key <code>x</code> is present in the map, and
<code>false</code> otherwise. The value of <code>v</code> is the value
<code>a[x]</code> as in the single-result form.
Rob Pike's avatar
Rob Pike committed
2429 2430 2431
</p>

<p>
2432
Similarly, if an assignment to a map element has the special form
Rob Pike's avatar
Rob Pike committed
2433
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2434

Rob Pike's avatar
Rob Pike committed
2435
<pre>
2436
a[x] = v, ok
Rob Pike's avatar
Rob Pike committed
2437 2438 2439 2440 2441 2442 2443 2444
</pre>

<p>
and boolean <code>ok</code> has the value <code>false</code>,
the entry for key <code>x</code> is deleted from the map; if
<code>ok</code> is <code>true</code>, the construct acts like
a regular assignment to an element of the map.
</p>
2445

2446 2447 2448 2449 2450
<p>
Assigning to an element of a <code>nil</code> map causes a
<a href="#Run_time_panics">run-time panic</a>.
</p>

2451

2452
<h3 id="Slices">Slices</h3>
2453

Rob Pike's avatar
Rob Pike committed
2454
<p>
2455
For a string, array, or slice <code>a</code>, the primary expression
Rob Pike's avatar
Rob Pike committed
2456
</p>
2457

2458
<pre>
2459
a[low : high]
2460
</pre>
2461

Rob Pike's avatar
Rob Pike committed
2462
<p>
2463 2464
constructs a substring or slice. The index expressions <code>low</code> and
<code>high</code> select which elements appear in the result. The result has
2465
indexes starting at 0 and length equal to
2466
<code>high</code>&nbsp;-&nbsp;<code>low</code>.
2467 2468 2469 2470
After slicing the array <code>a</code>
</p>

<pre>
2471 2472
a := [5]int{1, 2, 3, 4, 5}
s := a[1:4]
2473 2474 2475 2476
</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
2477
</p>
2478

2479 2480 2481
<pre>
s[0] == 2
s[1] == 3
2482
s[2] == 4
2483
</pre>
2484

Rob Pike's avatar
Rob Pike committed
2485
<p>
2486 2487 2488
For convenience, any of the index expressions may be omitted. A missing <code>low</code>
index defaults to zero; a missing <code>high</code> index defaults to the length of the
sliced operand:
2489 2490
</p>

2491 2492 2493 2494 2495 2496
<pre>
a[2:]	// same a[2 : len(a)]
a[:3]   // same as a[0 : 3]
a[:]    // same as a[0 : len(a)]
</pre>

2497 2498 2499 2500
<p>
For arrays or strings, the indexes <code>low</code> and <code>high</code> must
satisfy 0 &lt;= <code>low</code> &lt;= <code>high</code> &lt;= length; for
slices, the upper bound is the capacity rather than the length.
2501 2502
</p>

2503
<p>
2504 2505
If the sliced operand is a string or slice, the result of the slice operation
is a string or slice of the same type.
2506 2507
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
2508
</p>
2509 2510


2511
<h3 id="Type_assertions">Type assertions</h3>
2512

Rob Pike's avatar
Rob Pike committed
2513
<p>
2514 2515
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
2516
</p>
2517

2518 2519 2520
<pre>
x.(T)
</pre>
2521

2522
<p>
2523
asserts that <code>x</code> is not <code>nil</code>
Russ Cox's avatar
Russ Cox committed
2524
and that the value stored in <code>x</code> is of type <code>T</code>.
2525
The notation <code>x.(T)</code> is called a <i>type assertion</i>.
Rob Pike's avatar
Rob Pike committed
2526 2527
</p>
<p>
2528
More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
2529 2530
that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
to the type <code>T</code>.
2531
If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
Rob Pike's avatar
Rob Pike committed
2532
of <code>x</code> implements the interface <code>T</code><a href="#Interface_types">Interface types</a>).
Rob Pike's avatar
Rob Pike committed
2533
</p>
2534
<p>
2535
If the type assertion holds, the value of the expression is the value
2536 2537 2538
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>
2539
is known only at run-time, the type of <code>x.(T)</code> is
Rob Pike's avatar
Rob Pike committed
2540 2541
known to be <code>T</code> in a correct program.
</p>
2542
<p>
Rob Pike's avatar
Rob Pike committed
2543
If a type assertion is used in an assignment or initialization of the form
Rob Pike's avatar
Rob Pike committed
2544
</p>
2545

2546 2547 2548
<pre>
v, ok = x.(T)
v, ok := x.(T)
Rob Pike's avatar
Rob Pike committed
2549
var v, ok = x.(T)
2550
</pre>
2551

2552
<p>
2553 2554
the result of the assertion is a pair of values with types <code>(T, bool)</code>.
If the assertion holds, the expression returns the pair <code>(x.(T), true)</code>;
Rob Pike's avatar
Rob Pike committed
2555
otherwise, the expression returns <code>(Z, false)</code> where <code>Z</code>
Robert Griesemer's avatar
Robert Griesemer committed
2556
is the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
2557
No run-time panic occurs in this case.
2558
The type assertion in this construct thus acts like a function call
2559
returning a value and a boolean indicating success.  (§<a href="#Assignments">Assignments</a>)
Rob Pike's avatar
Rob Pike committed
2560
</p>
2561

2562

2563
<h3 id="Calls">Calls</h3>
2564

2565
<p>
Rob Pike's avatar
Rob Pike committed
2566 2567
Given an expression <code>f</code> of function type
<code>F</code>,
Rob Pike's avatar
Rob Pike committed
2568
</p>
2569

2570
<pre>
Rob Pike's avatar
Rob Pike committed
2571
f(a1, a2, ... an)
2572
</pre>
2573

2574
<p>
Rob Pike's avatar
Rob Pike committed
2575
calls <code>f</code> with arguments <code>a1, a2, ... an</code>.
2576
Except for one special case, arguments must be single-valued expressions
2577
<a href="#Assignability">assignable</a> to the parameter types of
Rob Pike's avatar
Rob Pike committed
2578 2579 2580 2581 2582 2583 2584
<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>
2585

2586
<pre>
2587
math.Atan2(x, y)    // function call
2588
var pt *Point
Rob Pike's avatar
Rob Pike committed
2589
pt.Scale(3.5)  // method call with receiver pt
2590
</pre>
2591

2592 2593
<p>
As a special case, if the return parameters of a function or method
2594 2595
<code>g</code> are equal in number and individually
assignable to the parameters of another function or method
2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606
<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
will invoke <code>f</code> after binding the return values of
<code>g</code> to the parameters of <code>f</code> in order.  The call
of <code>f</code> must contain no parameters other than the call of <code>g</code>.
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) {
2607
	return s[0:pos], s[pos:]
2608 2609 2610 2611 2612 2613 2614
}

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

if Join(Split(value, len(value)/2)) != value {
2615
	log.Panic("test fails")
2616 2617 2618
}
</pre>

Rob Pike's avatar
Rob Pike committed
2619
<p>
2620 2621
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
2622
argument list can be assigned to the parameter list of <code>m</code>.
Rob Pike's avatar
Rob Pike committed
2623
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
2624 2625
set contains <code>m</code>, <code>x.m()</code> is shorthand
for <code>(&amp;x).m()</code>:
Rob Pike's avatar
Rob Pike committed
2626
</p>
2627

2628
<pre>
2629
var p Point
Rob Pike's avatar
Rob Pike committed
2630
p.Scale(3.5)
2631
</pre>
2632

2633
<p>
2634
There is no distinct method type and there are no method literals.
Rob Pike's avatar
Rob Pike committed
2635
</p>
2636

2637
<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
2638

Rob Pike's avatar
Rob Pike committed
2639
<p>
Russ Cox's avatar
Russ Cox committed
2640 2641 2642 2643 2644
If <code>f</code> is variadic with final parameter type <code>...T</code>,
then within the function the argument is equivalent to a parameter of type
<code>[]T</code>.  At each call of <code>f</code>, the argument
passed to the final parameter is
a new slice of type <code>[]T</code> whose successive elements are
Robert Griesemer's avatar
Robert Griesemer committed
2645 2646 2647
the actual arguments, which all must be <a href="#Assignability">assignable</a>
to the type <code>T</code>. The length of the slice is therefore the number of
arguments bound to the final parameter and may differ for each call site.
2648
</p>
2649

Rob Pike's avatar
Rob Pike committed
2650
<p>
2651 2652 2653 2654 2655 2656 2657 2658
Given the function and call
</p>
<pre>
func Greeting(prefix string, who ... string)
Greeting("hello:", "Joe", "Anna", "Eileen")
</pre>

<p>
Robert Griesemer's avatar
Robert Griesemer committed
2659
within <code>Greeting</code>, <code>who</code> will have the value
Joe Poirier's avatar
Joe Poirier committed
2660
<code>[]string{"Joe", "Anna", "Eileen"}</code>
2661 2662
</p>

Robert Griesemer's avatar
Robert Griesemer committed
2663
<p>
2664 2665 2666
If the final argument is assignable to a slice type <code>[]T</code>, it may be
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
2667
</p>
2668 2669

<p>
Robert Griesemer's avatar
Robert Griesemer committed
2670
Given the slice <code>s</code> and call
2671
</p>
2672

Robert Griesemer's avatar
Robert Griesemer committed
2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683
<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>


2684
<h3 id="Operators">Operators</h3>
2685

Rob Pike's avatar
Rob Pike committed
2686
<p>
2687
Operators combine operands into expressions.
Rob Pike's avatar
Rob Pike committed
2688
</p>
2689

2690
<pre class="ebnf">
2691
Expression = UnaryExpr | Expression binary_op UnaryExpr .
Rob Pike's avatar
Rob Pike committed
2692
UnaryExpr  = PrimaryExpr | unary_op UnaryExpr .
2693

2694
binary_op  = "||" | "&amp;&amp;" | rel_op | add_op | mul_op .
Rob Pike's avatar
Rob Pike committed
2695 2696
rel_op     = "==" | "!=" | "&lt;" | "&lt;=" | ">" | ">=" .
add_op     = "+" | "-" | "|" | "^" .
2697
mul_op     = "*" | "/" | "%" | "&lt;&lt;" | "&gt;&gt;" | "&amp;" | "&amp;^" .
2698

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

2702
<p>
2703
Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
2704
For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
2705 2706 2707
unless the operation involves channels, shifts, or untyped <a href="#Constants">constants</a>.
For operations involving constants only, see the section on
<a href="#Constant_expressions">constant expressions</a>.
Rob Pike's avatar
Rob Pike committed
2708
</p>
2709

2710
<p>
2711
In a channel send, the first operand is always a channel and the second
2712 2713
must be a value <a href="#Assignability">assignable</a>
to the channel's element type.
2714
</p>
2715

2716 2717
<p>
Except for shift operations,
2718 2719 2720
if one operand is an untyped <a href="#Constants">constant</a>
and the other operand is not, the constant is <a href="#Conversions">converted</a>
to the type of the other operand.
2721
</p>
2722

2723 2724
<p>
The right operand in a shift operation must have unsigned integer type
2725
or be an untyped constant that can be converted to unsigned integer type.
2726
</p>
Rob Pike's avatar
Rob Pike committed
2727

2728
<p>
2729 2730 2731
If the left operand of a non-constant shift operation is an untyped constant,
the type of constant is what it would be if the shift operation were replaced by
the left operand alone.
2732
</p>
2733

2734
<pre>
2735
var s uint = 33
2736 2737 2738 2739 2740
var i = 1&lt;&lt;s            // 1 has type int
var j = int32(1&lt;&lt;s)     // 1 has type int32; j == 0
var u = uint64(1&lt;&lt;s)    // 1 has type uint64; u == 1&lt;&lt;33
var f = float32(1&lt;&lt;s)   // illegal: 1 has type float32, cannot shift
var g = float32(1&lt;&lt;33)  // legal; 1&lt;&lt;33 is a constant shift operation; g == 1&lt;&lt;33
2741
</pre>
2742

2743
<h3 id="Operator_precedence">Operator precedence</h3>
2744
<p>
Russ Cox's avatar
Russ Cox committed
2745 2746
Unary operators have the highest precedence.
As the  <code>++</code> and <code>--</code> operators form
Rob Pike's avatar
Rob Pike committed
2747
statements, not expressions, they fall
Russ Cox's avatar
Russ Cox committed
2748
outside the operator hierarchy.
Rob Pike's avatar
Rob Pike committed
2749 2750
As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
<p>
2751
There are five precedence levels for binary operators.
Rob Pike's avatar
Rob Pike committed
2752
Multiplication operators bind strongest, followed by addition
2753 2754
operators, comparison operators, <code>&amp;&amp;</code> (logical and),
and finally <code>||</code> (logical or):
Rob Pike's avatar
Rob Pike committed
2755
</p>
2756

Rob Pike's avatar
Rob Pike committed
2757
<pre class="grammar">
2758
Precedence    Operator
2759 2760
    5             *  /  %  &lt;&lt;  &gt;&gt;  &amp;  &amp;^
    4             +  -  |  ^
2761
    3             ==  !=  &lt;  &lt;=  &gt;  &gt;=
2762 2763 2764
    2             &amp;&amp;
    1             ||
</pre>
2765

Rob Pike's avatar
Rob Pike committed
2766
<p>
2767
Binary operators of the same precedence associate from left to right.
2768
For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
Rob Pike's avatar
Rob Pike committed
2769
</p>
2770

2771 2772 2773 2774
<pre>
+x
23 + 3*x[i]
x &lt;= f()
2775
^a &gt;&gt; b
2776
f() || g()
2777
x == y+1 &amp;&amp; &lt;-chan_ptr &gt; 0
2778
</pre>
2779 2780


2781
<h3 id="Arithmetic_operators">Arithmetic operators</h3>
2782
<p>
2783
Arithmetic operators apply to numeric values and yield a result of the same
Rob Pike's avatar
Rob Pike committed
2784
type as the first operand. The four standard arithmetic operators (<code>+</code>,
Rob Pike's avatar
Rob Pike committed
2785 2786
<code>-</code>,  <code>*</code>, <code>/</code>) apply to integer,
floating-point, and complex types; <code>+</code> also applies
2787
to strings. All other arithmetic operators apply to integers only.
Rob Pike's avatar
Rob Pike committed
2788
</p>
2789

Rob Pike's avatar
Rob Pike committed
2790
<pre class="grammar">
Rob Pike's avatar
Rob Pike committed
2791 2792 2793 2794
+    sum                    integers, floats, complex values, strings
-    difference             integers, floats, complex values
*    product                integers, floats, complex values
/    quotient               integers, floats, complex values
2795
%    remainder              integers
2796

2797 2798 2799 2800
&amp;    bitwise and            integers
|    bitwise or             integers
^    bitwise xor            integers
&amp;^   bit clear (and not)    integers
2801

2802 2803
&lt;&lt;   left shift             integer &lt;&lt; unsigned integer
&gt;&gt;   right shift            integer &gt;&gt; unsigned integer
2804
</pre>
2805

Rob Pike's avatar
Rob Pike committed
2806 2807 2808 2809
<p>
Strings can be concatenated using the <code>+</code> operator
or the <code>+=</code> assignment operator:
</p>
2810

2811
<pre>
2812 2813
s := "hi" + string(c)
s += " and good bye"
2814
</pre>
2815

2816
<p>
Rob Pike's avatar
Rob Pike committed
2817 2818 2819
String addition creates a new string by concatenating the operands.
</p>
<p>
2820 2821 2822
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
2823
</p>
2824

2825
<pre>
2826
x = q*y + r  and  |r| &lt; |y|
2827
</pre>
2828

Rob Pike's avatar
Rob Pike committed
2829
<p>
2830 2831
with <code>x / y</code> truncated towards zero
(<a href="http://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
Rob Pike's avatar
Rob Pike committed
2832
</p>
2833

2834 2835 2836 2837 2838 2839 2840
<pre>
 x     y     x / y     x % y
 5     3       1         2
-5     3      -1        -2
 5    -3      -1         2
-5    -3       1        -2
</pre>
2841

2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855
<p>
As an exception to this rule, 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>).
</p>

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

Rob Pike's avatar
Rob Pike committed
2856
<p>
2857
If the divisor is zero, a <a href="#Run_time_panics">run-time panic</a> occurs.
Rob Pike's avatar
Rob Pike committed
2858
If the dividend is positive and the divisor is a constant power of 2,
2859
the division may be replaced by a right shift, and computing the remainder may
2860
be replaced by a bitwise "and" operation:
Rob Pike's avatar
Rob Pike committed
2861
</p>
2862

2863
<pre>
2864
 x     x / 4     x % 4     x &gt;&gt; 2     x &amp; 3
2865 2866 2867
 11      2         3         2          3
-11     -2        -3        -3          1
</pre>
2868

Rob Pike's avatar
Rob Pike committed
2869
<p>
2870 2871
The shift operators shift the left operand by the shift count specified by the
right operand. They implement arithmetic shifts if the left operand is a signed
Rob Pike's avatar
Rob Pike committed
2872 2873 2874 2875
integer and logical shifts if it is an unsigned integer. The shift count must
be an unsigned integer. There is no upper limit on the shift count. Shifts behave
as if the left operand is shifted <code>n</code> times by 1 for a shift
count of <code>n</code>.
2876 2877
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
2878
<code>x/2</code> but truncated towards negative infinity.
Rob Pike's avatar
Rob Pike committed
2879
</p>
2880

Rob Pike's avatar
Rob Pike committed
2881 2882 2883
<p>
For integer operands, the unary operators
<code>+</code>, <code>-</code>, and <code>^</code> are defined as
Robert Griesemer's avatar
Robert Griesemer committed
2884
follows:
Rob Pike's avatar
Rob Pike committed
2885
</p>
2886

Rob Pike's avatar
Rob Pike committed
2887
<pre class="grammar">
2888 2889
+x                          is 0 + x
-x    negation              is 0 - x
Russ Cox's avatar
Russ Cox committed
2890 2891
^x    bitwise complement    is m ^ x  with m = "all bits set to 1" for unsigned x
                                      and  m = -1 for signed x
2892
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
2893

2894
<p>
2895
For floating-point numbers,
2896 2897
<code>+x</code> is the same as <code>x</code>,
while <code>-x</code> is the negation of <code>x</code>.
2898 2899 2900
The result of a floating-point 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.
2901
</p>
Robert Griesemer's avatar
Robert Griesemer committed
2902

2903
<h3 id="Integer_overflow">Integer overflow</h3>
Robert Griesemer's avatar
Robert Griesemer committed
2904

Rob Pike's avatar
Rob Pike committed
2905 2906 2907 2908 2909
<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
the unsigned integer's type
2910
<a href="#Numeric_types">Numeric types</a>). Loosely speaking, these unsigned integer operations
Robert Griesemer's avatar
Robert Griesemer committed
2911
discard high bits upon overflow, and programs may rely on ``wrap around''.
Rob Pike's avatar
Rob Pike committed
2912
</p>
2913
<p>
Rob Pike's avatar
Rob Pike committed
2914 2915
For signed integers, the operations <code>+</code>,
<code>-</code>, <code>*</code>, and <code>&lt;&lt;</code> may legally
Robert Griesemer's avatar
Robert Griesemer committed
2916 2917
overflow and the resulting value exists and is deterministically defined
by the signed integer representation, the operation, and its operands.
Rob Pike's avatar
Rob Pike committed
2918
No exception is raised as a result of overflow. A
Robert Griesemer's avatar
Robert Griesemer committed
2919
compiler may not optimize code under the assumption that overflow does
Rob Pike's avatar
Rob Pike committed
2920 2921
not occur. For instance, it may not assume that <code>x &lt; x + 1</code> is always true.
</p>
2922 2923


2924
<h3 id="Comparison_operators">Comparison operators</h3>
2925

Rob Pike's avatar
Rob Pike committed
2926
<p>
2927
Comparison operators compare two operands and yield a value of type <code>bool</code>.
Rob Pike's avatar
Rob Pike committed
2928
</p>
2929

Rob Pike's avatar
Rob Pike committed
2930
<pre class="grammar">
2931 2932
==    equal
!=    not equal
Anthony Martin's avatar
Anthony Martin committed
2933 2934
&lt;     less
&lt;=    less or equal
2935 2936 2937
>     greater
>=    greater or equal
</pre>
2938

Rob Pike's avatar
Rob Pike committed
2939
<p>
2940
The operands must be <i>comparable</i>; that is, the first operand
2941 2942
must be <a href="#Assignability">assignable</a>
to the type of the second operand, or vice versa.
Rob Pike's avatar
Rob Pike committed
2943
</p>
2944
<p>
2945 2946 2947 2948
The operators <code>==</code> and <code>!=</code> apply
to operands of all types except arrays and structs.
All other comparison operators apply only to integer, floating-point
and string values. The result of a comparison is defined as follows:
Rob Pike's avatar
Rob Pike committed
2949
</p>
2950

2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967
<ul>
	<li>
	Integer values are compared in the usual way.
	</li>
	<li>
	Floating point values are compared as defined by the IEEE-754
	standard.
	</li>
	<li>
	Two complex values <code>u</code>, <code>v</code> are
	equal if both <code>real(u) == real(v)</code> and
	<code>imag(u) == imag(v)</code>.
	</li>
	<li>
	String values are compared byte-wise (lexically).
	</li>
	<li>
2968
	Boolean values are equal if they are either both
2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987
	<code>true</code> or both <code>false</code>.
	</li>
	<li>
	Pointer values are equal if they point to the same location
	or if both are <code>nil</code>.
	</li>
	<li>
	Function values are equal if they refer to the same function
	or if both are <code>nil</code>.
	</li>
	<li>
	A slice value may only be compared to <code>nil</code>.
	</li>
	<li>
	Channel and map values are equal if they were created by the same call to <code>make</code>
<a href="#Making_slices_maps_and_channels">Making slices, maps, and channels</a>)
	or if both are <code>nil</code>.
	</li>
	<li>
2988
	Interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types and
2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004
	equal dynamic values or if both are <code>nil</code>.
	</li>
	<li>
	An interface value <code>x</code> is equal to a non-interface value
	<code>y</code> if the dynamic type of <code>x</code> is identical to
	the static type of <code>y</code> and the dynamic value of <code>x</code>
	is equal to <code>y</code>.
	</li>
	<li>
	A pointer, function, slice, channel, map, or interface value is equal
	to <code>nil</code> if it has been assigned the explicit value
	<code>nil</code>, if it is uninitialized, or if it has been assigned
	another value equal to <code>nil</code>.
	</li>
</ul>

3005

3006
<h3 id="Logical_operators">Logical operators</h3>
3007

Rob Pike's avatar
Rob Pike committed
3008
<p>
3009 3010
Logical operators apply to <a href="#Boolean_types">boolean</a> values
and yield a result of the same type as the operands.
3011
The right operand is evaluated conditionally.
Rob Pike's avatar
Rob Pike committed
3012
</p>
3013

Rob Pike's avatar
Rob Pike committed
3014
<pre class="grammar">
3015 3016 3017 3018
&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"
</pre>
3019 3020


3021
<h3 id="Address_operators">Address operators</h3>
3022

Rob Pike's avatar
Rob Pike committed
3023
<p>
3024 3025 3026
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>,
3027
that is, either a variable, pointer indirection, or slice indexing
3028
operation; or a field selector of an addressable struct operand;
3029
or an array indexing operation of an addressable array.
3030 3031 3032 3033 3034 3035 3036
As an exception to the addressability requirement, <code>x</code> may also be a
<a href="#Composite_literals">composite literal</a>.
</p>
<p>
For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
indirection <code>*x</code> denotes the value of type <code>T</code> pointed
to by <code>x</code>.
Rob Pike's avatar
Rob Pike committed
3037 3038 3039 3040 3041 3042 3043 3044 3045
</p>

<pre>
&amp;x
&amp;a[f(2)]
*p
*pf(x)
</pre>

Rob Pike's avatar
Rob Pike committed
3046

3047
<h3 id="Receive_operator">Receive operator</h3>
3048

Rob Pike's avatar
Rob Pike committed
3049
<p>
3050 3051 3052 3053
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
from the channel <code>ch</code>. The type of the value is the element type of
the channel. The expression blocks until a value is available.
3054
Receiving from a <code>nil</code> channel blocks forever.
Rob Pike's avatar
Rob Pike committed
3055
</p>
3056

3057
<pre>
3058 3059 3060
v1 := &lt;-ch
v2 = &lt;-ch
f(&lt;-ch)
3061
&lt;-strobe  // wait until clock pulse and discard received value
3062
</pre>
3063

Rob Pike's avatar
Rob Pike committed
3064
<p>
3065
A receive expression used in an assignment or initialization of the form
Rob Pike's avatar
Rob Pike committed
3066
</p>
3067

3068
<pre>
3069 3070 3071
x, ok = &lt;-ch
x, ok := &lt;-ch
var x, ok = &lt;-ch
3072
</pre>
3073

Rob Pike's avatar
Rob Pike committed
3074
<p>
3075 3076 3077 3078 3079
yields an additional result.
The boolean variable <code>ok</code> indicates whether
the received value was sent on the channel (<code>true</code>)
or is a <a href="#The_zero_value">zero value</a> returned
because the channel is closed and empty (<code>false</code>).
Rob Pike's avatar
Rob Pike committed
3080
</p>
3081

3082
<!--
Rob Pike's avatar
Rob Pike committed
3083
<p>
Robert Griesemer's avatar
Robert Griesemer committed
3084 3085
<span class="alert">TODO: Probably in a separate section, communication semantics
need to be presented regarding send, receive, select, and goroutines.</span>
Rob Pike's avatar
Rob Pike committed
3086
</p>
Rob Pike's avatar
Rob Pike committed
3087
-->
Rob Pike's avatar
Rob Pike committed
3088

3089

Rob Pike's avatar
Rob Pike committed
3090 3091
<h3 id="Method_expressions">Method expressions</h3>

3092
<p>
3093
If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
Rob Pike's avatar
Rob Pike committed
3094 3095 3096
<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.
Rob Pike's avatar
Rob Pike committed
3097
</p>
3098

3099
<pre class="ebnf">
Rob Pike's avatar
Rob Pike committed
3100 3101
MethodExpr    = ReceiverType "." MethodName .
ReceiverType  = TypeName | "(" "*" TypeName ")" .
3102
</pre>
3103

Rob Pike's avatar
Rob Pike committed
3104
<p>
Rob Pike's avatar
Rob Pike committed
3105 3106 3107
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>.
Rob Pike's avatar
Rob Pike committed
3108
</p>
3109

3110
<pre>
Rob Pike's avatar
Rob Pike committed
3111
type T struct {
3112
	a int
3113
}
3114 3115
func (tv  T) Mv(a int)     int     { return 0 }  // value receiver
func (tp *T) Mp(f float32) float32 { return 1 }  // pointer receiver
3116
var t T
3117
</pre>
3118

Rob Pike's avatar
Rob Pike committed
3119
<p>
Rob Pike's avatar
Rob Pike committed
3120
The expression
Rob Pike's avatar
Rob Pike committed
3121
</p>
3122

Rob Pike's avatar
Rob Pike committed
3123 3124 3125
<pre>
T.Mv
</pre>
3126

3127
<p>
Rob Pike's avatar
Rob Pike committed
3128 3129
yields a function equivalent to <code>Mv</code> but
with an explicit receiver as its first argument; it has signature
Rob Pike's avatar
Rob Pike committed
3130
</p>
3131

3132
<pre>
Russ Cox's avatar
Russ Cox committed
3133
func(tv T, a int) int
3134
</pre>
3135

Rob Pike's avatar
Rob Pike committed
3136
<p>
Rob Pike's avatar
Rob Pike committed
3137 3138
That function may be called normally with an explicit receiver, so
these three invocations are equivalent:
Rob Pike's avatar
Rob Pike committed
3139
</p>
3140

3141
<pre>
Rob Pike's avatar
Rob Pike committed
3142 3143 3144
t.Mv(7)
T.Mv(t, 7)
f := T.Mv; f(t, 7)
3145
</pre>
3146

Rob Pike's avatar
Rob Pike committed
3147
<p>
Rob Pike's avatar
Rob Pike committed
3148
Similarly, the expression
Rob Pike's avatar
Rob Pike committed
3149
</p>
Rob Pike's avatar
Rob Pike committed
3150 3151 3152 3153 3154

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

3155
<p>
Rob Pike's avatar
Rob Pike committed
3156
yields a function value representing <code>Mp</code> with signature
Rob Pike's avatar
Rob Pike committed
3157
</p>
3158

3159
<pre>
3160
func(tp *T, f float32) float32
3161
</pre>
3162

Rob Pike's avatar
Rob Pike committed
3163
<p>
Rob Pike's avatar
Rob Pike committed
3164 3165
For a method with a value receiver, one can derive a function
with an explicit pointer receiver, so
Rob Pike's avatar
Rob Pike committed
3166
</p>
3167

3168
<pre>
Rob Pike's avatar
Rob Pike committed
3169
(*T).Mv
3170
</pre>
3171

Rob Pike's avatar
Rob Pike committed
3172
<p>
Rob Pike's avatar
Rob Pike committed
3173
yields a function value representing <code>Mv</code> with signature
Rob Pike's avatar
Rob Pike committed
3174
</p>
3175

3176
<pre>
Russ Cox's avatar
Russ Cox committed
3177
func(tv *T, a int) int
3178
</pre>
3179

Rob Pike's avatar
Rob Pike committed
3180
<p>
Rob Pike's avatar
Rob Pike committed
3181 3182 3183 3184
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.
Rob Pike's avatar
Rob Pike committed
3185
</p>
3186

Rob Pike's avatar
Rob Pike committed
3187
<p>
Rob Pike's avatar
Rob Pike committed
3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198
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
3199
<a href="#Function_literals">closure</a>.
Rob Pike's avatar
Rob Pike committed
3200 3201 3202 3203 3204
</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.
Rob Pike's avatar
Rob Pike committed
3205
</p>
3206

3207 3208 3209 3210 3211 3212 3213 3214 3215
<h3 id="Conversions">Conversions</h3>

<p>
Conversions are expressions of the form <code>T(x)</code>
where <code>T</code> is a type and <code>x</code> is an expression
that can be converted to type <code>T</code>.
</p>

<pre class="ebnf">
3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227
Conversion = Type "(" Expression ")" .
</pre>

<p>
If the type starts with an operator it must be parenthesized:
</p>

<pre>
*Point(p)        // same as *(Point(p))
(*Point)(p)      // p is converted to (*Point)
&lt;-chan int(c)    // same as &lt;-(chan int(c))
(&lt;-chan int)(c)  // c is converted to (&lt;-chan int)
3228 3229 3230
</pre>

<p>
3231 3232
A value <code>x</code> can be converted to type <code>T</code> in any
of these cases:
3233
</p>
3234

3235 3236
<ul>
	<li>
3237
	<code>x</code> is <a href="#Assignability">assignable</a>
3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263
	to <code>T</code>.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> have identical
	<a href="#Types">underlying types</a>.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> are unnamed pointer types
	and their pointer base types have identical underlying types.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> are both integer or floating
	point types.
	</li>
	<li>
	<code>x</code>'s type and <code>T</code> are both complex types.
	</li>
	<li>
	<code>x</code> is an integer or has type <code>[]byte</code> or
	<code>[]int</code> and <code>T</code> is a string type.
	</li>
	<li>
	<code>x</code> is a string and <code>T</code> is <code>[]byte</code> or
	<code>[]int</code>.
	</li>
</ul>
3264 3265

<p>
3266 3267 3268 3269 3270 3271
Specific rules apply to conversions between numeric types or to and from
a string type.
These conversions may change the representation of <code>x</code>
and incur a run-time cost.
All other conversions only change the type but not the representation
of <code>x</code>.
3272 3273
</p>

3274
<h4>Conversions between numeric types</h4>
3275
<ol>
3276
<li>
3277 3278 3279 3280 3281
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.
3282 3283
</li>
<li>
3284 3285
When converting a floating-point number to an integer, the fraction is discarded
(truncation towards zero).
3286
</li>
Rob Pike's avatar
Rob Pike committed
3287
<li>
3288 3289
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
3290
to the precision specified by the destination type.
3291 3292 3293 3294
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
3295
of precision, but <code>float32(x + 0.1)</code> does not.
3296
</li>
3297 3298 3299
</ol>

<p>
Rob Pike's avatar
Rob Pike committed
3300 3301 3302
In all conversions involving floating-point or complex values,
if the result type cannot represent the value the conversion
succeeds but the result value is
3303 3304 3305
implementation-dependent.
</p>

3306 3307
<h4>Conversions to and from a string type</h4>

3308
<ol>
3309
<li>
3310
Converting a signed or unsigned integer value to a string type yields a
3311 3312
string containing the UTF-8 representation of the integer. Values outside
the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
3313 3314

<pre>
3315 3316 3317
string('a')           // "a"
string(-1)            // "\ufffd" == "\xef\xbf\xbd "
string(0xf8)          // "\u00f8" == "ø" == "\xc3\xb8"
3318
type MyString string
3319
MyString(0x65e5)      // "\u65e5" == "日" == "\xe6\x97\xa5"
3320 3321 3322 3323 3324 3325 3326 3327
</pre>
</li>

<li>
Converting a value of type <code>[]byte</code> (or
the equivalent <code>[]uint8</code>) to a string type yields a
string whose successive bytes are the elements of the slice.  If
the slice value is <code>nil</code>, the result is the empty string.
3328 3329

<pre>
3330
string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'})  // "hellø"
3331 3332
</pre>
</li>
3333

3334
<li>
3335 3336 3337 3338
Converting a value of type <code>[]int</code> to a string type yields
a string that is the concatenation of the individual integers
converted to strings.  If the slice value is <code>nil</code>, the
result is the empty string.
3339
<pre>
3340 3341
string([]int{0x767d, 0x9d6c, 0x7fd4})  // "\u767d\u9d6c\u7fd4" == "白鵬翔"
</pre>
3342 3343 3344
</li>

<li>
3345 3346 3347 3348 3349 3350 3351 3352
Converting a value of a string type to <code>[]byte</code> (or <code>[]uint8</code>)
yields a slice whose successive elements are the bytes of the string.
If the string is empty, the result is <code>[]byte(nil)</code>.

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

3354 3355 3356 3357
<li>
Converting a value of a string type to <code>[]int</code> yields a
slice containing the individual Unicode code points of the string.
If the string is empty, the result is <code>[]int(nil)</code>.
3358
<pre>
3359
[]int(MyString("白鵬翔"))  // []int{0x767d, 0x9d6c, 0x7fd4}
3360 3361
</pre>
</li>
3362
</ol>
3363 3364 3365 3366 3367 3368 3369 3370

<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>

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

3373
<p>
3374 3375
Constant expressions may contain only <a href="#Constants">constant</a>
operands and are evaluated at compile-time.
3376
</p>
Robert Griesemer's avatar
Robert Griesemer committed
3377

3378
<p>
3379 3380 3381 3382 3383 3384
Untyped boolean, numeric, and string constants may be used as operands
wherever it is legal to use an operand of boolean, numeric, or string type,
respectively. Except for shift operations, if the operands of a binary operation
are an untyped integer constant and an untyped floating-point constant,
the integer constant is converted to an untyped floating-point constant
(relevant for <code>/</code> and <code>%</code>).
Rob Pike's avatar
Rob Pike committed
3385 3386 3387 3388 3389
Similarly,
untyped integer or floating-point constants may be used as operands
wherever it is legal to use an operand of complex type;
the integer or floating point constant is converted to a
complex constant with a zero imaginary part.
3390
</p>
3391 3392

<p>
3393
Applying an operator to untyped constants results in an untyped
Rob Pike's avatar
Rob Pike committed
3394 3395 3396
constant of the same kind (that is, a boolean, integer, floating-point,
complex, or string constant), except for
<a href="#Comparison_operators">comparison operators</a>, which result in
3397
a constant of type <code>bool</code>.
3398 3399
</p>

Rob Pike's avatar
Rob Pike committed
3400 3401 3402 3403 3404 3405 3406
<p>
Imaginary literals are untyped complex constants (with zero real part)
and may be combined in binary
operations with untyped integer and floating-point constants; the
result is an untyped complex constant.
Complex constants are always constructed from
constant expressions involving imaginary
3407
literals or constants derived from them, or calls of the built-in function
3408
<a href="#Complex_numbers"><code>complex</code></a>.
Rob Pike's avatar
Rob Pike committed
3409 3410 3411 3412
</p>

<pre>
const Σ = 1 - 0.707i
3413
const Δ = Σ + 2.0e-4 - 1/1i
Rob Pike's avatar
Rob Pike committed
3414
const Φ = iota * 1i
3415
const iΓ = complex(0, Γ)
Rob Pike's avatar
Rob Pike committed
3416 3417
</pre>

3418
<p>
3419 3420 3421
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:
3422 3423 3424
</p>

<pre>
3425 3426
const Huge = 1 &lt;&lt; 100
const Four int8 = Huge &gt;&gt; 98
3427
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
3428

3429
<p>
3430 3431
The values of <i>typed</i> constants must always be accurately representable as values
of the constant type. The following constant expressions are illegal:
3432 3433 3434
</p>

<pre>
3435 3436 3437 3438 3439
uint(-1)       // -1 cannot be represented as a uint
int(3.14)      // 3.14 cannot be represented as an int
int64(Huge)    // 1&lt;&lt;100 cannot be represented as an int64
Four * 300     // 300 cannot be represented as an int8
Four * 100     // 400 cannot be represented as an int8
3440 3441 3442
</pre>

<p>
3443
The mask used by the unary bitwise complement operator <code>^</code> matches
Rob Pike's avatar
Rob Pike committed
3444
the rule for non-constants: the mask is all 1s for unsigned constants
3445
and -1 for signed and untyped constants.
3446 3447 3448
</p>

<pre>
3449
^1          // untyped integer constant, equal to -2
3450 3451 3452
uint8(^1)   // error, same as uint8(-2), out of range
^uint8(1)   // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
int8(^1)    // same as int8(-2)
Russ Cox's avatar
Russ Cox committed
3453
^int8(1)    // same as -1 ^ int8(1) = -2
3454 3455
</pre>

3456
<!--
3457
<p>
Robert Griesemer's avatar
Robert Griesemer committed
3458
<span class="alert">
3459 3460 3461
TODO: perhaps ^ should be disallowed on non-uints instead of assuming twos complement.
Also it may be possible to make typed constants more like variables, at the cost of fewer
overflow etc. errors being caught.
Robert Griesemer's avatar
Robert Griesemer committed
3462
</span>
3463
</p>
Rob Pike's avatar
Rob Pike committed
3464
-->
3465

3466
<h3 id="Order_of_evaluation">Order of evaluation</h3>
3467 3468 3469 3470 3471

<p>
When evaluating the elements of an assignment or expression,
all function calls, method calls and
communication operations are evaluated in lexical left-to-right
3472 3473 3474
order.
</p>

3475
<p>
3476
For example, in the assignment
3477 3478
</p>
<pre>
3479
y[f()], ok = g(h(), i() + x[j()], &lt;-c), k()
3480 3481
</pre>
<p>
3482 3483
the function calls and communication happen in the order
<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>,
3484
<code>&lt;-c</code>, <code>g()</code>, and <code>k()</code>.
3485 3486 3487
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.
3488 3489
</p>

3490 3491 3492 3493 3494 3495 3496 3497
<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>

3498
<h2 id="Statements">Statements</h2>
3499

Rob Pike's avatar
Rob Pike committed
3500
<p>
3501
Statements control execution.
Rob Pike's avatar
Rob Pike committed
3502
</p>
3503

3504
<pre class="ebnf">
3505
Statement =
3506 3507
	Declaration | LabeledStmt | SimpleStmt |
	GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
3508 3509
	FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
	DeferStmt .
Robert Griesemer's avatar
Robert Griesemer committed
3510

3511
SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
3512
</pre>
3513

3514

3515
<h3 id="Empty_statements">Empty statements</h3>
3516

Rob Pike's avatar
Rob Pike committed
3517
<p>
3518
The empty statement does nothing.
Rob Pike's avatar
Rob Pike committed
3519
</p>
3520

3521
<pre class="ebnf">
3522
EmptyStmt = .
3523
</pre>
3524 3525


3526
<h3 id="Labeled_statements">Labeled statements</h3>
3527 3528 3529 3530 3531 3532

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

3533
<pre class="ebnf">
3534
LabeledStmt = Label ":" Statement .
3535 3536 3537 3538
Label       = identifier .
</pre>

<pre>
3539
Error: log.Panic("error encountered")
3540 3541 3542
</pre>


3543
<h3 id="Expression_statements">Expression statements</h3>
3544

Rob Pike's avatar
Rob Pike committed
3545
<p>
3546
Function calls, method calls, and receive operations
3547
can appear in statement context. Such statements may be parenthesized.
Rob Pike's avatar
Rob Pike committed
3548 3549
</p>

3550
<pre class="ebnf">
3551
ExpressionStmt = Expression .
3552
</pre>
3553

3554
<pre>
3555 3556
h(x+y)
f.Close()
3557
&lt;-ch
3558
(&lt;-ch)
3559
</pre>
3560 3561


3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581
<h3 id="Send_statements">Send statements</h3>

<p>
A send statement sends a value on a channel.
The channel expression must be of <a href="#Channel_types">channel type</a>
and the type of the value must be <a href="#Assignability">assignable</a>
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
begins. Communication blocks until the send can proceed, at which point the
value is transmitted on the channel.
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.
3582
A send on a <code>nil</code> channel blocks forever.
3583 3584 3585 3586 3587 3588 3589
</p>

<pre>
ch &lt;- 3
</pre>


3590
<h3 id="IncDec_statements">IncDec statements</h3>
3591

Rob Pike's avatar
Rob Pike committed
3592
<p>
3593
The "++" and "--" statements increment or decrement their operands
3594
by the untyped <a href="#Constants">constant</a> <code>1</code>.
3595 3596
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
3597
</p>
3598

3599
<pre class="ebnf">
3600
IncDecStmt = Expression ( "++" | "--" ) .
3601
</pre>
3602

Rob Pike's avatar
Rob Pike committed
3603
<p>
Robert Griesemer's avatar
Robert Griesemer committed
3604
The following <a href="#Assignments">assignment statements</a> are semantically
3605
equivalent:
Rob Pike's avatar
Rob Pike committed
3606
</p>
3607

Rob Pike's avatar
Rob Pike committed
3608
<pre class="grammar">
3609 3610 3611 3612
IncDec statement    Assignment
x++                 x += 1
x--                 x -= 1
</pre>
3613

3614

3615
<h3 id="Assignments">Assignments</h3>
3616

3617
<pre class="ebnf">
3618
Assignment = ExpressionList assign_op ExpressionList .
Rob Pike's avatar
Rob Pike committed
3619

3620 3621
assign_op = [ add_op | mul_op ] "=" .
</pre>
3622

Rob Pike's avatar
Rob Pike committed
3623
<p>
Rob Pike's avatar
Rob Pike committed
3624
Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
3625 3626
a map index expression, or the <a href="#Blank_identifier">blank identifier</a>.
Operands may be parenthesized.
Rob Pike's avatar
Rob Pike committed
3627
</p>
3628

3629 3630 3631 3632
<pre>
x = 1
*p = f()
a[i] = 23
3633
(k) = &lt;-ch  // same as: k = &lt;-ch
3634
</pre>
3635

Rob Pike's avatar
Rob Pike committed
3636 3637 3638 3639
<p>
An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
<code>y</code> where <i>op</i> is a binary arithmetic operation is equivalent
to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
3640
<code>y</code> but evaluates <code>x</code>
Rob Pike's avatar
Rob Pike committed
3641
only once.  The <i>op</i><code>=</code> construct is a single token.
Rob Pike's avatar
Rob Pike committed
3642 3643
In assignment operations, both the left- and right-hand expression lists
must contain exactly one single-valued expression.
Rob Pike's avatar
Rob Pike committed
3644
</p>
3645

3646
<pre>
3647
a[i] &lt;&lt;= 2
Rob Pike's avatar
Rob Pike committed
3648
i &amp;^= 1&lt;&lt;n
3649
</pre>
3650

Rob Pike's avatar
Rob Pike committed
3651 3652 3653 3654
<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
Robert Griesemer's avatar
Robert Griesemer committed
3655 3656
such as a function evaluation or <a href="#Channel_types">channel</a> or
<a href="#Map_types">map</a> operation or a <a href="#Type_assertions">type assertion</a>.
3657
The number of operands on the left
Robert Griesemer's avatar
Robert Griesemer committed
3658
hand side must match the number of values.  For instance, if
Rob Pike's avatar
Rob Pike committed
3659 3660
<code>f</code> is a function returning two values,
</p>
3661

3662 3663 3664
<pre>
x, y = f()
</pre>
3665

Rob Pike's avatar
Rob Pike committed
3666 3667
<p>
assigns the first value to <code>x</code> and the second to <code>y</code>.
Rob Pike's avatar
Rob Pike committed
3668
The <a href="#Blank_identifier">blank identifier</a> provides a
Robert Griesemer's avatar
Robert Griesemer committed
3669
way to ignore values returned by a multi-valued expression:
Rob Pike's avatar
Rob Pike committed
3670
</p>
3671

Robert Griesemer's avatar
Robert Griesemer committed
3672 3673 3674 3675
<pre>
x, _ = f()  // ignore second value returned by f()
</pre>

Rob Pike's avatar
Rob Pike committed
3676 3677
<p>
In the second form, the number of operands on the left must equal the number
3678 3679 3680
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.
3681 3682
The expressions on the right are evaluated before assigning to
any of the operands on the left, but otherwise the evaluation
Rob Pike's avatar
Rob Pike committed
3683
order is unspecified beyond <a href="#Order_of_evaluation">the usual rules</a>.
Rob Pike's avatar
Rob Pike committed
3684
</p>
3685

3686
<pre>
Rob Pike's avatar
Rob Pike committed
3687
a, b = b, a  // exchange a and b
3688
</pre>
Rob Pike's avatar
Rob Pike committed
3689 3690

<p>
3691
In assignments, each value must be
3692
<a href="#Assignability">assignable</a> to the type of the
3693 3694
operand to which it is assigned. If an untyped <a href="#Constants">constant</a>
is assigned to a variable of interface type, the constant is <a href="#Conversions">converted</a>
3695 3696
to type <code>bool</code>, <code>int</code>, <code>float64</code>,
<code>complex128</code> or <code>string</code>
3697
respectively, depending on whether the value is a boolean, integer, floating-point,
Rob Pike's avatar
Rob Pike committed
3698
complex, or string constant.
Rob Pike's avatar
Rob Pike committed
3699
</p>
3700 3701


3702
<h3 id="If_statements">If statements</h3>
3703

Rob Pike's avatar
Rob Pike committed
3704 3705 3706 3707
<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
3708
present, the "else" branch is executed.
Rob Pike's avatar
Rob Pike committed
3709
</p>
3710

3711
<pre class="ebnf">
3712
IfStmt    = "if" [ SimpleStmt ";" ] Expression Block [ "else" Statement ] .
3713
</pre>
3714

3715
<pre>
3716 3717
if x &gt; max {
	x = max
3718 3719
}
</pre>
3720

3721
<p>
Russ Cox's avatar
Russ Cox committed
3722 3723
The expression may be preceded by a simple statement, which
executes before the expression is evaluated.
3724
</p>
3725

3726
<pre>
3727 3728
if x := f(); x &lt; y {
	return x
3729
} else if x &gt; z {
3730
	return z
3731
} else {
3732
	return y
3733 3734
}
</pre>
3735 3736


3737
<h3 id="Switch_statements">Switch statements</h3>
3738

Rob Pike's avatar
Rob Pike committed
3739 3740
<p>
"Switch" statements provide multi-way execution.
Rob Pike's avatar
Rob Pike committed
3741 3742 3743
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
3744
</p>
3745

3746
<pre class="ebnf">
3747
SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
3748 3749
</pre>

Rob Pike's avatar
Rob Pike committed
3750
<p>
Rob Pike's avatar
Rob Pike committed
3751 3752 3753 3754 3755 3756 3757
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.
</p>

3758
<h4 id="Expression_switches">Expression switches</h4>
Rob Pike's avatar
Rob Pike committed
3759 3760 3761 3762 3763

<p>
In an expression switch,
the switch expression is evaluated and
the case expressions, which need not be constants,
3764
are evaluated left-to-right and top-to-bottom; the first one that equals the
Rob Pike's avatar
Rob Pike committed
3765
switch expression
Rob Pike's avatar
Rob Pike committed
3766 3767
triggers execution of the statements of the associated case;
the other cases are skipped.
Rob Pike's avatar
Rob Pike committed
3768 3769
If no case matches and there is a "default" case,
its statements are executed.
Rob Pike's avatar
Rob Pike committed
3770 3771
There can be at most one default case and it may appear anywhere in the
"switch" statement.
3772
A missing switch expression is equivalent to
3773
the expression <code>true</code>.
Rob Pike's avatar
Rob Pike committed
3774
</p>
3775

3776
<pre class="ebnf">
3777
ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
3778
ExprCaseClause = ExprSwitchCase ":" { Statement ";" } .
3779
ExprSwitchCase = "case" ExpressionList | "default" .
3780 3781
</pre>

Rob Pike's avatar
Rob Pike committed
3782 3783 3784
<p>
In a case or default clause,
the last statement only may be a "fallthrough" statement
3785
<a href="#Fallthrough_statements">Fallthrough statement</a>) to
Rob Pike's avatar
Rob Pike committed
3786
indicate that control should flow from the end of this clause to
3787
the first statement of the next clause.
Rob Pike's avatar
Rob Pike committed
3788 3789
Otherwise control flows to the end of the "switch" statement.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
3790

3791
<p>
Russ Cox's avatar
Russ Cox committed
3792 3793
The expression may be preceded by a simple statement, which
executes before the expression is evaluated.
Rob Pike's avatar
Rob Pike committed
3794
</p>
3795

3796 3797
<pre>
switch tag {
3798 3799 3800
default: s3()
case 0, 1, 2, 3: s1()
case 4, 5, 6, 7: s2()
3801
}
3802

3803
switch x := f(); {  // missing switch expression means "true"
3804 3805
case x &lt; 0: return -x
default: return x
3806
}
3807

3808
switch {
3809 3810 3811
case x &lt; y: f1()
case x &lt; z: f2()
case x == 4: f3()
3812 3813
}
</pre>
3814

3815
<h4 id="Type_switches">Type switches</h4>
Rob Pike's avatar
Rob Pike committed
3816 3817

<p>
3818
A type switch compares types rather than values. It is otherwise similar
Robert Griesemer's avatar
Robert Griesemer committed
3819
to an expression switch. It is marked by a special switch expression that
3820
has the form of a <a href="#Type_assertions">type assertion</a>
3821 3822
using the reserved word <code>type</code> rather than an actual type.
Cases then match literal types against the dynamic type of the expression
3823
in the type assertion.
Rob Pike's avatar
Rob Pike committed
3824 3825
</p>

3826
<pre class="ebnf">
3827
TypeSwitchStmt  = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
3828
TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
3829
TypeCaseClause  = TypeSwitchCase ":" { Statement ";" } .
Rob Pike's avatar
Rob Pike committed
3830 3831
TypeSwitchCase  = "case" TypeList | "default" .
TypeList        = Type { "," Type } .
Rob Pike's avatar
Rob Pike committed
3832 3833
</pre>

3834
<p>
3835 3836 3837 3838 3839 3840
The TypeSwitchGuard may include a
<a href="#Short_variable_declarations">short variable declaration</a>.
When that form is used, the variable is declared in each clause.
In clauses with a case listing exactly one type, the variable
has that type; otherwise, the variable has the type of the expression
in the TypeSwitchGuard.
3841 3842
</p>

Rob Pike's avatar
Rob Pike committed
3843
<p>
3844 3845 3846
The type in a case may be <code>nil</code>
<a href="#Predeclared_identifiers">Predeclared identifiers</a>);
that case is used when the expression in the TypeSwitchGuard
Robert Griesemer's avatar
Robert Griesemer committed
3847
is a <code>nil</code> interface value.
3848 3849 3850
</p>

<p>
3851
Given an expression <code>x</code> of type <code>interface{}</code>,
3852
the following type switch:
Rob Pike's avatar
Rob Pike committed
3853 3854 3855
</p>

<pre>
3856
switch i := x.(type) {
3857
case nil:
3858
	printString("x is nil")
Rob Pike's avatar
Rob Pike committed
3859
case int:
3860
	printInt(i)  // i is an int
3861 3862 3863
case float64:
	printFloat64(i)  // i is a float64
case func(int) float64:
3864
	printFunction(i)  // i is a function
3865
case bool, string:
3866
	printString("type is bool or string")  // i is an interface{}
Rob Pike's avatar
Rob Pike committed
3867
default:
3868
	printString("don't know the type")
Rob Pike's avatar
Rob Pike committed
3869
}
3870
</pre>
Rob Pike's avatar
Rob Pike committed
3871

3872 3873 3874 3875 3876
<p>
could be rewritten:
</p>

<pre>
3877
v := x  // x is evaluated exactly once
3878
if v == nil {
3879
	printString("x is nil")
3880
} else if i, is_int := v.(int); is_int {
3881
	printInt(i)  // i is an int
3882 3883 3884
} else if i, is_float64 := v.(float64); is_float64 {
	printFloat64(i)  // i is a float64
} else if i, is_func := v.(func(int) float64); is_func {
3885
	printFunction(i)  // i is a function
3886
} else {
3887 3888
	i1, is_bool := v.(bool)
	i2, is_string := v.(string)
3889
	if is_bool || is_string {
3890 3891
		i := v
		printString("type is bool or string")  // i is an interface{}
3892
	} else {
3893 3894
		i := v
		printString("don't know the type")  // i is an interface{}
3895
	}
Rob Pike's avatar
Rob Pike committed
3896 3897
}
</pre>
3898

3899
<p>
Russ Cox's avatar
Russ Cox committed
3900 3901
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
3902
</p>
3903 3904 3905

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

3908
<h3 id="For_statements">For statements</h3>
3909

Rob Pike's avatar
Rob Pike committed
3910 3911 3912 3913
<p>
A "for" statement specifies repeated execution of a block. The iteration is
controlled by a condition, a "for" clause, or a "range" clause.
</p>
3914

3915
<pre class="ebnf">
3916
ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
3917 3918
Condition = Expression .
</pre>
3919

Rob Pike's avatar
Rob Pike committed
3920 3921 3922 3923 3924 3925
<p>
In its simplest form, a "for" statement specifies the repeated execution of
a block as long as a boolean condition evaluates to true.
The condition is evaluated before each iteration.
If the condition is absent, it is equivalent to <code>true</code>.
</p>
3926

3927 3928 3929 3930 3931
<pre>
for a &lt; b {
	a *= 2
}
</pre>
3932

Rob Pike's avatar
Rob Pike committed
3933
<p>
Rob Pike's avatar
Rob Pike committed
3934
A "for" statement with a ForClause is also controlled by its condition, but
Rob Pike's avatar
Rob Pike committed
3935 3936
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
3937
an increment or decrement statement. The init statement may be a
3938
<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
Rob Pike's avatar
Rob Pike committed
3939
</p>
3940

3941
<pre class="ebnf">
3942
ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
3943 3944
InitStmt = SimpleStmt .
PostStmt = SimpleStmt .
3945
</pre>
3946

3947
<pre>
3948
for i := 0; i &lt; 10; i++ {
3949 3950 3951
	f(i)
}
</pre>
3952

3953
<p>
Rob Pike's avatar
Rob Pike committed
3954 3955 3956 3957
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).
3958 3959
Any element of the ForClause may be empty but the
<a href="#Semicolons">semicolons</a> are
Rob Pike's avatar
Rob Pike committed
3960 3961 3962
required unless there is only a condition.
If the condition is absent, it is equivalent to <code>true</code>.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
3963

3964
<pre>
Rob Pike's avatar
Rob Pike committed
3965 3966
for cond { S() }    is the same as    for ; cond ; { S() }
for      { S() }    is the same as    for true     { S() }
3967
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
3968

Rob Pike's avatar
Rob Pike committed
3969 3970
<p>
A "for" statement with a "range" clause
Rob Pike's avatar
Rob Pike committed
3971
iterates through all entries of an array, slice, string or map,
3972 3973
or values received on a channel. For each entry it assigns <i>iteration values</i>
to corresponding <i>iteration variables</i> and then executes the block.
Rob Pike's avatar
Rob Pike committed
3974
</p>
Robert Griesemer's avatar
Robert Griesemer committed
3975

3976
<pre class="ebnf">
3977 3978 3979 3980 3981 3982 3983 3984 3985 3986
RangeClause = Expression [ "," Expression ] ( "=" | ":=" ) "range" Expression .
</pre>

<p>
The expression on the right in the "range" clause is called the <i>range expression</i>,
which may be an array, pointer to an array, slice, string, map, or channel.
As with an assignment, the operands on the left must be
<a href="#Address_operators">addressable</a> or map index expressions; they
denote the iteration variables. If the range expression is a channel, only
one iteration variable is permitted, otherwise there may be one or two.
3987 3988
If the second iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
the range clause is equivalent to the same clause with only the first variable present.
3989
</p>
3990 3991

<p>
3992 3993 3994
The range expression is evaluated once before beginning the loop
except if the expression is an array, in which case, depending on
the expression, it might not be evaluated (see below).
3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009
Function calls on the left are evaluated once per iteration.
For each iteration, iteration values are produced as follows:
</p>

<pre class="grammar">
Range expression                          1st value          2nd value (if 2nd variable is present)

array or slice  a  [n]E, *[n]E, or []E    index    i  int    a[i]       E
string          s  string type            index    i  int    see below  int
map             m  map[K]V                key      k  K      m[k]       V
channel         c  chan E                 element  e  E
</pre>

<ol>
<li>
4010 4011 4012 4013 4014
For an array, pointer to array, or slice value <code>a</code>, the index iteration
values are produced in increasing order, starting at element index 0. As a special
case, if only the first iteration variable is present, the range loop produces
iteration values from 0 up to <code>len(a)</code> and does not index into the array
or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
4015 4016 4017 4018 4019 4020 4021
</li>

<li>
For a string value, the "range" clause iterates over the Unicode code points
in the string starting at byte index 0.  On successive iterations, the index value will be the
index of the first byte of successive UTF-8-encoded code points in the string,
and the second value, of type <code>int</code>, will be the value of
Rob Pike's avatar
Rob Pike committed
4022
the corresponding code point.  If the iteration encounters an invalid
4023
UTF-8 sequence, the second value will be <code>0xFFFD</code>,
Rob Pike's avatar
Rob Pike committed
4024 4025
the Unicode replacement character, and the next iteration will advance
a single byte in the string.
4026 4027 4028 4029 4030 4031 4032
</li>

<li>
The iteration order over maps is not specified.
If map entries that have not yet been reached are deleted during iteration,
the corresponding iteration values will not be produced. If map entries are
inserted during iteration, the behavior is implementation-dependent, but the
4033 4034
iteration values for each entry will be produced at most once. If the map
is <code>nil</code>, the number of iterations is 0.
4035 4036 4037 4038
</li>

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

Rob Pike's avatar
Rob Pike committed
4044
<p>
4045 4046
The iteration values are assigned to the respective
iteration variables as in an <a href="#Assignments">assignment statement</a>.
4047
</p>
4048

4049
<p>
4050 4051 4052 4053
The iteration variables may be declared by the "range" clause (<code>:=</code>).
In this case their types are set to the types of the respective iteration values
and their <a href="#Declarations_and_scope">scope</a> ends at the end of the "for"
statement; they are re-used in each iteration.
Rob Pike's avatar
Rob Pike committed
4054 4055 4056
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
4057

4058
<pre>
4059 4060 4061 4062 4063 4064 4065 4066 4067
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)
}

4068 4069
var a [10]string
m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
4070 4071 4072 4073 4074 4075 4076
for i, s := range a {
	// type of i is int
	// type of s is string
	// s == a[i]
	g(i, s)
}

4077
var key string
4078
var val interface {}  // value type of m is assignable to val
Rob Pike's avatar
Rob Pike committed
4079 4080
for key, val = range m {
	h(key, val)
4081 4082 4083
}
// key == last map key encountered in iteration
// val == map[key]
4084 4085 4086 4087 4088

var ch chan Work = producer()
for w := range ch {
	doWork(w)
}
4089
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
4090

4091

4092
<h3 id="Go_statements">Go statements</h3>
4093

Rob Pike's avatar
Rob Pike committed
4094
<p>
4095
A "go" statement starts the execution of a function or method call
Rob Pike's avatar
Rob Pike committed
4096 4097 4098
as an independent concurrent thread of control, or <i>goroutine</i>,
within the same address space.
</p>
4099

4100
<pre class="ebnf">
4101
GoStmt = "go" Expression .
4102
</pre>
4103

Rob Pike's avatar
Rob Pike committed
4104 4105 4106
<p>
The expression must be a call, and
unlike with a regular call, program execution does not wait
4107
for the invoked function to complete.
Rob Pike's avatar
Rob Pike committed
4108
</p>
4109

4110 4111
<pre>
go Server()
4112
go func(ch chan&lt;- bool) { for { sleep(10); ch &lt;- true; }} (c)
4113
</pre>
4114 4115


4116
<h3 id="Select_statements">Select statements</h3>
4117

Rob Pike's avatar
Rob Pike committed
4118 4119 4120
<p>
A "select" statement chooses which of a set of possible communications
will proceed.  It looks similar to a "switch" statement but with the
4121
cases all referring to communication operations.
Rob Pike's avatar
Rob Pike committed
4122
</p>
4123

4124
<pre class="ebnf">
4125
SelectStmt = "select" "{" { CommClause } "}" .
4126
CommClause = CommCase ":" { Statement ";" } .
4127
CommCase   = "case" ( SendStmt | RecvStmt ) | "default" .
4128
RecvStmt   = [ Expression [ "," Expression ] ( "=" | ":=" ) ] RecvExpr .
4129
RecvExpr   = Expression .
4130
</pre>
4131

4132
<p>
4133
RecvExpr must be a <a href="#Receive_operator">receive operation</a>.
4134
For all the cases in the "select"
4135
statement, the channel expressions are evaluated in top-to-bottom order, along with
4136
any expressions that appear on the right hand side of send statements.
4137
A channel may be <code>nil</code>,
Rob Pike's avatar
Rob Pike committed
4138 4139 4140
which is equivalent to that case not
being present in the select statement
except, if a send, its expression is still evaluated.
4141 4142 4143 4144 4145 4146 4147 4148 4149 4150
If any of the resulting operations can proceed, one of those is
chosen and the corresponding communication and statements are
evaluated.  Otherwise, if there is a default case, that executes;
if there is no default case, the statement blocks until one of the communications can
complete.
If there are no cases with non-<code>nil</code> channels,
the statement blocks forever.
Even if the statement blocks,
the channel and send expressions are evaluated only once,
upon entering the select statement.
Rob Pike's avatar
Rob Pike committed
4151
</p>
4152
<p>
Rob Pike's avatar
Rob Pike committed
4153 4154
Since all the channels and send expressions are evaluated, any side
effects in that evaluation will occur for all the communications
Rob Pike's avatar
Rob Pike committed
4155 4156
in the "select" statement.
</p>
4157
<p>
4158
If multiple cases can proceed, a pseudo-random fair choice is made to decide
4159
which single communication will execute.
4160
<p>
4161
The receive case may declare one or two new variables using a
4162
<a href="#Short_variable_declarations">short variable declaration</a>.
Rob Pike's avatar
Rob Pike committed
4163
</p>
4164

4165
<pre>
4166
var c, c1, c2, c3 chan int
4167
var i1, i2 int
4168 4169
select {
case i1 = &lt;-c1:
4170
	print("received ", i1, " from c1\n")
4171
case c2 &lt;- i2:
4172
	print("sent ", i2, " to c2\n")
4173
case i3, ok := (&lt;-c3):  // same as: i3, ok := &lt;-c3
4174 4175 4176 4177 4178
	if ok {
		print("received ", i3, " from c3\n")
	} else {
		print("c3 is closed\n")
	}
4179
default:
4180
	print("no communication\n")
4181 4182 4183
}

for {  // send random sequence of bits to c
4184
	select {
4185 4186
	case c &lt;- 0:  // note: no statement, no fallthrough, no folding of cases
	case c &lt;- 1:
4187
	}
4188
}
4189 4190

select { }  // block forever
4191
</pre>
4192 4193


4194
<h3 id="Return_statements">Return statements</h3>
4195

Rob Pike's avatar
Rob Pike committed
4196 4197
<p>
A "return" statement terminates execution of the containing function
4198
and optionally provides a result value or values to the caller.
Rob Pike's avatar
Rob Pike committed
4199
</p>
4200

4201
<pre class="ebnf">
4202
ReturnStmt = "return" [ ExpressionList ] .
4203
</pre>
4204

4205 4206 4207 4208
<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
4209
<pre>
4210
func no_result() {
Rob Pike's avatar
Rob Pike committed
4211 4212 4213
	return
}
</pre>
4214

Rob Pike's avatar
Rob Pike committed
4215
<p>
4216 4217
There are three ways to return values from a function with a result
type:
Rob Pike's avatar
Rob Pike committed
4218
</p>
4219

4220 4221 4222
<ol>
	<li>The return value or values may be explicitly listed
		in the "return" statement. Each expression must be single-valued
4223 4224
		and <a href="#Assignability">assignable</a>
		to the corresponding element of the function's result type.
4225 4226
<pre>
func simple_f() int {
Rob Pike's avatar
Rob Pike committed
4227 4228 4229
	return 2
}

4230
func complex_f1() (re float64, im float64) {
Rob Pike's avatar
Rob Pike committed
4231
	return -7.0, -4.0
4232 4233
}
</pre>
4234 4235 4236 4237 4238 4239 4240
	</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.
4241
<pre>
4242
func complex_f2() (re float64, im float64) {
Rob Pike's avatar
Rob Pike committed
4243
	return complex_f1()
4244 4245
}
</pre>
4246
	</li>
4247
	<li>The expression list may be empty if the function's result
4248
		type specifies names for its result parameters (§<a href="#Function_types">Function Types</a>).
4249
		The result parameters act as ordinary local variables
4250 4251
		and the function may assign values to them as necessary.
		The "return" statement returns the values of these variables.
4252
<pre>
4253
func complex_f3() (re float64, im float64) {
4254 4255 4256
	re = 7.0
	im = 4.0
	return
4257
}
4258 4259 4260 4261 4262

func (devnull) Write(p []byte) (n int, _ os.Error) {
	n = len(p)
	return
} 
4263
</pre>
4264 4265
	</li>
</ol>
4266

4267 4268 4269 4270
<p>
Regardless of how they are declared, all the result values are initialized to the zero values for their type (§<a href="#The_zero_value">The zero value</a>) upon entry to the function.
</p>

4271
<!--
4272
<p>
Robert Griesemer's avatar
Robert Griesemer committed
4273
<span class="alert">
4274 4275 4276
TODO: Define when return is required.<br />
TODO: Language about result parameters needs to go into a section on
      function/method invocation<br />
Robert Griesemer's avatar
Robert Griesemer committed
4277
</span>
4278
</p>
Rob Pike's avatar
Rob Pike committed
4279
-->
4280

4281
<h3 id="Break_statements">Break statements</h3>
4282

Rob Pike's avatar
Rob Pike committed
4283 4284 4285 4286
<p>
A "break" statement terminates execution of the innermost
"for", "switch" or "select" statement.
</p>
4287

4288
<pre class="ebnf">
4289
BreakStmt = "break" [ Label ] .
4290
</pre>
4291

Rob Pike's avatar
Rob Pike committed
4292 4293 4294 4295
<p>
If there is a label, it must be that of an enclosing
"for", "switch" or "select" statement, and that is the one whose execution
terminates
4296
<a href="#For_statements">For statements</a>, §<a href="#Switch_statements">Switch statements</a>, §<a href="#Select_statements">Select statements</a>).
Rob Pike's avatar
Rob Pike committed
4297
</p>
4298

4299
<pre>
Russ Cox's avatar
Russ Cox committed
4300 4301 4302 4303 4304 4305
L:
	for i &lt; n {
		switch i {
		case 5:
			break L
		}
4306
	}
4307
</pre>
4308

4309
<h3 id="Continue_statements">Continue statements</h3>
4310

Rob Pike's avatar
Rob Pike committed
4311 4312
<p>
A "continue" statement begins the next iteration of the
Rob Pike's avatar
Rob Pike committed
4313
innermost "for" loop at its post statement (§<a href="#For_statements">For statements</a>).
Rob Pike's avatar
Rob Pike committed
4314
</p>
4315

4316
<pre class="ebnf">
4317
ContinueStmt = "continue" [ Label ] .
4318
</pre>
4319

Rob Pike's avatar
Rob Pike committed
4320
<p>
4321 4322 4323 4324
If there is a label, it must be that of an enclosing
"for" statement, and that is the one whose execution
advances
<a href="#For_statements">For statements</a>).
Rob Pike's avatar
Rob Pike committed
4325
</p>
4326

4327
<h3 id="Goto_statements">Goto statements</h3>
4328

Rob Pike's avatar
Rob Pike committed
4329 4330 4331
<p>
A "goto" statement transfers control to the statement with the corresponding label.
</p>
4332

4333
<pre class="ebnf">
4334
GotoStmt = "goto" Label .
4335
</pre>
4336

4337 4338 4339
<pre>
goto Error
</pre>
4340

Rob Pike's avatar
Rob Pike committed
4341 4342
<p>
Executing the "goto" statement must not cause any variables to come into
4343 4344
scope that were not already in scope at the point of the goto.  For
instance, this example:
Rob Pike's avatar
Rob Pike committed
4345
</p>
4346

4347
<pre>
Russ Cox's avatar
Russ Cox committed
4348 4349
	goto L  // BAD
	v := 3
4350 4351
L:
</pre>
4352

Rob Pike's avatar
Rob Pike committed
4353 4354 4355
<p>
is erroneous because the jump to label <code>L</code> skips
the creation of <code>v</code>.
4356
<!--
Robert Griesemer's avatar
Robert Griesemer committed
4357
(<span class="alert">TODO: Eliminate in favor of used and not set errors?</span>)
Rob Pike's avatar
Rob Pike committed
4358
-->
Rob Pike's avatar
Rob Pike committed
4359
</p>
4360

4361
<h3 id="Fallthrough_statements">Fallthrough statements</h3>
4362

Rob Pike's avatar
Rob Pike committed
4363 4364
<p>
A "fallthrough" statement transfers control to the first statement of the
4365
next case clause in a expression "switch" statement (§<a href="#Expression_switches">Expression switches</a>). It may
4366 4367
be used only as the final non-empty statement in a case or default clause in an
expression "switch" statement.
Rob Pike's avatar
Rob Pike committed
4368
</p>
4369

4370
<pre class="ebnf">
4371
FallthroughStmt = "fallthrough" .
4372
</pre>
4373 4374


4375
<h3 id="Defer_statements">Defer statements</h3>
Robert Griesemer's avatar
Robert Griesemer committed
4376

Rob Pike's avatar
Rob Pike committed
4377 4378 4379 4380
<p>
A "defer" statement invokes a function whose execution is deferred to the moment
the surrounding function returns.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4381

4382
<pre class="ebnf">
4383
DeferStmt = "defer" Expression .
4384
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
4385

Rob Pike's avatar
Rob Pike committed
4386 4387 4388
<p>
The expression must be a function or method call.
Each time the "defer" statement
4389
executes, the parameters to the function call are evaluated and saved anew but the
Rob Pike's avatar
Rob Pike committed
4390 4391 4392
function is not invoked.
Deferred function calls are executed in LIFO order
immediately before the surrounding function returns,
4393 4394
after the return values, if any, have been evaluated, but before they
are returned to the caller. For instance, if the deferred function is
4395
a <a href="#Function_literals">function literal</a> and the surrounding
4396 4397 4398
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.
Rob Pike's avatar
Rob Pike committed
4399
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4400

4401
<pre>
4402 4403
lock(l)
defer unlock(l)  // unlocking happens before surrounding function returns
Robert Griesemer's avatar
Robert Griesemer committed
4404

4405 4406
// prints 3 2 1 0 before surrounding function returns
for i := 0; i &lt;= 3; i++ {
4407
	defer fmt.Print(i)
4408
}
4409 4410 4411 4412 4413 4414 4415 4416

// f returns 1
func f() (result int) {
	defer func() {
		result++
	}()
	return 0
}
4417
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
4418

4419
<h2 id="Built-in_functions">Built-in functions</h2>
4420 4421

<p>
Rob Pike's avatar
Rob Pike committed
4422
Built-in functions are
4423 4424 4425 4426
<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
4427

4428 4429 4430 4431 4432 4433
<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>

4434
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
4435
BuiltinCall = identifier "(" [ BuiltinArgs [ "," ] ] ")" .
4436
BuiltinArgs = Type [ "," ExpressionList ] | ExpressionList .
4437
</pre>
4438

4439
<h3 id="Close">Close</h3>
4440

Rob Pike's avatar
Rob Pike committed
4441
<p>
4442 4443
For a channel <code>c</code>, the built-in function <code>close(c)</code>
marks the channel as unable to accept more values through a send operation;
4444
sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
4445
After calling <code>close</code>, and after any previously
4446
sent values have been received, receive operations will return
4447
the zero value for the channel's type without blocking.
4448

4449 4450
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
4451
</p>
4452

4453

4454
<h3 id="Length_and_capacity">Length and capacity</h3>
4455

Rob Pike's avatar
Rob Pike committed
4456
<p>
4457 4458 4459
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>.
4460 4461
</p>

4462
<pre class="grammar">
4463
Call      Argument type    Result
4464

4465 4466 4467 4468 4469
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
4470

4471 4472 4473
cap(s)    [n]T, *[n]T      array length (== n)
          []T              slice capacity
          chan T           channel buffer capacity
4474
</pre>
4475

4476 4477 4478 4479 4480
<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>
4481

4482
<pre>
Anthony Martin's avatar
Anthony Martin committed
4483
0 &lt;= len(s) &lt;= cap(s)
4484
</pre>
4485

4486 4487 4488 4489
<p>
The length and capacity of a <code>nil</code> slice, map, or channel are 0.
</p>

4490
<p>
4491 4492 4493 4494 4495 4496 4497 4498
The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
<code>s</code> is a string constant. The expressions <code>len(s)</code> and
<code>cap(s)</code> are constants if the type of <code>s</code> is an array
or pointer to an array and the expression <code>s</code> does not contain
<a href="#Receive_operator">channel receives</a> or
<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.
4499
</p>
4500

4501

4502
<h3 id="Allocation">Allocation</h3>
4503

Rob Pike's avatar
Rob Pike committed
4504 4505 4506
<p>
The built-in function <code>new</code> takes a type <code>T</code> and
returns a value of type <code>*T</code>.
4507
The memory is initialized as described in the section on initial values
4508
<a href="#The_zero_value">The zero value</a>).
Rob Pike's avatar
Rob Pike committed
4509
</p>
4510

4511
<pre class="grammar">
4512 4513
new(T)
</pre>
4514

Rob Pike's avatar
Rob Pike committed
4515
<p>
4516
For instance
Rob Pike's avatar
Rob Pike committed
4517
</p>
4518

4519
<pre>
4520
type S struct { a int; b float64 }
4521 4522
new(S)
</pre>
4523

4524
<p>
Rob Pike's avatar
Rob Pike committed
4525 4526 4527 4528 4529
dynamically allocates memory for a variable of type <code>S</code>,
initializes it (<code>a=0</code>, <code>b=0.0</code>),
and returns a value of type <code>*S</code> containing the address
of the memory.
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4530

4531
<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
Robert Griesemer's avatar
Robert Griesemer committed
4532

Rob Pike's avatar
Rob Pike committed
4533 4534 4535 4536 4537 4538 4539
<p>
Slices, maps and channels are reference types that do not require the
extra indirection of an allocation with <code>new</code>.
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>).
Robert Griesemer's avatar
Robert Griesemer committed
4540
The memory is initialized as described in the section on initial values
4541
<a href="#The_zero_value">The zero value</a>).
Rob Pike's avatar
Rob Pike committed
4542
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4543

4544
<pre class="grammar">
4545
Call             Type T     Result
Robert Griesemer's avatar
Robert Griesemer committed
4546

4547 4548
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
4549

4550 4551 4552 4553 4554
make(T)          map        map of type T
make(T, n)       map        map of type T with initial space for n elements

make(T)          channel    synchronous channel of type T
make(T, n)       channel    asynchronous channel of type T, buffer size n
4555
</pre>
Robert Griesemer's avatar
Robert Griesemer committed
4556 4557


Rob Pike's avatar
Rob Pike committed
4558
<p>
4559 4560 4561 4562
The arguments <code>n</code> and <code>m</code> must be of integer type.
A <a href="#Run_time_panics">run-time panic</a> occurs if <code>n</code>
is negative or larger than <code>m</code>, or if <code>n</code> or
<code>m</code> cannot be represented by an <code>int</code>.
Rob Pike's avatar
Rob Pike committed
4563
</p>
Robert Griesemer's avatar
Robert Griesemer committed
4564

4565
<pre>
4566 4567 4568 4569
s := make([]int, 10, 100)        // slice with len(s) == 10, cap(s) == 100
s := make([]int, 10)             // slice with len(s) == cap(s) == 10
c := make(chan int, 10)          // channel with a buffer size of 10
m := make(map[string] int, 100)  // map with initial space for 100 elements
4570
</pre>
4571

4572

Robert Griesemer's avatar
Robert Griesemer committed
4573
<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
4574 4575

<p>
Robert Griesemer's avatar
Robert Griesemer committed
4576 4577 4578 4579 4580
Two built-in functions assist in common slice operations.
</p>

<p>
The function <code>append</code> appends zero or more values <code>x</code>
4581 4582 4583 4584
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>.
Each value <code>x</code> must be <a href="#Assignability">assignable</a> to
the <a href="#Slice_types">element type</a> of <code>S</code>.
Robert Griesemer's avatar
Robert Griesemer committed
4585 4586 4587
</p>

<pre class="grammar">
4588
append(s S, x ...T) S  // T is the element type of S
Robert Griesemer's avatar
Robert Griesemer committed
4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602
</pre>

<p>
If the capacity of <code>s</code> is not large enough to fit the additional
values, <code>append</code> allocates a new, sufficiently large slice that fits
both the existing slice elements and the additional values. Thus, the returned
slice may refer to a different underlying array. 
</p>

<pre>
s0 := []int{0, 0}
s1 := append(s0, 2)        // append a single element     s1 == []int{0, 0, 2}
s2 := append(s1, 3, 5, 7)  // append multiple elements    s2 == []int{0, 0, 2, 3, 5, 7}
s3 := append(s2, s0...)    // append a slice              s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
4603 4604 4605

var t []interface{}
t = append(t, 42, 3.1415, "foo")                          t == []interface{}{42, 3.1415, "foo"}
Robert Griesemer's avatar
Robert Griesemer committed
4606 4607 4608 4609
</pre>

<p>
The function <code>copy</code> copies slice elements from
4610 4611
a source <code>src</code> to a destination <code>dst</code> and returns the
number of elements copied. Source and destination may overlap.
4612
Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be
4613 4614
<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>.
The number of arguments copied is the minimum of
4615
<code>len(src)</code> and <code>len(dst)</code>.
4616 4617 4618
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.
4619 4620 4621 4622
</p>

<pre class="grammar">
copy(dst, src []T) int
4623
copy(dst []byte, src string) int
4624 4625 4626 4627 4628 4629 4630
</pre>

<p>
Examples:
</p>

<pre>
4631 4632
var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
var s = make([]int, 6)
4633 4634 4635 4636
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")
4637 4638
</pre>

Rob Pike's avatar
Rob Pike committed
4639 4640 4641 4642
<h3 id="Complex_numbers">Assembling and disassembling complex numbers</h3>

<p>
Three functions assemble and disassemble complex numbers.
4643
The built-in function <code>complex</code> constructs a complex
Rob Pike's avatar
Rob Pike committed
4644 4645 4646 4647 4648 4649
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">
4650
complex(realPart, imaginaryPart floatT) complexT
Rob Pike's avatar
Rob Pike committed
4651 4652 4653 4654 4655 4656
real(complexT) floatT
imag(complexT) floatT
</pre>

<p>
The type of the arguments and return value correspond.
4657
For <code>complex</code>, the two arguments must be of the same
Rob Pike's avatar
Rob Pike committed
4658 4659 4660 4661 4662 4663
floating-point type and the return type is the complex type
with the corresponding floating-point constituents:
<code>complex64</code> for <code>float32</code>,
<code>complex128</code> for <code>float64</code>.
The <code>real</code> and <code>imag</code> functions
together form the inverse, so for a complex value <code>z</code>,
4664
<code>z</code> <code>==</code> <code>complex(real(z),</code> <code>imag(z))</code>.
Rob Pike's avatar
Rob Pike committed
4665 4666 4667 4668 4669 4670 4671 4672
</p>

<p>
If the operands of these functions are all constants, the return
value is a constant.
</p>

<pre>
4673 4674 4675 4676 4677 4678
var a = complex(2, -2)             // complex128
var b = complex(1.0, -1.4)         // complex128
x := float32(math.Cos(math.Pi/2))  // float32
var c64 = complex(5, -x)           // complex64
var im = imag(b)                   // float64
var rl = real(c64)                 // float32
Rob Pike's avatar
Rob Pike committed
4679 4680
</pre>

4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707
<h3 id="Handling_panics">Handling panics</h3>

<p> Two built-in functions, <code>panic</code> and <code>recover</code>,
assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
and program-defined error conditions. 
</p>

<pre class="grammar">
func panic(interface{})
func recover() interface{}
</pre>

<p>
When a function <code>F</code> calls <code>panic</code>, normal
execution of <code>F</code> stops immediately.  Any functions whose
execution was <a href="#Defer_statements">deferred</a> by the
invocation of <code>F</code> are run in the usual way, and then
<code>F</code> returns to its caller.  To the caller, <code>F</code>
then behaves like a call to <code>panic</code>, terminating its own
execution and running deferred functions.  This continues until all
functions in the goroutine have ceased execution, in reverse order.
At that point, the program is
terminated and the error condition is reported, including the value of
the argument to <code>panic</code>.  This termination sequence is
called <i>panicking</i>.
</p>

4708 4709 4710 4711 4712 4713
<pre>
panic(42)
panic("unreachable")
panic(Error("cannot parse"))
</pre>

4714 4715 4716
<p>
The <code>recover</code> function allows a program to manage behavior
of a panicking goroutine.  Executing a <code>recover</code> call
4717
<i>inside</i> a deferred function (but not any function called by it) stops
4718 4719 4720
the panicking sequence by restoring normal execution, and retrieves
the error value passed to the call of <code>panic</code>.  If
<code>recover</code> is called outside the deferred function it will
4721 4722 4723
not stop a panicking sequence.  In this case, or when the goroutine
is not panicking, or if the argument supplied to <code>panic</code>
was <code>nil</code>, <code>recover</code> returns <code>nil</code>.
4724 4725 4726
</p>

<p>
4727 4728 4729
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>.
4730 4731 4732
</p>

<pre>
4733
func protect(g func()) {
4734
	defer func() {
4735
		log.Println("done")  // Println executes normally even in there is a panic
4736
		if x := recover(); x != nil {
4737
			log.Printf("run time panic: %v", x)
4738
		}
4739
	}()
4740 4741
	log.Println("start")
	g()
4742 4743 4744
}
</pre>

4745

4746 4747
<h3 id="Bootstrapping">Bootstrapping</h3>

4748
<p>
4749 4750 4751
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.
4752 4753
</p>

4754
<pre class="grammar">
4755
Function   Behavior
4756 4757 4758 4759 4760 4761

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>


4762
<h2 id="Packages">Packages</h2>
4763

Rob Pike's avatar
Rob Pike committed
4764 4765
<p>
Go programs are constructed by linking together <i>packages</i>.
4766 4767 4768 4769 4770
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
4771 4772
</p>

4773
<h3 id="Source_file_organization">Source file organization</h3>
Rob Pike's avatar
Rob Pike committed
4774 4775 4776 4777 4778 4779

<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
4780
types, variables, and constants.
Rob Pike's avatar
Rob Pike committed
4781
</p>
4782

4783
<pre class="ebnf">
4784
SourceFile       = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
4785
</pre>
4786

4787
<h3 id="Package_clause">Package clause</h3>
Rob Pike's avatar
Rob Pike committed
4788

4789
<p>
Rob Pike's avatar
Rob Pike committed
4790 4791 4792
A package clause begins each source file and defines the package
to which the file belongs.
</p>
4793

4794
<pre class="ebnf">
Robert Griesemer's avatar
Robert Griesemer committed
4795 4796
PackageClause  = "package" PackageName .
PackageName    = identifier .
Rob Pike's avatar
Rob Pike committed
4797
</pre>
4798

Robert Griesemer's avatar
Robert Griesemer committed
4799 4800 4801 4802
<p>
The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
</p>

Rob Pike's avatar
Rob Pike committed
4803 4804
<pre>
package math
4805
</pre>
4806

Rob Pike's avatar
Rob Pike committed
4807 4808 4809 4810
<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>
4811

4812
<h3 id="Import_declarations">Import declarations</h3>
Rob Pike's avatar
Rob Pike committed
4813 4814

<p>
Rob Pike's avatar
Rob Pike committed
4815 4816 4817 4818 4819 4820
An import declaration states that the source file containing the
declaration uses identifiers
<a href="#Exported_identifiers">exported</a> by the <i>imported</i>
package and enables access to them.  The import names an
identifier (PackageName) to be used for access and an ImportPath
that specifies the package to be imported.
Rob Pike's avatar
Rob Pike committed
4821
</p>
4822

4823
<pre class="ebnf">
4824
ImportDecl       = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
4825
ImportSpec       = [ "." | PackageName ] ImportPath .
4826
ImportPath       = string_lit .
4827
</pre>
4828

4829
<p>
Rob Pike's avatar
Rob Pike committed
4830 4831 4832 4833
The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
to access the exported identifiers of the package within the importing source file.
It is declared in the <a href="#Blocks">file block</a>.
If the PackageName is omitted, it defaults to the identifier specified in the
Robert Griesemer's avatar
Robert Griesemer committed
4834
<a href="#Package_clause">package clause</a> of the imported package.
Rob Pike's avatar
Rob Pike committed
4835 4836 4837 4838 4839 4840 4841 4842 4843
If an explicit period (<code>.</code>) appears instead of a name, all the
package's exported identifiers will be declared in the current file's
file block and can be accessed without a qualifier.
</p>

<p>
The interpretation of the ImportPath is implementation-dependent but
it is typically a substring of the full file name of the compiled
package and may be relative to a repository of installed packages.
Rob Pike's avatar
Rob Pike committed
4844
</p>
Russ Cox's avatar
Russ Cox committed
4845

4846
<p>
Rob Pike's avatar
Rob Pike committed
4847 4848 4849
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
4850
<code>"lib/math"</code>.
Rob Pike's avatar
Rob Pike committed
4851 4852 4853
This table illustrates how <code>Sin</code> may be accessed in files
that import the package after the
various types of import declaration.
Rob Pike's avatar
Rob Pike committed
4854
</p>
4855

Rob Pike's avatar
Rob Pike committed
4856
<pre class="grammar">
4857
Import declaration          Local name of Sin
Rob Pike's avatar
Rob Pike committed
4858 4859

import   "lib/math"         math.Sin
4860
import M "lib/math"         M.Sin
Rob Pike's avatar
Rob Pike committed
4861
import . "lib/math"         Sin
4862
</pre>
4863

4864
<p>
Rob Pike's avatar
Rob Pike committed
4865 4866
An import declaration declares a dependency relation between
the importing and imported package.
4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877
It is illegal for a package to import itself or to import a package without
referring to any of its exported identifiers. To import a package solely for
its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
identifier as explicit package name:
</p>

<pre>
import _ "lib/math"
</pre>


4878
<h3 id="An_example_package">An example package</h3>
Rob Pike's avatar
Rob Pike committed
4879 4880 4881 4882

<p>
Here is a complete Go package that implements a concurrent prime sieve.
</p>
4883

4884 4885 4886
<pre>
package main

Rob Pike's avatar
Rob Pike committed
4887 4888
import "fmt"

4889
// Send the sequence 2, 3, 4, ... to channel 'ch'.
4890
func generate(ch chan&lt;- int) {
4891
	for i := 2; ; i++ {
4892
		ch &lt;- i  // Send 'i' to channel 'ch'.
4893
	}
4894 4895
}

Fazlul Shahriar's avatar
Fazlul Shahriar committed
4896
// Copy the values from channel 'src' to channel 'dst',
4897
// removing those divisible by 'prime'.
4898 4899 4900
func filter(src &lt;-chan int, dst chan&lt;- int, prime int) {
	for i := range src {	// Loop over values received from 'src'.
		if i%prime != 0 {
4901
			dst &lt;- i  // Send 'i' to channel 'dst'.
4902 4903
		}
	}
4904 4905 4906 4907
}

// The prime sieve: Daisy-chain filter processes together.
func sieve() {
4908 4909
	ch := make(chan int)  // Create a new channel.
	go generate(ch)       // Start generate() as a subprocess.
4910
	for {
4911 4912 4913 4914 4915
		prime := &lt;-ch
		fmt.Print(prime, "\n")
		ch1 := make(chan int)
		go filter(ch, ch1, prime)
		ch = ch1
4916
	}
4917
}
4918

4919
func main() {
4920
	sieve()
4921 4922
}
</pre>
4923

4924
<h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
4925

4926
<h3 id="The_zero_value">The zero value</h3>
Rob Pike's avatar
Rob Pike committed
4927
<p>
4928
When memory is allocated to store a value, either through a declaration
Rob Pike's avatar
Rob Pike committed
4929 4930
or <code>make()</code> or <code>new()</code> call,
and no explicit initialization is provided, the memory is
4931
given a default initialization.  Each element of such a value is
4932
set to the <i>zero value</i> for its type: <code>false</code> for booleans,
Rob Pike's avatar
Rob Pike committed
4933
<code>0</code> for integers, <code>0.0</code> for floats, <code>""</code>
4934
for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
Rob Pike's avatar
Rob Pike committed
4935
This initialization is done recursively, so for instance each element of an
Rob Pike's avatar
Rob Pike committed
4936 4937
array of structs will have its fields zeroed if no value is specified.
</p>
4938
<p>
4939
These two simple declarations are equivalent:
Rob Pike's avatar
Rob Pike committed
4940
</p>
4941

4942
<pre>
4943 4944
var i int
var i int = 0
4945
</pre>
4946

Rob Pike's avatar
Rob Pike committed
4947
<p>
4948
After
Rob Pike's avatar
Rob Pike committed
4949
</p>
4950

4951
<pre>
4952
type T struct { i int; f float64; next *T }
4953
t := new(T)
4954
</pre>
4955

Rob Pike's avatar
Rob Pike committed
4956
<p>
4957
the following holds:
Rob Pike's avatar
Rob Pike committed
4958
</p>
4959

4960 4961 4962 4963 4964
<pre>
t.i == 0
t.f == 0.0
t.next == nil
</pre>
4965

Rob Pike's avatar
Rob Pike committed
4966 4967 4968 4969 4970 4971 4972 4973
<p>
The same would also be true after
</p>

<pre>
var t T
</pre>

4974
<h3 id="Program_execution">Program execution</h3>
Rob Pike's avatar
Rob Pike committed
4975
<p>
4976
A package with no imports is initialized by assigning initial values to
4977
all its package-level variables
Rob Pike's avatar
Rob Pike committed
4978
and then calling any
Rob Pike's avatar
Rob Pike committed
4979 4980 4981 4982 4983 4984
package-level function with the name and signature of
</p>
<pre>
func init()
</pre>
<p>
4985 4986 4987 4988 4989
defined in its source.
A package may contain multiple
<code>init()</code> functions, even
within a single source file; they execute
in unspecified order.
Rob Pike's avatar
Rob Pike committed
4990
</p>
4991
<p>
4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005
Within a package, package-level variables are initialized,
and constant values are determined, in
data-dependent order: if the initializer of <code>A</code>
depends on the value of <code>B</code>, <code>A</code>
will be set after <code>B</code>.
It is an error if such dependencies form a cycle.
Dependency analysis is done lexically: <code>A</code>
depends on <code>B</code> if the value of <code>A</code>
contains a mention of <code>B</code>, contains a value
whose initializer
mentions <code>B</code>, or mentions a function that
mentions <code>B</code>, recursively.
If two items are not interdependent, they will be initialized
in the order they appear in the source.
Rob Pike's avatar
Rob Pike committed
5006 5007
Since the dependency analysis is done per package, it can produce
unspecified results  if <code>A</code>'s initializer calls a function defined
5008 5009 5010
in another package that refers to <code>B</code>.
</p>
<p>
5011
Initialization code may contain "go" statements, but the functions
5012 5013
they invoke do not begin execution until initialization of the entire
program is complete. Therefore, all initialization code is run in a single
Rob Pike's avatar
Rob Pike committed
5014
goroutine.
Rob Pike's avatar
Rob Pike committed
5015
</p>
5016
<p>
Rob Pike's avatar
Rob Pike committed
5017 5018 5019
An <code>init()</code> function cannot be referred to from anywhere
in a program. In particular, <code>init()</code> cannot be called explicitly,
nor can a pointer to <code>init</code> be assigned to a function variable.
Rob Pike's avatar
Rob Pike committed
5020
</p>
5021
<p>
5022
If a package has imports, the imported packages are initialized
5023
before initializing the package itself. If multiple packages import
Rob Pike's avatar
Rob Pike committed
5024
a package <code>P</code>, <code>P</code> will be initialized only once.
Rob Pike's avatar
Rob Pike committed
5025
</p>
5026
<p>
5027 5028
The importing of packages, by construction, guarantees that there can
be no cyclic dependencies in initialization.
Rob Pike's avatar
Rob Pike committed
5029
</p>
5030
<p>
5031 5032 5033 5034 5035 5036
A complete program is created by linking a single, unimported package
called the <i>main package</i> with all the packages it imports, transitively.
The main package must
have package name <code>main</code> and
declare a function <code>main</code> that takes no 
arguments and returns no value.
Rob Pike's avatar
Rob Pike committed
5037
</p>
5038

5039
<pre>
Rob Pike's avatar
Rob Pike committed
5040
func main() { ... }
5041
</pre>
5042

Rob Pike's avatar
Rob Pike committed
5043
<p>
5044 5045
Program execution begins by initializing the main package and then
invoking the function <code>main</code>.
Rob Pike's avatar
Rob Pike committed
5046
</p>
5047
<p>
5048 5049
When the function <code>main</code> returns, the program exits.
It does not wait for other (non-<code>main</code>) goroutines to complete.
Rob Pike's avatar
Rob Pike committed
5050
</p>
5051

5052
<h2 id="Run_time_panics">Run-time panics</h2>
5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073

<p>
Execution errors such as attempting to index an array out
of bounds trigger a <i>run-time panic</i> equivalent to a call of
the built-in function <a href="#Handling_panics"><code>panic</code></a>
with a value of the implementation-defined interface type <code>runtime.Error</code>.
That type defines at least the method
<code>String() string</code>.  The exact error values that
represent distinct run-time error conditions are unspecified,
at least for now.
</p>

<pre>
package runtime

type Error interface {
	String() string
	// and perhaps others
}
</pre>

5074
<h2 id="System_considerations">System considerations</h2>
5075

5076
<h3 id="Package_unsafe">Package <code>unsafe</code></h3>
5077

5078
<p>
Rob Pike's avatar
Rob Pike committed
5079 5080 5081 5082 5083
The built-in package <code>unsafe</code>, known to the compiler,
provides facilities for low-level programming including operations
that violate the type system. A package using <code>unsafe</code>
must be vetted manually for type safety.  The package provides the
following interface:
5084
</p>
5085

Rob Pike's avatar
Rob Pike committed
5086
<pre class="grammar">
5087
package unsafe
5088

5089 5090
type ArbitraryType int  // shorthand for an arbitrary Go type; it is not a real type
type Pointer *ArbitraryType
5091

5092 5093 5094
func Alignof(variable ArbitraryType) int
func Offsetof(selector ArbitraryType) int
func Sizeof(variable ArbitraryType) int
Rob Pike's avatar
Rob Pike committed
5095

5096 5097
func Reflect(val interface{}) (typ runtime.Type, addr uintptr)
func Typeof(val interface{}) (typ interface{})
Rob Pike's avatar
Rob Pike committed
5098
func Unreflect(typ runtime.Type, addr uintptr) interface{}
5099
</pre>
5100

5101
<p>
5102 5103 5104
Any pointer or value of type <code>uintptr</code> can be converted into
a <code>Pointer</code> and vice versa.
</p>
5105
<p>
5106
The function <code>Sizeof</code> takes an expression denoting a
5107
variable of any type and returns the size of the variable in bytes.
5108
</p>
5109
<p>
5110
The function <code>Offsetof</code> takes a selector (§<a href="#Selectors">Selectors</a>) denoting a struct
5111
field of any type and returns the field offset in bytes relative to the
Rob Pike's avatar
Rob Pike committed
5112 5113
struct's address.
For a struct <code>s</code> with field <code>f</code>:
5114
</p>
5115

5116
<pre>
5117
uintptr(unsafe.Pointer(&amp;s)) + uintptr(unsafe.Offsetof(s.f)) == uintptr(unsafe.Pointer(&amp;s.f))
5118
</pre>
5119

5120
<p>
5121 5122 5123 5124 5125 5126 5127
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>
5128

5129 5130 5131
<pre>
uintptr(unsafe.Pointer(&amp;x)) % uintptr(unsafe.Alignof(x)) == 0
</pre>
5132

5133 5134
<p>
Calls to <code>Alignof</code>, <code>Offsetof</code>, and
Rob Pike's avatar
Rob Pike committed
5135 5136 5137 5138 5139
<code>Sizeof</code> are compile-time constant expressions of type <code>int</code>.
</p>
<p>
The functions <code>unsafe.Typeof</code>,
<code>unsafe.Reflect</code>,
Russ Cox's avatar
Russ Cox committed
5140
and <code>unsafe.Unreflect</code> allow access at run time to the dynamic
Rob Pike's avatar
Rob Pike committed
5141 5142 5143 5144 5145 5146 5147 5148 5149 5150
types and values stored in interfaces.
<code>Typeof</code> returns a representation of
<code>val</code>'s
dynamic type as a <code>runtime.Type</code>.
<code>Reflect</code> allocates a copy of
<code>val</code>'s dynamic
value and returns both the type and the address of the copy.
<code>Unreflect</code> inverts <code>Reflect</code>,
creating an
interface value from a type and address.
5151
The <a href="/pkg/reflect/"><code>reflect</code> package</a> built on these primitives
Rob Pike's avatar
Rob Pike committed
5152
provides a safe, more convenient way to inspect interface values.
5153
</p>
5154

5155

5156
<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
5157

5158
<p>
5159
For the numeric types (§<a href="#Numeric_types">Numeric types</a>), the following sizes are guaranteed:
5160
</p>
5161

Rob Pike's avatar
Rob Pike committed
5162
<pre class="grammar">
5163
type                                 size in bytes
5164

5165 5166 5167 5168 5169
byte, uint8, int8                     1
uint16, int16                         2
uint32, int32, float32                4
uint64, int64, float64, complex64     8
complex128                           16
5170
</pre>
5171

5172
<p>
5173
The following minimal alignment properties are guaranteed:
Rob Pike's avatar
Rob Pike committed
5174
</p>
5175
<ol>
5176
<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
5177
</li>
5178

5179
<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
5180
   all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
5181
</li>
5182

5183 5184
<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
   <code>unsafe.Alignof(x[0])</code>, but at least 1.
5185
</li>
5186
</ol>
5187

Robert Griesemer's avatar
Robert Griesemer committed
5188
<h2 id="Implementation_differences"><span class="alert">Implementation differences - TODO</span></h2>
5189
<ul>
5190 5191 5192 5193
	<li><span class="alert">The restriction on <code>goto</code> statements and targets (no intervening declarations) is not honored.</span></li>
	<li><span class="alert"><code>len(a)</code> is only a constant if <code>a</code> is a (qualified) identifier denoting an array or pointer to an array.</span></li>
	<li><span class="alert"><code>nil</code> maps are not treated like empty maps.</span></li>
	<li><span class="alert">Trying to send/receive from a <code>nil</code> channel causes a run-time panic.</span></li>
5194
</ul>