blob: dcc81ed628717f58c481f7e998dd93bad5ccbb02 [file] [log] [blame]
Andrew Gerrand7cb21a72012-01-19 11:24:54 +11001<!--{
2 "Title": "The Go Programming Language Specification",
Russ Coxb7ba5232018-11-13 10:23:01 -05003 "Subtitle": "Version of November 16, 2018",
Andrew Gerrand48ba6fe2013-10-04 09:45:06 +10004 "Path": "/ref/spec"
Andrew Gerrand7cb21a72012-01-19 11:24:54 +11005}-->
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006
Russ Cox7c4f7cc2009-08-20 11:11:03 -07007<h2 id="Introduction">Introduction</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07008
Robert Griesemerc2d55862009-02-19 16:49:10 -08009<p>
Rob Pike4501d342009-02-19 17:31:36 -080010This is a reference manual for the Go programming language. For
Andrew Gerrand43ad89d2014-07-25 10:28:39 +100011more information and other documents, see <a href="/">golang.org</a>.
Rob Pike4501d342009-02-19 17:31:36 -080012</p>
Robert Griesemer67153582008-12-16 14:45:09 -080013
Robert Griesemerc2d55862009-02-19 16:49:10 -080014<p>
Rob Pike4501d342009-02-19 17:31:36 -080015Go is a general-purpose language designed with systems programming
Rob Pike678625d2009-09-15 09:54:22 -070016in mind. It is strongly typed and garbage-collected and has explicit
Rob Pike4501d342009-02-19 17:31:36 -080017support for concurrent programming. Programs are constructed from
18<i>packages</i>, whose properties allow efficient management of
griesemer0c5b00d2017-10-23 14:08:41 -070019dependencies.
Rob Pike4501d342009-02-19 17:31:36 -080020</p>
21
Robert Griesemerc2d55862009-02-19 16:49:10 -080022<p>
Rob Pike4501d342009-02-19 17:31:36 -080023The grammar is compact and regular, allowing for easy analysis by
24automatic tools such as integrated development environments.
25</p>
Larry Hosken698c6c02009-09-17 08:05:12 -070026
Russ Cox7c4f7cc2009-08-20 11:11:03 -070027<h2 id="Notation">Notation</h2>
Rob Pike4501d342009-02-19 17:31:36 -080028<p>
Robert Griesemer4d230302008-12-17 15:39:15 -080029The syntax is specified using Extended Backus-Naur Form (EBNF):
Rob Pike4501d342009-02-19 17:31:36 -080030</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -070031
Rob Pikeff70f092009-02-20 13:36:14 -080032<pre class="grammar">
Robert Griesemer32b822f2011-05-13 12:54:51 -070033Production = production_name "=" [ Expression ] "." .
Rob Pike4501d342009-02-19 17:31:36 -080034Expression = Alternative { "|" Alternative } .
Robert Griesemerc2d55862009-02-19 16:49:10 -080035Alternative = Term { Term } .
Robert Griesemer3c7271f2011-05-24 14:18:44 -070036Term = production_name | token [ "…" token ] | Group | Option | Repetition .
Rob Pike4501d342009-02-19 17:31:36 -080037Group = "(" Expression ")" .
Rob Pikec956e902009-04-14 20:10:49 -070038Option = "[" Expression "]" .
Rob Pike4501d342009-02-19 17:31:36 -080039Repetition = "{" Expression "}" .
Robert Griesemerc2d55862009-02-19 16:49:10 -080040</pre>
Robert Griesemerbbfe3122008-10-09 17:12:09 -070041
Rob Pike4501d342009-02-19 17:31:36 -080042<p>
43Productions are expressions constructed from terms and the following
44operators, in increasing precedence:
45</p>
Rob Pikeff70f092009-02-20 13:36:14 -080046<pre class="grammar">
Rob Pike4501d342009-02-19 17:31:36 -080047| alternation
48() grouping
49[] option (0 or 1 times)
50{} repetition (0 to n times)
Robert Griesemerc2d55862009-02-19 16:49:10 -080051</pre>
Robert Griesemer4d230302008-12-17 15:39:15 -080052
Robert Griesemerc2d55862009-02-19 16:49:10 -080053<p>
Rob Pike4501d342009-02-19 17:31:36 -080054Lower-case production names are used to identify lexical tokens.
Robert Griesemer7c1cb372012-02-29 10:39:20 -080055Non-terminals are in CamelCase. Lexical tokens are enclosed in
Rob Pike678625d2009-09-15 09:54:22 -070056double quotes <code>""</code> or back quotes <code>``</code>.
Rob Pike4501d342009-02-19 17:31:36 -080057</p>
58
Robert Griesemerc2d55862009-02-19 16:49:10 -080059<p>
Robert Griesemer3c7271f2011-05-24 14:18:44 -070060The form <code>a … b</code> represents the set of characters from
61<code>a</code> through <code>b</code> as alternatives. The horizontal
Jeremy Jackins7e054262012-03-19 08:26:36 +110062ellipsis <code></code> is also used elsewhere in the spec to informally denote various
Rob Pike8040f9b2012-02-13 14:38:31 +110063enumerations or code snippets that are not further specified. The character <code></code>
Robert Griesemer3c7271f2011-05-24 14:18:44 -070064(as opposed to the three characters <code>...</code>) is not a token of the Go
65language.
Rob Pike4501d342009-02-19 17:31:36 -080066</p>
67
Russ Cox7c4f7cc2009-08-20 11:11:03 -070068<h2 id="Source_code_representation">Source code representation</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -070069
Robert Griesemerc2d55862009-02-19 16:49:10 -080070<p>
Robert Griesemere9192752009-12-01 16:15:53 -080071Source code is Unicode text encoded in
Suriyaa Sundararuban1041ac82018-06-13 07:06:04 +000072<a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
Rob Pikeff70f092009-02-20 13:36:14 -080073canonicalized, so a single accented code point is distinct from the
74same character constructed from combining an accent and a letter;
75those are treated as two code points. For simplicity, this document
Rob Pike9dfc6f62012-08-29 14:46:57 -070076will use the unqualified term <i>character</i> to refer to a Unicode code point
77in the source text.
Rob Pikeff70f092009-02-20 13:36:14 -080078</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -080079<p>
Rob Pikeff70f092009-02-20 13:36:14 -080080Each code point is distinct; for instance, upper and lower case letters
81are different characters.
82</p>
Russ Coxb7d9ffe2010-02-16 16:47:18 -080083<p>
Robert Griesemerf42e8832010-02-17 15:50:34 -080084Implementation restriction: For compatibility with other tools, a
85compiler may disallow the NUL character (U+0000) in the source text.
Russ Coxb7d9ffe2010-02-16 16:47:18 -080086</p>
Rob Pikeafac01d2012-09-06 10:37:13 -070087<p>
88Implementation restriction: For compatibility with other tools, a
Rob Pike488350a2012-09-07 10:28:24 -070089compiler may ignore a UTF-8-encoded byte order mark
90(U+FEFF) if it is the first Unicode code point in the source text.
Rob Pike548c65a2013-04-11 11:33:25 -070091A byte order mark may be disallowed anywhere else in the source.
Rob Pikeafac01d2012-09-06 10:37:13 -070092</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -070093
Russ Cox7c4f7cc2009-08-20 11:11:03 -070094<h3 id="Characters">Characters</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -070095
Robert Griesemerc2d55862009-02-19 16:49:10 -080096<p>
Rob Pike4501d342009-02-19 17:31:36 -080097The following terms are used to denote specific Unicode character classes:
98</p>
Robert Griesemerf7ac31362009-07-10 16:06:40 -070099<pre class="ebnf">
Robert Griesemer0e8032c2011-05-05 09:03:00 -0700100newline = /* the Unicode code point U+000A */ .
101unicode_char = /* an arbitrary Unicode code point except newline */ .
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700102unicode_letter = /* a Unicode code point classified as "Letter" */ .
Robert Griesemer212bdd92016-01-05 14:15:49 -0800103unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ .
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700104</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700105
Rob Pike678625d2009-09-15 09:54:22 -0700106<p>
Suriyaa Sundararuban1041ac82018-06-13 07:06:04 +0000107In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>,
Robert Griesemer212bdd92016-01-05 14:15:49 -0800108Section 4.5 "General Category" defines a set of character categories.
109Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo
110as Unicode letters, and those in the Number category Nd as Unicode digits.
Rob Pike678625d2009-09-15 09:54:22 -0700111</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700112
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700113<h3 id="Letters_and_digits">Letters and digits</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800114
115<p>
Rob Pikef27e9f02009-02-23 19:22:05 -0800116The underscore character <code>_</code> (U+005F) is considered a letter.
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700117</p>
118<pre class="ebnf">
Robert Griesemerc2d55862009-02-19 16:49:10 -0800119letter = unicode_letter | "_" .
Robert Griesemer3c7271f2011-05-24 14:18:44 -0700120decimal_digit = "0" … "9" .
121octal_digit = "0" … "7" .
122hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800123</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700124
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700125<h2 id="Lexical_elements">Lexical elements</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700126
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700127<h3 id="Comments">Comments</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700128
Rob Pikeff70f092009-02-20 13:36:14 -0800129<p>
Robert Griesemer37a09752015-05-29 17:36:26 -0700130Comments serve as program documentation. There are two forms:
Rob Pikeff70f092009-02-20 13:36:14 -0800131</p>
132
Robert Griesemer130ac742009-12-10 16:43:01 -0800133<ol>
134<li>
135<i>Line comments</i> start with the character sequence <code>//</code>
Robert Griesemer37a09752015-05-29 17:36:26 -0700136and stop at the end of the line.
Robert Griesemer130ac742009-12-10 16:43:01 -0800137</li>
138<li>
139<i>General comments</i> start with the character sequence <code>/*</code>
Robert Griesemer37a09752015-05-29 17:36:26 -0700140and stop with the first subsequent character sequence <code>*/</code>.
Robert Griesemer130ac742009-12-10 16:43:01 -0800141</li>
142</ol>
143
144<p>
Robert Griesemer37a09752015-05-29 17:36:26 -0700145A comment cannot start inside a <a href="#Rune_literals">rune</a> or
146<a href="#String_literals">string literal</a>, or inside a comment.
147A general comment containing no newlines acts like a space.
148Any other comment acts like a newline.
Robert Griesemer130ac742009-12-10 16:43:01 -0800149</p>
150
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700151<h3 id="Tokens">Tokens</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800152
153<p>
154Tokens form the vocabulary of the Go language.
Robert Griesemereb109a72009-12-28 14:40:42 -0800155There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators
Robert Griesemer26e726c2017-03-10 17:17:23 -0800156and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from
Rob Pike4fe41922009-11-07 22:00:59 -0800157spaces (U+0020), horizontal tabs (U+0009),
158carriage returns (U+000D), and newlines (U+000A),
159is ignored except as it separates tokens
Robert Griesemer0e66a132010-09-27 18:59:11 -0700160that would otherwise combine into a single token. Also, a newline or end of file
Robert Griesemereb109a72009-12-28 14:40:42 -0800161may trigger the insertion of a <a href="#Semicolons">semicolon</a>.
Robert Griesemer130ac742009-12-10 16:43:01 -0800162While breaking the input into tokens,
Rob Pikeff70f092009-02-20 13:36:14 -0800163the next token is the longest sequence of characters that form a
164valid token.
165</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700166
Robert Griesemer130ac742009-12-10 16:43:01 -0800167<h3 id="Semicolons">Semicolons</h3>
168
169<p>
170The formal grammar uses semicolons <code>";"</code> as terminators in
171a number of productions. Go programs may omit most of these semicolons
172using the following two rules:
173</p>
174
175<ol>
176<li>
Robert Griesemer130ac742009-12-10 16:43:01 -0800177When the input is broken into tokens, a semicolon is automatically inserted
Robert Griesemer37a09752015-05-29 17:36:26 -0700178into the token stream immediately after a line's final token if that token is
Robert Griesemer130ac742009-12-10 16:43:01 -0800179<ul>
Robert Griesemer3af480372010-05-14 13:11:48 -0700180 <li>an
181 <a href="#Identifiers">identifier</a>
Robert Griesemer130ac742009-12-10 16:43:01 -0800182 </li>
Charles L. Dorian44262d12011-11-01 15:13:33 +0900183
Robert Griesemer3af480372010-05-14 13:11:48 -0700184 <li>an
185 <a href="#Integer_literals">integer</a>,
186 <a href="#Floating-point_literals">floating-point</a>,
187 <a href="#Imaginary_literals">imaginary</a>,
Rob Pike9dfc6f62012-08-29 14:46:57 -0700188 <a href="#Rune_literals">rune</a>, or
Robert Griesemer3af480372010-05-14 13:11:48 -0700189 <a href="#String_literals">string</a> literal
190 </li>
Charles L. Dorian44262d12011-11-01 15:13:33 +0900191
Robert Griesemer3af480372010-05-14 13:11:48 -0700192 <li>one of the <a href="#Keywords">keywords</a>
193 <code>break</code>,
194 <code>continue</code>,
195 <code>fallthrough</code>, or
196 <code>return</code>
197 </li>
Charles L. Dorian44262d12011-11-01 15:13:33 +0900198
Robert Griesemer26e726c2017-03-10 17:17:23 -0800199 <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a>
Robert Griesemer3af480372010-05-14 13:11:48 -0700200 <code>++</code>,
201 <code>--</code>,
202 <code>)</code>,
203 <code>]</code>, or
204 <code>}</code>
Robert Griesemer130ac742009-12-10 16:43:01 -0800205 </li>
206</ul>
207</li>
208
209<li>
210To allow complex statements to occupy a single line, a semicolon
211may be omitted before a closing <code>")"</code> or <code>"}"</code>.
212</li>
213</ol>
214
215<p>
216To reflect idiomatic use, code examples in this document elide semicolons
217using these rules.
218</p>
219
220
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700221<h3 id="Identifiers">Identifiers</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700222
Rob Pikeff70f092009-02-20 13:36:14 -0800223<p>
224Identifiers name program entities such as variables and types.
225An identifier is a sequence of one or more letters and digits.
226The first character in an identifier must be a letter.
227</p>
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700228<pre class="ebnf">
Robert Griesemerd36d1912009-09-18 11:58:35 -0700229identifier = letter { letter | unicode_digit } .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800230</pre>
Robert Griesemerc2d55862009-02-19 16:49:10 -0800231<pre>
232a
233_x9
234ThisVariableIsExported
235αβ
236</pre>
Robert Griesemer130ac742009-12-10 16:43:01 -0800237
238<p>
Robert Griesemer4e56b332009-09-10 10:14:00 -0700239Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
Robert Griesemer130ac742009-12-10 16:43:01 -0800240</p>
241
Robert Griesemer7a4ed4f2008-09-03 15:15:51 -0700242
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700243<h3 id="Keywords">Keywords</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700244
Rob Pikeff70f092009-02-20 13:36:14 -0800245<p>
246The following keywords are reserved and may not be used as identifiers.
247</p>
248<pre class="grammar">
249break default func interface select
250case defer go map struct
251chan else goto package switch
252const fallthrough if range type
253continue for import return var
254</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700255
Robert Griesemer26e726c2017-03-10 17:17:23 -0800256<h3 id="Operators_and_punctuation">Operators and punctuation</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800257
258<p>
Robert Griesemer26e726c2017-03-10 17:17:23 -0800259The following character sequences represent <a href="#Operators">operators</a>
260(including <a href="#assign_op">assignment operators</a>) and punctuation:
Rob Pikeff70f092009-02-20 13:36:14 -0800261</p>
262<pre class="grammar">
263+ &amp; += &amp;= &amp;&amp; == != ( )
264- | -= |= || &lt; &lt;= [ ]
265* ^ *= ^= &lt;- &gt; &gt;= { }
Robert Griesemer4ed666e2009-08-27 16:45:42 -0700266/ &lt;&lt; /= &lt;&lt;= ++ = := , ;
267% &gt;&gt; %= &gt;&gt;= -- ! ... . :
Robert Griesemer0eb26fa2016-11-18 09:27:18 -0800268 &amp;^ &amp;^=
Rob Pikeff70f092009-02-20 13:36:14 -0800269</pre>
270
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700271<h3 id="Integer_literals">Integer literals</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800272
273<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700274An integer literal is a sequence of digits representing an
275<a href="#Constants">integer constant</a>.
276An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</code> or
Rob Pikef27e9f02009-02-23 19:22:05 -0800277<code>0X</code> for hexadecimal. In hexadecimal literals, letters
278<code>a-f</code> and <code>A-F</code> represent values 10 through 15.
Rob Pikeff70f092009-02-20 13:36:14 -0800279</p>
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700280<pre class="ebnf">
Robert Griesemerd36d1912009-09-18 11:58:35 -0700281int_lit = decimal_lit | octal_lit | hex_lit .
Robert Griesemer3c7271f2011-05-24 14:18:44 -0700282decimal_lit = ( "1" … "9" ) { decimal_digit } .
Robert Griesemerd36d1912009-09-18 11:58:35 -0700283octal_lit = "0" { octal_digit } .
284hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800285</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700286
Robert Griesemerc2d55862009-02-19 16:49:10 -0800287<pre>
28842
2890600
2900xBadFace
291170141183460469231731687303715884105727
292</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700293
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700294<h3 id="Floating-point_literals">Floating-point literals</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800295<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700296A floating-point literal is a decimal representation of a
297<a href="#Constants">floating-point constant</a>.
298It has an integer part, a decimal point, a fractional part,
Rob Pikeff70f092009-02-20 13:36:14 -0800299and an exponent part. The integer and fractional part comprise
Rob Pikef27e9f02009-02-23 19:22:05 -0800300decimal digits; the exponent part is an <code>e</code> or <code>E</code>
Rob Pikeff70f092009-02-20 13:36:14 -0800301followed by an optionally signed decimal exponent. One of the
302integer part or the fractional part may be elided; one of the decimal
303point or the exponent may be elided.
304</p>
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700305<pre class="ebnf">
Robert Griesemerd36d1912009-09-18 11:58:35 -0700306float_lit = decimals "." [ decimals ] [ exponent ] |
307 decimals exponent |
308 "." decimals [ exponent ] .
309decimals = decimal_digit { decimal_digit } .
310exponent = ( "e" | "E" ) [ "+" | "-" ] decimals .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800311</pre>
Robert Griesemerad711102008-09-11 17:48:20 -0700312
Robert Griesemerc2d55862009-02-19 16:49:10 -0800313<pre>
3140.
Rob Pike72970872010-03-04 12:35:16 -080031572.40
316072.40 // == 72.40
Robert Griesemerc2d55862009-02-19 16:49:10 -08003172.71828
3181.e+0
3196.67428e-11
3201E6
321.25
322.12345E+5
323</pre>
Robert Griesemerad711102008-09-11 17:48:20 -0700324
Rob Pike72970872010-03-04 12:35:16 -0800325<h3 id="Imaginary_literals">Imaginary literals</h3>
326<p>
327An imaginary literal is a decimal representation of the imaginary part of a
328<a href="#Constants">complex constant</a>.
329It consists of a
330<a href="#Floating-point_literals">floating-point literal</a>
331or decimal integer followed
332by the lower-case letter <code>i</code>.
333</p>
334<pre class="ebnf">
335imaginary_lit = (decimals | float_lit) "i" .
336</pre>
337
338<pre>
3390i
340011i // == 11i
3410.i
3422.71828i
3431.e+0i
3446.67428e-11i
3451E6i
346.25i
347.12345E+5i
348</pre>
349
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700350
Rob Pike9dfc6f62012-08-29 14:46:57 -0700351<h3 id="Rune_literals">Rune literals</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700352
Rob Pike4501d342009-02-19 17:31:36 -0800353<p>
Rob Pike9dfc6f62012-08-29 14:46:57 -0700354A rune literal represents a <a href="#Constants">rune constant</a>,
355an integer value identifying a Unicode code point.
Robert Griesemer37a09752015-05-29 17:36:26 -0700356A rune literal is expressed as one or more characters enclosed in single quotes,
357as in <code>'x'</code> or <code>'\n'</code>.
358Within the quotes, any character may appear except newline and unescaped single
359quote. A single quoted character represents the Unicode value
Rob Pike9dfc6f62012-08-29 14:46:57 -0700360of the character itself,
Rob Pikeff70f092009-02-20 13:36:14 -0800361while multi-character sequences beginning with a backslash encode
362values in various formats.
Rob Pike4501d342009-02-19 17:31:36 -0800363</p>
Rob Pikeff70f092009-02-20 13:36:14 -0800364<p>
365The simplest form represents the single character within the quotes;
366since Go source text is Unicode characters encoded in UTF-8, multiple
367UTF-8-encoded bytes may represent a single integer value. For
Rob Pikef27e9f02009-02-23 19:22:05 -0800368instance, the literal <code>'a'</code> holds a single byte representing
369a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while
370<code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing
371a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>.
Rob Pikeff70f092009-02-20 13:36:14 -0800372</p>
373<p>
Rob Pike9dfc6f62012-08-29 14:46:57 -0700374Several backslash escapes allow arbitrary values to be encoded as
Oling Cat845f4d62012-09-05 14:53:13 +1000375ASCII text. There are four ways to represent the integer value
Rob Pikef27e9f02009-02-23 19:22:05 -0800376as a numeric constant: <code>\x</code> followed by exactly two hexadecimal
377digits; <code>\u</code> followed by exactly four hexadecimal digits;
378<code>\U</code> followed by exactly eight hexadecimal digits, and a
379plain backslash <code>\</code> followed by exactly three octal digits.
Rob Pikeff70f092009-02-20 13:36:14 -0800380In each case the value of the literal is the value represented by
381the digits in the corresponding base.
382</p>
383<p>
384Although these representations all result in an integer, they have
385different valid ranges. Octal escapes must represent a value between
Rob Pike678625d2009-09-15 09:54:22 -07003860 and 255 inclusive. Hexadecimal escapes satisfy this condition
387by construction. The escapes <code>\u</code> and <code>\U</code>
Rob Pikeff70f092009-02-20 13:36:14 -0800388represent Unicode code points so within them some values are illegal,
Rob Pikef27e9f02009-02-23 19:22:05 -0800389in particular those above <code>0x10FFFF</code> and surrogate halves.
Rob Pikeff70f092009-02-20 13:36:14 -0800390</p>
391<p>
392After a backslash, certain single-character escapes represent special values:
393</p>
394<pre class="grammar">
395\a U+0007 alert or bell
396\b U+0008 backspace
397\f U+000C form feed
398\n U+000A line feed or newline
399\r U+000D carriage return
400\t U+0009 horizontal tab
401\v U+000b vertical tab
402\\ U+005c backslash
Rob Pike9dfc6f62012-08-29 14:46:57 -0700403\' U+0027 single quote (valid escape only within rune literals)
Rob Pikeff70f092009-02-20 13:36:14 -0800404\" U+0022 double quote (valid escape only within string literals)
Robert Griesemerc2d55862009-02-19 16:49:10 -0800405</pre>
Robert Griesemerc2d55862009-02-19 16:49:10 -0800406<p>
Rob Pike9dfc6f62012-08-29 14:46:57 -0700407All other sequences starting with a backslash are illegal inside rune literals.
Rob Pike4501d342009-02-19 17:31:36 -0800408</p>
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700409<pre class="ebnf">
Robert Griesemerc863db42013-01-07 18:02:58 -0800410rune_lit = "'" ( unicode_value | byte_value ) "'" .
Rob Pikeff70f092009-02-20 13:36:14 -0800411unicode_value = unicode_char | little_u_value | big_u_value | escaped_char .
412byte_value = octal_byte_value | hex_byte_value .
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700413octal_byte_value = `\` octal_digit octal_digit octal_digit .
414hex_byte_value = `\` "x" hex_digit hex_digit .
415little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit .
416big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit
Rob Pikeff70f092009-02-20 13:36:14 -0800417 hex_digit hex_digit hex_digit hex_digit .
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700418escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
Rob Pikeff70f092009-02-20 13:36:14 -0800419</pre>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700420
Robert Griesemerc2d55862009-02-19 16:49:10 -0800421<pre>
422'a'
423'ä'
424'本'
425'\t'
426'\000'
427'\007'
428'\377'
429'\x07'
430'\xff'
431'\u12e4'
432'\U00101234'
Robert Griesemer37a09752015-05-29 17:36:26 -0700433'\'' // rune literal containing single quote character
Rob Pike9dfc6f62012-08-29 14:46:57 -0700434'aa' // illegal: too many characters
435'\xa' // illegal: too few hexadecimal digits
436'\0' // illegal: too few octal digits
437'\uDFFF' // illegal: surrogate half
438'\U00110000' // illegal: invalid Unicode code point
Robert Griesemerc2d55862009-02-19 16:49:10 -0800439</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700440
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700441
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700442<h3 id="String_literals">String literals</h3>
Rob Pikeff70f092009-02-20 13:36:14 -0800443
444<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700445A string literal represents a <a href="#Constants">string constant</a>
446obtained from concatenating a sequence of characters. There are two forms:
447raw string literals and interpreted string literals.
Rob Pikeff70f092009-02-20 13:36:14 -0800448</p>
449<p>
Robert Griesemer37a09752015-05-29 17:36:26 -0700450Raw string literals are character sequences between back quotes, as in
451<code>`foo`</code>. Within the quotes, any character may appear except
Robert Griesemerdb7a6222009-06-18 13:51:14 -0700452back quote. The value of a raw string literal is the
Rob Pike9dfc6f62012-08-29 14:46:57 -0700453string composed of the uninterpreted (implicitly UTF-8-encoded) characters
454between the quotes;
Robert Griesemerdb7a6222009-06-18 13:51:14 -0700455in particular, backslashes have no special meaning and the string may
Robert Griesemer11b7c892011-12-15 10:51:51 -0800456contain newlines.
Ian Lance Taylor2a627da2014-05-16 12:20:03 -0700457Carriage return characters ('\r') inside raw string literals
Rob Pikec26ca912011-12-14 21:52:41 -0800458are discarded from the raw string value.
Rob Pikeff70f092009-02-20 13:36:14 -0800459</p>
460<p>
461Interpreted string literals are character sequences between double
Robert Griesemer37a09752015-05-29 17:36:26 -0700462quotes, as in <code>&quot;bar&quot;</code>.
463Within the quotes, any character may appear except newline and unescaped double quote.
464The text between the quotes forms the
Rob Pikeff70f092009-02-20 13:36:14 -0800465value of the literal, with backslash escapes interpreted as they
Robin Eklindf82097f2014-09-03 10:44:33 -0700466are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and
Rob Pike9dfc6f62012-08-29 14:46:57 -0700467<code>\"</code> is legal), with the same restrictions.
468The three-digit octal (<code>\</code><i>nnn</i>)
Robert Griesemere9192752009-12-01 16:15:53 -0800469and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
Rob Pikeff70f092009-02-20 13:36:14 -0800470<i>bytes</i> of the resulting string; all other escapes represent
471the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
Rob Pikef27e9f02009-02-23 19:22:05 -0800472Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent
473a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>,
474<code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent
Robert Griesemere1e76192009-09-25 14:11:03 -0700475the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
Rob Pikeff70f092009-02-20 13:36:14 -0800476U+00FF.
477</p>
478
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700479<pre class="ebnf">
Rob Pikeff70f092009-02-20 13:36:14 -0800480string_lit = raw_string_lit | interpreted_string_lit .
Robert Griesemer0e8032c2011-05-05 09:03:00 -0700481raw_string_lit = "`" { unicode_char | newline } "`" .
Robert Griesemerd4d4ff02009-10-19 13:13:59 -0700482interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800483</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700484
Robert Griesemerc2d55862009-02-19 16:49:10 -0800485<pre>
Robert Griesemer37a09752015-05-29 17:36:26 -0700486`abc` // same as "abc"
Robert Griesemerdb7a6222009-06-18 13:51:14 -0700487`\n
Robert Griesemer37a09752015-05-29 17:36:26 -0700488\n` // same as "\\n\n\\n"
Robert Griesemerc2d55862009-02-19 16:49:10 -0800489"\n"
Robert Griesemer37a09752015-05-29 17:36:26 -0700490"\"" // same as `"`
Robert Griesemerc2d55862009-02-19 16:49:10 -0800491"Hello, world!\n"
492"日本語"
493"\u65e5本\U00008a9e"
494"\xff\u00FF"
Robert Griesemer37a09752015-05-29 17:36:26 -0700495"\uD800" // illegal: surrogate half
496"\U00110000" // illegal: invalid Unicode code point
Robert Griesemerc2d55862009-02-19 16:49:10 -0800497</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700498
Rob Pikeff70f092009-02-20 13:36:14 -0800499<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700500These examples all represent the same string:
Rob Pikeff70f092009-02-20 13:36:14 -0800501</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700502
Robert Griesemerc2d55862009-02-19 16:49:10 -0800503<pre>
Rob Pikeff70f092009-02-20 13:36:14 -0800504"日本語" // UTF-8 input text
505`日本語` // UTF-8 input text as a raw literal
Rob Pike9dfc6f62012-08-29 14:46:57 -0700506"\u65e5\u672c\u8a9e" // the explicit Unicode code points
507"\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points
508"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes
Robert Griesemerc2d55862009-02-19 16:49:10 -0800509</pre>
Robert Griesemercd499272008-09-29 12:09:00 -0700510
Robert Griesemerc2d55862009-02-19 16:49:10 -0800511<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700512If the source code represents a character as two code points, such as
513a combining form involving an accent and a letter, the result will be
Rob Pike9dfc6f62012-08-29 14:46:57 -0700514an error if placed in a rune literal (it is not a single code
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700515point), and will appear as two code points if placed in a string
516literal.
Rob Pikeff70f092009-02-20 13:36:14 -0800517</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700518
Robert Griesemer19b1d352009-09-24 19:36:48 -0700519
520<h2 id="Constants">Constants</h2>
521
Russ Coxa9336352011-12-08 21:48:19 -0500522<p>There are <i>boolean constants</i>,
Rob Pike9dfc6f62012-08-29 14:46:57 -0700523<i>rune constants</i>,
Russ Coxa9336352011-12-08 21:48:19 -0500524<i>integer constants</i>,
Rob Pike72970872010-03-04 12:35:16 -0800525<i>floating-point constants</i>, <i>complex constants</i>,
Robert Griesemerf3310122013-07-25 09:35:55 -0700526and <i>string constants</i>. Rune, integer, floating-point,
Rob Pike72970872010-03-04 12:35:16 -0800527and complex constants are
Robert Griesemer19b1d352009-09-24 19:36:48 -0700528collectively called <i>numeric constants</i>.
529</p>
Rob Pike678625d2009-09-15 09:54:22 -0700530
531<p>
Russ Coxa9336352011-12-08 21:48:19 -0500532A constant value is represented by a
Rob Pike9dfc6f62012-08-29 14:46:57 -0700533<a href="#Rune_literals">rune</a>,
Robert Griesemer19b1d352009-09-24 19:36:48 -0700534<a href="#Integer_literals">integer</a>,
535<a href="#Floating-point_literals">floating-point</a>,
Rob Pike72970872010-03-04 12:35:16 -0800536<a href="#Imaginary_literals">imaginary</a>,
Russ Coxa9336352011-12-08 21:48:19 -0500537or
Robert Griesemer19b1d352009-09-24 19:36:48 -0700538<a href="#String_literals">string</a> literal,
539an identifier denoting a constant,
Robert Griesemer27693562011-06-13 16:47:33 -0700540a <a href="#Constant_expressions">constant expression</a>,
541a <a href="#Conversions">conversion</a> with a result that is a constant, or
Russ Coxf4429182010-07-01 17:49:47 -0700542the result value of some built-in functions such as
543<code>unsafe.Sizeof</code> applied to any value,
544<code>cap</code> or <code>len</code> applied to
545<a href="#Length_and_capacity">some expressions</a>,
Rob Pike72970872010-03-04 12:35:16 -0800546<code>real</code> and <code>imag</code> applied to a complex constant
Robert Griesemerb94c0d22011-01-19 23:07:21 -0500547and <code>complex</code> applied to numeric constants.
Robert Griesemer19b1d352009-09-24 19:36:48 -0700548The boolean truth values are represented by the predeclared constants
549<code>true</code> and <code>false</code>. The predeclared identifier
550<a href="#Iota">iota</a> denotes an integer constant.
Rob Pike678625d2009-09-15 09:54:22 -0700551</p>
552
Robert Griesemer19b1d352009-09-24 19:36:48 -0700553<p>
Rob Pike72970872010-03-04 12:35:16 -0800554In general, complex constants are a form of
555<a href="#Constant_expressions">constant expression</a>
556and are discussed in that section.
557</p>
558
559<p>
Robert Griesemer55ecda42015-09-17 18:10:20 -0700560Numeric constants represent exact values of arbitrary precision and do not overflow.
561Consequently, there are no constants denoting the IEEE-754 negative zero, infinity,
562and not-a-number values.
Robert Griesemer19b1d352009-09-24 19:36:48 -0700563</p>
564
565<p>
Robert Griesemer47094dc2014-09-30 11:44:29 -0700566Constants may be <a href="#Types">typed</a> or <i>untyped</i>.
Robert Griesemer19b1d352009-09-24 19:36:48 -0700567Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>,
568and certain <a href="#Constant_expressions">constant expressions</a>
569containing only untyped constant operands are untyped.
570</p>
571
572<p>
573A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a>
574or <a href="#Conversions">conversion</a>, or implicitly when used in a
575<a href="#Variable_declarations">variable declaration</a> or an
576<a href="#Assignments">assignment</a> or as an
577operand in an <a href="#Expressions">expression</a>.
578It is an error if the constant value
griesemerb40831b2017-08-21 15:47:51 +0200579cannot be <a href="#Representability">represented</a> as a value of the respective type.
Robert Griesemer19b1d352009-09-24 19:36:48 -0700580</p>
581
582<p>
Robert Griesemer47094dc2014-09-30 11:44:29 -0700583An untyped constant has a <i>default type</i> which is the type to which the
584constant is implicitly converted in contexts where a typed value is required,
585for instance, in a <a href="#Short_variable_declarations">short variable declaration</a>
586such as <code>i := 0</code> where there is no explicit type.
587The default type of an untyped constant is <code>bool</code>, <code>rune</code>,
588<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code>
589respectively, depending on whether it is a boolean, rune, integer, floating-point,
590complex, or string constant.
591</p>
592
593<p>
Ian Lance Taylor9126c652012-02-13 11:25:56 -0800594Implementation restriction: Although numeric constants have arbitrary
595precision in the language, a compiler may implement them using an
596internal representation with limited precision. That said, every
597implementation must:
Robert Griesemer19b1d352009-09-24 19:36:48 -0700598</p>
Ian Lance Taylor9126c652012-02-13 11:25:56 -0800599<ul>
600 <li>Represent integer constants with at least 256 bits.</li>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700601
Ian Lance Taylor9126c652012-02-13 11:25:56 -0800602 <li>Represent floating-point constants, including the parts of
603 a complex constant, with a mantissa of at least 256 bits
Robert Griesemer8fbfdad2015-12-10 11:18:41 -0800604 and a signed binary exponent of at least 16 bits.</li>
Ian Lance Taylor9126c652012-02-13 11:25:56 -0800605
606 <li>Give an error if unable to represent an integer constant
607 precisely.</li>
608
609 <li>Give an error if unable to represent a floating-point or
610 complex constant due to overflow.</li>
611
612 <li>Round to the nearest representable constant if unable to
613 represent a floating-point or complex constant due to limits
614 on precision.</li>
615</ul>
616<p>
617These requirements apply both to literal constants and to the result
618of evaluating <a href="#Constant_expressions">constant
619expressions</a>.
620</p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700621
Robert Griesemer6962c152014-10-16 15:08:49 -0700622<h2 id="Variables">Variables</h2>
623
624<p>
625A variable is a storage location for holding a <i>value</i>.
626The set of permissible values is determined by the
627variable's <i><a href="#Types">type</a></i>.
628</p>
629
630<p>
631A <a href="#Variable_declarations">variable declaration</a>
632or, for function parameters and results, the signature
633of a <a href="#Function_declarations">function declaration</a>
634or <a href="#Function_literals">function literal</a> reserves
635storage for a named variable.
636
637Calling the built-in function <a href="#Allocation"><code>new</code></a>
638or taking the address of a <a href="#Composite_literals">composite literal</a>
639allocates storage for a variable at run time.
640Such an anonymous variable is referred to via a (possibly implicit)
641<a href="#Address_operators">pointer indirection</a>.
642</p>
643
644<p>
645<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>,
646and <a href="#Struct_types">struct</a> types have elements and fields that may
647be <a href="#Address_operators">addressed</a> individually. Each such element
648acts like a variable.
649</p>
650
651<p>
Robert Griesemer2d9378c2015-07-27 13:30:16 -0700652The <i>static type</i> (or just <i>type</i>) of a variable is the
Robert Griesemer6962c152014-10-16 15:08:49 -0700653type given in its declaration, the type provided in the
654<code>new</code> call or composite literal, or the type of
655an element of a structured variable.
656Variables of interface type also have a distinct <i>dynamic type</i>,
657which is the concrete type of the value assigned to the variable at run time
658(unless the value is the predeclared identifier <code>nil</code>,
659which has no type).
660The dynamic type may vary during execution but values stored in interface
661variables are always <a href="#Assignability">assignable</a>
Robert Griesemer2d9378c2015-07-27 13:30:16 -0700662to the static type of the variable.
663</p>
Robert Griesemer6962c152014-10-16 15:08:49 -0700664
665<pre>
666var x interface{} // x is nil and has static type interface{}
667var v *T // v has value nil, static type *T
668x = 42 // x has value 42 and dynamic type int
669x = v // x has value (*T)(nil) and dynamic type *T
670</pre>
671
672<p>
673A variable's value is retrieved by referring to the variable in an
674<a href="#Expressions">expression</a>; it is the most recent value
675<a href="#Assignments">assigned</a> to the variable.
676If a variable has not yet been assigned a value, its value is the
677<a href="#The_zero_value">zero value</a> for its type.
678</p>
679
680
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700681<h2 id="Types">Types</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700682
Robert Griesemerc2d55862009-02-19 16:49:10 -0800683<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -0800684A type determines a set of values together with operations and methods specific
685to those values. A type may be denoted by a <i>type name</i>, if it has one,
686or specified using a <i>type literal</i>, which composes a type from existing types.
Rob Pike5af7de32009-02-24 15:17:59 -0800687</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700688
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700689<pre class="ebnf">
Rob Pike8f2330d2009-02-25 16:20:44 -0800690Type = TypeName | TypeLit | "(" Type ")" .
Robert Griesemer809e06b2012-06-26 11:49:19 -0700691TypeName = identifier | QualifiedIdent .
Rob Pike8f2330d2009-02-25 16:20:44 -0800692TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
693 SliceType | MapType | ChannelType .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800694</pre>
Robert Griesemer434c6052008-11-07 13:34:37 -0800695
Robert Griesemerc2d55862009-02-19 16:49:10 -0800696<p>
Robert Griesemer9b49ac02018-01-22 16:20:01 -0800697The language <a href="#Predeclared_identifiers">predeclares</a> certain type names.
698Others are introduced with <a href="#Type_declarations">type declarations</a>.
Robert Griesemerfc61b772009-09-28 14:10:20 -0700699<i>Composite types</i>&mdash;array, struct, pointer, function,
700interface, slice, map, and channel types&mdash;may be constructed using
701type literals.
Rob Pike5af7de32009-02-24 15:17:59 -0800702</p>
Robert Griesemer7abfcd92008-10-07 17:14:30 -0700703
Rob Pike5af7de32009-02-24 15:17:59 -0800704<p>
Robert Griesemer7bc03712010-06-07 15:49:39 -0700705Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
Robert Griesemer8d77d2c2014-03-05 19:37:44 -0800706is one of the predeclared boolean, numeric, or string types, or a type literal,
707the corresponding underlying
Robert Griesemer7bc03712010-06-07 15:49:39 -0700708type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type
709is the underlying type of the type to which <code>T</code> refers in its
710<a href="#Type_declarations">type declaration</a>.
711</p>
712
713<pre>
Robert Griesemer56c9b512017-02-02 15:43:56 -0800714type (
715 A1 = string
716 A2 = A1
717)
718
719type (
720 B1 string
721 B2 B1
722 B3 []B1
723 B4 B3
724)
Robert Griesemer7bc03712010-06-07 15:49:39 -0700725</pre>
726
727<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -0800728The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>,
729and <code>B2</code> is <code>string</code>.
730The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>.
Robert Griesemer7bc03712010-06-07 15:49:39 -0700731</p>
732
Robert Griesemer2a838d62011-02-08 13:31:01 -0800733<h3 id="Method_sets">Method sets</h3>
Robert Griesemer7bc03712010-06-07 15:49:39 -0700734<p>
Robert Griesemer2c83f1e2014-05-22 12:23:25 -0700735A type may have a <i>method set</i> associated with it.
Robert Griesemer19b1d352009-09-24 19:36:48 -0700736The method set of an <a href="#Interface_types">interface type</a> is its interface.
Robert Griesemer2c83f1e2014-05-22 12:23:25 -0700737The method set of any other type <code>T</code> consists of all
738<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>.
739The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code>
740is the set of all methods declared with receiver <code>*T</code> or <code>T</code>
Robert Griesemer56809d02009-05-20 11:02:48 -0700741(that is, it also contains the method set of <code>T</code>).
Robert Griesemerf8b41232017-01-10 16:19:14 -0800742Further rules apply to structs containing embedded fields, as described
Robert Griesemer787adb62012-06-04 14:24:10 -0700743in the section on <a href="#Struct_types">struct types</a>.
Robert Griesemer56809d02009-05-20 11:02:48 -0700744Any other type has an empty method set.
Robert Griesemer103c9db2012-03-01 13:57:49 -0800745In a method set, each method must have a
Robert Griesemer2c83f1e2014-05-22 12:23:25 -0700746<a href="#Uniqueness_of_identifiers">unique</a>
747non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>.
Rob Pike5af7de32009-02-24 15:17:59 -0800748</p>
Robert Griesemer1f3e8422008-09-29 18:41:30 -0700749
Russ Coxfd2a5112012-02-08 14:28:51 -0500750<p>
751The method set of a type determines the interfaces that the
752type <a href="#Interface_types">implements</a>
753and the methods that can be <a href="#Calls">called</a>
754using a receiver of that type.
755</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700756
Robert Griesemer19b1d352009-09-24 19:36:48 -0700757<h3 id="Boolean_types">Boolean types</h3>
758
Stefan Nilssonc50074e2012-02-29 15:07:52 -0800759<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700760A <i>boolean type</i> represents the set of Boolean truth values
761denoted by the predeclared constants <code>true</code>
griesemer4a2391e2017-09-19 14:35:15 +0200762and <code>false</code>. The predeclared boolean type is <code>bool</code>;
763it is a <a href="#Type_definitions">defined type</a>.
Stefan Nilssonc50074e2012-02-29 15:07:52 -0800764</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700765
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700766<h3 id="Numeric_types">Numeric types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700767
Rob Pike5af7de32009-02-24 15:17:59 -0800768<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700769A <i>numeric type</i> represents sets of integer or floating-point values.
770The predeclared architecture-independent numeric types are:
Rob Pike5af7de32009-02-24 15:17:59 -0800771</p>
Robert Griesemerebf14c62008-10-30 14:50:23 -0700772
Rob Pikeff70f092009-02-20 13:36:14 -0800773<pre class="grammar">
Rob Pike72970872010-03-04 12:35:16 -0800774uint8 the set of all unsigned 8-bit integers (0 to 255)
775uint16 the set of all unsigned 16-bit integers (0 to 65535)
776uint32 the set of all unsigned 32-bit integers (0 to 4294967295)
777uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615)
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700778
Rob Pike72970872010-03-04 12:35:16 -0800779int8 the set of all signed 8-bit integers (-128 to 127)
780int16 the set of all signed 16-bit integers (-32768 to 32767)
781int32 the set of all signed 32-bit integers (-2147483648 to 2147483647)
782int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700783
Rob Pike72970872010-03-04 12:35:16 -0800784float32 the set of all IEEE-754 32-bit floating-point numbers
785float64 the set of all IEEE-754 64-bit floating-point numbers
786
787complex64 the set of all complex numbers with float32 real and imaginary parts
788complex128 the set of all complex numbers with float64 real and imaginary parts
Rob Pike5af7de32009-02-24 15:17:59 -0800789
Robert Griesemerb910a272011-11-01 01:09:22 -0400790byte alias for uint8
Russ Coxd7f050a2011-12-09 00:11:43 -0500791rune alias for int32
Robert Griesemerc2d55862009-02-19 16:49:10 -0800792</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700793
Rob Pike5af7de32009-02-24 15:17:59 -0800794<p>
Robert Griesemere9192752009-12-01 16:15:53 -0800795The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
Suriyaa Sundararuban1041ac82018-06-13 07:06:04 +0000796<a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
Rob Pike5af7de32009-02-24 15:17:59 -0800797</p>
Robert Griesemer9dfb2ea2008-12-12 10:30:10 -0800798
Rob Pike5af7de32009-02-24 15:17:59 -0800799<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700800There is also a set of predeclared numeric types with implementation-specific sizes:
Rob Pike5af7de32009-02-24 15:17:59 -0800801</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700802
Rob Pikeff70f092009-02-20 13:36:14 -0800803<pre class="grammar">
Robert Griesemercfe92112009-06-18 13:29:40 -0700804uint either 32 or 64 bits
Robert Griesemer97025eb2011-01-13 10:24:04 -0800805int same size as uint
Robert Griesemercfe92112009-06-18 13:29:40 -0700806uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value
Robert Griesemerc2d55862009-02-19 16:49:10 -0800807</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700808
Robert Griesemerc2d55862009-02-19 16:49:10 -0800809<p>
griesemer4a2391e2017-09-19 14:35:15 +0200810To avoid portability issues all numeric types are <a href="#Type_definitions">defined
811types</a> and thus distinct except
812<code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and
Russ Coxd7f050a2011-12-09 00:11:43 -0500813<code>rune</code>, which is an alias for <code>int32</code>.
Robert Griesemer26d22602018-10-02 15:55:38 -0700814Explicit conversions
Robert Griesemer7bc03712010-06-07 15:49:39 -0700815are required when different numeric types are mixed in an expression
Rob Pike5af7de32009-02-24 15:17:59 -0800816or assignment. For instance, <code>int32</code> and <code>int</code>
Russ Cox5958dd62009-03-04 17:19:21 -0800817are not the same type even though they may have the same size on a
Rob Pike5af7de32009-02-24 15:17:59 -0800818particular architecture.
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700819
820
Robert Griesemer19b1d352009-09-24 19:36:48 -0700821<h3 id="String_types">String types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700822
Rob Pike4501d342009-02-19 17:31:36 -0800823<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -0700824A <i>string type</i> represents the set of string values.
Robert Griesemercc065932012-09-14 11:31:56 -0700825A string value is a (possibly empty) sequence of bytes.
Robert Griesemerde578dc2018-11-12 11:25:58 -0800826The number of bytes is called the length of the string and is never negative.
Robert Griesemercc065932012-09-14 11:31:56 -0700827Strings are immutable: once created,
Rob Pike5af7de32009-02-24 15:17:59 -0800828it is impossible to change the contents of a string.
griesemer4a2391e2017-09-19 14:35:15 +0200829The predeclared string type is <code>string</code>;
830it is a <a href="#Type_definitions">defined type</a>.
Robert Griesemercc065932012-09-14 11:31:56 -0700831</p>
Rob Pike5af7de32009-02-24 15:17:59 -0800832
833<p>
Robert Griesemerde578dc2018-11-12 11:25:58 -0800834The length of a string <code>s</code> can be discovered using
Robert Griesemercc065932012-09-14 11:31:56 -0700835the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
836The length is a compile-time constant if the string is a constant.
Robert Griesemer9c9e8112012-12-10 11:55:57 -0800837A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a>
8380 through <code>len(s)-1</code>.
Robert Griesemercc065932012-09-14 11:31:56 -0700839It is illegal to take the address of such an element; if
840<code>s[i]</code> is the <code>i</code>'th byte of a
841string, <code>&amp;s[i]</code> is invalid.
Rob Pike4501d342009-02-19 17:31:36 -0800842</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700843
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700844
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700845<h3 id="Array_types">Array types</h3>
Russ Cox461dd912009-03-04 14:44:51 -0800846
847<p>
848An array is a numbered sequence of elements of a single
Robert Griesemer4023dce2009-08-14 17:41:52 -0700849type, called the element type.
Robert Griesemerde578dc2018-11-12 11:25:58 -0800850The number of elements is called the length of the array and is never negative.
Russ Cox461dd912009-03-04 14:44:51 -0800851</p>
852
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700853<pre class="ebnf">
Russ Cox461dd912009-03-04 14:44:51 -0800854ArrayType = "[" ArrayLength "]" ElementType .
855ArrayLength = Expression .
Robert Griesemer4023dce2009-08-14 17:41:52 -0700856ElementType = Type .
Russ Cox461dd912009-03-04 14:44:51 -0800857</pre>
858
859<p>
Robert Griesemer2c83f1e2014-05-22 12:23:25 -0700860The length is part of the array's type; it must evaluate to a
griesemerb40831b2017-08-21 15:47:51 +0200861non-negative <a href="#Constants">constant</a>
862<a href="#Representability">representable</a> by a value
Robert Griesemer39067062012-12-12 11:06:26 -0800863of type <code>int</code>.
864The length of array <code>a</code> can be discovered
Robert Griesemercc065932012-09-14 11:31:56 -0700865using the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
Robert Griesemer9c9e8112012-12-10 11:55:57 -0800866The elements can be addressed by integer <a href="#Index_expressions">indices</a>
Robert Griesemer39067062012-12-12 11:06:26 -08008670 through <code>len(a)-1</code>.
Rob Pikeff6a8fd2009-11-20 15:47:15 -0800868Array types are always one-dimensional but may be composed to form
869multi-dimensional types.
Russ Cox461dd912009-03-04 14:44:51 -0800870</p>
871
872<pre>
873[32]byte
874[2*N] struct { x, y int32 }
875[1000]*float64
Rob Pikeff6a8fd2009-11-20 15:47:15 -0800876[3][5]int
877[2][2][2]float64 // same as [2]([2]([2]float64))
Russ Cox461dd912009-03-04 14:44:51 -0800878</pre>
879
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700880<h3 id="Slice_types">Slice types</h3>
Russ Cox461dd912009-03-04 14:44:51 -0800881
882<p>
Robert Griesemer15da9972013-10-16 16:16:54 -0700883A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
Robert Griesemerb34f0552013-04-02 23:17:37 -0700884provides access to a numbered sequence of elements from that array.
885A slice type denotes the set of all slices of arrays of its element type.
Robert Griesemerde578dc2018-11-12 11:25:58 -0800886The number of elements is called the length of the slice and is never negative.
Robert Griesemer7bc03712010-06-07 15:49:39 -0700887The value of an uninitialized slice is <code>nil</code>.
Russ Cox461dd912009-03-04 14:44:51 -0800888</p>
889
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700890<pre class="ebnf">
Russ Cox461dd912009-03-04 14:44:51 -0800891SliceType = "[" "]" ElementType .
892</pre>
893
894<p>
Robert Griesemerde578dc2018-11-12 11:25:58 -0800895The length of a slice <code>s</code> can be discovered by the built-in function
Robert Griesemercc065932012-09-14 11:31:56 -0700896<a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during
Robert Griesemer9c9e8112012-12-10 11:55:57 -0800897execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a>
8980 through <code>len(s)-1</code>. The slice index of a
Russ Cox461dd912009-03-04 14:44:51 -0800899given element may be less than the index of the same element in the
900underlying array.
901</p>
902<p>
903A slice, once initialized, is always associated with an underlying
Rob Pike7ec08562010-01-09 07:32:26 +1100904array that holds its elements. A slice therefore shares storage
Russ Cox461dd912009-03-04 14:44:51 -0800905with its array and with other slices of the same array; by contrast,
906distinct arrays always represent distinct storage.
907</p>
908<p>
909The array underlying a slice may extend past the end of the slice.
Russ Cox5958dd62009-03-04 17:19:21 -0800910The <i>capacity</i> is a measure of that extent: it is the sum of
Russ Cox461dd912009-03-04 14:44:51 -0800911the length of the slice and the length of the array beyond the slice;
Robert Griesemer462a17e2013-03-22 15:36:04 -0700912a slice of length up to that capacity can be created by
Robert Griesemere333b962013-09-11 17:18:52 -0700913<a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
Russ Cox461dd912009-03-04 14:44:51 -0800914The capacity of a slice <code>a</code> can be discovered using the
Robert Griesemer0c2e6b32010-07-13 11:54:57 -0700915built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
Russ Cox461dd912009-03-04 14:44:51 -0800916</p>
917
Russ Cox461dd912009-03-04 14:44:51 -0800918<p>
Robert Griesemer0c2e6b32010-07-13 11:54:57 -0700919A new, initialized slice value for a given element type <code>T</code> is
920made using the built-in function
921<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
922which takes a slice type
Robert Griesemer15da9972013-10-16 16:16:54 -0700923and parameters specifying the length and optionally the capacity.
924A slice created with <code>make</code> always allocates a new, hidden array
925to which the returned slice value refers. That is, executing
Russ Cox461dd912009-03-04 14:44:51 -0800926</p>
927
928<pre>
929make([]T, length, capacity)
930</pre>
931
932<p>
Robert Griesemer15da9972013-10-16 16:16:54 -0700933produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
934it, so these two expressions are equivalent:
Russ Cox461dd912009-03-04 14:44:51 -0800935</p>
936
937<pre>
938make([]int, 50, 100)
939new([100]int)[0:50]
940</pre>
941
Rob Pikeff6a8fd2009-11-20 15:47:15 -0800942<p>
943Like arrays, slices are always one-dimensional but may be composed to construct
944higher-dimensional objects.
945With arrays of arrays, the inner arrays are, by construction, always the same length;
Robert Griesemer15da9972013-10-16 16:16:54 -0700946however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
947Moreover, the inner slices must be initialized individually.
Rob Pikeff6a8fd2009-11-20 15:47:15 -0800948</p>
Russ Cox461dd912009-03-04 14:44:51 -0800949
Russ Cox7c4f7cc2009-08-20 11:11:03 -0700950<h3 id="Struct_types">Struct types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700951
Rob Pike5af7de32009-02-24 15:17:59 -0800952<p>
Robert Griesemerd3b15652009-11-16 08:58:55 -0800953A struct is a sequence of named elements, called fields, each of which has a
954name and a type. Field names may be specified explicitly (IdentifierList) or
Robert Griesemerf8b41232017-01-10 16:19:14 -0800955implicitly (EmbeddedField).
Robert Griesemerd3b15652009-11-16 08:58:55 -0800956Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
Robert Griesemer103c9db2012-03-01 13:57:49 -0800957be <a href="#Uniqueness_of_identifiers">unique</a>.
Rob Pike5af7de32009-02-24 15:17:59 -0800958</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700959
Robert Griesemerf7ac31362009-07-10 16:06:40 -0700960<pre class="ebnf">
Robert Griesemerf8b41232017-01-10 16:19:14 -0800961StructType = "struct" "{" { FieldDecl ";" } "}" .
962FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] .
963EmbeddedField = [ "*" ] TypeName .
964Tag = string_lit .
Robert Griesemerc2d55862009-02-19 16:49:10 -0800965</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700966
Robert Griesemerc2d55862009-02-19 16:49:10 -0800967<pre>
968// An empty struct.
969struct {}
Robert Griesemerdf49fb32008-08-28 17:47:53 -0700970
Robert Griesemer4e56b332009-09-10 10:14:00 -0700971// A struct with 6 fields.
Robert Griesemerc2d55862009-02-19 16:49:10 -0800972struct {
Robert Griesemer130ac742009-12-10 16:43:01 -0800973 x, y int
Robert Griesemerb94c0d22011-01-19 23:07:21 -0500974 u float32
975 _ float32 // padding
Robert Griesemer130ac742009-12-10 16:43:01 -0800976 A *[]int
977 F func()
Robert Griesemerc2d55862009-02-19 16:49:10 -0800978}
979</pre>
Robert Griesemer1f3e8422008-09-29 18:41:30 -0700980
Rob Pike5af7de32009-02-24 15:17:59 -0800981<p>
Robert Griesemerf8b41232017-01-10 16:19:14 -0800982A field declared with a type but no explicit field name is called an <i>embedded field</i>.
983An embedded field must be specified as
Russ Coxbee2d5b2010-09-30 14:59:41 -0400984a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
Ian Lance Taylor3e804ba2009-08-17 11:40:57 -0700985and <code>T</code> itself may not be
Robert Griesemerd3b15652009-11-16 08:58:55 -0800986a pointer type. The unqualified type name acts as the field name.
Rob Pike5af7de32009-02-24 15:17:59 -0800987</p>
Robert Griesemer1f3e8422008-09-29 18:41:30 -0700988
Robert Griesemerc2d55862009-02-19 16:49:10 -0800989<pre>
Robert Griesemerf8b41232017-01-10 16:19:14 -0800990// A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4
Robert Griesemerc2d55862009-02-19 16:49:10 -0800991struct {
Robert Griesemer130ac742009-12-10 16:43:01 -0800992 T1 // field name is T1
993 *T2 // field name is T2
994 P.T3 // field name is T3
995 *P.T4 // field name is T4
996 x, y int // field names are x and y
Robert Griesemerc2d55862009-02-19 16:49:10 -0800997}
998</pre>
Robert Griesemer1f3e8422008-09-29 18:41:30 -0700999
Rob Pike5af7de32009-02-24 15:17:59 -08001000<p>
Robert Griesemerd3b15652009-11-16 08:58:55 -08001001The following declaration is illegal because field names must be unique
1002in a struct type:
Rob Pike5af7de32009-02-24 15:17:59 -08001003</p>
Robert Griesemer071c91b2008-10-23 12:04:45 -07001004
Robert Griesemerc2d55862009-02-19 16:49:10 -08001005<pre>
1006struct {
Robert Griesemerf8b41232017-01-10 16:19:14 -08001007 T // conflicts with embedded field *T and *P.T
1008 *T // conflicts with embedded field T and *P.T
1009 *P.T // conflicts with embedded field T and *T
Robert Griesemerc2d55862009-02-19 16:49:10 -08001010}
1011</pre>
Robert Griesemer1f3e8422008-09-29 18:41:30 -07001012
Robert Griesemerc2d55862009-02-19 16:49:10 -08001013<p>
Robert Griesemer787adb62012-06-04 14:24:10 -07001014A field or <a href="#Method_declarations">method</a> <code>f</code> of an
Robert Griesemerf8b41232017-01-10 16:19:14 -08001015embedded field in a struct <code>x</code> is called <i>promoted</i> if
Robert Griesemer787adb62012-06-04 14:24:10 -07001016<code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes
1017that field or method <code>f</code>.
1018</p>
1019
1020<p>
1021Promoted fields act like ordinary fields
1022of a struct except that they cannot be used as field names in
1023<a href="#Composite_literals">composite literals</a> of the struct.
1024</p>
1025
1026<p>
Robert Griesemer9b49ac02018-01-22 16:20:01 -08001027Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a>
1028<code>T</code>, promoted methods are included in the method set of the struct as follows:
Rob Pike5af7de32009-02-24 15:17:59 -08001029</p>
Robert Griesemer56809d02009-05-20 11:02:48 -07001030<ul>
Robert Griesemer787adb62012-06-04 14:24:10 -07001031 <li>
Robert Griesemerf8b41232017-01-10 16:19:14 -08001032 If <code>S</code> contains an embedded field <code>T</code>,
Robert Griesemer787adb62012-06-04 14:24:10 -07001033 the <a href="#Method_sets">method sets</a> of <code>S</code>
1034 and <code>*S</code> both include promoted methods with receiver
1035 <code>T</code>. The method set of <code>*S</code> also
1036 includes promoted methods with receiver <code>*T</code>.
Robert Griesemer56809d02009-05-20 11:02:48 -07001037 </li>
Robin Eklind1d46fc42012-12-11 12:17:53 -05001038
Robert Griesemer787adb62012-06-04 14:24:10 -07001039 <li>
Robert Griesemerf8b41232017-01-10 16:19:14 -08001040 If <code>S</code> contains an embedded field <code>*T</code>,
Robert Griesemer787adb62012-06-04 14:24:10 -07001041 the method sets of <code>S</code> and <code>*S</code> both
1042 include promoted methods with receiver <code>T</code> or
1043 <code>*T</code>.
Robert Griesemer56809d02009-05-20 11:02:48 -07001044 </li>
1045</ul>
Robert Griesemer787adb62012-06-04 14:24:10 -07001046
Rob Pike5af7de32009-02-24 15:17:59 -08001047<p>
Robert Griesemer56809d02009-05-20 11:02:48 -07001048A field declaration may be followed by an optional string literal <i>tag</i>,
Robert Griesemerd3b15652009-11-16 08:58:55 -08001049which becomes an attribute for all the fields in the corresponding
Robert Griesemer0436a892016-04-22 16:35:29 -07001050field declaration. An empty tag string is equivalent to an absent tag.
1051The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a>
Emil Hessman13141312014-01-03 22:48:03 -08001052and take part in <a href="#Type_identity">type identity</a> for structs
Rob Pike5af7de32009-02-24 15:17:59 -08001053but are otherwise ignored.
1054</p>
Robert Griesemer2e90e542008-10-30 15:52:37 -07001055
Robert Griesemerc2d55862009-02-19 16:49:10 -08001056<pre>
Robert Griesemerc2d55862009-02-19 16:49:10 -08001057struct {
Robert Griesemer7305b552015-11-30 14:18:09 -08001058 x, y float64 "" // an empty tag string is like an absent tag
1059 name string "any string is permitted as a tag"
1060 _ [4]byte "ceci n'est pas un champ de structure"
1061}
1062
1063// A struct corresponding to a TimeStamp protocol buffer.
1064// The tag strings define the protocol buffer field numbers;
1065// they follow the convention outlined by the reflect package.
1066struct {
1067 microsec uint64 `protobuf:"1"`
1068 serverIP6 uint64 `protobuf:"2"`
Robert Griesemerc2d55862009-02-19 16:49:10 -08001069}
1070</pre>
Robert Griesemer2e90e542008-10-30 15:52:37 -07001071
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001072<h3 id="Pointer_types">Pointer types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001073
Rob Pike5af7de32009-02-24 15:17:59 -08001074<p>
Robert Griesemer6962c152014-10-16 15:08:49 -07001075A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given
Rob Pikeda389742009-03-02 19:13:40 -08001076type, called the <i>base type</i> of the pointer.
Peter Mundy5928e1d2010-11-09 10:10:57 -08001077The value of an uninitialized pointer is <code>nil</code>.
Rob Pike5af7de32009-02-24 15:17:59 -08001078</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001079
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001080<pre class="ebnf">
Robert Griesemerc2d55862009-02-19 16:49:10 -08001081PointerType = "*" BaseType .
Robin Eklindcac006a2014-08-30 10:27:01 -07001082BaseType = Type .
Robert Griesemerc2d55862009-02-19 16:49:10 -08001083</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001084
Robert Griesemerc2d55862009-02-19 16:49:10 -08001085<pre>
Robert Griesemer953f2de2012-03-01 10:35:15 -08001086*Point
1087*[4]int
Robert Griesemerc2d55862009-02-19 16:49:10 -08001088</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001089
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001090<h3 id="Function_types">Function types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001091
Rob Pike8f2330d2009-02-25 16:20:44 -08001092<p>
Robert Griesemer7231ceb2008-09-08 15:01:04 -07001093A function type denotes the set of all functions with the same parameter
Peter Mundy5928e1d2010-11-09 10:10:57 -08001094and result types. The value of an uninitialized variable of function type
Robert Griesemer7bc03712010-06-07 15:49:39 -07001095is <code>nil</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001096</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001097
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001098<pre class="ebnf">
Rob Pike8f2330d2009-02-25 16:20:44 -08001099FunctionType = "func" Signature .
1100Signature = Parameters [ Result ] .
Robert Griesemer4023dce2009-08-14 17:41:52 -07001101Result = Parameters | Type .
Robert Griesemer130ac742009-12-10 16:43:01 -08001102Parameters = "(" [ ParameterList [ "," ] ] ")" .
Rob Pike8f2330d2009-02-25 16:20:44 -08001103ParameterList = ParameterDecl { "," ParameterDecl } .
Russ Cox95625922010-06-12 11:37:13 -07001104ParameterDecl = [ IdentifierList ] [ "..." ] Type .
Robert Griesemerc2d55862009-02-19 16:49:10 -08001105</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001106
Robert Griesemerc2d55862009-02-19 16:49:10 -08001107<p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001108Within a list of parameters or results, the names (IdentifierList)
1109must either all be present or all be absent. If present, each name
Robert Griesemer85e451e2012-11-29 14:47:47 -08001110stands for one item (parameter or result) of the specified type and
1111all non-<a href="#Blank_identifier">blank</a> names in the signature
1112must be <a href="#Uniqueness_of_identifiers">unique</a>.
1113If absent, each type stands for one item of that type.
1114Parameter and result
Rob Pike8f2330d2009-02-25 16:20:44 -08001115lists are always parenthesized except that if there is exactly
Robert Griesemer73ca1272010-07-09 13:02:54 -07001116one unnamed result it may be written as an unparenthesized type.
Rob Pike8f2330d2009-02-25 16:20:44 -08001117</p>
Russ Cox95625922010-06-12 11:37:13 -07001118
Robert Griesemerac771a82010-09-24 14:08:28 -07001119<p>
Robert Griesemer57c81ef2015-12-15 13:13:38 -08001120The final incoming parameter in a function signature may have
Robert Griesemerac771a82010-09-24 14:08:28 -07001121a type prefixed with <code>...</code>.
1122A function with such a parameter is called <i>variadic</i> and
1123may be invoked with zero or more arguments for that parameter.
Rob Pike8f2330d2009-02-25 16:20:44 -08001124</p>
Robert Griesemer2bfa9572008-10-24 13:13:12 -07001125
Robert Griesemerc2d55862009-02-19 16:49:10 -08001126<pre>
Russ Cox46871692010-01-26 10:25:56 -08001127func()
Robert Griesemer953f2de2012-03-01 10:35:15 -08001128func(x int) int
1129func(a, _ int, z float32) bool
Robert Griesemerb94c0d22011-01-19 23:07:21 -05001130func(a, b int, z float32) (bool)
Robert Griesemer953f2de2012-03-01 10:35:15 -08001131func(prefix string, values ...int)
Robert Griesemerb94c0d22011-01-19 23:07:21 -05001132func(a, b int, z float64, opt ...interface{}) (success bool)
1133func(int, int, float64) (float64, *[]int)
Russ Cox46871692010-01-26 10:25:56 -08001134func(n int) func(p *T)
Robert Griesemerc2d55862009-02-19 16:49:10 -08001135</pre>
Robert Griesemer2b9fe0e2009-01-30 14:48:29 -08001136
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001137
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001138<h3 id="Interface_types">Interface types</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001139
Rob Pike8f2330d2009-02-25 16:20:44 -08001140<p>
Robert Griesemer2a838d62011-02-08 13:31:01 -08001141An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>.
Robert Griesemer56809d02009-05-20 11:02:48 -07001142A variable of interface type can store a value of any type with a method set
1143that is any superset of the interface. Such a type is said to
Robert Griesemer7bc03712010-06-07 15:49:39 -07001144<i>implement the interface</i>.
Peter Mundy5928e1d2010-11-09 10:10:57 -08001145The value of an uninitialized variable of interface type is <code>nil</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001146</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001147
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001148<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08001149InterfaceType = "interface" "{" { MethodSpec ";" } "}" .
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07001150MethodSpec = MethodName Signature | InterfaceTypeName .
1151MethodName = identifier .
Rob Pike8f2330d2009-02-25 16:20:44 -08001152InterfaceTypeName = TypeName .
Robert Griesemerc2d55862009-02-19 16:49:10 -08001153</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001154
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07001155<p>
Robert Griesemer103c9db2012-03-01 13:57:49 -08001156As with all method sets, in an interface type, each method must have a
Robert Griesemer2c83f1e2014-05-22 12:23:25 -07001157<a href="#Uniqueness_of_identifiers">unique</a>
1158non-<a href="#Blank_identifier">blank</a> name.
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07001159</p>
1160
Robert Griesemerc2d55862009-02-19 16:49:10 -08001161<pre>
Rob Pike8f2330d2009-02-25 16:20:44 -08001162// A simple File interface
Robert Griesemerc2d55862009-02-19 16:49:10 -08001163interface {
Robert Griesemer130ac742009-12-10 16:43:01 -08001164 Read(b Buffer) bool
1165 Write(b Buffer) bool
1166 Close()
Robert Griesemerc2d55862009-02-19 16:49:10 -08001167}
1168</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001169
Rob Pike8f2330d2009-02-25 16:20:44 -08001170<p>
Robert Griesemer56809d02009-05-20 11:02:48 -07001171More than one type may implement an interface.
Rob Pike8f2330d2009-02-25 16:20:44 -08001172For instance, if two types <code>S1</code> and <code>S2</code>
Robert Griesemer56809d02009-05-20 11:02:48 -07001173have the method set
Rob Pike8f2330d2009-02-25 16:20:44 -08001174</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001175
Robert Griesemerc2d55862009-02-19 16:49:10 -08001176<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07001177func (p T) Read(b Buffer) bool { return … }
1178func (p T) Write(b Buffer) bool { return … }
1179func (p T) Close() { … }
Robert Griesemerc2d55862009-02-19 16:49:10 -08001180</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001181
Rob Pike8f2330d2009-02-25 16:20:44 -08001182<p>
1183(where <code>T</code> stands for either <code>S1</code> or <code>S2</code>)
1184then the <code>File</code> interface is implemented by both <code>S1</code> and
1185<code>S2</code>, regardless of what other methods
1186<code>S1</code> and <code>S2</code> may have or share.
1187</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001188
Rob Pike8f2330d2009-02-25 16:20:44 -08001189<p>
1190A type implements any interface comprising any subset of its methods
1191and may therefore implement several distinct interfaces. For
1192instance, all types implement the <i>empty interface</i>:
1193</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001194
Robert Griesemerc2d55862009-02-19 16:49:10 -08001195<pre>
Robert Griesemer19b1d352009-09-24 19:36:48 -07001196interface{}
Robert Griesemerc2d55862009-02-19 16:49:10 -08001197</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001198
Rob Pike8f2330d2009-02-25 16:20:44 -08001199<p>
1200Similarly, consider this interface specification,
Robert Griesemer4ed666e2009-08-27 16:45:42 -07001201which appears within a <a href="#Type_declarations">type declaration</a>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001202to define an interface called <code>Locker</code>:
Rob Pike8f2330d2009-02-25 16:20:44 -08001203</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001204
Robert Griesemerc2d55862009-02-19 16:49:10 -08001205<pre>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001206type Locker interface {
Robert Griesemer130ac742009-12-10 16:43:01 -08001207 Lock()
1208 Unlock()
Robert Griesemerc2d55862009-02-19 16:49:10 -08001209}
1210</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001211
Rob Pike8f2330d2009-02-25 16:20:44 -08001212<p>
1213If <code>S1</code> and <code>S2</code> also implement
1214</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001215
Robert Griesemerc2d55862009-02-19 16:49:10 -08001216<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07001217func (p T) Lock() { … }
1218func (p T) Unlock() { … }
Robert Griesemerc2d55862009-02-19 16:49:10 -08001219</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07001220
Robert Griesemerc2d55862009-02-19 16:49:10 -08001221<p>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001222they implement the <code>Locker</code> interface as well
Rob Pike8f2330d2009-02-25 16:20:44 -08001223as the <code>File</code> interface.
1224</p>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001225
Rob Pike8f2330d2009-02-25 16:20:44 -08001226<p>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001227An interface <code>T</code> may use a (possibly qualified) interface type
1228name <code>E</code> in place of a method specification. This is called
1229<i>embedding</i> interface <code>E</code> in <code>T</code>; it adds
1230all (exported and non-exported) methods of <code>E</code> to the interface
1231<code>T</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001232</p>
Robert Griesemer38c232f2009-02-11 15:09:15 -08001233
Robert Griesemerc2d55862009-02-19 16:49:10 -08001234<pre>
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001235type ReadWriter interface {
Robert Griesemer130ac742009-12-10 16:43:01 -08001236 Read(b Buffer) bool
1237 Write(b Buffer) bool
Robert Griesemerc2d55862009-02-19 16:49:10 -08001238}
Robert Griesemer38c232f2009-02-11 15:09:15 -08001239
Robert Griesemerc2d55862009-02-19 16:49:10 -08001240type File interface {
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001241 ReadWriter // same as adding the methods of ReadWriter
1242 Locker // same as adding the methods of Locker
Robert Griesemer130ac742009-12-10 16:43:01 -08001243 Close()
Robert Griesemerc2d55862009-02-19 16:49:10 -08001244}
Robert Griesemerbb29c5a2014-09-25 12:49:42 -07001245
1246type LockedFile interface {
1247 Locker
1248 File // illegal: Lock, Unlock not unique
1249 Lock() // illegal: Lock not unique
1250}
Robert Griesemerc2d55862009-02-19 16:49:10 -08001251</pre>
Robert Griesemer38c232f2009-02-11 15:09:15 -08001252
Russ Cox388816a2012-02-08 14:35:00 -05001253<p>
Russ Cox7c5d6402012-02-08 15:37:58 -05001254An interface type <code>T</code> may not embed itself
1255or any interface type that embeds <code>T</code>, recursively.
Russ Cox388816a2012-02-08 14:35:00 -05001256</p>
1257
1258<pre>
1259// illegal: Bad cannot embed itself
1260type Bad interface {
1261 Bad
1262}
1263
1264// illegal: Bad1 cannot embed itself using Bad2
1265type Bad1 interface {
1266 Bad2
1267}
1268type Bad2 interface {
1269 Bad1
1270}
1271</pre>
1272
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001273<h3 id="Map_types">Map types</h3>
Robert Griesemera3294712009-01-05 11:17:26 -08001274
Rob Pike8f2330d2009-02-25 16:20:44 -08001275<p>
1276A map is an unordered group of elements of one type, called the
Robert Griesemer0660d242009-11-15 17:42:27 -08001277element type, indexed by a set of unique <i>keys</i> of another type,
Robert Griesemer4023dce2009-08-14 17:41:52 -07001278called the key type.
Robert Griesemer7bc03712010-06-07 15:49:39 -07001279The value of an uninitialized map is <code>nil</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001280</p>
Robert Griesemera3294712009-01-05 11:17:26 -08001281
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001282<pre class="ebnf">
Robert Griesemer19b1d352009-09-24 19:36:48 -07001283MapType = "map" "[" KeyType "]" ElementType .
Robert Griesemer4023dce2009-08-14 17:41:52 -07001284KeyType = Type .
Robert Griesemerc2d55862009-02-19 16:49:10 -08001285</pre>
Robert Griesemera3294712009-01-05 11:17:26 -08001286
Robert Griesemerc2d55862009-02-19 16:49:10 -08001287<p>
Robert Griesemer462a17e2013-03-22 15:36:04 -07001288The <a href="#Comparison_operators">comparison operators</a>
1289<code>==</code> and <code>!=</code> must be fully defined
Robert Griesemer9c3d8762012-01-30 15:31:33 -08001290for operands of the key type; thus the key type must not be a function, map, or
1291slice.
Robert Griesemer1d282a82010-06-03 16:55:50 -07001292If the key type is an interface type, these
Rob Pike8f2330d2009-02-25 16:20:44 -08001293comparison operators must be defined for the dynamic key values;
Rob Pike5bb29fb2010-03-25 17:59:59 -07001294failure will cause a <a href="#Run_time_panics">run-time panic</a>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001295
1296</p>
Robert Griesemera3294712009-01-05 11:17:26 -08001297
Robert Griesemerc2d55862009-02-19 16:49:10 -08001298<pre>
David Symonds72a29792011-11-29 15:47:36 -08001299map[string]int
1300map[*T]struct{ x, y float64 }
1301map[string]interface{}
Robert Griesemerc2d55862009-02-19 16:49:10 -08001302</pre>
Robert Griesemera3294712009-01-05 11:17:26 -08001303
Rob Pike5af7de32009-02-24 15:17:59 -08001304<p>
Robert Griesemer0c2e6b32010-07-13 11:54:57 -07001305The number of map elements is called its length.
1306For a map <code>m</code>, it can be discovered using the
Robert Griesemercc065932012-09-14 11:31:56 -07001307built-in function <a href="#Length_and_capacity"><code>len</code></a>
Robert Griesemer3e0c0a82011-10-17 12:53:10 -07001308and may change during execution. Elements may be added during execution
1309using <a href="#Assignments">assignments</a> and retrieved with
Robert Griesemer9c9e8112012-12-10 11:55:57 -08001310<a href="#Index_expressions">index expressions</a>; they may be removed with the
Robert Griesemer3e0c0a82011-10-17 12:53:10 -07001311<a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function.
Rob Pike5af7de32009-02-24 15:17:59 -08001312</p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001313<p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001314A new, empty map value is made using the built-in
Robert Griesemer0c2e6b32010-07-13 11:54:57 -07001315function <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
1316which takes the map type and an optional capacity hint as arguments:
Rob Pike8f2330d2009-02-25 16:20:44 -08001317</p>
1318
1319<pre>
David Symonds72a29792011-11-29 15:47:36 -08001320make(map[string]int)
1321make(map[string]int, 100)
Rob Pike8f2330d2009-02-25 16:20:44 -08001322</pre>
Robert Griesemera3294712009-01-05 11:17:26 -08001323
Rob Pikeda389742009-03-02 19:13:40 -08001324<p>
1325The initial capacity does not bound its size:
1326maps grow to accommodate the number of items
Robert Griesemer54731032011-05-12 09:15:59 -07001327stored in them, with the exception of <code>nil</code> maps.
1328A <code>nil</code> map is equivalent to an empty map except that no elements
1329may be added.
Rob Pikeda389742009-03-02 19:13:40 -08001330
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001331<h3 id="Channel_types">Channel types</h3>
Robert Griesemera3294712009-01-05 11:17:26 -08001332
Rob Pike8f2330d2009-02-25 16:20:44 -08001333<p>
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001334A channel provides a mechanism for
1335<a href="#Go_statements">concurrently executing functions</a>
1336to communicate by
1337<a href="#Send_statements">sending</a> and
1338<a href="#Receive_operator">receiving</a>
1339values of a specified element type.
Robert Griesemer7bc03712010-06-07 15:49:39 -07001340The value of an uninitialized channel is <code>nil</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08001341</p>
Robert Griesemera3294712009-01-05 11:17:26 -08001342
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001343<pre class="ebnf">
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001344ChannelType = ( "chan" | "chan" "&lt;-" | "&lt;-" "chan" ) ElementType .
Robert Griesemerc2d55862009-02-19 16:49:10 -08001345</pre>
Robert Griesemera3294712009-01-05 11:17:26 -08001346
Rob Pike8f2330d2009-02-25 16:20:44 -08001347<p>
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001348The optional <code>&lt;-</code> operator specifies the channel <i>direction</i>,
Robert Griesemer56ca6972010-05-07 18:22:40 -07001349<i>send</i> or <i>receive</i>. If no direction is given, the channel is
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001350<i>bidirectional</i>.
Russ Coxb7ba5232018-11-13 10:23:01 -05001351A channel may be constrained only to send or only to receive by
1352<a href="#Assignments">assignment</a> or
1353explicit <a href="#Conversions">conversion</a>.
Robert Griesemer56ca6972010-05-07 18:22:40 -07001354</p>
1355
1356<pre>
David Symonds72a29792011-11-29 15:47:36 -08001357chan T // can be used to send and receive values of type T
1358chan&lt;- float64 // can only be used to send float64s
1359&lt;-chan int // can only be used to receive ints
Robert Griesemer56ca6972010-05-07 18:22:40 -07001360</pre>
1361
1362<p>
1363The <code>&lt;-</code> operator associates with the leftmost <code>chan</code>
1364possible:
Robert Griesemer1c369bd2010-01-27 09:35:39 -08001365</p>
1366
1367<pre>
David Symonds72a29792011-11-29 15:47:36 -08001368chan&lt;- chan int // same as chan&lt;- (chan int)
1369chan&lt;- &lt;-chan int // same as chan&lt;- (&lt;-chan int)
1370&lt;-chan &lt;-chan int // same as &lt;-chan (&lt;-chan int)
Robert Griesemer1c369bd2010-01-27 09:35:39 -08001371chan (&lt;-chan int)
1372</pre>
1373
1374<p>
Robert Griesemer7bc03712010-06-07 15:49:39 -07001375A new, initialized channel
Robert Griesemer56ca6972010-05-07 18:22:40 -07001376value can be made using the built-in function
1377<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001378which takes the channel type and an optional <i>capacity</i> as arguments:
Rob Pike8f2330d2009-02-25 16:20:44 -08001379</p>
Robert Griesemera3294712009-01-05 11:17:26 -08001380
Robert Griesemerc2d55862009-02-19 16:49:10 -08001381<pre>
Rob Pikeda389742009-03-02 19:13:40 -08001382make(chan int, 100)
Robert Griesemerc2d55862009-02-19 16:49:10 -08001383</pre>
Robert Griesemera3294712009-01-05 11:17:26 -08001384
Rob Pike8f2330d2009-02-25 16:20:44 -08001385<p>
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001386The capacity, in number of elements, sets the size of the buffer in the channel.
1387If the capacity is zero or absent, the channel is unbuffered and communication
Robert Griesemer61d8a332014-05-14 11:47:19 -07001388succeeds only when both a sender and receiver are ready. Otherwise, the channel
1389is buffered and communication succeeds without blocking if the buffer
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001390is not full (sends) or not empty (receives).
Robert Griesemer54731032011-05-12 09:15:59 -07001391A <code>nil</code> channel is never ready for communication.
Rob Pike8f2330d2009-02-25 16:20:44 -08001392</p>
Robert Griesemera3294712009-01-05 11:17:26 -08001393
Rob Pike94b67eb2009-03-24 17:40:47 -07001394<p>
Russ Cox9f2cb862011-03-11 14:47:02 -05001395A channel may be closed with the built-in function
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001396<a href="#Close"><code>close</code></a>.
1397The multi-valued assignment form of the
Russ Cox9f2cb862011-03-11 14:47:02 -05001398<a href="#Receive_operator">receive operator</a>
Robert Griesemer97aa90d2014-05-07 10:40:39 -07001399reports whether a received value was sent before
1400the channel was closed.
1401</p>
1402
1403<p>
1404A single channel may be used in
1405<a href="#Send_statements">send statements</a>,
1406<a href="#Receive_operator">receive operations</a>,
1407and calls to the built-in functions
1408<a href="#Length_and_capacity"><code>cap</code></a> and
1409<a href="#Length_and_capacity"><code>len</code></a>
1410by any number of goroutines without further synchronization.
1411Channels act as first-in-first-out queues.
1412For example, if one goroutine sends values on a channel
1413and a second goroutine receives them, the values are
1414received in the order sent.
Rob Pike94b67eb2009-03-24 17:40:47 -07001415</p>
1416
Rob Pike83cbca52009-08-21 14:18:08 -07001417<h2 id="Properties_of_types_and_values">Properties of types and values</h2>
Robert Griesemer434c6052008-11-07 13:34:37 -08001418
Robert Griesemer7bc03712010-06-07 15:49:39 -07001419<h3 id="Type_identity">Type identity</h3>
1420
Rob Pike4501d342009-02-19 17:31:36 -08001421<p>
Robert Griesemer7bc03712010-06-07 15:49:39 -07001422Two types are either <i>identical</i> or <i>different</i>.
Robert Griesemer19b1d352009-09-24 19:36:48 -07001423</p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001424
Robert Griesemerc2d55862009-02-19 16:49:10 -08001425<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001426A <a href="#Type_definitions">defined type</a> is always different from any other type.
1427Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are
1428structurally equivalent; that is, they have the same literal structure and corresponding
1429components have identical types. In detail:
Rob Pike4501d342009-02-19 17:31:36 -08001430</p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001431
Robert Griesemerc2d55862009-02-19 16:49:10 -08001432<ul>
Robert Griesemer533dfd62009-05-13 16:56:00 -07001433 <li>Two array types are identical if they have identical element types and
1434 the same array length.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001435
Robert Griesemer533dfd62009-05-13 16:56:00 -07001436 <li>Two slice types are identical if they have identical element types.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001437
Robert Griesemer533dfd62009-05-13 16:56:00 -07001438 <li>Two struct types are identical if they have the same sequence of fields,
Russ Coxe4953512010-06-21 12:42:33 -07001439 and if corresponding fields have the same names, and identical types,
1440 and identical tags.
Robert Griesemerf8b41232017-01-10 16:19:14 -08001441 <a href="#Exported_identifiers">Non-exported</a> field names from different
1442 packages are always different.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001443
Robert Griesemer533dfd62009-05-13 16:56:00 -07001444 <li>Two pointer types are identical if they have identical base types.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001445
Robert Griesemer533dfd62009-05-13 16:56:00 -07001446 <li>Two function types are identical if they have the same number of parameters
Russ Cox95625922010-06-12 11:37:13 -07001447 and result values, corresponding parameter and result types are
1448 identical, and either both functions are variadic or neither is.
Robert Griesemer533dfd62009-05-13 16:56:00 -07001449 Parameter and result names are not required to match.</li>
Robert Griesemera3294712009-01-05 11:17:26 -08001450
Robert Griesemer533dfd62009-05-13 16:56:00 -07001451 <li>Two interface types are identical if they have the same set of methods
Robert Griesemerf8b41232017-01-10 16:19:14 -08001452 with the same names and identical function types.
1453 <a href="#Exported_identifiers">Non-exported</a> method names from different
1454 packages are always different. The order of the methods is irrelevant.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001455
Robert Griesemer4de1d1d2018-01-03 10:33:11 -08001456 <li>Two map types are identical if they have identical key and element types.</li>
Robert Griesemer434c6052008-11-07 13:34:37 -08001457
Robert Griesemer4de1d1d2018-01-03 10:33:11 -08001458 <li>Two channel types are identical if they have identical element types and
Robert Griesemer533dfd62009-05-13 16:56:00 -07001459 the same direction.</li>
Robert Griesemerc2d55862009-02-19 16:49:10 -08001460</ul>
Robert Griesemer434c6052008-11-07 13:34:37 -08001461
Robert Griesemerc2d55862009-02-19 16:49:10 -08001462<p>
Rob Pike8f2330d2009-02-25 16:20:44 -08001463Given the declarations
1464</p>
Robert Griesemer434c6052008-11-07 13:34:37 -08001465
Robert Griesemerc2d55862009-02-19 16:49:10 -08001466<pre>
1467type (
Robert Griesemer56c9b512017-02-02 15:43:56 -08001468 A0 = []string
1469 A1 = A0
1470 A2 = struct{ a, b int }
1471 A3 = int
1472 A4 = func(A3, float64) *A0
1473 A5 = func(x int, _ float64) *[]string
Robert Griesemerc2d55862009-02-19 16:49:10 -08001474)
Robert Griesemer56c9b512017-02-02 15:43:56 -08001475
1476type (
1477 B0 A0
1478 B1 []string
1479 B2 struct{ a, b int }
1480 B3 struct{ a, c int }
1481 B4 func(int, float64) *B0
1482 B5 func(x int, y float64) *A1
1483)
1484
1485type C0 = B0
Robert Griesemerc2d55862009-02-19 16:49:10 -08001486</pre>
Robert Griesemer434c6052008-11-07 13:34:37 -08001487
Rob Pike8f2330d2009-02-25 16:20:44 -08001488<p>
Robert Griesemer533dfd62009-05-13 16:56:00 -07001489these types are identical:
Rob Pike8f2330d2009-02-25 16:20:44 -08001490</p>
Robert Griesemer434c6052008-11-07 13:34:37 -08001491
Robert Griesemerc2d55862009-02-19 16:49:10 -08001492<pre>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001493A0, A1, and []string
1494A2 and struct{ a, b int }
1495A3 and int
1496A4, func(int, float64) *[]string, and A5
1497
Robert Griesemerc13e0e82018-01-11 10:41:03 -08001498B0 and C0
Robert Griesemerc2d55862009-02-19 16:49:10 -08001499[]int and []int
David Symonds72a29792011-11-29 15:47:36 -08001500struct{ a, b *T5 } and struct{ a, b *T5 }
Robert Griesemer56c9b512017-02-02 15:43:56 -08001501func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5
Robert Griesemerc2d55862009-02-19 16:49:10 -08001502</pre>
Robert Griesemer434c6052008-11-07 13:34:37 -08001503
Rob Pike8f2330d2009-02-25 16:20:44 -08001504<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001505<code>B0</code> and <code>B1</code> are different because they are new types
1506created by distinct <a href="#Type_definitions">type definitions</a>;
1507<code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code>
1508are different because <code>B0</code> is different from <code>[]string</code>.
Robert Griesemer533dfd62009-05-13 16:56:00 -07001509</p>
1510
Robert Griesemer434c6052008-11-07 13:34:37 -08001511
Robert Griesemer440cc952010-06-07 17:40:21 -07001512<h3 id="Assignability">Assignability</h3>
Rob Pike5af7de32009-02-24 15:17:59 -08001513
Rob Pike5af7de32009-02-24 15:17:59 -08001514<p>
Robert Griesemer6962c152014-10-16 15:08:49 -07001515A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code>
griesemerb40831b2017-08-21 15:47:51 +02001516("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies:
Rob Pike5af7de32009-02-24 15:17:59 -08001517</p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07001518
Rob Pike5af7de32009-02-24 15:17:59 -08001519<ul>
1520<li>
Robert Griesemer7bc03712010-06-07 15:49:39 -07001521<code>x</code>'s type is identical to <code>T</code>.
1522</li>
1523<li>
Rob Pike68f16092010-09-01 10:40:50 +10001524<code>x</code>'s type <code>V</code> and <code>T</code> have identical
1525<a href="#Types">underlying types</a> and at least one of <code>V</code>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001526or <code>T</code> is not a <a href="#Type_definitions">defined</a> type.
Rob Pike5af7de32009-02-24 15:17:59 -08001527</li>
1528<li>
Robert Griesemer19b1d352009-09-24 19:36:48 -07001529<code>T</code> is an interface type and
Robert Griesemer7bc03712010-06-07 15:49:39 -07001530<code>x</code> <a href="#Interface_types">implements</a> <code>T</code>.
Robert Griesemere2cb60b2009-06-19 13:03:01 -07001531</li>
1532<li>
Robert Griesemer7bc03712010-06-07 15:49:39 -07001533<code>x</code> is a bidirectional channel value, <code>T</code> is a channel type,
1534<code>x</code>'s type <code>V</code> and <code>T</code> have identical element types,
Robert Griesemer56c9b512017-02-02 15:43:56 -08001535and at least one of <code>V</code> or <code>T</code> is not a defined type.
Robert Griesemer7bc03712010-06-07 15:49:39 -07001536</li>
1537<li>
1538<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
1539is a pointer, function, slice, map, channel, or interface type.
1540</li>
1541<li>
griesemerb40831b2017-08-21 15:47:51 +02001542<code>x</code> is an untyped <a href="#Constants">constant</a>
1543<a href="#Representability">representable</a>
Robert Griesemer7bc03712010-06-07 15:49:39 -07001544by a value of type <code>T</code>.
Robert Griesemer4e56b332009-09-10 10:14:00 -07001545</li>
Rob Pike5af7de32009-02-24 15:17:59 -08001546</ul>
1547
Rob Pikea9ed30f2009-02-23 19:26:07 -08001548
griesemerb40831b2017-08-21 15:47:51 +02001549<h3 id="Representability">Representability</h3>
1550
1551<p>
1552A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i>
1553by a value of type <code>T</code> if one of the following conditions applies:
1554</p>
1555
1556<ul>
1557<li>
1558<code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>.
1559</li>
1560
1561<li>
1562<code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s
1563precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE
1564negative zero further simplified to an unsigned zero. Note that constant values never result
1565in an IEEE negative zero, NaN, or infinity.
1566</li>
1567
1568<li>
1569<code>T</code> is a complex type, and <code>x</code>'s
1570<a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code>
1571are representable by values of <code>T</code>'s component type (<code>float32</code> or
1572<code>float64</code>).
1573</li>
1574</ul>
1575
1576<pre>
1577x T x is representable by a value of T because
1578
1579'a' byte 97 is in the set of byte values
158097 rune rune is an alias for int32, and 97 is in the set of 32-bit integers
1581"foo" string "foo" is in the set of string values
15821024 int16 1024 is in the set of 16-bit integers
158342.0 byte 42 is in the set of unsigned 8-bit integers
15841e10 uint64 10000000000 is in the set of unsigned 64-bit integers
15852.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values
1586-1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0
15870i int 0 is an integer value
1588(42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values
1589</pre>
1590
1591<pre>
1592x T x is not representable by a value of T because
1593
15940 bool 0 is not in the set of boolean values
1595'a' string 'a' is a rune, it is not in the set of string values
15961024 byte 1024 is not in the set of unsigned 8-bit integers
1597-1 uint16 -1 is not in the set of unsigned 16-bit integers
15981.1 int 1.1 is not an integer value
159942i float32 (0 + 42i) is not in the set of float32 values
16001e1000 float64 1e1000 overflows to IEEE +Inf after rounding
1601</pre>
1602
1603
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001604<h2 id="Blocks">Blocks</h2>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001605
1606<p>
Robert Griesemer9905cec2013-03-04 13:55:35 -08001607A <i>block</i> is a possibly empty sequence of declarations and statements
1608within matching brace brackets.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001609</p>
1610
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001611<pre class="ebnf">
Robert Griesemer9905cec2013-03-04 13:55:35 -08001612Block = "{" StatementList "}" .
1613StatementList = { Statement ";" } .
Rob Pikea9ed30f2009-02-23 19:26:07 -08001614</pre>
Russ Cox5958dd62009-03-04 17:19:21 -08001615
Rob Pikea9ed30f2009-02-23 19:26:07 -08001616<p>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001617In addition to explicit blocks in the source code, there are implicit blocks:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001618</p>
1619
1620<ol>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001621 <li>The <i>universe block</i> encompasses all Go source text.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001622
Robert Griesemer4e56b332009-09-10 10:14:00 -07001623 <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
Robert Griesemer0a162a12009-08-19 16:44:04 -07001624 Go source text for that package.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001625
Robert Griesemer0a162a12009-08-19 16:44:04 -07001626 <li>Each file has a <i>file block</i> containing all Go source text
1627 in that file.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001628
Robert Griesemer9905cec2013-03-04 13:55:35 -08001629 <li>Each <a href="#If_statements">"if"</a>,
1630 <a href="#For_statements">"for"</a>, and
1631 <a href="#Switch_statements">"switch"</a>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001632 statement is considered to be in its own implicit block.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001633
Robert Griesemer9905cec2013-03-04 13:55:35 -08001634 <li>Each clause in a <a href="#Switch_statements">"switch"</a>
1635 or <a href="#Select_statements">"select"</a> statement
Robert Griesemer0a162a12009-08-19 16:44:04 -07001636 acts as an implicit block.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001637</ol>
1638
Robert Griesemer0a162a12009-08-19 16:44:04 -07001639<p>
Robert Griesemer4e56b332009-09-10 10:14:00 -07001640Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
Robert Griesemer0a162a12009-08-19 16:44:04 -07001641</p>
1642
1643
Robert Griesemeraeaab592009-08-31 17:30:55 -07001644<h2 id="Declarations_and_scope">Declarations and scope</h2>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001645
1646<p>
Robert Griesemer4cc71e32013-10-03 16:38:22 -07001647A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a
1648<a href="#Constant_declarations">constant</a>,
1649<a href="#Type_declarations">type</a>,
1650<a href="#Variable_declarations">variable</a>,
1651<a href="#Function_declarations">function</a>,
1652<a href="#Labeled_statements">label</a>, or
1653<a href="#Import_declarations">package</a>.
Robert Griesemer0a162a12009-08-19 16:44:04 -07001654Every identifier in a program must be declared.
1655No identifier may be declared twice in the same block, and
1656no identifier may be declared in both the file and package block.
1657</p>
1658
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05001659<p>
1660The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
1661in a declaration, but it does not introduce a binding and thus is not declared.
Robert Griesemera4366982014-05-20 13:51:39 -07001662In the package block, the identifier <code>init</code> may only be used for
1663<a href="#Package_initialization"><code>init</code> function</a> declarations,
1664and like the blank identifier it does not introduce a new binding.
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05001665</p>
1666
Robert Griesemer0a162a12009-08-19 16:44:04 -07001667<pre class="ebnf">
1668Declaration = ConstDecl | TypeDecl | VarDecl .
1669TopLevelDecl = Declaration | FunctionDecl | MethodDecl .
1670</pre>
1671
1672<p>
1673The <i>scope</i> of a declared identifier is the extent of source text in which
Robert Griesemer4cc71e32013-10-03 16:38:22 -07001674the identifier denotes the specified constant, type, variable, function, label, or package.
Robert Griesemer0a162a12009-08-19 16:44:04 -07001675</p>
1676
1677<p>
Robert Griesemer4cc71e32013-10-03 16:38:22 -07001678Go is lexically scoped using <a href="#Blocks">blocks</a>:
Robert Griesemer0a162a12009-08-19 16:44:04 -07001679</p>
1680
1681<ol>
Robert Griesemer4cc71e32013-10-03 16:38:22 -07001682 <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001683
1684 <li>The scope of an identifier denoting a constant, type, variable,
Robert Griesemer967a2b32011-03-03 15:24:28 -08001685 or function (but not method) declared at top level (outside any
1686 function) is the package block.</li>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001687
Robert Griesemere1267632012-11-21 14:40:50 -08001688 <li>The scope of the package name of an imported package is the file block
Robert Griesemer0a162a12009-08-19 16:44:04 -07001689 of the file containing the import declaration.</li>
1690
Robert Griesemer85e451e2012-11-29 14:47:47 -08001691 <li>The scope of an identifier denoting a method receiver, function parameter,
1692 or result variable is the function body.</li>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001693
1694 <li>The scope of a constant or variable identifier declared
1695 inside a function begins at the end of the ConstSpec or VarSpec
Robert Griesemer95b81372011-06-12 12:09:50 -07001696 (ShortVarDecl for short variable declarations)
Robert Griesemer0a162a12009-08-19 16:44:04 -07001697 and ends at the end of the innermost containing block.</li>
1698
1699 <li>The scope of a type identifier declared inside a function
Russ Cox16b95ba2009-08-20 10:22:52 -07001700 begins at the identifier in the TypeSpec
Robert Griesemer0a162a12009-08-19 16:44:04 -07001701 and ends at the end of the innermost containing block.</li>
1702</ol>
1703
1704<p>
1705An identifier declared in a block may be redeclared in an inner block.
1706While the identifier of the inner declaration is in scope, it denotes
1707the entity declared by the inner declaration.
1708</p>
1709
1710<p>
Robert Griesemer506c0082009-09-08 15:41:14 -07001711The <a href="#Package_clause">package clause</a> is not a declaration; the package name
Robert Griesemer0a162a12009-08-19 16:44:04 -07001712does not appear in any scope. Its purpose is to identify the files belonging
Robert Griesemer997851e2009-09-25 15:36:25 -07001713to the same <a href="#Packages">package</a> and to specify the default package name for import
Robert Griesemer0a162a12009-08-19 16:44:04 -07001714declarations.
1715</p>
1716
1717
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001718<h3 id="Label_scopes">Label scopes</h3>
Robert Griesemer0a162a12009-08-19 16:44:04 -07001719
1720<p>
Robert Griesemer506c0082009-09-08 15:41:14 -07001721Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
Robert Griesemer462a17e2013-03-22 15:36:04 -07001722used in the <a href="#Break_statements">"break"</a>,
1723<a href="#Continue_statements">"continue"</a>, and
1724<a href="#Goto_statements">"goto"</a> statements.
Russ Cox108564d2011-03-15 13:51:24 -04001725It is illegal to define a label that is never used.
Robert Griesemer0a162a12009-08-19 16:44:04 -07001726In contrast to other identifiers, labels are not block scoped and do
1727not conflict with identifiers that are not labels. The scope of a label
1728is the body of the function in which it is declared and excludes
1729the body of any nested function.
1730</p>
1731
1732
Robert Griesemer103c9db2012-03-01 13:57:49 -08001733<h3 id="Blank_identifier">Blank identifier</h3>
1734
1735<p>
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05001736The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
1737It serves as an anonymous placeholder instead of a regular (non-blank)
1738identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
1739as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>.
Robert Griesemer103c9db2012-03-01 13:57:49 -08001740</p>
1741
1742
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001743<h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001744
1745<p>
Robert Griesemer103c9db2012-03-01 13:57:49 -08001746The following identifiers are implicitly declared in the
1747<a href="#Blocks">universe block</a>:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001748</p>
1749<pre class="grammar">
Russ Coxd9877e22011-11-01 21:45:02 -04001750Types:
1751 bool byte complex64 complex128 error float32 float64
1752 int int8 int16 int32 int64 rune string
1753 uint uint8 uint16 uint32 uint64 uintptr
Rob Pikea9ed30f2009-02-23 19:26:07 -08001754
1755Constants:
Robert Griesemer19b1d352009-09-24 19:36:48 -07001756 true false iota
1757
1758Zero value:
1759 nil
Rob Pikea9ed30f2009-02-23 19:26:07 -08001760
1761Functions:
Robert Griesemerb910a272011-11-01 01:09:22 -04001762 append cap close complex copy delete imag len
Robert Griesemer07e983a2010-10-25 16:50:31 -07001763 make new panic print println real recover
Rob Pikea9ed30f2009-02-23 19:26:07 -08001764</pre>
1765
Robert Griesemeraeaab592009-08-31 17:30:55 -07001766
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001767<h3 id="Exported_identifiers">Exported identifiers</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001768
1769<p>
Robert Griesemer103c9db2012-03-01 13:57:49 -08001770An identifier may be <i>exported</i> to permit access to it from another package.
1771An identifier is exported if both:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001772</p>
1773<ol>
Robert Griesemer103c9db2012-03-01 13:57:49 -08001774 <li>the first character of the identifier's name is a Unicode upper case
1775 letter (Unicode class "Lu"); and</li>
1776 <li>the identifier is declared in the <a href="#Blocks">package block</a>
1777 or it is a <a href="#Struct_types">field name</a> or
1778 <a href="#MethodName">method name</a>.</li>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001779</ol>
1780<p>
Robert Griesemeraeaab592009-08-31 17:30:55 -07001781All other identifiers are not exported.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001782</p>
1783
Robert Griesemeraeaab592009-08-31 17:30:55 -07001784
Robert Griesemer103c9db2012-03-01 13:57:49 -08001785<h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3>
Robert Griesemer4e56b332009-09-10 10:14:00 -07001786
1787<p>
Robert Griesemer103c9db2012-03-01 13:57:49 -08001788Given a set of identifiers, an identifier is called <i>unique</i> if it is
1789<i>different</i> from every other in the set.
1790Two identifiers are different if they are spelled differently, or if they
1791appear in different <a href="#Packages">packages</a> and are not
Shenghou Ma2195f1a2012-03-30 14:04:03 +08001792<a href="#Exported_identifiers">exported</a>. Otherwise, they are the same.
Robert Griesemer4e56b332009-09-10 10:14:00 -07001793</p>
1794
Robert Griesemer19b1d352009-09-24 19:36:48 -07001795<h3 id="Constant_declarations">Constant declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001796
1797<p>
1798A constant declaration binds a list of identifiers (the names of
Robert Griesemer506c0082009-09-08 15:41:14 -07001799the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>.
1800The number of identifiers must be equal
1801to the number of expressions, and the <i>n</i>th identifier on
1802the left is bound to the value of the <i>n</i>th expression on the
Rob Pikea9ed30f2009-02-23 19:26:07 -08001803right.
1804</p>
1805
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001806<pre class="ebnf">
Robert Griesemer87f4e362016-11-04 12:38:53 -07001807ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
Robert Griesemer4023dce2009-08-14 17:41:52 -07001808ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] .
Rob Pikea9ed30f2009-02-23 19:26:07 -08001809
1810IdentifierList = identifier { "," identifier } .
1811ExpressionList = Expression { "," Expression } .
Rob Pikea9ed30f2009-02-23 19:26:07 -08001812</pre>
1813
1814<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07001815If the type is present, all constants take the type specified, and
Robert Griesemer440cc952010-06-07 17:40:21 -07001816the expressions must be <a href="#Assignability">assignable</a> to that type.
Robert Griesemer4023dce2009-08-14 17:41:52 -07001817If the type is omitted, the constants take the
Robert Griesemer19b1d352009-09-24 19:36:48 -07001818individual types of the corresponding expressions.
1819If the expression values are untyped <a href="#Constants">constants</a>,
1820the declared constants remain untyped and the constant identifiers
1821denote the constant values. For instance, if the expression is a
1822floating-point literal, the constant identifier denotes a floating-point
1823constant, even if the literal's fractional part is zero.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001824</p>
1825
1826<pre>
1827const Pi float64 = 3.14159265358979323846
David Symonds72a29792011-11-29 15:47:36 -08001828const zero = 0.0 // untyped floating-point constant
Rob Pikea9ed30f2009-02-23 19:26:07 -08001829const (
Robert Griesemer130ac742009-12-10 16:43:01 -08001830 size int64 = 1024
David Symonds72a29792011-11-29 15:47:36 -08001831 eof = -1 // untyped integer constant
Rob Pikea9ed30f2009-02-23 19:26:07 -08001832)
Robert Griesemer19b1d352009-09-24 19:36:48 -07001833const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants
Robert Griesemerb94c0d22011-01-19 23:07:21 -05001834const u, v float32 = 0, 3 // u = 0.0, v = 3.0
Rob Pikea9ed30f2009-02-23 19:26:07 -08001835</pre>
1836
1837<p>
1838Within a parenthesized <code>const</code> declaration list the
griesemer85177f42017-10-19 11:48:54 -07001839expression list may be omitted from any but the first ConstSpec.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001840Such an empty list is equivalent to the textual substitution of the
Rob Pike678625d2009-09-15 09:54:22 -07001841first preceding non-empty expression list and its type if any.
Russ Cox5958dd62009-03-04 17:19:21 -08001842Omitting the list of expressions is therefore equivalent to
1843repeating the previous list. The number of identifiers must be equal
1844to the number of expressions in the previous list.
Robert Griesemer506c0082009-09-08 15:41:14 -07001845Together with the <a href="#Iota"><code>iota</code> constant generator</a>
1846this mechanism permits light-weight declaration of sequential values:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001847</p>
1848
1849<pre>
1850const (
Robert Griesemer130ac742009-12-10 16:43:01 -08001851 Sunday = iota
1852 Monday
1853 Tuesday
1854 Wednesday
1855 Thursday
1856 Friday
1857 Partyday
1858 numberOfDays // this constant is not exported
Rob Pikea9ed30f2009-02-23 19:26:07 -08001859)
1860</pre>
1861
1862
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001863<h3 id="Iota">Iota</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001864
1865<p>
Robert Griesemer39f009c2010-04-29 10:57:27 -07001866Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
Robert Griesemer19b1d352009-09-24 19:36:48 -07001867<code>iota</code> represents successive untyped integer <a href="#Constants">
griesemer52dd3992017-10-18 15:31:42 -07001868constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a>
1869in that constant declaration, starting at zero.
Robert Griesemer39f009c2010-04-29 10:57:27 -07001870It can be used to construct a set of related constants:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001871</p>
1872
1873<pre>
griesemer85177f42017-10-19 11:48:54 -07001874const (
Robert Griesemer130ac742009-12-10 16:43:01 -08001875 c0 = iota // c0 == 0
1876 c1 = iota // c1 == 1
1877 c2 = iota // c2 == 2
Rob Pikea9ed30f2009-02-23 19:26:07 -08001878)
1879
griesemer85177f42017-10-19 11:48:54 -07001880const (
1881 a = 1 &lt;&lt; iota // a == 1 (iota == 0)
1882 b = 1 &lt;&lt; iota // b == 2 (iota == 1)
1883 c = 3 // c == 3 (iota == 2, unused)
1884 d = 1 &lt;&lt; iota // d == 8 (iota == 3)
Rob Pikea9ed30f2009-02-23 19:26:07 -08001885)
1886
griesemer85177f42017-10-19 11:48:54 -07001887const (
Robert Griesemerb94c0d22011-01-19 23:07:21 -05001888 u = iota * 42 // u == 0 (untyped integer constant)
1889 v float64 = iota * 42 // v == 42.0 (float64 constant)
1890 w = iota * 42 // w == 84 (untyped integer constant)
Rob Pikea9ed30f2009-02-23 19:26:07 -08001891)
1892
griesemer85177f42017-10-19 11:48:54 -07001893const x = iota // x == 0
1894const y = iota // y == 0
Rob Pikea9ed30f2009-02-23 19:26:07 -08001895</pre>
1896
1897<p>
griesemer85177f42017-10-19 11:48:54 -07001898By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value:
Rob Pikea9ed30f2009-02-23 19:26:07 -08001899</p>
1900
1901<pre>
1902const (
griesemer85177f42017-10-19 11:48:54 -07001903 bit0, mask0 = 1 &lt;&lt; iota, 1&lt;&lt;iota - 1 // bit0 == 1, mask0 == 0 (iota == 0)
1904 bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1)
1905 _, _ // (iota == 2, unused)
1906 bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3)
Rob Pikea9ed30f2009-02-23 19:26:07 -08001907)
1908</pre>
1909
1910<p>
griesemer85177f42017-10-19 11:48:54 -07001911This last example exploits the <a href="#Constant_declarations">implicit repetition</a>
1912of the last non-empty expression list.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001913</p>
1914
1915
Russ Cox7c4f7cc2009-08-20 11:11:03 -07001916<h3 id="Type_declarations">Type declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001917
1918<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001919A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>.
Robert Griesemerc0bd4f32017-02-06 15:57:00 -08001920Type declarations come in two forms: alias declarations and type definitions.
Robert Griesemer56c9b512017-02-02 15:43:56 -08001921<p>
1922
1923<pre class="ebnf">
1924TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
1925TypeSpec = AliasDecl | TypeDef .
1926</pre>
1927
1928<h4 id="Alias_declarations">Alias declarations</h4>
1929
1930<p>
1931An alias declaration binds an identifier to the given type.
Rob Pikea9ed30f2009-02-23 19:26:07 -08001932</p>
1933
Robert Griesemerf7ac31362009-07-10 16:06:40 -07001934<pre class="ebnf">
Robert Griesemer56c9b512017-02-02 15:43:56 -08001935AliasDecl = identifier "=" Type .
Rob Pikea9ed30f2009-02-23 19:26:07 -08001936</pre>
1937
Robert Griesemer56c9b512017-02-02 15:43:56 -08001938<p>
1939Within the <a href="#Declarations_and_scope">scope</a> of
1940the identifier, it serves as an <i>alias</i> for the type.
1941</p>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001942
Robert Griesemer56c9b512017-02-02 15:43:56 -08001943<pre>
Rob Pikea9ed30f2009-02-23 19:26:07 -08001944type (
Robert Griesemer56c9b512017-02-02 15:43:56 -08001945 nodeList = []*Node // nodeList and []*Node are identical types
1946 Polar = polar // Polar and polar denote identical types
1947)
1948</pre>
1949
1950
1951<h4 id="Type_definitions">Type definitions</h4>
1952
1953<p>
Robert Griesemerc0bd4f32017-02-06 15:57:00 -08001954A type definition creates a new, distinct type with the same
1955<a href="#Types">underlying type</a> and operations as the given type,
1956and binds an identifier to it.
Robert Griesemer56c9b512017-02-02 15:43:56 -08001957</p>
1958
1959<pre class="ebnf">
1960TypeDef = identifier Type .
1961</pre>
1962
1963<p>
1964The new type is called a <i>defined type</i>.
1965It is <a href="#Type_identity">different</a> from any other type,
1966including the type it is created from.
1967</p>
1968
1969<pre>
1970type (
1971 Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types
1972 polar Point // polar and Point denote different types
Rob Pikea9ed30f2009-02-23 19:26:07 -08001973)
1974
1975type TreeNode struct {
Robert Griesemer130ac742009-12-10 16:43:01 -08001976 left, right *TreeNode
1977 value *Comparable
Rob Pikea9ed30f2009-02-23 19:26:07 -08001978}
1979
Rob Pike217408a2011-11-09 14:22:44 -08001980type Block interface {
Robert Griesemer130ac742009-12-10 16:43:01 -08001981 BlockSize() int
1982 Encrypt(src, dst []byte)
1983 Decrypt(src, dst []byte)
Rob Pikea9ed30f2009-02-23 19:26:07 -08001984}
1985</pre>
1986
Robert Griesemerfc61b772009-09-28 14:10:20 -07001987<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08001988A defined type may have <a href="#Method_declarations">methods</a> associated with it.
1989It does not inherit any methods bound to the given type,
1990but the <a href="#Method_sets">method set</a>
Robert Griesemerd4a16192010-04-01 12:48:34 -07001991of an interface type or of elements of a composite type remains unchanged:
Robert Griesemerfc61b772009-09-28 14:10:20 -07001992</p>
1993
1994<pre>
Rob Pikebdbe0de2011-05-25 06:00:07 +10001995// A Mutex is a data type with two methods, Lock and Unlock.
Robert Griesemerfc61b772009-09-28 14:10:20 -07001996type Mutex struct { /* Mutex fields */ }
1997func (m *Mutex) Lock() { /* Lock implementation */ }
1998func (m *Mutex) Unlock() { /* Unlock implementation */ }
1999
2000// NewMutex has the same composition as Mutex but its method set is empty.
2001type NewMutex Mutex
2002
griesemer5abc8c892017-08-11 16:51:40 +02002003// The method set of PtrMutex's underlying type *Mutex remains unchanged,
Robert Griesemer2a838d62011-02-08 13:31:01 -08002004// but the method set of PtrMutex is empty.
2005type PtrMutex *Mutex
2006
Robert Griesemerf5b3c142010-04-27 17:52:44 -07002007// The method set of *PrintableMutex contains the methods
Robert Griesemerf8b41232017-01-10 16:19:14 -08002008// Lock and Unlock bound to its embedded field Mutex.
Robert Griesemerfc61b772009-09-28 14:10:20 -07002009type PrintableMutex struct {
Robert Griesemer130ac742009-12-10 16:43:01 -08002010 Mutex
Robert Griesemerfc61b772009-09-28 14:10:20 -07002011}
Robert Griesemer735e00d2010-03-31 16:37:22 -07002012
Rob Pike217408a2011-11-09 14:22:44 -08002013// MyBlock is an interface type that has the same method set as Block.
2014type MyBlock Block
Robert Griesemerfc61b772009-09-28 14:10:20 -07002015</pre>
2016
2017<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08002018Type definitions may be used to define different boolean, numeric,
2019or string types and associate methods with them:
Robert Griesemerfc61b772009-09-28 14:10:20 -07002020</p>
2021
2022<pre>
2023type TimeZone int
2024
2025const (
Robert Griesemer130ac742009-12-10 16:43:01 -08002026 EST TimeZone = -(5 + iota)
2027 CST
2028 MST
2029 PST
Robert Griesemerfc61b772009-09-28 14:10:20 -07002030)
2031
2032func (tz TimeZone) String() string {
Robert Griesemer02d74482015-07-31 11:15:11 -07002033 return fmt.Sprintf("GMT%+dh", tz)
Robert Griesemerfc61b772009-09-28 14:10:20 -07002034}
2035</pre>
2036
2037
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002038<h3 id="Variable_declarations">Variable declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002039
2040<p>
Robert Griesemer56c9b512017-02-02 15:43:56 -08002041A variable declaration creates one or more <a href="#Variables">variables</a>,
2042binds corresponding identifiers to them, and gives each a type and an initial value.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002043</p>
Robert Griesemer47094dc2014-09-30 11:44:29 -07002044
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002045<pre class="ebnf">
Robert Griesemer87f4e362016-11-04 12:38:53 -07002046VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
Robert Griesemer4023dce2009-08-14 17:41:52 -07002047VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
Rob Pikea9ed30f2009-02-23 19:26:07 -08002048</pre>
2049
2050<pre>
2051var i int
Robert Griesemerb94c0d22011-01-19 23:07:21 -05002052var U, V, W float64
Rob Pikea9ed30f2009-02-23 19:26:07 -08002053var k = 0
Robert Griesemerb94c0d22011-01-19 23:07:21 -05002054var x, y float32 = -1, -2
Rob Pikea9ed30f2009-02-23 19:26:07 -08002055var (
David Symonds72a29792011-11-29 15:47:36 -08002056 i int
Rob Pikea9ed30f2009-02-23 19:26:07 -08002057 u, v, s = 2.0, 3.0, "bar"
2058)
Robert Griesemer4e56b332009-09-10 10:14:00 -07002059var re, im = complexSqrt(-1)
Robert Griesemer130ac742009-12-10 16:43:01 -08002060var _, found = entries[name] // map lookup; only interested in "found"
Rob Pikea9ed30f2009-02-23 19:26:07 -08002061</pre>
2062
2063<p>
Robert Griesemeref45e642009-08-21 11:25:00 -07002064If a list of expressions is given, the variables are initialized
Robert Griesemer47094dc2014-09-30 11:44:29 -07002065with the expressions following the rules for <a href="#Assignments">assignments</a>.
Rob Pike4fe41922009-11-07 22:00:59 -08002066Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002067</p>
Robert Griesemeref45e642009-08-21 11:25:00 -07002068
Rob Pikea9ed30f2009-02-23 19:26:07 -08002069<p>
Robert Griesemer47094dc2014-09-30 11:44:29 -07002070If a type is present, each variable is given that type.
2071Otherwise, each variable is given the type of the corresponding
2072initialization value in the assignment.
Robert Griesemer26d22602018-10-02 15:55:38 -07002073If that value is an untyped constant, it is first implicitly
Robert Griesemer47094dc2014-09-30 11:44:29 -07002074<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
Robert Griesemer26d22602018-10-02 15:55:38 -07002075if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
Robert Griesemer47094dc2014-09-30 11:44:29 -07002076The predeclared value <code>nil</code> cannot be used to initialize a variable
2077with no explicit type.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002078</p>
Robert Griesemeref45e642009-08-21 11:25:00 -07002079
Robert Griesemer47094dc2014-09-30 11:44:29 -07002080<pre>
Brad Fitzpatrick5f029de2014-12-22 07:58:26 -08002081var d = math.Sin(0.5) // d is float64
Robert Griesemer47094dc2014-09-30 11:44:29 -07002082var i = 42 // i is int
2083var t, ok = x.(T) // t is T, ok is bool
2084var n = nil // illegal
2085</pre>
Robert Griesemer2c9e1632012-02-28 17:44:24 -08002086
2087<p>
2088Implementation restriction: A compiler may make it illegal to declare a variable
2089inside a <a href="#Function_declarations">function body</a> if the variable is
2090never used.
2091</p>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002092
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002093<h3 id="Short_variable_declarations">Short variable declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002094
Robert Griesemer997851e2009-09-25 15:36:25 -07002095<p>
Robert Griesemeref45e642009-08-21 11:25:00 -07002096A <i>short variable declaration</i> uses the syntax:
Robert Griesemer997851e2009-09-25 15:36:25 -07002097</p>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002098
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002099<pre class="ebnf">
Robert Griesemere1b8cb82009-07-16 20:31:41 -07002100ShortVarDecl = IdentifierList ":=" ExpressionList .
Rob Pikea9ed30f2009-02-23 19:26:07 -08002101</pre>
2102
Robert Griesemer997851e2009-09-25 15:36:25 -07002103<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07002104It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
Robert Griesemer2c9e1632012-02-28 17:44:24 -08002105with initializer expressions but no types:
Robert Griesemer997851e2009-09-25 15:36:25 -07002106</p>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002107
2108<pre class="grammar">
2109"var" IdentifierList = ExpressionList .
2110</pre>
2111
2112<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08002113i, j := 0, 10
2114f := func() int { return 7 }
2115ch := make(chan int)
Dina Garmash8a2b5f12018-08-30 16:59:29 -04002116r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any
2117_, y, _ := coord(p) // coord() returns three values; only interested in y coordinate
Rob Pikea9ed30f2009-02-23 19:26:07 -08002118</pre>
2119
2120<p>
Robert Griesemer85789da2015-08-04 11:29:28 -07002121Unlike regular variable declarations, a short variable declaration may <i>redeclare</i>
2122variables provided they were originally declared earlier in the same block
Robert Griesemer120cf672016-11-17 16:39:11 -08002123(or the parameter lists if the block is the function body) with the same type,
Robert Griesemer85789da2015-08-04 11:29:28 -07002124and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new.
2125As a consequence, redeclaration can only appear in a multi-variable short declaration.
2126Redeclaration does not introduce a new variable; it just assigns a new value to the original.
Rob Pike2a1683a2009-04-19 20:04:15 -07002127</p>
2128
2129<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08002130field1, offset := nextField(str, 0)
2131field2, offset := nextField(str, offset) // redeclares offset
Robert Griesemerf1cc0f42013-01-09 11:31:32 -08002132a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere
Rob Pike2a1683a2009-04-19 20:04:15 -07002133</pre>
2134
2135<p>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002136Short variable declarations may appear only inside functions.
Robert Griesemer462a17e2013-03-22 15:36:04 -07002137In some contexts such as the initializers for
2138<a href="#If_statements">"if"</a>,
2139<a href="#For_statements">"for"</a>, or
2140<a href="#Switch_statements">"switch"</a> statements,
2141they can be used to declare local temporary variables.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002142</p>
2143
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002144<h3 id="Function_declarations">Function declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002145
2146<p>
Robert Griesemerb1d9ae92012-02-12 20:03:30 -08002147A function declaration binds an identifier, the <i>function name</i>,
2148to a function.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002149</p>
2150
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002151<pre class="ebnf">
Robert Griesemer851e98f2018-02-01 14:08:45 -08002152FunctionDecl = "func" FunctionName Signature [ FunctionBody ] .
Robert Griesemerb1d9ae92012-02-12 20:03:30 -08002153FunctionName = identifier .
Robert Griesemer9905cec2013-03-04 13:55:35 -08002154FunctionBody = Block .
Rob Pikea9ed30f2009-02-23 19:26:07 -08002155</pre>
2156
Robert Griesemer4023dce2009-08-14 17:41:52 -07002157<p>
Robert Griesemer9905cec2013-03-04 13:55:35 -08002158If the function's <a href="#Function_types">signature</a> declares
2159result parameters, the function body's statement list must end in
2160a <a href="#Terminating_statements">terminating statement</a>.
2161</p>
2162
Rob Piked0208912013-03-22 10:03:55 -07002163<pre>
Robert Griesemer02d74482015-07-31 11:15:11 -07002164func IndexRune(s string, r rune) int {
2165 for i, c := range s {
2166 if c == r {
2167 return i
Rob Piked0208912013-03-22 10:03:55 -07002168 }
2169 }
Robert Griesemer02d74482015-07-31 11:15:11 -07002170 // invalid: missing return statement
Rob Piked0208912013-03-22 10:03:55 -07002171}
2172</pre>
2173
Robert Griesemer9905cec2013-03-04 13:55:35 -08002174<p>
Robert Griesemer4023dce2009-08-14 17:41:52 -07002175A function declaration may omit the body. Such a declaration provides the
2176signature for a function implemented outside Go, such as an assembly routine.
2177</p>
2178
Rob Pikea9ed30f2009-02-23 19:26:07 -08002179<pre>
2180func min(x int, y int) int {
2181 if x &lt; y {
Robert Griesemer130ac742009-12-10 16:43:01 -08002182 return x
Rob Pikea9ed30f2009-02-23 19:26:07 -08002183 }
Robert Griesemer130ac742009-12-10 16:43:01 -08002184 return y
Rob Pikea9ed30f2009-02-23 19:26:07 -08002185}
Robert Griesemer4023dce2009-08-14 17:41:52 -07002186
2187func flushICache(begin, end uintptr) // implemented externally
Rob Pikea9ed30f2009-02-23 19:26:07 -08002188</pre>
2189
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002190<h3 id="Method_declarations">Method declarations</h3>
Rob Pikea9ed30f2009-02-23 19:26:07 -08002191
2192<p>
Robert Griesemer9905cec2013-03-04 13:55:35 -08002193A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
2194A method declaration binds an identifier, the <i>method name</i>, to a method,
2195and associates the method with the receiver's <i>base type</i>.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002196</p>
Robert Griesemerb1d9ae92012-02-12 20:03:30 -08002197
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002198<pre class="ebnf">
Robert Griesemer851e98f2018-02-01 14:08:45 -08002199MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] .
Robert Griesemer56c9b512017-02-02 15:43:56 -08002200Receiver = Parameters .
Rob Pikea9ed30f2009-02-23 19:26:07 -08002201</pre>
2202
2203<p>
Paolo Martini35491782015-07-17 17:26:08 +02002204The receiver is specified via an extra parameter section preceding the method
Robert Griesemer57c81ef2015-12-15 13:13:38 -08002205name. That parameter section must declare a single non-variadic parameter, the receiver.
Robert Griesemerbb3e2112018-10-16 16:50:25 -07002206Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a
2207pointer to a defined type <code>T</code>. <code>T</code> is called the receiver
2208<i>base type</i>. A receiver base type cannot be a pointer or interface type and
2209it must be defined in the same package as the method.
2210The method is said to be <i>bound</i> to its receiver base type and the method name
Robert Griesemer05614bf2015-08-04 11:52:01 -07002211is visible only within <a href="#Selectors">selectors</a> for type <code>T</code>
2212or <code>*T</code>.
Robert Griesemerb1d9ae92012-02-12 20:03:30 -08002213</p>
2214
2215<p>
Robert Griesemer85e451e2012-11-29 14:47:47 -08002216A non-<a href="#Blank_identifier">blank</a> receiver identifier must be
2217<a href="#Uniqueness_of_identifiers">unique</a> in the method signature.
2218If the receiver's value is not referenced inside the body of the method,
2219its identifier may be omitted in the declaration. The same applies in
2220general to parameters of functions and methods.
2221</p>
2222
2223<p>
2224For a base type, the non-blank names of methods bound to it must be unique.
Robert Griesemerb1d9ae92012-02-12 20:03:30 -08002225If the base type is a <a href="#Struct_types">struct type</a>,
2226the non-blank method and field names must be distinct.
Rob Pikea9ed30f2009-02-23 19:26:07 -08002227</p>
2228
2229<p>
Robert Griesemerbb3e2112018-10-16 16:50:25 -07002230Given defined type <code>Point</code>, the declarations
Rob Pikea9ed30f2009-02-23 19:26:07 -08002231</p>
2232
2233<pre>
Robert Griesemer777a96a2010-12-02 12:32:14 -08002234func (p *Point) Length() float64 {
2235 return math.Sqrt(p.x * p.x + p.y * p.y)
Rob Pikea9ed30f2009-02-23 19:26:07 -08002236}
2237
Robert Griesemer777a96a2010-12-02 12:32:14 -08002238func (p *Point) Scale(factor float64) {
2239 p.x *= factor
2240 p.y *= factor
Rob Pikea9ed30f2009-02-23 19:26:07 -08002241}
2242</pre>
2243
2244<p>
Rob Pike678625d2009-09-15 09:54:22 -07002245bind the methods <code>Length</code> and <code>Scale</code>,
2246with receiver type <code>*Point</code>,
Rob Pikea9ed30f2009-02-23 19:26:07 -08002247to the base type <code>Point</code>.
2248</p>
2249
2250<p>
Rob Pikedf3183f2009-02-26 16:37:23 -08002251The type of a method is the type of a function with the receiver as first
2252argument. For instance, the method <code>Scale</code> has type
2253</p>
2254
2255<pre>
Robert Griesemer777a96a2010-12-02 12:32:14 -08002256func(p *Point, factor float64)
Rob Pikedf3183f2009-02-26 16:37:23 -08002257</pre>
2258
2259<p>
2260However, a function declared this way is not a method.
2261</p>
2262
Rob Pikea9ed30f2009-02-23 19:26:07 -08002263
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002264<h2 id="Expressions">Expressions</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002265
Rob Pikedf3183f2009-02-26 16:37:23 -08002266<p>
2267An expression specifies the computation of a value by applying
Robert Griesemer19b1d352009-09-24 19:36:48 -07002268operators and functions to operands.
Rob Pikedf3183f2009-02-26 16:37:23 -08002269</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002270
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002271<h3 id="Operands">Operands</h3>
Robert Griesemerad711102008-09-11 17:48:20 -07002272
Robert Griesemer997851e2009-09-25 15:36:25 -07002273<p>
Robert Griesemer809e06b2012-06-26 11:49:19 -07002274Operands denote the elementary values in an expression. An operand may be a
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05002275literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
2276non-<a href="#Blank_identifier">blank</a> identifier denoting a
Robert Griesemer809e06b2012-06-26 11:49:19 -07002277<a href="#Constant_declarations">constant</a>,
2278<a href="#Variable_declarations">variable</a>, or
2279<a href="#Function_declarations">function</a>,
Robert Griesemer809e06b2012-06-26 11:49:19 -07002280or a parenthesized expression.
Robert Griesemer997851e2009-09-25 15:36:25 -07002281</p>
Robert Griesemerad711102008-09-11 17:48:20 -07002282
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05002283<p>
2284The <a href="#Blank_identifier">blank identifier</a> may appear as an
2285operand only on the left-hand side of an <a href="#Assignments">assignment</a>.
2286</p>
2287
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002288<pre class="ebnf">
griesemerf2d52512017-10-25 11:26:02 -07002289Operand = Literal | OperandName | "(" Expression ")" .
Robin Eklindcac006a2014-08-30 10:27:01 -07002290Literal = BasicLit | CompositeLit | FunctionLit .
2291BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
Robert Griesemer809e06b2012-06-26 11:49:19 -07002292OperandName = identifier | QualifiedIdent.
Robert Griesemerc2d55862009-02-19 16:49:10 -08002293</pre>
Robert Griesemerad711102008-09-11 17:48:20 -07002294
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002295<h3 id="Qualified_identifiers">Qualified identifiers</h3>
Robert Griesemerad711102008-09-11 17:48:20 -07002296
Robert Griesemerc2d55862009-02-19 16:49:10 -08002297<p>
Robert Griesemer809e06b2012-06-26 11:49:19 -07002298A qualified identifier is an identifier qualified with a package name prefix.
2299Both the package name and the identifier must not be
2300<a href="#Blank_identifier">blank</a>.
Rob Pikedf3183f2009-02-26 16:37:23 -08002301</p>
Robert Griesemer337af312008-11-17 18:11:36 -08002302
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002303<pre class="ebnf">
Robert Griesemer809e06b2012-06-26 11:49:19 -07002304QualifiedIdent = PackageName "." identifier .
Robert Griesemerc2d55862009-02-19 16:49:10 -08002305</pre>
Robert Griesemerad711102008-09-11 17:48:20 -07002306
Rob Pikedf3183f2009-02-26 16:37:23 -08002307<p>
Robert Griesemerda633712012-02-29 09:06:05 -08002308A qualified identifier accesses an identifier in a different package, which
2309must be <a href="#Import_declarations">imported</a>.
Robert Griesemer103c9db2012-03-01 13:57:49 -08002310The identifier must be <a href="#Exported_identifiers">exported</a> and
2311declared in the <a href="#Blocks">package block</a> of that package.
Rob Pikedf3183f2009-02-26 16:37:23 -08002312</p>
Rob Pikedf3183f2009-02-26 16:37:23 -08002313
2314<pre>
Robert Griesemer103c9db2012-03-01 13:57:49 -08002315math.Sin // denotes the Sin function in package math
Rob Pikedf3183f2009-02-26 16:37:23 -08002316</pre>
Robert Griesemerad711102008-09-11 17:48:20 -07002317
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002318<h3 id="Composite_literals">Composite literals</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002319
Rob Pikedf3183f2009-02-26 16:37:23 -08002320<p>
2321Composite literals construct values for structs, arrays, slices, and maps
2322and create a new value each time they are evaluated.
Robert Griesemerc7208752015-09-22 17:47:38 -07002323They consist of the type of the literal followed by a brace-bound list of elements.
Robert Griesemer3b022422015-09-11 16:20:23 -07002324Each element may optionally be preceded by a corresponding key.
Rob Pikedf3183f2009-02-26 16:37:23 -08002325</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002326
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002327<pre class="ebnf">
Robert Griesemera12141e2010-10-22 08:58:52 -07002328CompositeLit = LiteralType LiteralValue .
Rob Pikedf3183f2009-02-26 16:37:23 -08002329LiteralType = StructType | ArrayType | "[" "..." "]" ElementType |
Robert Griesemer07cc6442010-07-29 18:13:41 -07002330 SliceType | MapType | TypeName .
Robert Griesemera12141e2010-10-22 08:58:52 -07002331LiteralValue = "{" [ ElementList [ "," ] ] "}" .
Robert Griesemer3b022422015-09-11 16:20:23 -07002332ElementList = KeyedElement { "," KeyedElement } .
2333KeyedElement = [ Key ":" ] Element .
Robert Griesemer7727dee2015-01-08 16:01:31 -08002334Key = FieldName | Expression | LiteralValue .
Rob Pike678625d2009-09-15 09:54:22 -07002335FieldName = identifier .
Robert Griesemer3b022422015-09-11 16:20:23 -07002336Element = Expression | LiteralValue .
Robert Griesemerc2d55862009-02-19 16:49:10 -08002337</pre>
Robert Griesemer0976e342008-09-03 13:37:44 -07002338
Rob Pikedf3183f2009-02-26 16:37:23 -08002339<p>
Robert Griesemerc7208752015-09-22 17:47:38 -07002340The LiteralType's underlying type must be a struct, array, slice, or map type
Robert Griesemer838cf122009-05-22 10:25:06 -07002341(the grammar enforces this constraint except when the type is given
2342as a TypeName).
Robert Griesemer3b022422015-09-11 16:20:23 -07002343The types of the elements and keys must be <a href="#Assignability">assignable</a>
Robert Griesemerc7208752015-09-22 17:47:38 -07002344to the respective field, element, and key types of the literal type;
Russ Cox7a5e97b2009-03-03 15:40:30 -08002345there is no additional conversion.
Robert Griesemer838cf122009-05-22 10:25:06 -07002346The key is interpreted as a field name for struct literals,
Robert Griesemer9c9e8112012-12-10 11:55:57 -08002347an index for array and slice literals, and a key for map literals.
Robert Griesemer838cf122009-05-22 10:25:06 -07002348For map literals, all elements must have a key. It is an error
2349to specify multiple elements with the same field name or
Robert Griesemer369d1082017-03-24 09:19:46 -07002350constant key value. For non-constant map keys, see the section on
2351<a href="#Order_of_evaluation">evaluation order</a>.
Rob Pikedf3183f2009-02-26 16:37:23 -08002352</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002353
Robert Griesemer838cf122009-05-22 10:25:06 -07002354<p>
2355For struct literals the following rules apply:
Robert Griesemercfe92112009-06-18 13:29:40 -07002356</p>
Robert Griesemer838cf122009-05-22 10:25:06 -07002357<ul>
Robert Griesemerc7208752015-09-22 17:47:38 -07002358 <li>A key must be a field name declared in the struct type.
Robert Griesemerd3b15652009-11-16 08:58:55 -08002359 </li>
Robert Griesemer369a9742012-10-31 15:07:25 -07002360 <li>An element list that does not contain any keys must
Robert Griesemer838cf122009-05-22 10:25:06 -07002361 list an element for each struct field in the
2362 order in which the fields are declared.
2363 </li>
2364 <li>If any element has a key, every element must have a key.
2365 </li>
Robert Griesemer369a9742012-10-31 15:07:25 -07002366 <li>An element list that contains keys does not need to
Robert Griesemer838cf122009-05-22 10:25:06 -07002367 have an element for each struct field. Omitted fields
2368 get the zero value for that field.
2369 </li>
2370 <li>A literal may omit the element list; such a literal evaluates
Robert Griesemer369a9742012-10-31 15:07:25 -07002371 to the zero value for its type.
Robert Griesemer838cf122009-05-22 10:25:06 -07002372 </li>
2373 <li>It is an error to specify an element for a non-exported
2374 field of a struct belonging to a different package.
2375 </li>
2376</ul>
Robert Griesemer838cf122009-05-22 10:25:06 -07002377
2378<p>
2379Given the declarations
2380</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08002381<pre>
Robert Griesemer777a96a2010-12-02 12:32:14 -08002382type Point3D struct { x, y, z float64 }
2383type Line struct { p, q Point3D }
Robert Griesemerc2d55862009-02-19 16:49:10 -08002384</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002385
Rob Pikedf3183f2009-02-26 16:37:23 -08002386<p>
2387one may write
2388</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002389
Robert Griesemerc2d55862009-02-19 16:49:10 -08002390<pre>
Robert Griesemer777a96a2010-12-02 12:32:14 -08002391origin := Point3D{} // zero value for Point3D
2392line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x
Rob Pike37ab8382009-03-18 22:58:36 -07002393</pre>
2394
Robert Griesemercfe92112009-06-18 13:29:40 -07002395<p>
2396For array and slice literals the following rules apply:
2397</p>
Robert Griesemer838cf122009-05-22 10:25:06 -07002398<ul>
2399 <li>Each element has an associated integer index marking
2400 its position in the array.
2401 </li>
Robert Griesemera016ecf2016-10-05 15:59:09 -07002402 <li>An element with a key uses the key as its index. The
griesemerb40831b2017-08-21 15:47:51 +02002403 key must be a non-negative constant
2404 <a href="#Representability">representable</a> by
Robert Griesemera016ecf2016-10-05 15:59:09 -07002405 a value of type <code>int</code>; and if it is typed
2406 it must be of integer type.
Robert Griesemer838cf122009-05-22 10:25:06 -07002407 </li>
2408 <li>An element without a key uses the previous element's index plus one.
2409 If the first element has no key, its index is zero.
2410 </li>
2411</ul>
Robert Griesemer838cf122009-05-22 10:25:06 -07002412
Rob Pike37ab8382009-03-18 22:58:36 -07002413<p>
Robert Griesemer462a17e2013-03-22 15:36:04 -07002414<a href="#Address_operators">Taking the address</a> of a composite literal
Robert Griesemer6962c152014-10-16 15:08:49 -07002415generates a pointer to a unique <a href="#Variables">variable</a> initialized
2416with the literal's value.
Rob Pike37ab8382009-03-18 22:58:36 -07002417</p>
Rob Pike37ab8382009-03-18 22:58:36 -07002418<pre>
Robert Griesemer777a96a2010-12-02 12:32:14 -08002419var pointer *Point3D = &amp;Point3D{y: 1000}
Robert Griesemerc2d55862009-02-19 16:49:10 -08002420</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002421
Rob Pikedf3183f2009-02-26 16:37:23 -08002422<p>
Robert Griesemerc7208752015-09-22 17:47:38 -07002423The length of an array literal is the length specified in the literal type.
Robert Griesemera3294712009-01-05 11:17:26 -08002424If fewer elements than the length are provided in the literal, the missing
Rob Pike8f2330d2009-02-25 16:20:44 -08002425elements are set to the zero value for the array element type.
Robert Griesemer838cf122009-05-22 10:25:06 -07002426It is an error to provide elements with index values outside the index range
2427of the array. The notation <code>...</code> specifies an array length equal
2428to the maximum element index plus one.
Rob Pikedf3183f2009-02-26 16:37:23 -08002429</p>
Robert Griesemerb90b2132008-09-19 15:49:55 -07002430
Robert Griesemerc2d55862009-02-19 16:49:10 -08002431<pre>
David Symonds72a29792011-11-29 15:47:36 -08002432buffer := [10]string{} // len(buffer) == 10
2433intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6
2434days := [...]string{"Sat", "Sun"} // len(days) == 2
Robert Griesemerc2d55862009-02-19 16:49:10 -08002435</pre>
Robert Griesemer91bbd642009-01-07 09:31:35 -08002436
Rob Pikedf3183f2009-02-26 16:37:23 -08002437<p>
2438A slice literal describes the entire underlying array literal.
Robert Griesemera6563902016-08-25 21:01:17 -07002439Thus the length and capacity of a slice literal are the maximum
Robert Griesemer838cf122009-05-22 10:25:06 -07002440element index plus one. A slice literal has the form
Rob Pikedf3183f2009-02-26 16:37:23 -08002441</p>
Robert Griesemer91bbd642009-01-07 09:31:35 -08002442
Robert Griesemerc2d55862009-02-19 16:49:10 -08002443<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07002444[]T{x1, x2, … xn}
Robert Griesemerc2d55862009-02-19 16:49:10 -08002445</pre>
Robert Griesemer91bbd642009-01-07 09:31:35 -08002446
Rob Pikedf3183f2009-02-26 16:37:23 -08002447<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07002448and is shorthand for a slice operation applied to an array:
Rob Pikedf3183f2009-02-26 16:37:23 -08002449</p>
Robert Griesemer91bbd642009-01-07 09:31:35 -08002450
Robert Griesemerc2d55862009-02-19 16:49:10 -08002451<pre>
Russ Cox4dfe9762011-12-02 12:30:20 -05002452tmp := [n]T{x1, x2, … xn}
2453tmp[0 : n]
Robert Griesemerc2d55862009-02-19 16:49:10 -08002454</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002455
Rob Pikedf3183f2009-02-26 16:37:23 -08002456<p>
Robert Griesemera12141e2010-10-22 08:58:52 -07002457Within a composite literal of array, slice, or map type <code>T</code>,
Robert Griesemer7727dee2015-01-08 16:01:31 -08002458elements or map keys that are themselves composite literals may elide the respective
2459literal type if it is identical to the element or key type of <code>T</code>.
2460Similarly, elements or keys that are addresses of composite literals may elide
2461the <code>&amp;T</code> when the element or key type is <code>*T</code>.
Robert Griesemera12141e2010-10-22 08:58:52 -07002462</p>
2463
2464<pre>
Robert Griesemer7727dee2015-01-08 16:01:31 -08002465[...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
2466[][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
2467[][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}}
2468map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}}
Robert Griesemer7727dee2015-01-08 16:01:31 -08002469map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"}
Robert Griesemer120cf672016-11-17 16:39:11 -08002470
2471type PPoint *Point
2472[2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&amp;Point{1.5, -3.5}, &amp;Point{}}
2473[2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&amp;Point{1.5, -3.5}), PPoint(&amp;Point{})}
Robert Griesemera12141e2010-10-22 08:58:52 -07002474</pre>
2475
2476<p>
Russ Cox7a5e97b2009-03-03 15:40:30 -08002477A parsing ambiguity arises when a composite literal using the
Robert Griesemera36b5b92014-02-27 08:57:30 -08002478TypeName form of the LiteralType appears as an operand between the
2479<a href="#Keywords">keyword</a> and the opening brace of the block
2480of an "if", "for", or "switch" statement, and the composite literal
2481is not enclosed in parentheses, square brackets, or curly braces.
2482In this rare case, the opening brace of the literal is erroneously parsed
2483as the one introducing the block of statements. To resolve the ambiguity,
2484the composite literal must appear within parentheses.
Russ Cox7a5e97b2009-03-03 15:40:30 -08002485</p>
2486
2487<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07002488if x == (T{a,b,c}[i]) { … }
2489if (x == T{a,b,c}[i]) { … }
Russ Cox7a5e97b2009-03-03 15:40:30 -08002490</pre>
2491
Robert Griesemer838cf122009-05-22 10:25:06 -07002492<p>
2493Examples of valid array, slice, and map literals:
2494</p>
2495
2496<pre>
2497// list of prime numbers
Andrew Bonventre7974f082018-03-19 21:50:42 +00002498primes := []int{2, 3, 5, 7, 9, 2147483647}
Robert Griesemer838cf122009-05-22 10:25:06 -07002499
2500// vowels[ch] is true if ch is a vowel
Robert Griesemer130ac742009-12-10 16:43:01 -08002501vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
Robert Griesemer838cf122009-05-22 10:25:06 -07002502
Robert Griesemerb94c0d22011-01-19 23:07:21 -05002503// the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1}
2504filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}
Robert Griesemer838cf122009-05-22 10:25:06 -07002505
2506// frequencies in Hz for equal-tempered scale (A4 = 440Hz)
Robert Griesemerb94c0d22011-01-19 23:07:21 -05002507noteFrequency := map[string]float32{
Robert Griesemer838cf122009-05-22 10:25:06 -07002508 "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
2509 "G0": 24.50, "A0": 27.50, "B0": 30.87,
2510}
2511</pre>
2512
2513
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002514<h3 id="Function_literals">Function literals</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002515
Rob Pikedf3183f2009-02-26 16:37:23 -08002516<p>
Robert Griesemer9905cec2013-03-04 13:55:35 -08002517A function literal represents an anonymous <a href="#Function_declarations">function</a>.
Rob Pikedf3183f2009-02-26 16:37:23 -08002518</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002519
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002520<pre class="ebnf">
Robert Griesemer851e98f2018-02-01 14:08:45 -08002521FunctionLit = "func" Signature FunctionBody .
Robert Griesemerc2d55862009-02-19 16:49:10 -08002522</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002523
Robert Griesemerc2d55862009-02-19 16:49:10 -08002524<pre>
Robert Griesemerb94c0d22011-01-19 23:07:21 -05002525func(a, b int, z float64) bool { return a*b &lt; int(z) }
Robert Griesemerc2d55862009-02-19 16:49:10 -08002526</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002527
Rob Pikedf3183f2009-02-26 16:37:23 -08002528<p>
2529A function literal can be assigned to a variable or invoked directly.
2530</p>
Robert Griesemer7231ceb2008-09-08 15:01:04 -07002531
Robert Griesemerc2d55862009-02-19 16:49:10 -08002532<pre>
Rob Pikedf3183f2009-02-26 16:37:23 -08002533f := func(x, y int) int { return x + y }
Russ Cox9c08d652012-02-21 22:04:30 -05002534func(ch chan int) { ch &lt;- ACK }(replyChan)
Robert Griesemerc2d55862009-02-19 16:49:10 -08002535</pre>
Robert Griesemer7231ceb2008-09-08 15:01:04 -07002536
Rob Pikedf3183f2009-02-26 16:37:23 -08002537<p>
2538Function literals are <i>closures</i>: they may refer to variables
Robert Griesemerd8a764c2009-02-06 17:01:10 -08002539defined in a surrounding function. Those variables are then shared between
2540the surrounding function and the function literal, and they survive as long
Rob Pikedf3183f2009-02-26 16:37:23 -08002541as they are accessible.
2542</p>
Robert Griesemer7231ceb2008-09-08 15:01:04 -07002543
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002544
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002545<h3 id="Primary_expressions">Primary expressions</h3>
Russ Cox5958dd62009-03-04 17:19:21 -08002546
Robert Griesemer164a7bc2009-09-30 12:00:25 -07002547<p>
2548Primary expressions are the operands for unary and binary expressions.
2549</p>
2550
Robert Griesemerf7ac31362009-07-10 16:06:40 -07002551<pre class="ebnf">
Robert Griesemerc2d55862009-02-19 16:49:10 -08002552PrimaryExpr =
2553 Operand |
Robert Griesemer5eb36242009-09-16 11:05:14 -07002554 Conversion |
griesemerf2d52512017-10-25 11:26:02 -07002555 MethodExpr |
Robert Griesemerc2d55862009-02-19 16:49:10 -08002556 PrimaryExpr Selector |
2557 PrimaryExpr Index |
2558 PrimaryExpr Slice |
Russ Cox5958dd62009-03-04 17:19:21 -08002559 PrimaryExpr TypeAssertion |
Robert Griesemerccc713c2014-10-27 16:31:15 -07002560 PrimaryExpr Arguments .
Robert Griesemer57b34612008-10-10 12:45:44 -07002561
Russ Cox5958dd62009-03-04 17:19:21 -08002562Selector = "." identifier .
2563Index = "[" Expression "]" .
Robert Griesemer5583e8a2016-02-23 10:42:06 -08002564Slice = "[" [ Expression ] ":" [ Expression ] "]" |
2565 "[" [ Expression ] ":" Expression ":" Expression "]" .
Russ Cox5958dd62009-03-04 17:19:21 -08002566TypeAssertion = "." "(" Type ")" .
Robert Griesemerccc713c2014-10-27 16:31:15 -07002567Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
Robert Griesemerc2d55862009-02-19 16:49:10 -08002568</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002569
2570
Robert Griesemerc2d55862009-02-19 16:49:10 -08002571<pre>
2572x
25732
2574(s + ".txt")
2575f(3.1415, true)
Rob Pike426335f2009-03-02 17:52:52 -08002576Point{1, 2}
Robert Griesemerc2d55862009-02-19 16:49:10 -08002577m["foo"]
2578s[i : j + 1]
2579obj.color
Robert Griesemerc2d55862009-02-19 16:49:10 -08002580f.p[i].x()
2581</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002582
2583
Russ Cox7c4f7cc2009-08-20 11:11:03 -07002584<h3 id="Selectors">Selectors</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002585
Rob Pikedf3183f2009-02-26 16:37:23 -08002586<p>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002587For a <a href="#Primary_expressions">primary expression</a> <code>x</code>
2588that is not a <a href="#Package_clause">package name</a>, the
2589<i>selector expression</i>
Rob Pikedf3183f2009-02-26 16:37:23 -08002590</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002591
Robert Griesemerc2d55862009-02-19 16:49:10 -08002592<pre>
2593x.f
2594</pre>
Robert Griesemerbbfe3122008-10-09 17:12:09 -07002595
Robert Griesemerc2d55862009-02-19 16:49:10 -08002596<p>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002597denotes the field or method <code>f</code> of the value <code>x</code>
2598(or sometimes <code>*x</code>; see below).
2599The identifier <code>f</code> is called the (field or method) <i>selector</i>;
2600it must not be the <a href="#Blank_identifier">blank identifier</a>.
2601The type of the selector expression is the type of <code>f</code>.
2602If <code>x</code> is a package name, see the section on
2603<a href="#Qualified_identifiers">qualified identifiers</a>.
Rob Pikedf3183f2009-02-26 16:37:23 -08002604</p>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002605
Robert Griesemerc2d55862009-02-19 16:49:10 -08002606<p>
Rob Pikedf3183f2009-02-26 16:37:23 -08002607A selector <code>f</code> may denote a field or method <code>f</code> of
2608a type <code>T</code>, or it may refer
Robert Griesemer71de83b2012-06-28 12:22:24 -07002609to a field or method <code>f</code> of a nested
Robert Griesemerf8b41232017-01-10 16:19:14 -08002610<a href="#Struct_types">embedded field</a> of <code>T</code>.
2611The number of embedded fields traversed
Rob Pikedf3183f2009-02-26 16:37:23 -08002612to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
2613The depth of a field or method <code>f</code>
2614declared in <code>T</code> is zero.
2615The depth of a field or method <code>f</code> declared in
Robert Griesemerf8b41232017-01-10 16:19:14 -08002616an embedded field <code>A</code> in <code>T</code> is the
Rob Pikedf3183f2009-02-26 16:37:23 -08002617depth of <code>f</code> in <code>A</code> plus one.
2618</p>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002619
Robert Griesemerc2d55862009-02-19 16:49:10 -08002620<p>
Robert Griesemer071c91b2008-10-23 12:04:45 -07002621The following rules apply to selectors:
Rob Pikedf3183f2009-02-26 16:37:23 -08002622</p>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002623
Rob Pikedf3183f2009-02-26 16:37:23 -08002624<ol>
2625<li>
2626For a value <code>x</code> of type <code>T</code> or <code>*T</code>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002627where <code>T</code> is not a pointer or interface type,
Rob Pikedf3183f2009-02-26 16:37:23 -08002628<code>x.f</code> denotes the field or method at the shallowest depth
2629in <code>T</code> where there
2630is such an <code>f</code>.
Robert Griesemer103c9db2012-03-01 13:57:49 -08002631If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a>
2632with shallowest depth, the selector expression is illegal.
Rob Pikedf3183f2009-02-26 16:37:23 -08002633</li>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002634
Rob Pikedf3183f2009-02-26 16:37:23 -08002635<li>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002636For a value <code>x</code> of type <code>I</code> where <code>I</code>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002637is an interface type, <code>x.f</code> denotes the actual method with name
Robert Griesemer40818cf2014-11-11 13:19:47 -08002638<code>f</code> of the dynamic value of <code>x</code>.
Robert Griesemer71de83b2012-06-28 12:22:24 -07002639If there is no method with name <code>f</code> in the
2640<a href="#Method_sets">method set</a> of <code>I</code>, the selector
2641expression is illegal.
Rob Pikedf3183f2009-02-26 16:37:23 -08002642</li>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002643
2644<li>
Robert Griesemer9b49ac02018-01-22 16:20:01 -08002645As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a>
2646pointer type and <code>(*x).f</code> is a valid selector expression denoting a field
Robert Griesemer40818cf2014-11-11 13:19:47 -08002647(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>.
2648</li>
2649
Rob Pikedf3183f2009-02-26 16:37:23 -08002650<li>
2651In all other cases, <code>x.f</code> is illegal.
Robert Griesemer3af480372010-05-14 13:11:48 -07002652</li>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002653
Robert Griesemer71de83b2012-06-28 12:22:24 -07002654<li>
Russ Cox6e156832013-03-20 16:54:07 -04002655If <code>x</code> is of pointer type and has the value
2656<code>nil</code> and <code>x.f</code> denotes a struct field,
2657assigning to or evaluating <code>x.f</code>
2658causes a <a href="#Run_time_panics">run-time panic</a>.
2659</li>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002660
Russ Cox6e156832013-03-20 16:54:07 -04002661<li>
2662If <code>x</code> is of interface type and has the value
2663<code>nil</code>, <a href="#Calls">calling</a> or
2664<a href="#Method_values">evaluating</a> the method <code>x.f</code>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002665causes a <a href="#Run_time_panics">run-time panic</a>.
Rob Pike9dfc6f62012-08-29 14:46:57 -07002666</li>
Rob Pikedf3183f2009-02-26 16:37:23 -08002667</ol>
Robert Griesemer71de83b2012-06-28 12:22:24 -07002668
Robert Griesemerc2d55862009-02-19 16:49:10 -08002669<p>
Rob Pikedf3183f2009-02-26 16:37:23 -08002670For example, given the declarations:
2671</p>
Robert Griesemer071c91b2008-10-23 12:04:45 -07002672
Robert Griesemerc2d55862009-02-19 16:49:10 -08002673<pre>
2674type T0 struct {
Robert Griesemer130ac742009-12-10 16:43:01 -08002675 x int
Robert Griesemerc2d55862009-02-19 16:49:10 -08002676}
Robert Griesemer071c91b2008-10-23 12:04:45 -07002677
Robert Griesemer40818cf2014-11-11 13:19:47 -08002678func (*T0) M0()
Robert Griesemer071c91b2008-10-23 12:04:45 -07002679
Robert Griesemerc2d55862009-02-19 16:49:10 -08002680type T1 struct {
Robert Griesemer130ac742009-12-10 16:43:01 -08002681 y int
Robert Griesemerc2d55862009-02-19 16:49:10 -08002682}
Robert Griesemer071c91b2008-10-23 12:04:45 -07002683
Robert Griesemer40818cf2014-11-11 13:19:47 -08002684func (T1) M1()
Robert Griesemer071c91b2008-10-23 12:04:45 -07002685
Robert Griesemerc2d55862009-02-19 16:49:10 -08002686type T2 struct {
Robert Griesemer130ac742009-12-10 16:43:01 -08002687 z int
2688 T1
2689 *T0
Robert Griesemerc2d55862009-02-19 16:49:10 -08002690}
Robert Griesemer071c91b2008-10-23 12:04:45 -07002691
Robert Griesemer40818cf2014-11-11 13:19:47 -08002692func (*T2) M2()
Robert Griesemer071c91b2008-10-23 12:04:45 -07002693
Robert Griesemer40818cf2014-11-11 13:19:47 -08002694type Q *T2
2695
2696var t T2 // with t.T0 != nil
2697var p *T2 // with p != nil and (*p).T0 != nil
2698var q Q = p
Robert Griesemerc2d55862009-02-19 16:49:10 -08002699</pre>
Robert Griesemer071c91b2008-10-23 12:04:45 -07002700
Rob Pikedf3183f2009-02-26 16:37:23 -08002701<p>
2702one may write:
2703</p>
Robert Griesemer071c91b2008-10-23 12:04:45 -07002704
Robert Griesemerc2d55862009-02-19 16:49:10 -08002705<pre>
Robert Griesemer40818cf2014-11-11 13:19:47 -08002706t.z // t.z
2707t.y // t.T1.y
Robert Griesemerf9ec9292015-05-18 11:18:58 -07002708t.x // (*t.T0).x
Robert Griesemer071c91b2008-10-23 12:04:45 -07002709
Robert Griesemer40818cf2014-11-11 13:19:47 -08002710p.z // (*p).z
2711p.y // (*p).T1.y
2712p.x // (*(*p).T0).x
2713
2714q.x // (*(*q).T0).x (*q).x is a valid field selector
2715
Robert Griesemer02d74482015-07-31 11:15:11 -07002716p.M0() // ((*p).T0).M0() M0 expects *T0 receiver
Robert Griesemer40818cf2014-11-11 13:19:47 -08002717p.M1() // ((*p).T1).M1() M1 expects T1 receiver
Robert Griesemer02d74482015-07-31 11:15:11 -07002718p.M2() // p.M2() M2 expects *T2 receiver
2719t.M2() // (&amp;t).M2() M2 expects *T2 receiver, see section on Calls
Robert Griesemer40818cf2014-11-11 13:19:47 -08002720</pre>
2721
2722<p>
2723but the following is invalid:
2724</p>
2725
2726<pre>
2727q.M0() // (*q).M0 is valid but not a field selector
Robert Griesemerc2d55862009-02-19 16:49:10 -08002728</pre>
Robert Griesemerbbfe3122008-10-09 17:12:09 -07002729
2730
Robert Griesemerf8520342014-08-28 08:53:25 -07002731<h3 id="Method_expressions">Method expressions</h3>
2732
2733<p>
2734If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
2735<code>T.M</code> is a function that is callable as a regular function
2736with the same arguments as <code>M</code> prefixed by an additional
2737argument that is the receiver of the method.
2738</p>
2739
2740<pre class="ebnf">
2741MethodExpr = ReceiverType "." MethodName .
griesemerf2d52512017-10-25 11:26:02 -07002742ReceiverType = Type .
Robert Griesemerf8520342014-08-28 08:53:25 -07002743</pre>
2744
2745<p>
2746Consider a struct type <code>T</code> with two methods,
2747<code>Mv</code>, whose receiver is of type <code>T</code>, and
2748<code>Mp</code>, whose receiver is of type <code>*T</code>.
2749</p>
2750
2751<pre>
2752type T struct {
2753 a int
2754}
2755func (tv T) Mv(a int) int { return 0 } // value receiver
2756func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
2757
2758var t T
2759</pre>
2760
2761<p>
2762The expression
2763</p>
2764
2765<pre>
2766T.Mv
2767</pre>
2768
2769<p>
2770yields a function equivalent to <code>Mv</code> but
2771with an explicit receiver as its first argument; it has signature
2772</p>
2773
2774<pre>
2775func(tv T, a int) int
2776</pre>
2777
2778<p>
2779That function may be called normally with an explicit receiver, so
2780these five invocations are equivalent:
2781</p>
2782
2783<pre>
2784t.Mv(7)
2785T.Mv(t, 7)
2786(T).Mv(t, 7)
2787f1 := T.Mv; f1(t, 7)
2788f2 := (T).Mv; f2(t, 7)
2789</pre>
2790
2791<p>
2792Similarly, the expression
2793</p>
2794
2795<pre>
2796(*T).Mp
2797</pre>
2798
2799<p>
2800yields a function value representing <code>Mp</code> with signature
2801</p>
2802
2803<pre>
2804func(tp *T, f float32) float32
2805</pre>
2806
2807<p>
2808For a method with a value receiver, one can derive a function
2809with an explicit pointer receiver, so
2810</p>
2811
2812<pre>
2813(*T).Mv
2814</pre>
2815
2816<p>
2817yields a function value representing <code>Mv</code> with signature
2818</p>
2819
2820<pre>
2821func(tv *T, a int) int
2822</pre>
2823
2824<p>
2825Such a function indirects through the receiver to create a value
2826to pass as the receiver to the underlying method;
2827the method does not overwrite the value whose address is passed in
2828the function call.
2829</p>
2830
2831<p>
2832The final case, a value-receiver function for a pointer-receiver method,
2833is illegal because pointer-receiver methods are not in the method set
2834of the value type.
2835</p>
2836
2837<p>
2838Function values derived from methods are called with function call syntax;
2839the receiver is provided as the first argument to the call.
2840That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
2841as <code>f(t, 7)</code> not <code>t.f(7)</code>.
2842To construct a function that binds the receiver, use a
2843<a href="#Function_literals">function literal</a> or
2844<a href="#Method_values">method value</a>.
2845</p>
2846
2847<p>
2848It is legal to derive a function value from a method of an interface type.
2849The resulting function takes an explicit receiver of that interface type.
2850</p>
2851
2852<h3 id="Method_values">Method values</h3>
2853
2854<p>
2855If the expression <code>x</code> has static type <code>T</code> and
2856<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
2857<code>x.M</code> is called a <i>method value</i>.
2858The method value <code>x.M</code> is a function value that is callable
2859with the same arguments as a method call of <code>x.M</code>.
2860The expression <code>x</code> is evaluated and saved during the evaluation of the
2861method value; the saved copy is then used as the receiver in any calls,
2862which may be executed later.
2863</p>
2864
2865<p>
2866The type <code>T</code> may be an interface or non-interface type.
2867</p>
2868
2869<p>
2870As in the discussion of <a href="#Method_expressions">method expressions</a> above,
2871consider a struct type <code>T</code> with two methods,
2872<code>Mv</code>, whose receiver is of type <code>T</code>, and
2873<code>Mp</code>, whose receiver is of type <code>*T</code>.
2874</p>
2875
2876<pre>
2877type T struct {
2878 a int
2879}
2880func (tv T) Mv(a int) int { return 0 } // value receiver
2881func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
2882
2883var t T
2884var pt *T
2885func makeT() T
2886</pre>
2887
2888<p>
2889The expression
2890</p>
2891
2892<pre>
2893t.Mv
2894</pre>
2895
2896<p>
2897yields a function value of type
2898</p>
2899
2900<pre>
2901func(int) int
2902</pre>
2903
2904<p>
2905These two invocations are equivalent:
2906</p>
2907
2908<pre>
2909t.Mv(7)
2910f := t.Mv; f(7)
2911</pre>
2912
2913<p>
2914Similarly, the expression
2915</p>
2916
2917<pre>
2918pt.Mp
2919</pre>
2920
2921<p>
2922yields a function value of type
2923</p>
2924
2925<pre>
2926func(float32) float32
2927</pre>
2928
2929<p>
2930As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
2931using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
2932</p>
2933
2934<p>
2935As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
2936using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&amp;t).Mp</code>.
2937</p>
2938
2939<pre>
2940f := t.Mv; f(7) // like t.Mv(7)
2941f := pt.Mp; f(7) // like pt.Mp(7)
2942f := pt.Mv; f(7) // like (*pt).Mv(7)
2943f := t.Mp; f(7) // like (&amp;t).Mp(7)
2944f := makeT().Mp // invalid: result of makeT() is not addressable
2945</pre>
2946
2947<p>
2948Although the examples above use non-interface types, it is also legal to create a method value
2949from a value of interface type.
2950</p>
2951
2952<pre>
2953var i interface { M(int) } = myVal
2954f := i.M; f(7) // like i.M(7)
2955</pre>
2956
2957
Robert Griesemer9c9e8112012-12-10 11:55:57 -08002958<h3 id="Index_expressions">Index expressions</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002959
Rob Pikedf3183f2009-02-26 16:37:23 -08002960<p>
Robert Griesemerbbfe3122008-10-09 17:12:09 -07002961A primary expression of the form
Rob Pikedf3183f2009-02-26 16:37:23 -08002962</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07002963
Robert Griesemerc2d55862009-02-19 16:49:10 -08002964<pre>
2965a[x]
2966</pre>
Robert Griesemerbbfe3122008-10-09 17:12:09 -07002967
Rob Pike4501d342009-02-19 17:31:36 -08002968<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07002969denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
2970The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
2971The following rules apply:
Rob Pike4501d342009-02-19 17:31:36 -08002972</p>
Russ Coxeaa92e02009-06-25 14:43:55 -07002973
Robert Griesemerc2d55862009-02-19 16:49:10 -08002974<p>
Robert Griesemer39067062012-12-12 11:06:26 -08002975If <code>a</code> is not a map:
2976</p>
2977<ul>
griesemer9690d242017-08-30 15:10:12 +02002978 <li>the index <code>x</code> must be of integer type or an untyped constant</li>
2979 <li>a constant index must be non-negative and
2980 <a href="#Representability">representable</a> by a value of type <code>int</code></li>
2981 <li>a constant index that is untyped is given type <code>int</code></li>
2982 <li>the index <code>x</code> is <i>in range</i> if <code>0 &lt;= x &lt; len(a)</code>,
Robert Griesemer39067062012-12-12 11:06:26 -08002983 otherwise it is <i>out of range</i></li>
Robert Griesemer39067062012-12-12 11:06:26 -08002984</ul>
2985
2986<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07002987For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
Rob Pike4501d342009-02-19 17:31:36 -08002988</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08002989<ul>
Robert Griesemerea7c57a2012-10-17 11:08:42 -07002990 <li>a <a href="#Constants">constant</a> index must be in range</li>
Robert Griesemer2961d222013-07-31 22:25:47 -07002991 <li>if <code>x</code> is out of range at run time,
Robert Griesemerea7c57a2012-10-17 11:08:42 -07002992 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
Rob Pikedf3183f2009-02-26 16:37:23 -08002993 <li><code>a[x]</code> is the array element at index <code>x</code> and the type of
Oling Cat018e89f2013-01-24 20:46:33 +11002994 <code>a[x]</code> is the element type of <code>A</code></li>
Robert Griesemerea7c57a2012-10-17 11:08:42 -07002995</ul>
2996
2997<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07002998For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
Robert Griesemerea7c57a2012-10-17 11:08:42 -07002999</p>
3000<ul>
Robert Griesemer2961d222013-07-31 22:25:47 -07003001 <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
3002</ul>
3003
3004<p>
3005For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
3006</p>
3007<ul>
3008 <li>if <code>x</code> is out of range at run time,
Robert Griesemerea7c57a2012-10-17 11:08:42 -07003009 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
3010 <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
Oling Cat018e89f2013-01-24 20:46:33 +11003011 <code>a[x]</code> is the element type of <code>S</code></li>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003012</ul>
Russ Coxeaa92e02009-06-25 14:43:55 -07003013
Robert Griesemerc2d55862009-02-19 16:49:10 -08003014<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07003015For <code>a</code> of <a href="#String_types">string type</a>:
Russ Coxeaa92e02009-06-25 14:43:55 -07003016</p>
3017<ul>
Robert Griesemer39067062012-12-12 11:06:26 -08003018 <li>a <a href="#Constants">constant</a> index must be in range
Robert Griesemerea7c57a2012-10-17 11:08:42 -07003019 if the string <code>a</code> is also constant</li>
3020 <li>if <code>x</code> is out of range at run time,
3021 a <a href="#Run_time_panics">run-time panic</a> occurs</li>
Robert Griesemer2961d222013-07-31 22:25:47 -07003022 <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
Oling Cat018e89f2013-01-24 20:46:33 +11003023 <code>a[x]</code> is <code>byte</code></li>
Robert Griesemer3af480372010-05-14 13:11:48 -07003024 <li><code>a[x]</code> may not be assigned to</li>
Russ Coxeaa92e02009-06-25 14:43:55 -07003025</ul>
3026
3027<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07003028For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
Rob Pike4501d342009-02-19 17:31:36 -08003029</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003030<ul>
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003031 <li><code>x</code>'s type must be
Oling Cat018e89f2013-01-24 20:46:33 +11003032 <a href="#Assignability">assignable</a>
3033 to the key type of <code>M</code></li>
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003034 <li>if the map contains an entry with key <code>x</code>,
Robert Griesemer4de1d1d2018-01-03 10:33:11 -08003035 <code>a[x]</code> is the map element with key <code>x</code>
3036 and the type of <code>a[x]</code> is the element type of <code>M</code></li>
Robert Griesemer54731032011-05-12 09:15:59 -07003037 <li>if the map is <code>nil</code> or does not contain such an entry,
Oling Cat018e89f2013-01-24 20:46:33 +11003038 <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
Robert Griesemer4de1d1d2018-01-03 10:33:11 -08003039 for the element type of <code>M</code></li>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003040</ul>
Robert Griesemerbbfe3122008-10-09 17:12:09 -07003041
Robert Griesemerc2d55862009-02-19 16:49:10 -08003042<p>
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003043Otherwise <code>a[x]</code> is illegal.
Rob Pikedf3183f2009-02-26 16:37:23 -08003044</p>
Robert Griesemer7abfcd92008-10-07 17:14:30 -07003045
Rob Pikedf3183f2009-02-26 16:37:23 -08003046<p>
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003047An index expression on a map <code>a</code> of type <code>map[K]V</code>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003048used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pikedf3183f2009-02-26 16:37:23 -08003049</p>
3050
3051<pre>
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003052v, ok = a[x]
3053v, ok := a[x]
3054var v, ok = a[x]
Rob Pikedf3183f2009-02-26 16:37:23 -08003055</pre>
3056
3057<p>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003058yields an additional untyped boolean value. The value of <code>ok</code> is
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003059<code>true</code> if the key <code>x</code> is present in the map, and
Robert Griesemerc0fca132014-08-05 11:31:32 -07003060<code>false</code> otherwise.
Rob Pikedf3183f2009-02-26 16:37:23 -08003061</p>
3062
3063<p>
Robert Griesemer54731032011-05-12 09:15:59 -07003064Assigning to an element of a <code>nil</code> map causes a
3065<a href="#Run_time_panics">run-time panic</a>.
3066</p>
3067
Robert Griesemer29f1ca52010-03-23 14:01:51 -07003068
Robert Griesemere333b962013-09-11 17:18:52 -07003069<h3 id="Slice_expressions">Slice expressions</h3>
3070
3071<p>
3072Slice expressions construct a substring or slice from a string, array, pointer
3073to array, or slice. There are two variants: a simple form that specifies a low
3074and high bound, and a full form that also specifies a bound on the capacity.
3075</p>
3076
3077<h4>Simple slice expressions</h4>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003078
Rob Pikedf3183f2009-02-26 16:37:23 -08003079<p>
Russ Cox8a8445b2011-12-02 13:11:30 -05003080For a string, array, pointer to array, or slice <code>a</code>, the primary expression
Rob Pikedf3183f2009-02-26 16:37:23 -08003081</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003082
Robert Griesemerc2d55862009-02-19 16:49:10 -08003083<pre>
Robert Griesemer9e5bf272010-09-07 16:32:35 -07003084a[low : high]
Robert Griesemerc2d55862009-02-19 16:49:10 -08003085</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003086
Rob Pikedf3183f2009-02-26 16:37:23 -08003087<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07003088constructs a substring or slice. The <i>indices</i> <code>low</code> and
3089<code>high</code> select which elements of operand <code>a</code> appear
3090in the result. The result has indices starting at 0 and length equal to
Robert Griesemer9e5bf272010-09-07 16:32:35 -07003091<code>high</code>&nbsp;-&nbsp;<code>low</code>.
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08003092After slicing the array <code>a</code>
3093</p>
3094
3095<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08003096a := [5]int{1, 2, 3, 4, 5}
3097s := a[1:4]
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08003098</pre>
3099
3100<p>
3101the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements
Rob Pikedf3183f2009-02-26 16:37:23 -08003102</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003103
Robert Griesemerc2d55862009-02-19 16:49:10 -08003104<pre>
3105s[0] == 2
3106s[1] == 3
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08003107s[2] == 4
Robert Griesemerc2d55862009-02-19 16:49:10 -08003108</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003109
Rob Pikedf3183f2009-02-26 16:37:23 -08003110<p>
Robert Griesemer9c9e8112012-12-10 11:55:57 -08003111For convenience, any of the indices may be omitted. A missing <code>low</code>
Robert Griesemer9e5bf272010-09-07 16:32:35 -07003112index defaults to zero; a missing <code>high</code> index defaults to the length of the
3113sliced operand:
Scott Lawrence0c1695b2010-09-07 14:30:17 -07003114</p>
3115
Robert Griesemer9e5bf272010-09-07 16:32:35 -07003116<pre>
Robert Hencke58d18e22013-10-03 12:46:02 -07003117a[2:] // same as a[2 : len(a)]
David Symonds72a29792011-11-29 15:47:36 -08003118a[:3] // same as a[0 : 3]
3119a[:] // same as a[0 : len(a)]
Robert Griesemer9e5bf272010-09-07 16:32:35 -07003120</pre>
3121
Scott Lawrence0c1695b2010-09-07 14:30:17 -07003122<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07003123If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
3124<code>(*a)[low : high]</code>.
3125</p>
3126
3127<p>
3128For arrays or strings, the indices are <i>in range</i> if
3129<code>0</code> &lt;= <code>low</code> &lt;= <code>high</code> &lt;= <code>len(a)</code>,
Robert Griesemerea7c57a2012-10-17 11:08:42 -07003130otherwise they are <i>out of range</i>.
3131For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
griesemerb40831b2017-08-21 15:47:51 +02003132A <a href="#Constants">constant</a> index must be non-negative and
3133<a href="#Representability">representable</a> by a value of type
Robert Griesemer6ffd2352014-03-06 17:11:13 -08003134<code>int</code>; for arrays or constant strings, constant indices must also be in range.
Robert Griesemer2961d222013-07-31 22:25:47 -07003135If both indices are constant, they must satisfy <code>low &lt;= high</code>.
3136If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
Robert Griesemer19b1d352009-09-24 19:36:48 -07003137</p>
3138
Robert Griesemerc2d55862009-02-19 16:49:10 -08003139<p>
Robert Griesemer2961d222013-07-31 22:25:47 -07003140Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
3141the result of the slice operation is a non-constant value of the same type as the operand.
3142For untyped string operands the result is a non-constant value of type <code>string</code>.
Robert Griesemerc423e952010-09-02 10:16:31 -07003143If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
3144and the result of the slice operation is a slice with the same element type as the array.
Rob Pikedf3183f2009-02-26 16:37:23 -08003145</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003146
Robert Griesemer2961d222013-07-31 22:25:47 -07003147<p>
3148If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
griesemer2ac43d52017-08-29 15:48:07 +02003149is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying
3150array with the operand.
Rob Pike15e6ce22013-08-15 13:15:55 +10003151</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003152
Robert Griesemere333b962013-09-11 17:18:52 -07003153<h4>Full slice expressions</h4>
3154
3155<p>
3156For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression
3157</p>
3158
3159<pre>
3160a[low : high : max]
3161</pre>
3162
3163<p>
3164constructs a slice of the same type, and with the same length and elements as the simple slice
3165expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity
3166by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0.
3167After slicing the array <code>a</code>
3168</p>
3169
3170<pre>
3171a := [5]int{1, 2, 3, 4, 5}
3172t := a[1:3:5]
3173</pre>
3174
3175<p>
3176the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements
3177</p>
3178
3179<pre>
3180t[0] == 2
3181t[1] == 3
3182</pre>
3183
3184<p>
3185As for simple slice expressions, if <code>a</code> is a pointer to an array,
3186<code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>.
3187If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>.
3188</p>
3189
3190<p>
3191The indices are <i>in range</i> if <code>0 &lt;= low &lt;= high &lt;= max &lt;= cap(a)</code>,
3192otherwise they are <i>out of range</i>.
griesemerb40831b2017-08-21 15:47:51 +02003193A <a href="#Constants">constant</a> index must be non-negative and
3194<a href="#Representability">representable</a> by a value of type
Robert Griesemer6ffd2352014-03-06 17:11:13 -08003195<code>int</code>; for arrays, constant indices must also be in range.
Robert Griesemere333b962013-09-11 17:18:52 -07003196If multiple indices are constant, the constants that are present must be in range relative to each
3197other.
3198If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
3199</p>
3200
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003201<h3 id="Type_assertions">Type assertions</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003202
Rob Pikedf3183f2009-02-26 16:37:23 -08003203<p>
Robert Griesemere9192752009-12-01 16:15:53 -08003204For an expression <code>x</code> of <a href="#Interface_types">interface type</a>
3205and a type <code>T</code>, the primary expression
Rob Pikedf3183f2009-02-26 16:37:23 -08003206</p>
Robert Griesemer434c6052008-11-07 13:34:37 -08003207
Robert Griesemerc2d55862009-02-19 16:49:10 -08003208<pre>
3209x.(T)
3210</pre>
Robert Griesemer434c6052008-11-07 13:34:37 -08003211
Robert Griesemerc2d55862009-02-19 16:49:10 -08003212<p>
Robert Griesemere9192752009-12-01 16:15:53 -08003213asserts that <code>x</code> is not <code>nil</code>
Russ Coxb89a54e2009-05-20 18:16:04 -07003214and that the value stored in <code>x</code> is of type <code>T</code>.
Russ Cox5958dd62009-03-04 17:19:21 -08003215The notation <code>x.(T)</code> is called a <i>type assertion</i>.
Rob Pikedf3183f2009-02-26 16:37:23 -08003216</p>
3217<p>
Russ Cox5958dd62009-03-04 17:19:21 -08003218More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
Robert Griesemer7bc03712010-06-07 15:49:39 -07003219that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
3220to the type <code>T</code>.
Robert Griesemer48567312012-12-06 09:17:20 -08003221In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>;
3222otherwise the type assertion is invalid since it is not possible for <code>x</code>
3223to store a value of type <code>T</code>.
Russ Cox5958dd62009-03-04 17:19:21 -08003224If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
Robert Griesemer48567312012-12-06 09:17:20 -08003225of <code>x</code> implements the interface <code>T</code>.
Rob Pikedf3183f2009-02-26 16:37:23 -08003226</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003227<p>
Russ Cox5958dd62009-03-04 17:19:21 -08003228If the type assertion holds, the value of the expression is the value
Rob Pike5bb29fb2010-03-25 17:59:59 -07003229stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false,
3230a <a href="#Run_time_panics">run-time panic</a> occurs.
3231In other words, even though the dynamic type of <code>x</code>
Robert Griesemerea7c57a2012-10-17 11:08:42 -07003232is known only at run time, the type of <code>x.(T)</code> is
Rob Pikedf3183f2009-02-26 16:37:23 -08003233known to be <code>T</code> in a correct program.
3234</p>
Robert Griesemer48567312012-12-06 09:17:20 -08003235
3236<pre>
Robert Griesemer023bb032016-10-19 09:56:53 -07003237var x interface{} = 7 // x has dynamic type int and value 7
3238i := x.(int) // i has type int and value 7
Robert Griesemer48567312012-12-06 09:17:20 -08003239
3240type I interface { m() }
Robert Griesemer023bb032016-10-19 09:56:53 -07003241
3242func f(y I) {
3243 s := y.(string) // illegal: string does not implement I (missing method m)
3244 r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader
3245
3246}
Robert Griesemer48567312012-12-06 09:17:20 -08003247</pre>
3248
Robert Griesemerc2d55862009-02-19 16:49:10 -08003249<p>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003250A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pikedf3183f2009-02-26 16:37:23 -08003251</p>
Robert Griesemer434c6052008-11-07 13:34:37 -08003252
Robert Griesemerc2d55862009-02-19 16:49:10 -08003253<pre>
3254v, ok = x.(T)
3255v, ok := x.(T)
Rob Piked5537072009-08-22 00:04:04 -07003256var v, ok = x.(T)
Robert Griesemer507051d2016-08-24 11:33:55 -07003257var v, ok T1 = x.(T)
Robert Griesemerc2d55862009-02-19 16:49:10 -08003258</pre>
Robert Griesemer434c6052008-11-07 13:34:37 -08003259
Robert Griesemerc2d55862009-02-19 16:49:10 -08003260<p>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003261yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code>
3262if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is
3263the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
Robert Griesemer1e38ecd2018-10-23 14:54:59 -07003264No <a href="#Run_time_panics">run-time panic</a> occurs in this case.
Rob Pikedf3183f2009-02-26 16:37:23 -08003265</p>
Robert Griesemer7a4ed4f2008-09-03 15:15:51 -07003266
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003267
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003268<h3 id="Calls">Calls</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003269
Robert Griesemerc2d55862009-02-19 16:49:10 -08003270<p>
Rob Pike96750f12009-02-27 16:47:48 -08003271Given an expression <code>f</code> of function type
3272<code>F</code>,
Rob Pikedf3183f2009-02-26 16:37:23 -08003273</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003274
Robert Griesemerc2d55862009-02-19 16:49:10 -08003275<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07003276f(a1, a2, … an)
Robert Griesemerc2d55862009-02-19 16:49:10 -08003277</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003278
Robert Griesemerc2d55862009-02-19 16:49:10 -08003279<p>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07003280calls <code>f</code> with arguments <code>a1, a2, … an</code>.
Rob Pike4fe41922009-11-07 22:00:59 -08003281Except for one special case, arguments must be single-valued expressions
Robert Griesemer440cc952010-06-07 17:40:21 -07003282<a href="#Assignability">assignable</a> to the parameter types of
Rob Pikedf3183f2009-02-26 16:37:23 -08003283<code>F</code> and are evaluated before the function is called.
3284The type of the expression is the result type
3285of <code>F</code>.
3286A method invocation is similar but the method itself
3287is specified as a selector upon a value of the receiver type for
3288the method.
3289</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003290
Robert Griesemerc2d55862009-02-19 16:49:10 -08003291<pre>
David Symonds72a29792011-11-29 15:47:36 -08003292math.Atan2(x, y) // function call
Robert Griesemer130ac742009-12-10 16:43:01 -08003293var pt *Point
Robert Griesemerccc713c2014-10-27 16:31:15 -07003294pt.Scale(3.5) // method call with receiver pt
Robert Griesemerc2d55862009-02-19 16:49:10 -08003295</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003296
Rob Pikedf3183f2009-02-26 16:37:23 -08003297<p>
Rob Pike633a2ce2012-01-23 08:40:13 -08003298In a function call, the function value and arguments are evaluated in
3299<a href="#Order_of_evaluation">the usual order</a>.
3300After they are evaluated, the parameters of the call are passed by value to the function
3301and the called function begins execution.
3302The return parameters of the function are passed by value
3303back to the calling function when the function returns.
3304</p>
3305
3306<p>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003307Calling a <code>nil</code> function value
Rob Pike633a2ce2012-01-23 08:40:13 -08003308causes a <a href="#Run_time_panics">run-time panic</a>.
3309</p>
3310
3311<p>
Russ Cox1b3083e2013-02-09 14:46:55 -05003312As a special case, if the return values of a function or method
Robert Griesemer440cc952010-06-07 17:40:21 -07003313<code>g</code> are equal in number and individually
3314assignable to the parameters of another function or method
Rob Pike4fe41922009-11-07 22:00:59 -08003315<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
3316will invoke <code>f</code> after binding the return values of
3317<code>g</code> to the parameters of <code>f</code> in order. The call
Russ Cox1b3083e2013-02-09 14:46:55 -05003318of <code>f</code> must contain no parameters other than the call of <code>g</code>,
3319and <code>g</code> must have at least one return value.
Rob Pike4fe41922009-11-07 22:00:59 -08003320If <code>f</code> has a final <code>...</code> parameter, it is
3321assigned the return values of <code>g</code> that remain after
3322assignment of regular parameters.
3323</p>
3324
3325<pre>
3326func Split(s string, pos int) (string, string) {
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08003327 return s[0:pos], s[pos:]
Rob Pike4fe41922009-11-07 22:00:59 -08003328}
3329
3330func Join(s, t string) string {
3331 return s + t
3332}
3333
3334if Join(Split(value, len(value)/2)) != value {
Robert Griesemer7fc4e372011-02-01 12:51:10 -08003335 log.Panic("test fails")
Rob Pike4fe41922009-11-07 22:00:59 -08003336}
3337</pre>
3338
3339<p>
Robert Griesemer2a838d62011-02-08 13:31:01 -08003340A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a>
3341of (the type of) <code>x</code> contains <code>m</code> and the
Robert Griesemer63f01492010-05-28 14:17:30 -07003342argument list can be assigned to the parameter list of <code>m</code>.
Rob Pike678625d2009-09-15 09:54:22 -07003343If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&amp;x</code>'s method
Robert Griesemer56809d02009-05-20 11:02:48 -07003344set contains <code>m</code>, <code>x.m()</code> is shorthand
3345for <code>(&amp;x).m()</code>:
Rob Pikedf3183f2009-02-26 16:37:23 -08003346</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003347
Robert Griesemerc2d55862009-02-19 16:49:10 -08003348<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08003349var p Point
Rob Pikedf3183f2009-02-26 16:37:23 -08003350p.Scale(3.5)
Robert Griesemerc2d55862009-02-19 16:49:10 -08003351</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003352
Robert Griesemerc2d55862009-02-19 16:49:10 -08003353<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003354There is no distinct method type and there are no method literals.
Rob Pikedf3183f2009-02-26 16:37:23 -08003355</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003356
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003357<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003358
Robert Griesemerc2d55862009-02-19 16:49:10 -08003359<p>
Robert Griesemera7662772014-03-06 10:35:05 -08003360If <code>f</code> is <a href="#Function_types">variadic</a> with a final
3361parameter <code>p</code> of type <code>...T</code>, then within <code>f</code>
3362the type of <code>p</code> is equivalent to type <code>[]T</code>.
3363If <code>f</code> is invoked with no actual arguments for <code>p</code>,
3364the value passed to <code>p</code> is <code>nil</code>.
3365Otherwise, the value passed is a new slice
3366of type <code>[]T</code> with a new underlying array whose successive elements
3367are the actual arguments, which all must be <a href="#Assignability">assignable</a>
3368to <code>T</code>. The length and capacity of the slice is therefore
3369the number of arguments bound to <code>p</code> and may differ for each
3370call site.
Rob Pikeb81065d2010-01-27 13:14:40 -08003371</p>
Robert Griesemer69e26bf2008-11-04 16:46:45 -08003372
Rob Pikedf3183f2009-02-26 16:37:23 -08003373<p>
Robert Griesemera7662772014-03-06 10:35:05 -08003374Given the function and calls
Rob Pikeb81065d2010-01-27 13:14:40 -08003375</p>
3376<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07003377func Greeting(prefix string, who ...string)
Robert Griesemera7662772014-03-06 10:35:05 -08003378Greeting("nobody")
Rob Pikeb81065d2010-01-27 13:14:40 -08003379Greeting("hello:", "Joe", "Anna", "Eileen")
3380</pre>
3381
3382<p>
Robert Griesemerac771a82010-09-24 14:08:28 -07003383within <code>Greeting</code>, <code>who</code> will have the value
Robert Griesemera7662772014-03-06 10:35:05 -08003384<code>nil</code> in the first call, and
3385<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second.
Rob Pikeb81065d2010-01-27 13:14:40 -08003386</p>
3387
Robert Griesemerac771a82010-09-24 14:08:28 -07003388<p>
Robert Griesemer904adfd2010-10-27 10:44:31 -07003389If the final argument is assignable to a slice type <code>[]T</code>, it may be
3390passed unchanged as the value for a <code>...T</code> parameter if the argument
3391is followed by <code>...</code>. In this case no new slice is created.
Robert Griesemerac771a82010-09-24 14:08:28 -07003392</p>
Rob Pikeb81065d2010-01-27 13:14:40 -08003393
3394<p>
Robert Griesemerac771a82010-09-24 14:08:28 -07003395Given the slice <code>s</code> and call
Rob Pikeb81065d2010-01-27 13:14:40 -08003396</p>
Robert Griesemer69e26bf2008-11-04 16:46:45 -08003397
Robert Griesemerac771a82010-09-24 14:08:28 -07003398<pre>
3399s := []string{"James", "Jasmine"}
3400Greeting("goodbye:", s...)
3401</pre>
3402
3403<p>
3404within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code>
3405with the same underlying array.
3406</p>
3407
3408
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003409<h3 id="Operators">Operators</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003410
Rob Pikedf3183f2009-02-26 16:37:23 -08003411<p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003412Operators combine operands into expressions.
Rob Pikedf3183f2009-02-26 16:37:23 -08003413</p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003414
Robert Griesemerf7ac31362009-07-10 16:06:40 -07003415<pre class="ebnf">
Matthew Dempskyabb818b2015-04-20 17:17:24 -07003416Expression = UnaryExpr | Expression binary_op Expression .
Rob Pikedf3183f2009-02-26 16:37:23 -08003417UnaryExpr = PrimaryExpr | unary_op UnaryExpr .
Robert Griesemer57b34612008-10-10 12:45:44 -07003418
Robert Griesemerb50ed022011-02-01 12:02:49 -08003419binary_op = "||" | "&amp;&amp;" | rel_op | add_op | mul_op .
Rob Pikedf3183f2009-02-26 16:37:23 -08003420rel_op = "==" | "!=" | "&lt;" | "&lt;=" | ">" | ">=" .
3421add_op = "+" | "-" | "|" | "^" .
Robert Griesemer4ed666e2009-08-27 16:45:42 -07003422mul_op = "*" | "/" | "%" | "&lt;&lt;" | "&gt;&gt;" | "&amp;" | "&amp;^" .
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003423
Rob Pikedf3183f2009-02-26 16:37:23 -08003424unary_op = "+" | "-" | "!" | "^" | "*" | "&amp;" | "&lt;-" .
Robert Griesemerc2d55862009-02-19 16:49:10 -08003425</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003426
Robert Griesemerc2d55862009-02-19 16:49:10 -08003427<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07003428Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
Robert Griesemer7bc03712010-06-07 15:49:39 -07003429For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
Robert Griesemer32d12782011-05-23 14:12:42 -07003430unless the operation involves shifts or untyped <a href="#Constants">constants</a>.
Robert Griesemer19b1d352009-09-24 19:36:48 -07003431For operations involving constants only, see the section on
3432<a href="#Constant_expressions">constant expressions</a>.
Rob Pike4501d342009-02-19 17:31:36 -08003433</p>
Robert Griesemerc8e18762008-09-12 12:26:22 -07003434
Rob Pike83cbca52009-08-21 14:18:08 -07003435<p>
Robert Griesemer32d12782011-05-23 14:12:42 -07003436Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a>
Robert Griesemer26d22602018-10-02 15:55:38 -07003437and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a>
Robert Griesemer19b1d352009-09-24 19:36:48 -07003438to the type of the other operand.
Rob Pike83cbca52009-08-21 14:18:08 -07003439</p>
Robert Griesemer7539c852009-07-31 18:05:07 -07003440
Rob Pike83cbca52009-08-21 14:18:08 -07003441<p>
Robert Griesemer32d12782011-05-23 14:12:42 -07003442The right operand in a shift expression must have unsigned integer type
griesemerb40831b2017-08-21 15:47:51 +02003443or be an untyped constant <a href="#Representability">representable</a> by a
3444value of type <code>uint</code>.
Robert Griesemer32d12782011-05-23 14:12:42 -07003445If the left operand of a non-constant shift expression is an untyped constant,
Robert Griesemer26d22602018-10-02 15:55:38 -07003446it is first implicitly converted to the type it would assume if the shift expression were
Robert Griesemer58e21dd2013-03-15 13:55:50 -07003447replaced by its left operand alone.
Rob Pike83cbca52009-08-21 14:18:08 -07003448</p>
Robert Griesemera6b546f2008-10-20 11:46:40 -07003449
Rob Pike83cbca52009-08-21 14:18:08 -07003450<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08003451var s uint = 33
griesemer9690d242017-08-30 15:10:12 +02003452var i = 1&lt;&lt;s // 1 has type int
3453var j int32 = 1&lt;&lt;s // 1 has type int32; j == 0
3454var k = uint64(1&lt;&lt;s) // 1 has type uint64; k == 1&lt;&lt;33
3455var m int = 1.0&lt;&lt;s // 1.0 has type int; m == 0 if ints are 32bits in size
3456var n = 1.0&lt;&lt;s == j // 1.0 has type int32; n == true
3457var o = 1&lt;&lt;s == 2&lt;&lt;s // 1 and 2 have type int; o == true if ints are 32bits in size
3458var p = 1&lt;&lt;s == 1&lt;&lt;33 // illegal if ints are 32bits in size: 1 has type int, but 1&lt;&lt;33 overflows int
3459var u = 1.0&lt;&lt;s // illegal: 1.0 has type float64, cannot shift
3460var u1 = 1.0&lt;&lt;s != 0 // illegal: 1.0 has type float64, cannot shift
3461var u2 = 1&lt;&lt;s != 1.0 // illegal: 1 has type float64, cannot shift
3462var v float32 = 1&lt;&lt;s // illegal: 1 has type float32, cannot shift
3463var w int64 = 1.0&lt;&lt;33 // 1.0&lt;&lt;33 is a constant shift expression
3464var x = a[1.0&lt;&lt;s] // 1.0 has type int; x == a[0] if ints are 32bits in size
3465var a = make([]byte, 1.0&lt;&lt;s) // 1.0 has type int; len(a) == 0 if ints are 32bits in size
Rob Pike83cbca52009-08-21 14:18:08 -07003466</pre>
Robert Griesemer18b05c12009-01-26 09:34:19 -08003467
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003468
3469<h4 id="Operator_precedence">Operator precedence</h4>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003470<p>
Russ Coxec9b0422009-07-09 16:44:13 -07003471Unary operators have the highest precedence.
3472As the <code>++</code> and <code>--</code> operators form
Rob Pikedf3183f2009-02-26 16:37:23 -08003473statements, not expressions, they fall
Russ Coxec9b0422009-07-09 16:44:13 -07003474outside the operator hierarchy.
Rob Pikedf3183f2009-02-26 16:37:23 -08003475As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
3476<p>
Robert Griesemerb50ed022011-02-01 12:02:49 -08003477There are five precedence levels for binary operators.
Rob Pikedf3183f2009-02-26 16:37:23 -08003478Multiplication operators bind strongest, followed by addition
Russ Cox1b4e37a2012-09-12 12:05:24 -04003479operators, comparison operators, <code>&amp;&amp;</code> (logical AND),
3480and finally <code>||</code> (logical OR):
Rob Pikedf3183f2009-02-26 16:37:23 -08003481</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003482
Rob Pikeff70f092009-02-20 13:36:14 -08003483<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08003484Precedence Operator
Robert Griesemerb50ed022011-02-01 12:02:49 -08003485 5 * / % &lt;&lt; &gt;&gt; &amp; &amp;^
3486 4 + - | ^
Robert Griesemera1368a62011-02-22 15:31:57 -08003487 3 == != &lt; &lt;= &gt; &gt;=
Robert Griesemerc2d55862009-02-19 16:49:10 -08003488 2 &amp;&amp;
3489 1 ||
3490</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003491
Robert Griesemerc2d55862009-02-19 16:49:10 -08003492<p>
Rob Pikedf3183f2009-02-26 16:37:23 -08003493Binary operators of the same precedence associate from left to right.
Robert Griesemerd36d1912009-09-18 11:58:35 -07003494For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
Rob Pikedf3183f2009-02-26 16:37:23 -08003495</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003496
Robert Griesemerc2d55862009-02-19 16:49:10 -08003497<pre>
3498+x
349923 + 3*x[i]
3500x &lt;= f()
Robert Griesemer4ed666e2009-08-27 16:45:42 -07003501^a &gt;&gt; b
Robert Griesemerc2d55862009-02-19 16:49:10 -08003502f() || g()
Russ Cox9c08d652012-02-21 22:04:30 -05003503x == y+1 &amp;&amp; &lt;-chanPtr &gt; 0
Robert Griesemerc2d55862009-02-19 16:49:10 -08003504</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003505
3506
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003507<h3 id="Arithmetic_operators">Arithmetic operators</h3>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003508<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07003509Arithmetic operators apply to numeric values and yield a result of the same
Rob Pikedf3183f2009-02-26 16:37:23 -08003510type as the first operand. The four standard arithmetic operators (<code>+</code>,
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003511<code>-</code>, <code>*</code>, <code>/</code>) apply to integer,
3512floating-point, and complex types; <code>+</code> also applies to strings.
3513The bitwise logical and shift operators apply to integers only.
Rob Pikedf3183f2009-02-26 16:37:23 -08003514</p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003515
Rob Pikeff70f092009-02-20 13:36:14 -08003516<pre class="grammar">
Rob Pike72970872010-03-04 12:35:16 -08003517+ sum integers, floats, complex values, strings
3518- difference integers, floats, complex values
3519* product integers, floats, complex values
3520/ quotient integers, floats, complex values
Rob Pike307ec212009-03-12 15:53:56 -07003521% remainder integers
Robert Griesemerc2d55862009-02-19 16:49:10 -08003522
Russ Cox1b4e37a2012-09-12 12:05:24 -04003523&amp; bitwise AND integers
3524| bitwise OR integers
3525^ bitwise XOR integers
3526&amp;^ bit clear (AND NOT) integers
Robert Griesemerc2d55862009-02-19 16:49:10 -08003527
Robert Griesemer4ed666e2009-08-27 16:45:42 -07003528&lt;&lt; left shift integer &lt;&lt; unsigned integer
3529&gt;&gt; right shift integer &gt;&gt; unsigned integer
Robert Griesemerc2d55862009-02-19 16:49:10 -08003530</pre>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003531
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003532
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003533<h4 id="Integer_operators">Integer operators</h4>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003534
Robert Griesemerc2d55862009-02-19 16:49:10 -08003535<p>
Robert Griesemerbb7eb402011-05-02 17:23:18 -07003536For two integer values <code>x</code> and <code>y</code>, the integer quotient
3537<code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following
3538relationships:
Rob Pikedf3183f2009-02-26 16:37:23 -08003539</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003540
Robert Griesemerc2d55862009-02-19 16:49:10 -08003541<pre>
Robert Griesemerbb7eb402011-05-02 17:23:18 -07003542x = q*y + r and |r| &lt; |y|
Robert Griesemerc2d55862009-02-19 16:49:10 -08003543</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003544
Rob Pikedf3183f2009-02-26 16:37:23 -08003545<p>
Robert Griesemerbb7eb402011-05-02 17:23:18 -07003546with <code>x / y</code> truncated towards zero
Suriyaa Sundararuban1041ac82018-06-13 07:06:04 +00003547(<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
Rob Pikedf3183f2009-02-26 16:37:23 -08003548</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003549
Robert Griesemerc2d55862009-02-19 16:49:10 -08003550<pre>
3551 x y x / y x % y
3552 5 3 1 2
3553-5 3 -1 -2
3554 5 -3 -1 2
3555-5 -3 1 -2
3556</pre>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003557
Rob Pikedf3183f2009-02-26 16:37:23 -08003558<p>
Robert Griesemer18d527b2018-01-16 21:30:46 -08003559The one exception to this rule is that if the dividend <code>x</code> is
3560the most negative value for the int type of <code>x</code>, the quotient
3561<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>)
3562due to two's-complement <a href="#Integer_overflow">integer overflow</a>:
Robert Griesemerbb7eb402011-05-02 17:23:18 -07003563</p>
3564
3565<pre>
3566 x, q
3567int8 -128
3568int16 -32768
3569int32 -2147483648
3570int64 -9223372036854775808
3571</pre>
3572
3573<p>
Robert Griesemerddddd392012-10-19 10:12:09 -07003574If the divisor is a <a href="#Constants">constant</a>, it must not be zero.
3575If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
Matthew Dempsky80a87a92013-01-06 16:56:06 -08003576If the dividend is non-negative and the divisor is a constant power of 2,
Rob Pikef3a33bc2009-09-14 17:39:17 -07003577the division may be replaced by a right shift, and computing the remainder may
Russ Cox1b4e37a2012-09-12 12:05:24 -04003578be replaced by a bitwise AND operation:
Rob Pikedf3183f2009-02-26 16:37:23 -08003579</p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003580
Robert Griesemerc2d55862009-02-19 16:49:10 -08003581<pre>
Robert Griesemer4ed666e2009-08-27 16:45:42 -07003582 x x / 4 x % 4 x &gt;&gt; 2 x &amp; 3
Robert Griesemerc2d55862009-02-19 16:49:10 -08003583 11 2 3 2 3
3584-11 -2 -3 -3 1
3585</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003586
Rob Pikedf3183f2009-02-26 16:37:23 -08003587<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003588The shift operators shift the left operand by the shift count specified by the
3589right operand. They implement arithmetic shifts if the left operand is a signed
Robert Griesemer32d12782011-05-23 14:12:42 -07003590integer and logical shifts if it is an unsigned integer.
3591There is no upper limit on the shift count. Shifts behave
Rob Pikedf3183f2009-02-26 16:37:23 -08003592as if the left operand is shifted <code>n</code> times by 1 for a shift
3593count of <code>n</code>.
Robert Griesemer4ed666e2009-08-27 16:45:42 -07003594As a result, <code>x &lt;&lt; 1</code> is the same as <code>x*2</code>
3595and <code>x &gt;&gt; 1</code> is the same as
Robert Griesemere9192752009-12-01 16:15:53 -08003596<code>x/2</code> but truncated towards negative infinity.
Rob Pikedf3183f2009-02-26 16:37:23 -08003597</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003598
Rob Pikedf3183f2009-02-26 16:37:23 -08003599<p>
3600For integer operands, the unary operators
3601<code>+</code>, <code>-</code>, and <code>^</code> are defined as
Robert Griesemer9dfb2ea2008-12-12 10:30:10 -08003602follows:
Rob Pikedf3183f2009-02-26 16:37:23 -08003603</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003604
Rob Pikeff70f092009-02-20 13:36:14 -08003605<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08003606+x is 0 + x
3607-x negation is 0 - x
Russ Coxd83dc4f2009-05-29 16:04:16 -07003608^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x
3609 and m = -1 for signed x
Robert Griesemerc2d55862009-02-19 16:49:10 -08003610</pre>
Robert Griesemer9dfb2ea2008-12-12 10:30:10 -08003611
3612
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003613<h4 id="Integer_overflow">Integer overflow</h4>
Robert Griesemer9dfb2ea2008-12-12 10:30:10 -08003614
Rob Pikedf3183f2009-02-26 16:37:23 -08003615<p>
3616For unsigned integer values, the operations <code>+</code>,
3617<code>-</code>, <code>*</code>, and <code>&lt;&lt;</code> are
3618computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
Robert Griesemer462a17e2013-03-22 15:36:04 -07003619the <a href="#Numeric_types">unsigned integer</a>'s type.
3620Loosely speaking, these unsigned integer operations
Robert Griesemer8c916a22018-01-09 12:42:28 -08003621discard high bits upon overflow, and programs may rely on "wrap around".
Rob Pikedf3183f2009-02-26 16:37:23 -08003622</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08003623<p>
Rob Pikedf3183f2009-02-26 16:37:23 -08003624For signed integers, the operations <code>+</code>,
Robert Griesemer18d527b2018-01-16 21:30:46 -08003625<code>-</code>, <code>*</code>, <code>/</code>, and <code>&lt;&lt;</code> may legally
Robert Griesemer9dfb2ea2008-12-12 10:30:10 -08003626overflow and the resulting value exists and is deterministically defined
3627by the signed integer representation, the operation, and its operands.
Russ Coxb7ba5232018-11-13 10:23:01 -05003628Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>.
Robert Griesemer18d527b2018-01-16 21:30:46 -08003629A compiler may not optimize code under the assumption that overflow does
Rob Pikedf3183f2009-02-26 16:37:23 -08003630not occur. For instance, it may not assume that <code>x &lt; x + 1</code> is always true.
3631</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003632
3633
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003634<h4 id="Floating_point_operators">Floating-point operators</h4>
3635
3636<p>
3637For floating-point and complex numbers,
3638<code>+x</code> is the same as <code>x</code>,
3639while <code>-x</code> is the negation of <code>x</code>.
3640The result of a floating-point or complex division by zero is not specified beyond the
3641IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a>
3642occurs is implementation-specific.
3643</p>
3644
Robert Griesemer94b60112017-04-11 13:39:24 -07003645<p>
3646An implementation may combine multiple floating-point operations into a single
3647fused operation, possibly across statements, and produce a result that differs
3648from the value obtained by executing and rounding the instructions individually.
Robert Griesemer26d22602018-10-02 15:55:38 -07003649An explicit floating-point type <a href="#Conversions">conversion</a> rounds to
Robert Griesemer94b60112017-04-11 13:39:24 -07003650the precision of the target type, preventing fusion that would discard that rounding.
3651</p>
3652
3653<p>
3654For instance, some architectures provide a "fused multiply and add" (FMA) instruction
3655that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>.
3656These examples show when a Go implementation can use that instruction:
3657</p>
3658
3659<pre>
3660// FMA allowed for computing r, because x*y is not explicitly rounded:
3661r = x*y + z
3662r = z; r += x*y
3663t = x*y; r = t + z
3664*p = x*y; r = *p + z
3665r = x*y + float64(z)
3666
3667// FMA disallowed for computing r, because it would omit rounding of x*y:
3668r = float64(x*y) + z
3669r = z; r += float64(x*y)
3670t = float64(x*y); r = t + z
3671</pre>
Robert Griesemer3dd3ab42015-08-04 15:04:39 -07003672
3673<h4 id="String_concatenation">String concatenation</h4>
3674
3675<p>
3676Strings can be concatenated using the <code>+</code> operator
3677or the <code>+=</code> assignment operator:
3678</p>
3679
3680<pre>
3681s := "hi" + string(c)
3682s += " and good bye"
3683</pre>
3684
3685<p>
3686String addition creates a new string by concatenating the operands.
3687</p>
3688
3689
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003690<h3 id="Comparison_operators">Comparison operators</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003691
Rob Pike5af7de32009-02-24 15:17:59 -08003692<p>
Robert Griesemerc729ed62013-03-11 09:16:29 -07003693Comparison operators compare two operands and yield an untyped boolean value.
Rob Pike5af7de32009-02-24 15:17:59 -08003694</p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003695
Rob Pikeff70f092009-02-20 13:36:14 -08003696<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08003697== equal
3698!= not equal
Anthony Martin0122a662011-02-08 14:51:15 -08003699&lt; less
3700&lt;= less or equal
Russ Cox83f648c2011-12-12 22:21:46 -05003701&gt; greater
3702&gt;= greater or equal
Robert Griesemerc2d55862009-02-19 16:49:10 -08003703</pre>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003704
Rob Pike5af7de32009-02-24 15:17:59 -08003705<p>
Russ Cox83f648c2011-12-12 22:21:46 -05003706In any comparison, the first operand
Robert Griesemer440cc952010-06-07 17:40:21 -07003707must be <a href="#Assignability">assignable</a>
3708to the type of the second operand, or vice versa.
Rob Pike5af7de32009-02-24 15:17:59 -08003709</p>
Robert Griesemer7bc03712010-06-07 15:49:39 -07003710<p>
Russ Cox83f648c2011-12-12 22:21:46 -05003711The equality operators <code>==</code> and <code>!=</code> apply
3712to operands that are <i>comparable</i>.
3713The ordering operators <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code>
3714apply to operands that are <i>ordered</i>.
3715These terms and the result of the comparisons are defined as follows:
Rob Pike5af7de32009-02-24 15:17:59 -08003716</p>
Robert Griesemer1d282a82010-06-03 16:55:50 -07003717
3718<ul>
3719 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003720 Boolean values are comparable.
3721 Two boolean values are equal if they are either both
3722 <code>true</code> or both <code>false</code>.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003723 </li>
Russ Cox83f648c2011-12-12 22:21:46 -05003724
Robert Griesemer1d282a82010-06-03 16:55:50 -07003725 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003726 Integer values are comparable and ordered, in the usual way.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003727 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003728
Robert Griesemer1d282a82010-06-03 16:55:50 -07003729 <li>
Robert Griesemer94b60112017-04-11 13:39:24 -07003730 Floating-point values are comparable and ordered,
Russ Cox83f648c2011-12-12 22:21:46 -05003731 as defined by the IEEE-754 standard.
3732 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003733
Russ Cox83f648c2011-12-12 22:21:46 -05003734 <li>
3735 Complex values are comparable.
3736 Two complex values <code>u</code> and <code>v</code> are
Robert Griesemer1d282a82010-06-03 16:55:50 -07003737 equal if both <code>real(u) == real(v)</code> and
3738 <code>imag(u) == imag(v)</code>.
3739 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003740
Robert Griesemer1d282a82010-06-03 16:55:50 -07003741 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003742 String values are comparable and ordered, lexically byte-wise.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003743 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003744
Robert Griesemer1d282a82010-06-03 16:55:50 -07003745 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003746 Pointer values are comparable.
Robert Griesemer1320ce02012-01-09 16:54:24 -08003747 Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>.
3748 Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003749 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003750
Robert Griesemer1d282a82010-06-03 16:55:50 -07003751 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003752 Channel values are comparable.
Robert Griesemer462a17e2013-03-22 15:36:04 -07003753 Two channel values are equal if they were created by the same call to
3754 <a href="#Making_slices_maps_and_channels"><code>make</code></a>
Russ Cox83f648c2011-12-12 22:21:46 -05003755 or if both have value <code>nil</code>.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003756 </li>
Russ Cox83f648c2011-12-12 22:21:46 -05003757
Robert Griesemer1d282a82010-06-03 16:55:50 -07003758 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003759 Interface values are comparable.
3760 Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types
3761 and equal dynamic values or if both have value <code>nil</code>.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003762 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003763
Robert Griesemer1d282a82010-06-03 16:55:50 -07003764 <li>
Russ Cox83f648c2011-12-12 22:21:46 -05003765 A value <code>x</code> of non-interface type <code>X</code> and
3766 a value <code>t</code> of interface type <code>T</code> are comparable when values
3767 of type <code>X</code> are comparable and
3768 <code>X</code> implements <code>T</code>.
3769 They are equal if <code>t</code>'s dynamic type is identical to <code>X</code>
3770 and <code>t</code>'s dynamic value is equal to <code>x</code>.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003771 </li>
Russ Cox83f648c2011-12-12 22:21:46 -05003772
Robert Griesemer1d282a82010-06-03 16:55:50 -07003773 <li>
Robert Griesemer39084672012-02-16 14:13:17 -08003774 Struct values are comparable if all their fields are comparable.
3775 Two struct values are equal if their corresponding
3776 non-<a href="#Blank_identifier">blank</a> fields are equal.
Russ Cox83f648c2011-12-12 22:21:46 -05003777 </li>
Hong Ruiqi8374e672012-04-05 22:37:07 +10003778
Russ Cox83f648c2011-12-12 22:21:46 -05003779 <li>
3780 Array values are comparable if values of the array element type are comparable.
3781 Two array values are equal if their corresponding elements are equal.
Robert Griesemer1d282a82010-06-03 16:55:50 -07003782 </li>
3783</ul>
Robert Griesemera3294712009-01-05 11:17:26 -08003784
Russ Cox83f648c2011-12-12 22:21:46 -05003785<p>
3786A comparison of two interface values with identical dynamic types
3787causes a <a href="#Run_time_panics">run-time panic</a> if values
3788of that type are not comparable. This behavior applies not only to direct interface
3789value comparisons but also when comparing arrays of interface values
3790or structs with interface-valued fields.
3791</p>
3792
3793<p>
3794Slice, map, and function values are not comparable.
3795However, as a special case, a slice, map, or function value may
3796be compared to the predeclared identifier <code>nil</code>.
3797Comparison of pointer, channel, and interface values to <code>nil</code>
3798is also allowed and follows from the general rules above.
3799</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003800
Russ Cox9c08d652012-02-21 22:04:30 -05003801<pre>
Matthew Dempskyff85f862015-10-20 15:05:22 -07003802const c = 3 &lt; 4 // c is the untyped boolean constant true
Russ Cox9c08d652012-02-21 22:04:30 -05003803
Robert Griesemerc729ed62013-03-11 09:16:29 -07003804type MyBool bool
Russ Cox9c08d652012-02-21 22:04:30 -05003805var x, y int
3806var (
Matthew Dempskyff85f862015-10-20 15:05:22 -07003807 // The result of a comparison is an untyped boolean.
Robert Griesemerc729ed62013-03-11 09:16:29 -07003808 // The usual assignment rules apply.
3809 b3 = x == y // b3 has type bool
3810 b4 bool = x == y // b4 has type bool
3811 b5 MyBool = x == y // b5 has type MyBool
Russ Cox9c08d652012-02-21 22:04:30 -05003812)
3813</pre>
3814
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003815<h3 id="Logical_operators">Logical operators</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003816
Rob Pikedf3183f2009-02-26 16:37:23 -08003817<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07003818Logical operators apply to <a href="#Boolean_types">boolean</a> values
3819and yield a result of the same type as the operands.
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003820The right operand is evaluated conditionally.
Rob Pikedf3183f2009-02-26 16:37:23 -08003821</p>
Robert Griesemer41d65ac2008-09-04 15:17:27 -07003822
Rob Pikeff70f092009-02-20 13:36:14 -08003823<pre class="grammar">
Russ Cox1b4e37a2012-09-12 12:05:24 -04003824&amp;&amp; conditional AND p &amp;&amp; q is "if p then q else false"
3825|| conditional OR p || q is "if p then true else q"
3826! NOT !p is "not p"
Robert Griesemerc2d55862009-02-19 16:49:10 -08003827</pre>
Robert Griesemer7a4ed4f2008-09-03 15:15:51 -07003828
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003829
Russ Cox7c4f7cc2009-08-20 11:11:03 -07003830<h3 id="Address_operators">Address operators</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003831
Rob Pikedf3183f2009-02-26 16:37:23 -08003832<p>
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003833For an operand <code>x</code> of type <code>T</code>, the address operation
3834<code>&amp;x</code> generates a pointer of type <code>*T</code> to <code>x</code>.
3835The operand must be <i>addressable</i>,
Russ Coxe7561de2010-05-24 14:31:43 -07003836that is, either a variable, pointer indirection, or slice indexing
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003837operation; or a field selector of an addressable struct operand;
Russ Coxe7561de2010-05-24 14:31:43 -07003838or an array indexing operation of an addressable array.
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003839As an exception to the addressability requirement, <code>x</code> may also be a
Robert Griesemer614b02d2013-01-02 18:11:49 -08003840(possibly parenthesized)
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003841<a href="#Composite_literals">composite literal</a>.
Robin Eklindcac006a2014-08-30 10:27:01 -07003842If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>,
Rob Pikecec09542013-09-17 07:41:11 +10003843then the evaluation of <code>&amp;x</code> does too.
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003844</p>
Russ Cox5ce78b72013-08-15 14:33:26 -04003845
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003846<p>
3847For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
Robert Griesemer6962c152014-10-16 15:08:49 -07003848indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed
Robert Griesemer0e1d9412011-01-26 11:21:23 -08003849to by <code>x</code>.
Rob Pike633a2ce2012-01-23 08:40:13 -08003850If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code>
3851will cause a <a href="#Run_time_panics">run-time panic</a>.
Rob Pikeafee1c52009-03-20 17:41:25 -07003852</p>
3853
3854<pre>
3855&amp;x
3856&amp;a[f(2)]
Robert Griesemer614b02d2013-01-02 18:11:49 -08003857&amp;Point{2, 3}
Rob Pikeafee1c52009-03-20 17:41:25 -07003858*p
3859*pf(x)
Russ Cox5ce78b72013-08-15 14:33:26 -04003860
3861var x *int = nil
3862*x // causes a run-time panic
Rob Pikecec09542013-09-17 07:41:11 +10003863&amp;*x // causes a run-time panic
Rob Pikeafee1c52009-03-20 17:41:25 -07003864</pre>
3865
Robert Griesemerb50ed022011-02-01 12:02:49 -08003866
3867<h3 id="Receive_operator">Receive operator</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003868
Robert Griesemerc2d55862009-02-19 16:49:10 -08003869<p>
Robert Griesemerb50ed022011-02-01 12:02:49 -08003870For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>,
3871the value of the receive operation <code>&lt;-ch</code> is the value received
Robert Griesemercc3f21c2012-12-03 14:23:41 -08003872from the channel <code>ch</code>. The channel direction must permit receive operations,
3873and the type of the receive operation is the element type of the channel.
3874The expression blocks until a value is available.
Robert Griesemer54731032011-05-12 09:15:59 -07003875Receiving from a <code>nil</code> channel blocks forever.
Robert Griesemerab5c7622013-05-31 11:21:37 -07003876A receive operation on a <a href="#Close">closed</a> channel can always proceed
Robert Griesemer97aa90d2014-05-07 10:40:39 -07003877immediately, yielding the element type's <a href="#The_zero_value">zero value</a>
3878after any previously sent values have been received.
Rob Pikedf3183f2009-02-26 16:37:23 -08003879</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003880
Robert Griesemerc2d55862009-02-19 16:49:10 -08003881<pre>
Robert Griesemere1e76192009-09-25 14:11:03 -07003882v1 := &lt;-ch
3883v2 = &lt;-ch
3884f(&lt;-ch)
Robert Griesemerb50ed022011-02-01 12:02:49 -08003885&lt;-strobe // wait until clock pulse and discard received value
Robert Griesemerc2d55862009-02-19 16:49:10 -08003886</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003887
Rob Pikedf3183f2009-02-26 16:37:23 -08003888<p>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003889A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form
Rob Pikedf3183f2009-02-26 16:37:23 -08003890</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003891
Robert Griesemerc2d55862009-02-19 16:49:10 -08003892<pre>
Robert Griesemere1e76192009-09-25 14:11:03 -07003893x, ok = &lt;-ch
3894x, ok := &lt;-ch
3895var x, ok = &lt;-ch
Robert Griesemer507051d2016-08-24 11:33:55 -07003896var x, ok T = &lt;-ch
Robert Griesemerc2d55862009-02-19 16:49:10 -08003897</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003898
Rob Pikedf3183f2009-02-26 16:37:23 -08003899<p>
Robert Griesemerc0fca132014-08-05 11:31:32 -07003900yields an additional untyped boolean result reporting whether the
Robert Griesemer689931c2012-06-25 11:28:24 -07003901communication succeeded. The value of <code>ok</code> is <code>true</code>
3902if the value received was delivered by a successful send operation to the
3903channel, or <code>false</code> if it is a zero value generated because the
3904channel is closed and empty.
Rob Pikedf3183f2009-02-26 16:37:23 -08003905</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07003906
Robert Griesemerb50ed022011-02-01 12:02:49 -08003907
Robert Griesemer164a7bc2009-09-30 12:00:25 -07003908<h3 id="Conversions">Conversions</h3>
3909
3910<p>
Robert Griesemer26d22602018-10-02 15:55:38 -07003911A conversion changes the <a href="#Types">type</a> of an expression
3912to the type specified by the conversion.
3913A conversion may appear literally in the source, or it may be <i>implied</i>
3914by the context in which an expression appears.
3915</p>
3916
3917<p>
3918An <i>explicit</i> conversion is an expression of the form <code>T(x)</code>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07003919where <code>T</code> is a type and <code>x</code> is an expression
3920that can be converted to type <code>T</code>.
3921</p>
3922
3923<pre class="ebnf">
Robert Griesemer60a6ae82012-09-26 10:31:57 -07003924Conversion = Type "(" Expression [ "," ] ")" .
Robert Griesemer934a5202010-05-24 14:58:26 -07003925</pre>
3926
3927<p>
Robert Griesemer3188ffc2012-10-03 13:46:37 -07003928If the type starts with the operator <code>*</code> or <code>&lt;-</code>,
Russ Cox71c941b2013-02-11 07:48:14 -05003929or if the type starts with the keyword <code>func</code>
3930and has no result list, it must be parenthesized when
3931necessary to avoid ambiguity:
Robert Griesemer934a5202010-05-24 14:58:26 -07003932</p>
3933
3934<pre>
3935*Point(p) // same as *(Point(p))
Russ Cox71c941b2013-02-11 07:48:14 -05003936(*Point)(p) // p is converted to *Point
Robert Griesemer934a5202010-05-24 14:58:26 -07003937&lt;-chan int(c) // same as &lt;-(chan int(c))
Russ Cox71c941b2013-02-11 07:48:14 -05003938(&lt;-chan int)(c) // c is converted to &lt;-chan int
Robert Griesemer3188ffc2012-10-03 13:46:37 -07003939func()(x) // function signature func() x
Russ Cox71c941b2013-02-11 07:48:14 -05003940(func())(x) // x is converted to func()
3941(func() int)(x) // x is converted to func() int
3942func() int(x) // x is converted to func() int (unambiguous)
Robert Griesemer164a7bc2009-09-30 12:00:25 -07003943</pre>
3944
3945<p>
Robert Griesemer27693562011-06-13 16:47:33 -07003946A <a href="#Constants">constant</a> value <code>x</code> can be converted to
griesemerb40831b2017-08-21 15:47:51 +02003947type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a>
3948by a value of <code>T</code>.
Robert Griesemer26d22602018-10-02 15:55:38 -07003949As a special case, an integer constant <code>x</code> can be explicitly converted to a
griesemerb40831b2017-08-21 15:47:51 +02003950<a href="#String_types">string type</a> using the
3951<a href="#Conversions_to_and_from_a_string_type">same rule</a>
3952as for non-constant <code>x</code>.
Robert Griesemer27693562011-06-13 16:47:33 -07003953</p>
3954
Robert Griesemer27693562011-06-13 16:47:33 -07003955<p>
3956Converting a constant yields a typed constant as result.
3957</p>
3958
3959<pre>
3960uint(iota) // iota value of type uint
3961float32(2.718281828) // 2.718281828 of type float32
3962complex128(1) // 1.0 + 0.0i of type complex128
Russ Cox75761792013-02-11 07:47:41 -05003963float32(0.49999999) // 0.5 of type float32
Robert Griesemer55ecda42015-09-17 18:10:20 -07003964float64(-1e-1000) // 0.0 of type float64
Robert Griesemer27693562011-06-13 16:47:33 -07003965string('x') // "x" of type string
3966string(0x266c) // "♬" of type string
3967MyString("foo" + "bar") // "foobar" of type MyString
3968string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant
3969(*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
3970int(1.2) // illegal: 1.2 cannot be represented as an int
3971string(65.0) // illegal: 65.0 is not an integer constant
3972</pre>
3973
3974<p>
3975A non-constant value <code>x</code> can be converted to type <code>T</code>
3976in any of these cases:
Robert Griesemer63f01492010-05-28 14:17:30 -07003977</p>
Robert Griesemer7bc03712010-06-07 15:49:39 -07003978
3979<ul>
3980 <li>
Robert Griesemer440cc952010-06-07 17:40:21 -07003981 <code>x</code> is <a href="#Assignability">assignable</a>
Robert Griesemer7bc03712010-06-07 15:49:39 -07003982 to <code>T</code>.
3983 </li>
3984 <li>
Robert Griesemer5c7a0052016-06-03 13:21:55 -07003985 ignoring struct tags (see below),
3986 <code>x</code>'s type and <code>T</code> have <a href="#Type_identity">identical</a>
Robert Griesemer7bc03712010-06-07 15:49:39 -07003987 <a href="#Types">underlying types</a>.
3988 </li>
3989 <li>
Robert Griesemer5c7a0052016-06-03 13:21:55 -07003990 ignoring struct tags (see below),
Robert Griesemer866f63e2017-02-09 13:22:37 -08003991 <code>x</code>'s type and <code>T</code> are pointer types
3992 that are not <a href="#Type_definitions">defined types</a>,
Robert Griesemer7bc03712010-06-07 15:49:39 -07003993 and their pointer base types have identical underlying types.
3994 </li>
3995 <li>
3996 <code>x</code>'s type and <code>T</code> are both integer or floating
3997 point types.
3998 </li>
3999 <li>
4000 <code>x</code>'s type and <code>T</code> are both complex types.
4001 </li>
4002 <li>
Robert Griesemer60a6ae82012-09-26 10:31:57 -07004003 <code>x</code> is an integer or a slice of bytes or runes
4004 and <code>T</code> is a string type.
Robert Griesemer7bc03712010-06-07 15:49:39 -07004005 </li>
4006 <li>
Robert Griesemer60a6ae82012-09-26 10:31:57 -07004007 <code>x</code> is a string and <code>T</code> is a slice of bytes or runes.
Robert Griesemer7bc03712010-06-07 15:49:39 -07004008 </li>
4009</ul>
4010
4011<p>
Robert Griesemer5c7a0052016-06-03 13:21:55 -07004012<a href="#Struct_types">Struct tags</a> are ignored when comparing struct types
4013for identity for the purpose of conversion:
4014</p>
4015
4016<pre>
4017type Person struct {
4018 Name string
4019 Address *struct {
4020 Street string
4021 City string
4022 }
4023}
4024
4025var data *struct {
4026 Name string `json:"name"`
4027 Address *struct {
4028 Street string `json:"street"`
4029 City string `json:"city"`
4030 } `json:"address"`
4031}
4032
4033var person = (*Person)(data) // ignoring tags, the underlying types are identical
4034</pre>
4035
4036<p>
Robert Griesemer27693562011-06-13 16:47:33 -07004037Specific rules apply to (non-constant) conversions between numeric types or
4038to and from a string type.
Robert Griesemer7bc03712010-06-07 15:49:39 -07004039These conversions may change the representation of <code>x</code>
4040and incur a run-time cost.
4041All other conversions only change the type but not the representation
4042of <code>x</code>.
4043</p>
4044
Robert Griesemer27693562011-06-13 16:47:33 -07004045<p>
4046There is no linguistic mechanism to convert between pointers and integers.
4047The package <a href="#Package_unsafe"><code>unsafe</code></a>
4048implements this functionality under
4049restricted circumstances.
4050</p>
4051
Robert Griesemer7bc03712010-06-07 15:49:39 -07004052<h4>Conversions between numeric types</h4>
Robert Griesemer27693562011-06-13 16:47:33 -07004053
4054<p>
4055For the conversion of non-constant numeric values, the following rules apply:
4056</p>
4057
Robert Griesemer63f01492010-05-28 14:17:30 -07004058<ol>
4059<li>
Robert Griesemer7bc03712010-06-07 15:49:39 -07004060When converting between integer types, if the value is a signed integer, it is
4061sign extended to implicit infinite precision; otherwise it is zero extended.
4062It is then truncated to fit in the result type's size.
4063For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>.
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004064The conversion always yields a valid value; there is no indication of overflow.
Robert Griesemer7bc03712010-06-07 15:49:39 -07004065</li>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004066<li>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004067When converting a floating-point number to an integer, the fraction is discarded
4068(truncation towards zero).
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004069</li>
4070<li>
Robert Griesemer7bc03712010-06-07 15:49:39 -07004071When converting an integer or floating-point number to a floating-point type,
4072or a complex number to another complex type, the result value is rounded
Rob Pike72970872010-03-04 12:35:16 -08004073to the precision specified by the destination type.
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004074For instance, the value of a variable <code>x</code> of type <code>float32</code>
4075may be stored using additional precision beyond that of an IEEE-754 32-bit number,
4076but float32(x) represents the result of rounding <code>x</code>'s value to
407732-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits
Evan Shawcb4e9f82010-05-23 11:21:47 -07004078of precision, but <code>float32(x + 0.1)</code> does not.
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004079</li>
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004080</ol>
4081
4082<p>
Robert Griesemer27693562011-06-13 16:47:33 -07004083In all non-constant conversions involving floating-point or complex values,
Rob Pike72970872010-03-04 12:35:16 -08004084if the result type cannot represent the value the conversion
Robert Griesemer27693562011-06-13 16:47:33 -07004085succeeds but the result value is implementation-dependent.
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004086</p>
4087
Robert Griesemer27693562011-06-13 16:47:33 -07004088<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
Rob Pike1811fac2010-02-17 11:26:09 +11004089
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004090<ol>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004091<li>
Rob Pike1811fac2010-02-17 11:26:09 +11004092Converting a signed or unsigned integer value to a string type yields a
Robert Griesemer7bc03712010-06-07 15:49:39 -07004093string containing the UTF-8 representation of the integer. Values outside
4094the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004095
4096<pre>
David Symonds72a29792011-11-29 15:47:36 -08004097string('a') // "a"
Rémy Oudompheng2b4cc6c2012-07-11 20:26:51 +02004098string(-1) // "\ufffd" == "\xef\xbf\xbd"
David Symonds72a29792011-11-29 15:47:36 -08004099string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8"
Rob Pike1811fac2010-02-17 11:26:09 +11004100type MyString string
David Symonds72a29792011-11-29 15:47:36 -08004101MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5"
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004102</pre>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004103</li>
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004104
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004105<li>
Russ Cox6e3e3802011-11-22 12:30:02 -05004106Converting a slice of bytes to a string type yields
Robert Griesemerde47f682013-06-21 16:11:13 -07004107a string whose successive bytes are the elements of the slice.
Rob Pike1811fac2010-02-17 11:26:09 +11004108
4109<pre>
Robert Griesemerde47f682013-06-21 16:11:13 -07004110string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
4111string([]byte{}) // ""
4112string([]byte(nil)) // ""
Russ Cox6e3e3802011-11-22 12:30:02 -05004113
4114type MyBytes []byte
4115string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
Rob Pike1811fac2010-02-17 11:26:09 +11004116</pre>
4117</li>
4118
4119<li>
Russ Cox6e3e3802011-11-22 12:30:02 -05004120Converting a slice of runes to a string type yields
Robert Griesemerb910a272011-11-01 01:09:22 -04004121a string that is the concatenation of the individual rune values
Robert Griesemerde47f682013-06-21 16:11:13 -07004122converted to strings.
Robert Griesemerb910a272011-11-01 01:09:22 -04004123
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004124<pre>
Robert Griesemerde47f682013-06-21 16:11:13 -07004125string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
4126string([]rune{}) // ""
4127string([]rune(nil)) // ""
Russ Cox6e3e3802011-11-22 12:30:02 -05004128
4129type MyRunes []rune
4130string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004131</pre>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004132</li>
4133
4134<li>
Russ Cox6e3e3802011-11-22 12:30:02 -05004135Converting a value of a string type to a slice of bytes type
Rob Pike1811fac2010-02-17 11:26:09 +11004136yields a slice whose successive elements are the bytes of the string.
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004137
4138<pre>
David Symonds72a29792011-11-29 15:47:36 -08004139[]byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
Robert Griesemerde47f682013-06-21 16:11:13 -07004140[]byte("") // []byte{}
4141
David Symonds72a29792011-11-29 15:47:36 -08004142MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
Rob Pike1811fac2010-02-17 11:26:09 +11004143</pre>
4144</li>
4145
4146<li>
Russ Cox6e3e3802011-11-22 12:30:02 -05004147Converting a value of a string type to a slice of runes type
4148yields a slice containing the individual Unicode code points of the string.
Robert Griesemerde47f682013-06-21 16:11:13 -07004149
Rob Pike1811fac2010-02-17 11:26:09 +11004150<pre>
Robert Griesemerb910a272011-11-01 01:09:22 -04004151[]rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4}
Robert Griesemerde47f682013-06-21 16:11:13 -07004152[]rune("") // []rune{}
4153
Russ Cox6e3e3802011-11-22 12:30:02 -05004154MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4}
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004155</pre>
4156</li>
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004157</ol>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004158
Robert Griesemer164a7bc2009-09-30 12:00:25 -07004159
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004160<h3 id="Constant_expressions">Constant expressions</h3>
Robert Griesemerb90b2132008-09-19 15:49:55 -07004161
Rob Pikef27e9f02009-02-23 19:22:05 -08004162<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07004163Constant expressions may contain only <a href="#Constants">constant</a>
Robert Griesemerea7c57a2012-10-17 11:08:42 -07004164operands and are evaluated at compile time.
Rob Pikef27e9f02009-02-23 19:22:05 -08004165</p>
4166
4167<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07004168Untyped boolean, numeric, and string constants may be used as operands
4169wherever it is legal to use an operand of boolean, numeric, or string type,
Russ Coxa9336352011-12-08 21:48:19 -05004170respectively.
Robert Griesemer19b1d352009-09-24 19:36:48 -07004171</p>
Robert Griesemer997851e2009-09-25 15:36:25 -07004172
4173<p>
Robert Griesemer32d12782011-05-23 14:12:42 -07004174A constant <a href="#Comparison_operators">comparison</a> always yields
Russ Cox9c08d652012-02-21 22:04:30 -05004175an untyped boolean constant. If the left operand of a constant
Robert Griesemer32d12782011-05-23 14:12:42 -07004176<a href="#Operators">shift expression</a> is an untyped constant, the
4177result is an integer constant; otherwise it is a constant of the same
Robert Griesemer462a17e2013-03-22 15:36:04 -07004178type as the left operand, which must be of
4179<a href="#Numeric_types">integer type</a>.
Bryan C. Millsdf480032018-04-13 11:57:13 -04004180</p>
4181
4182<p>
4183Any other operation on untyped constants results in an untyped constant of the
4184same kind; that is, a boolean, integer, floating-point, complex, or string
4185constant.
4186If the untyped operands of a binary operation (other than a shift) are of
4187different kinds, the result is of the operand's kind that appears later in this
4188list: integer, rune, floating-point, complex.
4189For example, an untyped integer constant divided by an
4190untyped complex constant yields an untyped complex constant.
Robert Griesemer19b1d352009-09-24 19:36:48 -07004191</p>
4192
Robert Griesemer32d12782011-05-23 14:12:42 -07004193<pre>
Russ Coxa9336352011-12-08 21:48:19 -05004194const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant)
4195const b = 15 / 4 // b == 3 (untyped integer constant)
4196const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant)
Robert Griesemer2ae61d52012-11-17 11:16:07 -08004197const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division)
4198const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division)
Russ Coxa9336352011-12-08 21:48:19 -05004199const d = 1 &lt;&lt; 3.0 // d == 8 (untyped integer constant)
4200const e = 1.0 &lt;&lt; 3 // e == 8 (untyped integer constant)
Robert Griesemer2d846f62013-05-08 10:42:08 -07004201const f = int32(1) &lt;&lt; 33 // illegal (constant 8589934592 overflows int32)
Robert Griesemer32d12782011-05-23 14:12:42 -07004202const g = float64(2) &gt;&gt; 1 // illegal (float64(2) is a typed floating-point constant)
Russ Coxef1c5352011-12-09 00:13:19 -05004203const h = "foo" &gt; "bar" // h == true (untyped boolean constant)
4204const j = true // j == true (untyped boolean constant)
Rob Pike9dfc6f62012-08-29 14:46:57 -07004205const k = 'w' + 1 // k == 'x' (untyped rune constant)
Russ Coxef1c5352011-12-09 00:13:19 -05004206const l = "hi" // l == "hi" (untyped string constant)
4207const m = string(k) // m == "x" (type string)
Robert Hencke1084ab92011-12-10 10:04:33 -08004208const Σ = 1 - 0.707i // (untyped complex constant)
Russ Coxa9336352011-12-08 21:48:19 -05004209const Δ = Σ + 2.0e-4 // (untyped complex constant)
4210const Φ = iota*1i - 1/1i // (untyped complex constant)
Robert Griesemer32d12782011-05-23 14:12:42 -07004211</pre>
4212
Robert Griesemer19b1d352009-09-24 19:36:48 -07004213<p>
Russ Coxa9336352011-12-08 21:48:19 -05004214Applying the built-in function <code>complex</code> to untyped
Rob Pike9dfc6f62012-08-29 14:46:57 -07004215integer, rune, or floating-point constants yields
Russ Coxa9336352011-12-08 21:48:19 -05004216an untyped complex constant.
Rob Pike72970872010-03-04 12:35:16 -08004217</p>
4218
4219<pre>
Robert Griesemer462860b2012-12-12 14:25:40 -08004220const ic = complex(0, c) // ic == 3.75i (untyped complex constant)
Mihai Borobocea8183ed12013-12-30 13:29:56 -08004221const iΘ = complex(0, Θ) // iΘ == 1i (type complex128)
Rob Pike72970872010-03-04 12:35:16 -08004222</pre>
4223
4224<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07004225Constant expressions are always evaluated exactly; intermediate values and the
4226constants themselves may require precision significantly larger than supported
4227by any predeclared type in the language. The following are legal declarations:
Rob Pikef27e9f02009-02-23 19:22:05 -08004228</p>
4229
4230<pre>
Robert Griesemer462860b2012-12-12 14:25:40 -08004231const Huge = 1 &lt;&lt; 100 // Huge == 1267650600228229401496703205376 (untyped integer constant)
4232const Four int8 = Huge &gt;&gt; 98 // Four == 4 (type int8)
Rob Pikef27e9f02009-02-23 19:22:05 -08004233</pre>
4234
4235<p>
Robert Griesemerddddd392012-10-19 10:12:09 -07004236The divisor of a constant division or remainder operation must not be zero:
4237</p>
4238
4239<pre>
42403.14 / 0.0 // illegal: division by zero
4241</pre>
4242
4243<p>
griesemerb40831b2017-08-21 15:47:51 +02004244The values of <i>typed</i> constants must always be accurately
4245<a href="#Representability">representable</a> by values
Robert Griesemer19b1d352009-09-24 19:36:48 -07004246of the constant type. The following constant expressions are illegal:
Rob Pike21d03492009-03-24 19:16:42 -07004247</p>
4248
4249<pre>
David Symonds72a29792011-11-29 15:47:36 -08004250uint(-1) // -1 cannot be represented as a uint
4251int(3.14) // 3.14 cannot be represented as an int
Robert Griesemer462860b2012-12-12 14:25:40 -08004252int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64
4253Four * 300 // operand 300 cannot be represented as an int8 (type of Four)
4254Four * 100 // product 400 cannot be represented as an int8 (type of Four)
Rob Pike21d03492009-03-24 19:16:42 -07004255</pre>
4256
4257<p>
Robert Griesemer19b1d352009-09-24 19:36:48 -07004258The mask used by the unary bitwise complement operator <code>^</code> matches
Rob Pike678625d2009-09-15 09:54:22 -07004259the rule for non-constants: the mask is all 1s for unsigned constants
Robert Griesemer19b1d352009-09-24 19:36:48 -07004260and -1 for signed and untyped constants.
Rob Pike21d03492009-03-24 19:16:42 -07004261</p>
4262
4263<pre>
David Symonds72a29792011-11-29 15:47:36 -08004264^1 // untyped integer constant, equal to -2
Robert Griesemer462860b2012-12-12 14:25:40 -08004265uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8
David Symonds72a29792011-11-29 15:47:36 -08004266^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
4267int8(^1) // same as int8(-2)
4268^int8(1) // same as -1 ^ int8(1) = -2
Rob Pike21d03492009-03-24 19:16:42 -07004269</pre>
4270
Ian Lance Taylor9126c652012-02-13 11:25:56 -08004271<p>
4272Implementation restriction: A compiler may use rounding while
4273computing untyped floating-point or complex constant expressions; see
4274the implementation restriction in the section
4275on <a href="#Constants">constants</a>. This rounding may cause a
4276floating-point constant expression to be invalid in an integer
4277context, even if it would be integral when calculated using infinite
Robert Griesemerd8c6dac2015-06-23 14:17:59 -07004278precision, and vice versa.
Ian Lance Taylor9126c652012-02-13 11:25:56 -08004279</p>
4280
Robert Griesemer19b1d352009-09-24 19:36:48 -07004281
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004282<h3 id="Order_of_evaluation">Order of evaluation</h3>
Rob Pikec956e902009-04-14 20:10:49 -07004283
4284<p>
Robert Griesemera4366982014-05-20 13:51:39 -07004285At package level, <a href="#Package_initialization">initialization dependencies</a>
Robert Griesemerdbe5f882014-05-07 08:50:52 -07004286determine the evaluation order of individual initialization expressions in
4287<a href="#Variable_declarations">variable declarations</a>.
4288Otherwise, when evaluating the <a href="#Operands">operands</a> of an
4289expression, assignment, or
Robert Griesemerf05a91e2012-08-09 11:50:16 -07004290<a href="#Return_statements">return statement</a>,
4291all function calls, method calls, and
Rob Pikec956e902009-04-14 20:10:49 -07004292communication operations are evaluated in lexical left-to-right
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07004293order.
4294</p>
4295
4296<p>
Robert Griesemerdbe5f882014-05-07 08:50:52 -07004297For example, in the (function-local) assignment
Rob Pikec956e902009-04-14 20:10:49 -07004298</p>
4299<pre>
David Symonds72a29792011-11-29 15:47:36 -08004300y[f()], ok = g(h(), i()+x[j()], &lt;-c), k()
Rob Pikec956e902009-04-14 20:10:49 -07004301</pre>
4302<p>
Robert Griesemer4f185492009-05-01 17:00:16 -07004303the function calls and communication happen in the order
4304<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>,
Robert Griesemere1e76192009-09-25 14:11:03 -07004305<code>&lt;-c</code>, <code>g()</code>, and <code>k()</code>.
Robert Griesemer4f185492009-05-01 17:00:16 -07004306However, the order of those events compared to the evaluation
4307and indexing of <code>x</code> and the evaluation
4308of <code>y</code> is not specified.
Rob Pikec956e902009-04-14 20:10:49 -07004309</p>
4310
Robert Griesemerf05a91e2012-08-09 11:50:16 -07004311<pre>
4312a := 1
Shenghou Mabdac9892013-06-11 02:52:07 +08004313f := func() int { a++; return a }
Robert Griesemerdbe5f882014-05-07 08:50:52 -07004314x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
4315m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
4316n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
Robert Griesemerf05a91e2012-08-09 11:50:16 -07004317</pre>
4318
Rob Pike4fe41922009-11-07 22:00:59 -08004319<p>
Robert Griesemerdbe5f882014-05-07 08:50:52 -07004320At package level, initialization dependencies override the left-to-right rule
4321for individual initialization expressions, but not for operands within each
Robin Eklindcac006a2014-08-30 10:27:01 -07004322expression:
Robert Griesemerdbe5f882014-05-07 08:50:52 -07004323</p>
4324
4325<pre>
4326var a, b, c = f() + v(), g(), sqr(u()) + v()
4327
4328func f() int { return c }
4329func g() int { return a }
4330func sqr(x int) int { return x*x }
4331
4332// functions u and v are independent of all other variables and functions
4333</pre>
4334
4335<p>
4336The function calls happen in the order
4337<code>u()</code>, <code>sqr()</code>, <code>v()</code>,
4338<code>f()</code>, <code>v()</code>, and <code>g()</code>.
4339</p>
4340
4341<p>
Rob Pike4fe41922009-11-07 22:00:59 -08004342Floating-point operations within a single expression are evaluated according to
4343the associativity of the operators. Explicit parentheses affect the evaluation
4344by overriding the default associativity.
4345In the expression <code>x + (y + z)</code> the addition <code>y + z</code>
4346is performed before adding <code>x</code>.
4347</p>
4348
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004349<h2 id="Statements">Statements</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004350
Rob Pike96750f12009-02-27 16:47:48 -08004351<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004352Statements control execution.
Rob Pike96750f12009-02-27 16:47:48 -08004353</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004354
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004355<pre class="ebnf">
Robert Griesemerdea43942009-03-16 17:36:52 -07004356Statement =
Rob Pikef3a33bc2009-09-14 17:39:17 -07004357 Declaration | LabeledStmt | SimpleStmt |
4358 GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
Rob Pike11417162009-03-24 17:45:53 -07004359 FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
4360 DeferStmt .
Robert Griesemer7abfcd92008-10-07 17:14:30 -07004361
Robert Griesemerb50ed022011-02-01 12:02:49 -08004362SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004363</pre>
Robert Griesemer7271e042008-10-09 20:05:24 -07004364
Robert Griesemer9905cec2013-03-04 13:55:35 -08004365<h3 id="Terminating_statements">Terminating statements</h3>
4366
4367<p>
Robert Griesemerf3f507b2017-12-21 15:17:35 -08004368A <i>terminating statement</i> prevents execution of all statements that lexically
4369appear after it in the same <a href="#Blocks">block</a>. The following statements
4370are terminating:
Robert Griesemer9905cec2013-03-04 13:55:35 -08004371</p>
4372
4373<ol>
4374<li>
4375 A <a href="#Return_statements">"return"</a> or
4376 <a href="#Goto_statements">"goto"</a> statement.
4377 <!-- ul below only for regular layout -->
4378 <ul> </ul>
4379</li>
4380
4381<li>
4382 A call to the built-in function
4383 <a href="#Handling_panics"><code>panic</code></a>.
4384 <!-- ul below only for regular layout -->
4385 <ul> </ul>
4386</li>
4387
4388<li>
4389 A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
4390 <!-- ul below only for regular layout -->
4391 <ul> </ul>
4392</li>
4393
4394<li>
4395 An <a href="#If_statements">"if" statement</a> in which:
4396 <ul>
4397 <li>the "else" branch is present, and</li>
4398 <li>both branches are terminating statements.</li>
4399 </ul>
4400</li>
4401
4402<li>
4403 A <a href="#For_statements">"for" statement</a> in which:
4404 <ul>
4405 <li>there are no "break" statements referring to the "for" statement, and</li>
4406 <li>the loop condition is absent.</li>
4407 </ul>
4408</li>
4409
4410<li>
4411 A <a href="#Switch_statements">"switch" statement</a> in which:
4412 <ul>
4413 <li>there are no "break" statements referring to the "switch" statement,</li>
4414 <li>there is a default case, and</li>
4415 <li>the statement lists in each case, including the default, end in a terminating
4416 statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
4417 statement</a>.</li>
4418 </ul>
4419</li>
4420
4421<li>
4422 A <a href="#Select_statements">"select" statement</a> in which:
4423 <ul>
4424 <li>there are no "break" statements referring to the "select" statement, and</li>
4425 <li>the statement lists in each case, including the default if present,
4426 end in a terminating statement.</li>
4427 </ul>
4428</li>
4429
4430<li>
4431 A <a href="#Labeled_statements">labeled statement</a> labeling
4432 a terminating statement.
4433</li>
4434</ol>
4435
4436<p>
4437All other statements are not terminating.
4438</p>
4439
4440<p>
4441A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
Robert Griesemerb5ddbb92016-02-26 15:52:13 -08004442is not empty and its final non-empty statement is terminating.
Robert Griesemer9905cec2013-03-04 13:55:35 -08004443</p>
4444
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004445
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004446<h3 id="Empty_statements">Empty statements</h3>
Robert Griesemeraed247f2008-10-08 17:05:30 -07004447
Rob Pike96750f12009-02-27 16:47:48 -08004448<p>
Robert Griesemeraed247f2008-10-08 17:05:30 -07004449The empty statement does nothing.
Rob Pike96750f12009-02-27 16:47:48 -08004450</p>
Robert Griesemeraed247f2008-10-08 17:05:30 -07004451
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004452<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07004453EmptyStmt = .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004454</pre>
Robert Griesemeraed247f2008-10-08 17:05:30 -07004455
4456
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004457<h3 id="Labeled_statements">Labeled statements</h3>
Robert Griesemerdea43942009-03-16 17:36:52 -07004458
4459<p>
4460A labeled statement may be the target of a <code>goto</code>,
4461<code>break</code> or <code>continue</code> statement.
4462</p>
4463
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004464<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07004465LabeledStmt = Label ":" Statement .
Robert Griesemerdea43942009-03-16 17:36:52 -07004466Label = identifier .
4467</pre>
4468
4469<pre>
Robert Griesemer7fc4e372011-02-01 12:51:10 -08004470Error: log.Panic("error encountered")
Robert Griesemerdea43942009-03-16 17:36:52 -07004471</pre>
4472
4473
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004474<h3 id="Expression_statements">Expression statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004475
Rob Pike96750f12009-02-27 16:47:48 -08004476<p>
Robert Griesemer8c058b32012-09-18 11:25:53 -07004477With the exception of specific built-in functions,
4478function and method <a href="#Calls">calls</a> and
4479<a href="#Receive_operator">receive operations</a>
Robert Griesemer6af887e2011-05-02 09:16:31 -07004480can appear in statement context. Such statements may be parenthesized.
Rob Pike96750f12009-02-27 16:47:48 -08004481</p>
4482
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004483<pre class="ebnf">
Robert Griesemerc1347182011-04-29 12:20:31 -07004484ExpressionStmt = Expression .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004485</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004486
Robert Griesemer8c058b32012-09-18 11:25:53 -07004487<p>
4488The following built-in functions are not permitted in statement context:
4489</p>
4490
4491<pre>
4492append cap complex imag len make new real
4493unsafe.Alignof unsafe.Offsetof unsafe.Sizeof
4494</pre>
4495
Robert Griesemerc2d55862009-02-19 16:49:10 -08004496<pre>
Robert Griesemerb50ed022011-02-01 12:02:49 -08004497h(x+y)
4498f.Close()
Robert Griesemere1e76192009-09-25 14:11:03 -07004499&lt;-ch
Robert Griesemer6af887e2011-05-02 09:16:31 -07004500(&lt;-ch)
Robert Griesemer8c058b32012-09-18 11:25:53 -07004501len("foo") // illegal if len is the built-in function
Robert Griesemerc2d55862009-02-19 16:49:10 -08004502</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004503
4504
Robert Griesemerb50ed022011-02-01 12:02:49 -08004505<h3 id="Send_statements">Send statements</h3>
4506
4507<p>
4508A send statement sends a value on a channel.
Robert Griesemercc3f21c2012-12-03 14:23:41 -08004509The channel expression must be of <a href="#Channel_types">channel type</a>,
4510the channel direction must permit send operations,
4511and the type of the value to be sent must be <a href="#Assignability">assignable</a>
Robert Griesemerb50ed022011-02-01 12:02:49 -08004512to the channel's element type.
4513</p>
4514
4515<pre class="ebnf">
4516SendStmt = Channel "&lt;-" Expression .
4517Channel = Expression .
4518</pre>
4519
4520<p>
4521Both the channel and the value expression are evaluated before communication
Russ Coxe7a138b2012-02-08 15:24:48 -05004522begins. Communication blocks until the send can proceed.
Robert Griesemerb50ed022011-02-01 12:02:49 -08004523A send on an unbuffered channel can proceed if a receiver is ready.
4524A send on a buffered channel can proceed if there is room in the buffer.
Russ Coxe7a138b2012-02-08 15:24:48 -05004525A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>.
Robert Griesemer54731032011-05-12 09:15:59 -07004526A send on a <code>nil</code> channel blocks forever.
Robert Griesemerb50ed022011-02-01 12:02:49 -08004527</p>
4528
4529<pre>
Robert Griesemer97aa90d2014-05-07 10:40:39 -07004530ch &lt;- 3 // send value 3 to channel ch
Robert Griesemerb50ed022011-02-01 12:02:49 -08004531</pre>
4532
Robert Griesemerb50ed022011-02-01 12:02:49 -08004533
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004534<h3 id="IncDec_statements">IncDec statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004535
Rob Pike96750f12009-02-27 16:47:48 -08004536<p>
Robert Griesemer52a54802008-09-30 13:02:50 -07004537The "++" and "--" statements increment or decrement their operands
Robert Griesemer19b1d352009-09-24 19:36:48 -07004538by the untyped <a href="#Constants">constant</a> <code>1</code>.
Robert Griesemer5474e162010-09-28 14:44:19 -07004539As with an assignment, the operand must be <a href="#Address_operators">addressable</a>
4540or a map index expression.
Rob Pike96750f12009-02-27 16:47:48 -08004541</p>
Robert Griesemer52a54802008-09-30 13:02:50 -07004542
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004543<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07004544IncDecStmt = Expression ( "++" | "--" ) .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004545</pre>
Russ Cox5958dd62009-03-04 17:19:21 -08004546
Rob Pike96750f12009-02-27 16:47:48 -08004547<p>
Robert Griesemer506c0082009-09-08 15:41:14 -07004548The following <a href="#Assignments">assignment statements</a> are semantically
Robert Griesemer52a54802008-09-30 13:02:50 -07004549equivalent:
Rob Pike96750f12009-02-27 16:47:48 -08004550</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004551
Rob Pikeff70f092009-02-20 13:36:14 -08004552<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08004553IncDec statement Assignment
4554x++ x += 1
4555x-- x -= 1
4556</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004557
Robert Griesemer5474e162010-09-28 14:44:19 -07004558
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004559<h3 id="Assignments">Assignments</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004560
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004561<pre class="ebnf">
Robert Griesemerc2d55862009-02-19 16:49:10 -08004562Assignment = ExpressionList assign_op ExpressionList .
Rob Pikeff70f092009-02-20 13:36:14 -08004563
Robert Griesemerc2d55862009-02-19 16:49:10 -08004564assign_op = [ add_op | mul_op ] "=" .
4565</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004566
Rob Pike96750f12009-02-27 16:47:48 -08004567<p>
Rob Pike678625d2009-09-15 09:54:22 -07004568Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004569a map index expression, or (for <code>=</code> assignments only) the
4570<a href="#Blank_identifier">blank identifier</a>.
Robert Griesemer6af887e2011-05-02 09:16:31 -07004571Operands may be parenthesized.
Rob Pike96750f12009-02-27 16:47:48 -08004572</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004573
Robert Griesemerc2d55862009-02-19 16:49:10 -08004574<pre>
4575x = 1
4576*p = f()
4577a[i] = 23
Robert Griesemer6af887e2011-05-02 09:16:31 -07004578(k) = &lt;-ch // same as: k = &lt;-ch
Robert Griesemerc2d55862009-02-19 16:49:10 -08004579</pre>
Rob Pike96750f12009-02-27 16:47:48 -08004580
4581<p>
4582An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
Robert Griesemer26e726c2017-03-10 17:17:23 -08004583<code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a>
4584is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
Robert Griesemer637d5982015-06-11 13:21:46 -07004585<code>(y)</code> but evaluates <code>x</code>
Rob Pike96750f12009-02-27 16:47:48 -08004586only once. The <i>op</i><code>=</code> construct is a single token.
Rob Pike678625d2009-09-15 09:54:22 -07004587In assignment operations, both the left- and right-hand expression lists
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004588must contain exactly one single-valued expression, and the left-hand
4589expression must not be the blank identifier.
Rob Pike96750f12009-02-27 16:47:48 -08004590</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004591
Robert Griesemerc2d55862009-02-19 16:49:10 -08004592<pre>
Robert Griesemer4ed666e2009-08-27 16:45:42 -07004593a[i] &lt;&lt;= 2
Rob Pike678625d2009-09-15 09:54:22 -07004594i &amp;^= 1&lt;&lt;n
Robert Griesemerc2d55862009-02-19 16:49:10 -08004595</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004596
Rob Pike96750f12009-02-27 16:47:48 -08004597<p>
4598A tuple assignment assigns the individual elements of a multi-valued
4599operation to a list of variables. There are two forms. In the
4600first, the right hand operand is a single multi-valued expression
Robert Griesemer47094dc2014-09-30 11:44:29 -07004601such as a function call, a <a href="#Channel_types">channel</a> or
4602<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>.
Russ Cox5958dd62009-03-04 17:19:21 -08004603The number of operands on the left
Robert Griesemer4e56b332009-09-10 10:14:00 -07004604hand side must match the number of values. For instance, if
Rob Pike96750f12009-02-27 16:47:48 -08004605<code>f</code> is a function returning two values,
4606</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004607
Robert Griesemerc2d55862009-02-19 16:49:10 -08004608<pre>
4609x, y = f()
4610</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004611
Rob Pike96750f12009-02-27 16:47:48 -08004612<p>
4613assigns the first value to <code>x</code> and the second to <code>y</code>.
Rob Pike96750f12009-02-27 16:47:48 -08004614In the second form, the number of operands on the left must equal the number
Robert Griesemeref45e642009-08-21 11:25:00 -07004615of expressions on the right, each of which must be single-valued, and the
4616<i>n</i>th expression on the right is assigned to the <i>n</i>th
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004617operand on the left:
Robert Griesemer2dde4f52012-05-24 10:59:48 -07004618</p>
4619
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004620<pre>
4621one, two, three = '一', '二', '三'
4622</pre>
4623
4624<p>
4625The <a href="#Blank_identifier">blank identifier</a> provides a way to
4626ignore right-hand side values in an assignment:
4627</p>
4628
4629<pre>
4630_ = x // evaluate x but ignore it
4631x, _ = f() // evaluate f() but ignore second result value
4632</pre>
4633
Robert Griesemer2dde4f52012-05-24 10:59:48 -07004634<p>
4635The assignment proceeds in two phases.
Robert Griesemer9c9e8112012-12-10 11:55:57 -08004636First, the operands of <a href="#Index_expressions">index expressions</a>
Russ Coxfa538112011-10-13 15:44:17 -04004637and <a href="#Address_operators">pointer indirections</a>
4638(including implicit pointer indirections in <a href="#Selectors">selectors</a>)
4639on the left and the expressions on the right are all
4640<a href="#Order_of_evaluation">evaluated in the usual order</a>.
4641Second, the assignments are carried out in left-to-right order.
Rob Pike96750f12009-02-27 16:47:48 -08004642</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004643
Robert Griesemerc2d55862009-02-19 16:49:10 -08004644<pre>
Rob Pike96750f12009-02-27 16:47:48 -08004645a, b = b, a // exchange a and b
Russ Coxfa538112011-10-13 15:44:17 -04004646
4647x := []int{1, 2, 3}
4648i := 0
David Symonds72a29792011-11-29 15:47:36 -08004649i, x[i] = 1, 2 // set i = 1, x[0] = 2
Russ Coxfa538112011-10-13 15:44:17 -04004650
4651i = 0
4652x[i], i = 2, 1 // set x[0] = 2, i = 1
4653
Robert Griesemer2dde4f52012-05-24 10:59:48 -07004654x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end)
Russ Coxfa538112011-10-13 15:44:17 -04004655
David Symonds72a29792011-11-29 15:47:36 -08004656x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5.
Russ Coxfa538112011-10-13 15:44:17 -04004657
4658type Point struct { x, y int }
4659var p *Point
4660x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7
Robert Griesemer2dde4f52012-05-24 10:59:48 -07004661
4662i = 2
4663x = []int{3, 5, 7}
4664for i, x[i] = range x { // set i, x[2] = 0, x[0]
4665 break
4666}
4667// after this loop, i == 0 and x == []int{3, 5, 3}
Robert Griesemerc2d55862009-02-19 16:49:10 -08004668</pre>
Rob Pike96750f12009-02-27 16:47:48 -08004669
4670<p>
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004671In assignments, each value must be <a href="#Assignability">assignable</a>
4672to the type of the operand to which it is assigned, with the following special cases:
Rob Pike96750f12009-02-27 16:47:48 -08004673</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004674
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004675<ol>
Robert Griesemer47094dc2014-09-30 11:44:29 -07004676<li>
4677 Any typed value may be assigned to the blank identifier.
4678</li>
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004679
Robert Griesemer47094dc2014-09-30 11:44:29 -07004680<li>
4681 If an untyped constant
4682 is assigned to a variable of interface type or the blank identifier,
Robert Griesemer26d22602018-10-02 15:55:38 -07004683 the constant is first implicitly <a href="#Conversions">converted</a> to its
Robert Griesemer47094dc2014-09-30 11:44:29 -07004684 <a href="#Constants">default type</a>.
4685</li>
4686
4687<li>
4688 If an untyped boolean value is assigned to a variable of interface type or
Robert Griesemer26d22602018-10-02 15:55:38 -07004689 the blank identifier, it is first implicitly converted to type <code>bool</code>.
Robert Griesemer47094dc2014-09-30 11:44:29 -07004690</li>
Robert Griesemerf57bf7a2013-11-12 21:06:54 -05004691</ol>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004692
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004693<h3 id="If_statements">If statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004694
Rob Pike96750f12009-02-27 16:47:48 -08004695<p>
4696"If" statements specify the conditional execution of two branches
4697according to the value of a boolean expression. If the expression
4698evaluates to true, the "if" branch is executed, otherwise, if
Robert Griesemera1368a62011-02-22 15:31:57 -08004699present, the "else" branch is executed.
Rob Pike96750f12009-02-27 16:47:48 -08004700</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004701
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004702<pre class="ebnf">
Russ Cox58e19aa2011-07-14 17:15:52 -04004703IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004704</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004705
Robert Griesemerc2d55862009-02-19 16:49:10 -08004706<pre>
Robert Griesemera1368a62011-02-22 15:31:57 -08004707if x &gt; max {
4708 x = max
Robert Griesemerc2d55862009-02-19 16:49:10 -08004709}
4710</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004711
Russ Cox5958dd62009-03-04 17:19:21 -08004712<p>
Russ Cox16b95ba2009-08-20 10:22:52 -07004713The expression may be preceded by a simple statement, which
4714executes before the expression is evaluated.
Russ Cox5958dd62009-03-04 17:19:21 -08004715</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004716
Robert Griesemerc2d55862009-02-19 16:49:10 -08004717<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08004718if x := f(); x &lt; y {
4719 return x
Robert Griesemera1368a62011-02-22 15:31:57 -08004720} else if x &gt; z {
Robert Griesemer130ac742009-12-10 16:43:01 -08004721 return z
Robert Griesemerc2d55862009-02-19 16:49:10 -08004722} else {
Robert Griesemer130ac742009-12-10 16:43:01 -08004723 return y
Robert Griesemerc2d55862009-02-19 16:49:10 -08004724}
4725</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004726
4727
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004728<h3 id="Switch_statements">Switch statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004729
Rob Pike96750f12009-02-27 16:47:48 -08004730<p>
4731"Switch" statements provide multi-way execution.
Rob Pike5a578492009-03-17 16:48:35 -07004732An expression or type specifier is compared to the "cases"
4733inside the "switch" to determine which branch
4734to execute.
Rob Pikeafee1c52009-03-20 17:41:25 -07004735</p>
Robert Griesemer091cba82009-03-19 08:39:40 -07004736
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004737<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07004738SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
Robert Griesemer091cba82009-03-19 08:39:40 -07004739</pre>
4740
Rob Pikeafee1c52009-03-20 17:41:25 -07004741<p>
Rob Pike5a578492009-03-17 16:48:35 -07004742There are two forms: expression switches and type switches.
Rob Pike5a578492009-03-17 16:48:35 -07004743In an expression switch, the cases contain expressions that are compared
4744against the value of the switch expression.
4745In a type switch, the cases contain types that are compared against the
4746type of a specially annotated switch expression.
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004747The switch expression is evaluated exactly once in a switch statement.
Rob Pike96750f12009-02-27 16:47:48 -08004748</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004749
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004750<h4 id="Expression_switches">Expression switches</h4>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004751
Rob Pike96750f12009-02-27 16:47:48 -08004752<p>
Rob Pike5a578492009-03-17 16:48:35 -07004753In an expression switch,
4754the switch expression is evaluated and
4755the case expressions, which need not be constants,
Robert Griesemer4f185492009-05-01 17:00:16 -07004756are evaluated left-to-right and top-to-bottom; the first one that equals the
Rob Pike5a578492009-03-17 16:48:35 -07004757switch expression
Rob Pike96750f12009-02-27 16:47:48 -08004758triggers execution of the statements of the associated case;
4759the other cases are skipped.
Rob Pike5a578492009-03-17 16:48:35 -07004760If no case matches and there is a "default" case,
4761its statements are executed.
Rob Pike96750f12009-02-27 16:47:48 -08004762There can be at most one default case and it may appear anywhere in the
4763"switch" statement.
Robert Griesemerab266232014-02-25 09:13:37 -08004764A missing switch expression is equivalent to the boolean value
4765<code>true</code>.
Rob Pike96750f12009-02-27 16:47:48 -08004766</p>
Rob Pike70c1a102009-03-18 19:23:59 -07004767
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004768<pre class="ebnf">
Rob Pikef3a33bc2009-09-14 17:39:17 -07004769ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
Robert Griesemer9905cec2013-03-04 13:55:35 -08004770ExprCaseClause = ExprSwitchCase ":" StatementList .
Robert Griesemer091cba82009-03-19 08:39:40 -07004771ExprSwitchCase = "case" ExpressionList | "default" .
Rob Pike70c1a102009-03-18 19:23:59 -07004772</pre>
4773
Rob Pike96750f12009-02-27 16:47:48 -08004774<p>
Robert Griesemer26d22602018-10-02 15:55:38 -07004775If the switch expression evaluates to an untyped constant, it is first implicitly
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004776<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
Robert Griesemer26d22602018-10-02 15:55:38 -07004777if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>.
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004778The predeclared untyped value <code>nil</code> cannot be used as a switch expression.
4779</p>
4780
4781<p>
Robert Griesemer26d22602018-10-02 15:55:38 -07004782If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a>
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004783to the type of the switch expression.
4784For each (possibly converted) case expression <code>x</code> and the value <code>t</code>
4785of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>.
4786</p>
4787
4788<p>
4789In other words, the switch expression is treated as if it were used to declare and
4790initialize a temporary variable <code>t</code> without explicit type; it is that
4791value of <code>t</code> against which each case expression <code>x</code> is tested
4792for equality.
4793</p>
4794
4795<p>
Robert Griesemer67a6b4f2013-03-01 16:45:14 -08004796In a case or default clause, the last non-empty statement
4797may be a (possibly <a href="#Labeled_statements">labeled</a>)
4798<a href="#Fallthrough_statements">"fallthrough" statement</a> to
Rob Pike96750f12009-02-27 16:47:48 -08004799indicate that control should flow from the end of this clause to
Robert Griesemeraed247f2008-10-08 17:05:30 -07004800the first statement of the next clause.
Rob Pike96750f12009-02-27 16:47:48 -08004801Otherwise control flows to the end of the "switch" statement.
Robert Griesemer67a6b4f2013-03-01 16:45:14 -08004802A "fallthrough" statement may appear as the last statement of all
4803but the last clause of an expression switch.
Rob Pike96750f12009-02-27 16:47:48 -08004804</p>
Robert Griesemer0a162a12009-08-19 16:44:04 -07004805
Robert Griesemerc2d55862009-02-19 16:49:10 -08004806<p>
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004807The switch expression may be preceded by a simple statement, which
Russ Cox16b95ba2009-08-20 10:22:52 -07004808executes before the expression is evaluated.
Rob Pike96750f12009-02-27 16:47:48 -08004809</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004810
Robert Griesemerc2d55862009-02-19 16:49:10 -08004811<pre>
4812switch tag {
Rob Pike65ec16b2009-05-29 15:46:03 -07004813default: s3()
4814case 0, 1, 2, 3: s1()
4815case 4, 5, 6, 7: s2()
Robert Griesemerc2d55862009-02-19 16:49:10 -08004816}
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004817
Andrew Gerrand10b77f72010-03-29 13:12:08 +11004818switch x := f(); { // missing switch expression means "true"
Rob Pike65ec16b2009-05-29 15:46:03 -07004819case x &lt; 0: return -x
4820default: return x
Robert Griesemerc2d55862009-02-19 16:49:10 -08004821}
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004822
Robert Griesemere9192752009-12-01 16:15:53 -08004823switch {
Robert Griesemer130ac742009-12-10 16:43:01 -08004824case x &lt; y: f1()
4825case x &lt; z: f2()
4826case x == 4: f3()
Robert Griesemerc2d55862009-02-19 16:49:10 -08004827}
4828</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004829
Robert Griesemer2d9378c2015-07-27 13:30:16 -07004830<p>
4831Implementation restriction: A compiler may disallow multiple case
4832expressions evaluating to the same constant.
4833For instance, the current compilers disallow duplicate integer,
4834floating point, or string constants in case expressions.
4835</p>
4836
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004837<h4 id="Type_switches">Type switches</h4>
Rob Pike70c1a102009-03-18 19:23:59 -07004838
Rob Pike5a578492009-03-17 16:48:35 -07004839<p>
Rob Pike70c1a102009-03-18 19:23:59 -07004840A type switch compares types rather than values. It is otherwise similar
Robert Griesemer1f95f0d2009-08-27 16:44:17 -07004841to an expression switch. It is marked by a special switch expression that
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004842has the form of a <a href="#Type_assertions">type assertion</a>
Robert Griesemer48567312012-12-06 09:17:20 -08004843using the reserved word <code>type</code> rather than an actual type:
4844</p>
4845
4846<pre>
4847switch x.(type) {
4848// cases
4849}
4850</pre>
4851
4852<p>
4853Cases then match actual types <code>T</code> against the dynamic type of the
4854expression <code>x</code>. As with type assertions, <code>x</code> must be of
4855<a href="#Interface_types">interface type</a>, and each non-interface type
4856<code>T</code> listed in a case must implement the type of <code>x</code>.
Robert Griesemer3d81d4a2016-05-31 13:32:34 -07004857The types listed in the cases of a type switch must all be
4858<a href="#Type_identity">different</a>.
Rob Pike5a578492009-03-17 16:48:35 -07004859</p>
4860
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004861<pre class="ebnf">
Rob Pikef3a33bc2009-09-14 17:39:17 -07004862TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
Russ Coxc1045db2009-12-23 13:48:44 -08004863TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
Robert Griesemer9905cec2013-03-04 13:55:35 -08004864TypeCaseClause = TypeSwitchCase ":" StatementList .
Rob Pike678625d2009-09-15 09:54:22 -07004865TypeSwitchCase = "case" TypeList | "default" .
4866TypeList = Type { "," Type } .
Rob Pike5a578492009-03-17 16:48:35 -07004867</pre>
4868
4869<p>
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004870The TypeSwitchGuard may include a
4871<a href="#Short_variable_declarations">short variable declaration</a>.
Robert Griesemerf8555ea2016-08-18 13:14:30 -07004872When that form is used, the variable is declared at the end of the
4873TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause.
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004874In clauses with a case listing exactly one type, the variable
4875has that type; otherwise, the variable has the type of the expression
4876in the TypeSwitchGuard.
Rob Pike94b67eb2009-03-24 17:40:47 -07004877</p>
4878
4879<p>
griesemer84ac90e2017-08-24 15:05:53 +02004880Instead of a type, a case may use the predeclared identifier
4881<a href="#Predeclared_identifiers"><code>nil</code></a>;
4882that case is selected when the expression in the TypeSwitchGuard
Robert Griesemer1f95f0d2009-08-27 16:44:17 -07004883is a <code>nil</code> interface value.
Robert Griesemer3d81d4a2016-05-31 13:32:34 -07004884There may be at most one <code>nil</code> case.
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004885</p>
4886
4887<p>
Robert Griesemere9192752009-12-01 16:15:53 -08004888Given an expression <code>x</code> of type <code>interface{}</code>,
Rob Pike70c1a102009-03-18 19:23:59 -07004889the following type switch:
Rob Pike5a578492009-03-17 16:48:35 -07004890</p>
4891
4892<pre>
Robert Griesemere9192752009-12-01 16:15:53 -08004893switch i := x.(type) {
Rob Pike94b67eb2009-03-24 17:40:47 -07004894case nil:
Robert Griesemer48567312012-12-06 09:17:20 -08004895 printString("x is nil") // type of i is type of x (interface{})
Rob Pike5a578492009-03-17 16:48:35 -07004896case int:
Robert Griesemer48567312012-12-06 09:17:20 -08004897 printInt(i) // type of i is int
Robert Griesemerb94c0d22011-01-19 23:07:21 -05004898case float64:
Robert Griesemer48567312012-12-06 09:17:20 -08004899 printFloat64(i) // type of i is float64
Robert Griesemerb94c0d22011-01-19 23:07:21 -05004900case func(int) float64:
Robert Griesemer48567312012-12-06 09:17:20 -08004901 printFunction(i) // type of i is func(int) float64
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004902case bool, string:
Robert Griesemer48567312012-12-06 09:17:20 -08004903 printString("type is bool or string") // type of i is type of x (interface{})
Rob Pike5a578492009-03-17 16:48:35 -07004904default:
Robert Griesemer48567312012-12-06 09:17:20 -08004905 printString("don't know the type") // type of i is type of x (interface{})
Rob Pike5a578492009-03-17 16:48:35 -07004906}
4907</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004908
Rob Pike70c1a102009-03-18 19:23:59 -07004909<p>
4910could be rewritten:
4911</p>
4912
4913<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08004914v := x // x is evaluated exactly once
Rob Pike94b67eb2009-03-24 17:40:47 -07004915if v == nil {
Robert Griesemer48567312012-12-06 09:17:20 -08004916 i := v // type of i is type of x (interface{})
Robert Griesemer130ac742009-12-10 16:43:01 -08004917 printString("x is nil")
Russ Cox9c08d652012-02-21 22:04:30 -05004918} else if i, isInt := v.(int); isInt {
Robert Griesemer48567312012-12-06 09:17:20 -08004919 printInt(i) // type of i is int
Russ Cox9c08d652012-02-21 22:04:30 -05004920} else if i, isFloat64 := v.(float64); isFloat64 {
Robert Griesemer48567312012-12-06 09:17:20 -08004921 printFloat64(i) // type of i is float64
Russ Cox9c08d652012-02-21 22:04:30 -05004922} else if i, isFunc := v.(func(int) float64); isFunc {
Robert Griesemer48567312012-12-06 09:17:20 -08004923 printFunction(i) // type of i is func(int) float64
Rob Pike70c1a102009-03-18 19:23:59 -07004924} else {
Robert Griesemer48567312012-12-06 09:17:20 -08004925 _, isBool := v.(bool)
4926 _, isString := v.(string)
Russ Cox9c08d652012-02-21 22:04:30 -05004927 if isBool || isString {
Robert Griesemer48567312012-12-06 09:17:20 -08004928 i := v // type of i is type of x (interface{})
4929 printString("type is bool or string")
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004930 } else {
Robert Griesemer48567312012-12-06 09:17:20 -08004931 i := v // type of i is type of x (interface{})
4932 printString("don't know the type")
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004933 }
Rob Pike70c1a102009-03-18 19:23:59 -07004934}
4935</pre>
4936
Robert Griesemeraeaab592009-08-31 17:30:55 -07004937<p>
Russ Cox16b95ba2009-08-20 10:22:52 -07004938The type switch guard may be preceded by a simple statement, which
4939executes before the guard is evaluated.
Robert Griesemer1f95f0d2009-08-27 16:44:17 -07004940</p>
Robert Griesemer9ecd30a2009-08-27 14:22:51 -07004941
4942<p>
4943The "fallthrough" statement is not permitted in a type switch.
Russ Cox16b95ba2009-08-20 10:22:52 -07004944</p>
4945
Russ Cox7c4f7cc2009-08-20 11:11:03 -07004946<h3 id="For_statements">For statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004947
Rob Pike96750f12009-02-27 16:47:48 -08004948<p>
Robert Griesemerb01f6122016-11-18 10:49:29 -08004949A "for" statement specifies repeated execution of a block. There are three forms:
4950The iteration may be controlled by a single condition, a "for" clause, or a "range" clause.
Rob Pike96750f12009-02-27 16:47:48 -08004951</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004952
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004953<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07004954ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004955Condition = Expression .
4956</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004957
Robert Griesemerb01f6122016-11-18 10:49:29 -08004958<h4 id="For_condition">For statements with single condition</h4>
4959
Rob Pike96750f12009-02-27 16:47:48 -08004960<p>
4961In its simplest form, a "for" statement specifies the repeated execution of
4962a block as long as a boolean condition evaluates to true.
4963The condition is evaluated before each iteration.
Robert Griesemerab266232014-02-25 09:13:37 -08004964If the condition is absent, it is equivalent to the boolean value
4965<code>true</code>.
Rob Pike96750f12009-02-27 16:47:48 -08004966</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004967
Robert Griesemerc2d55862009-02-19 16:49:10 -08004968<pre>
4969for a &lt; b {
4970 a *= 2
4971}
4972</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004973
Robert Griesemerb01f6122016-11-18 10:49:29 -08004974<h4 id="For_clause">For statements with <code>for</code> clause</h4>
4975
Rob Pike96750f12009-02-27 16:47:48 -08004976<p>
Rob Pike678625d2009-09-15 09:54:22 -07004977A "for" statement with a ForClause is also controlled by its condition, but
Rob Pike96750f12009-02-27 16:47:48 -08004978additionally it may specify an <i>init</i>
4979and a <i>post</i> statement, such as an assignment,
Russ Cox16b95ba2009-08-20 10:22:52 -07004980an increment or decrement statement. The init statement may be a
Robert Griesemer4ed666e2009-08-27 16:45:42 -07004981<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
Robert Griesemer2fa3e43f2014-09-25 12:52:05 -07004982Variables declared by the init statement are re-used in each iteration.
Rob Pike96750f12009-02-27 16:47:48 -08004983</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07004984
Robert Griesemerf7ac31362009-07-10 16:06:40 -07004985<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08004986ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
Rob Pike11417162009-03-24 17:45:53 -07004987InitStmt = SimpleStmt .
4988PostStmt = SimpleStmt .
Robert Griesemerc2d55862009-02-19 16:49:10 -08004989</pre>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08004990
Robert Griesemerc2d55862009-02-19 16:49:10 -08004991<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08004992for i := 0; i &lt; 10; i++ {
Robert Griesemerc2d55862009-02-19 16:49:10 -08004993 f(i)
4994}
4995</pre>
Russ Cox5958dd62009-03-04 17:19:21 -08004996
Robert Griesemerc2d55862009-02-19 16:49:10 -08004997<p>
Rob Pike96750f12009-02-27 16:47:48 -08004998If non-empty, the init statement is executed once before evaluating the
4999condition for the first iteration;
5000the post statement is executed after each execution of the block (and
5001only if the block was executed).
Robert Griesemer130ac742009-12-10 16:43:01 -08005002Any element of the ForClause may be empty but the
5003<a href="#Semicolons">semicolons</a> are
Rob Pike96750f12009-02-27 16:47:48 -08005004required unless there is only a condition.
Robert Griesemerab266232014-02-25 09:13:37 -08005005If the condition is absent, it is equivalent to the boolean value
5006<code>true</code>.
Rob Pike96750f12009-02-27 16:47:48 -08005007</p>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08005008
Robert Griesemerc2d55862009-02-19 16:49:10 -08005009<pre>
Rob Pike678625d2009-09-15 09:54:22 -07005010for cond { S() } is the same as for ; cond ; { S() }
5011for { S() } is the same as for true { S() }
Robert Griesemerc2d55862009-02-19 16:49:10 -08005012</pre>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08005013
Robert Griesemerb01f6122016-11-18 10:49:29 -08005014<h4 id="For_range">For statements with <code>range</code> clause</h4>
5015
Rob Pike96750f12009-02-27 16:47:48 -08005016<p>
5017A "for" statement with a "range" clause
Rob Pike7aee71b2009-04-15 20:28:25 -07005018iterates through all entries of an array, slice, string or map,
Robert Griesemer5474e162010-09-28 14:44:19 -07005019or values received on a channel. For each entry it assigns <i>iteration values</i>
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005020to corresponding <i>iteration variables</i> if present and then executes the block.
Rob Pike96750f12009-02-27 16:47:48 -08005021</p>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08005022
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005023<pre class="ebnf">
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005024RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005025</pre>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08005026
Robert Griesemerc2d55862009-02-19 16:49:10 -08005027<p>
Robert Griesemer5474e162010-09-28 14:44:19 -07005028The expression on the right in the "range" clause is called the <i>range expression</i>,
Robert Griesemercc3f21c2012-12-03 14:23:41 -08005029which may be an array, pointer to an array, slice, string, map, or channel permitting
5030<a href="#Receive_operator">receive operations</a>.
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005031As with an assignment, if present the operands on the left must be
Robert Griesemer5474e162010-09-28 14:44:19 -07005032<a href="#Address_operators">addressable</a> or map index expressions; they
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005033denote the iteration variables. If the range expression is a channel, at most
5034one iteration variable is permitted, otherwise there may be up to two.
5035If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
5036the range clause is equivalent to the same clause without that identifier.
Robert Griesemer5474e162010-09-28 14:44:19 -07005037</p>
Rob Pike29d0f022011-01-05 11:39:57 -08005038
5039<p>
griesemerada65572017-10-17 15:30:12 -07005040The range expression <code>x</code> is evaluated once before beginning the loop,
5041with one exception: if at most one iteration variable is present and
5042<code>len(x)</code> is <a href="#Length_and_capacity">constant</a>,
5043the range expression is not evaluated.
Russ Cox61e02ee2013-02-15 14:39:28 -05005044</p>
5045
5046<p>
Robert Griesemer5474e162010-09-28 14:44:19 -07005047Function calls on the left are evaluated once per iteration.
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005048For each iteration, iteration values are produced as follows
5049if the respective iteration variables are present:
Robert Griesemer5474e162010-09-28 14:44:19 -07005050</p>
5051
5052<pre class="grammar">
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005053Range expression 1st value 2nd value
Robert Griesemer5474e162010-09-28 14:44:19 -07005054
5055array or slice a [n]E, *[n]E, or []E index i int a[i] E
Robert Griesemerb910a272011-11-01 01:09:22 -04005056string s string type index i int see below rune
Robert Griesemer5474e162010-09-28 14:44:19 -07005057map m map[K]V key k K m[k] V
Shenghou Maced57152013-01-17 23:11:25 +08005058channel c chan E, &lt;-chan E element e E
Robert Griesemer5474e162010-09-28 14:44:19 -07005059</pre>
5060
5061<ol>
5062<li>
Robert Griesemer54731032011-05-12 09:15:59 -07005063For an array, pointer to array, or slice value <code>a</code>, the index iteration
Russ Cox61e02ee2013-02-15 14:39:28 -05005064values are produced in increasing order, starting at element index 0.
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005065If at most one iteration variable is present, the range loop produces
Robert Griesemerbb3a32e2013-05-20 13:27:53 -07005066iteration values from 0 up to <code>len(a)-1</code> and does not index into the array
Robert Griesemer54731032011-05-12 09:15:59 -07005067or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
Robert Griesemer5474e162010-09-28 14:44:19 -07005068</li>
5069
5070<li>
5071For a string value, the "range" clause iterates over the Unicode code points
5072in the string starting at byte index 0. On successive iterations, the index value will be the
5073index of the first byte of successive UTF-8-encoded code points in the string,
Robert Griesemerb910a272011-11-01 01:09:22 -04005074and the second value, of type <code>rune</code>, will be the value of
Rob Pike7aee71b2009-04-15 20:28:25 -07005075the corresponding code point. If the iteration encounters an invalid
Robert Griesemer5474e162010-09-28 14:44:19 -07005076UTF-8 sequence, the second value will be <code>0xFFFD</code>,
Rob Pike7aee71b2009-04-15 20:28:25 -07005077the Unicode replacement character, and the next iteration will advance
5078a single byte in the string.
Robert Griesemer5474e162010-09-28 14:44:19 -07005079</li>
5080
5081<li>
Russ Coxe40d6e02011-10-17 18:49:02 -04005082The iteration order over maps is not specified
5083and is not guaranteed to be the same from one iteration to the next.
Robert Griesemer4e9c86a2017-06-28 10:15:24 -07005084If a map entry that has not yet been reached is removed during iteration,
5085the corresponding iteration value will not be produced. If a map entry is
Shenghou Maced57152013-01-17 23:11:25 +08005086created during iteration, that entry may be produced during the iteration or
5087may be skipped. The choice may vary for each entry created and from one
5088iteration to the next.
5089If the map is <code>nil</code>, the number of iterations is 0.
Robert Griesemer5474e162010-09-28 14:44:19 -07005090</li>
5091
5092<li>
5093For channels, the iteration values produced are the successive values sent on
Robert Griesemer54731032011-05-12 09:15:59 -07005094the channel until the channel is <a href="#Close">closed</a>. If the channel
5095is <code>nil</code>, the range expression blocks forever.
Robert Griesemer5474e162010-09-28 14:44:19 -07005096</li>
Anthony Martin0122a662011-02-08 14:51:15 -08005097</ol>
Robert Griesemer5474e162010-09-28 14:44:19 -07005098
Rob Pike7aee71b2009-04-15 20:28:25 -07005099<p>
Robert Griesemer5474e162010-09-28 14:44:19 -07005100The iteration values are assigned to the respective
5101iteration variables as in an <a href="#Assignments">assignment statement</a>.
Rob Pike94b67eb2009-03-24 17:40:47 -07005102</p>
Robert Griesemer5474e162010-09-28 14:44:19 -07005103
Rob Pike94b67eb2009-03-24 17:40:47 -07005104<p>
Robert Griesemerda633712012-02-29 09:06:05 -08005105The iteration variables may be declared by the "range" clause using a form of
Robert Griesemer2c9e1632012-02-28 17:44:24 -08005106<a href="#Short_variable_declarations">short variable declaration</a>
5107(<code>:=</code>).
Robert Griesemer5474e162010-09-28 14:44:19 -07005108In this case their types are set to the types of the respective iteration values
Robert Griesemer2fa3e43f2014-09-25 12:52:05 -07005109and their <a href="#Declarations_and_scope">scope</a> is the block of the "for"
Robert Griesemer5474e162010-09-28 14:44:19 -07005110statement; they are re-used in each iteration.
Rob Pike96750f12009-02-27 16:47:48 -08005111If the iteration variables are declared outside the "for" statement,
5112after execution their values will be those of the last iteration.
5113</p>
Robert Griesemer30a1a8c2008-12-16 11:38:56 -08005114
Robert Griesemerc2d55862009-02-19 16:49:10 -08005115<pre>
Robert Griesemer54731032011-05-12 09:15:59 -07005116var testdata *struct {
5117 a *[7]int
5118}
5119for i, _ := range testdata.a {
5120 // testdata.a is never evaluated; len(testdata.a) is constant
5121 // i ranges from 0 to 6
5122 f(i)
5123}
5124
Robert Griesemer130ac742009-12-10 16:43:01 -08005125var a [10]string
Robert Griesemerc2d55862009-02-19 16:49:10 -08005126for i, s := range a {
5127 // type of i is int
5128 // type of s is string
5129 // s == a[i]
5130 g(i, s)
5131}
5132
Robert Griesemer130ac742009-12-10 16:43:01 -08005133var key string
Robert Griesemer4de1d1d2018-01-03 10:33:11 -08005134var val interface {} // element type of m is assignable to val
Robert Griesemer63f54ae2013-07-11 14:41:46 -07005135m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
Rob Pike678625d2009-09-15 09:54:22 -07005136for key, val = range m {
5137 h(key, val)
Robert Griesemerc2d55862009-02-19 16:49:10 -08005138}
5139// key == last map key encountered in iteration
5140// val == map[key]
Robert Griesemer54731032011-05-12 09:15:59 -07005141
5142var ch chan Work = producer()
5143for w := range ch {
5144 doWork(w)
5145}
Robert Griesemer20ae6d92014-07-14 15:08:09 -07005146
5147// empty a channel
5148for range ch {}
Robert Griesemerc2d55862009-02-19 16:49:10 -08005149</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005150
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005151
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005152<h3 id="Go_statements">Go statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005153
Rob Pike96750f12009-02-27 16:47:48 -08005154<p>
Robert Griesemer25dd0022012-11-29 11:46:25 -08005155A "go" statement starts the execution of a function call
Rob Pike96750f12009-02-27 16:47:48 -08005156as an independent concurrent thread of control, or <i>goroutine</i>,
5157within the same address space.
5158</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005159
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005160<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005161GoStmt = "go" Expression .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005162</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005163
Rob Pike96750f12009-02-27 16:47:48 -08005164<p>
Robert Griesemer25dd0022012-11-29 11:46:25 -08005165The expression must be a function or method call; it cannot be parenthesized.
5166Calls of built-in functions are restricted as for
5167<a href="#Expression_statements">expression statements</a>.
5168</p>
5169
5170<p>
Rob Pike633a2ce2012-01-23 08:40:13 -08005171The function value and parameters are
5172<a href="#Calls">evaluated as usual</a>
5173in the calling goroutine, but
Rob Pike96750f12009-02-27 16:47:48 -08005174unlike with a regular call, program execution does not wait
Robert Griesemerb9f8b9c2008-09-26 13:38:38 -07005175for the invoked function to complete.
Rob Pike633a2ce2012-01-23 08:40:13 -08005176Instead, the function begins executing independently
5177in a new goroutine.
5178When the function terminates, its goroutine also terminates.
5179If the function has any return values, they are discarded when the
5180function completes.
Rob Pike96750f12009-02-27 16:47:48 -08005181</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005182
Robert Griesemerc2d55862009-02-19 16:49:10 -08005183<pre>
5184go Server()
Brad Fitzpatricke9635102017-05-04 02:39:56 +00005185go func(ch chan&lt;- bool) { for { sleep(10); ch &lt;- true }} (c)
Robert Griesemerc2d55862009-02-19 16:49:10 -08005186</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005187
5188
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005189<h3 id="Select_statements">Select statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005190
Rob Pike96750f12009-02-27 16:47:48 -08005191<p>
Robert Griesemer61d8a332014-05-14 11:47:19 -07005192A "select" statement chooses which of a set of possible
5193<a href="#Send_statements">send</a> or
5194<a href="#Receive_operator">receive</a>
5195operations will proceed.
5196It looks similar to a
5197<a href="#Switch_statements">"switch"</a> statement but with the
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005198cases all referring to communication operations.
Rob Pike96750f12009-02-27 16:47:48 -08005199</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005200
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005201<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005202SelectStmt = "select" "{" { CommClause } "}" .
Robert Griesemer9905cec2013-03-04 13:55:35 -08005203CommClause = CommCase ":" StatementList .
Robert Griesemerb50ed022011-02-01 12:02:49 -08005204CommCase = "case" ( SendStmt | RecvStmt ) | "default" .
Robert Griesemerd3679722013-01-18 13:59:25 -08005205RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
Robert Griesemerc1347182011-04-29 12:20:31 -07005206RecvExpr = Expression .
Russ Cox61439182011-01-31 17:42:10 -05005207</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005208
Rob Pike96750f12009-02-27 16:47:48 -08005209<p>
Robert Griesemer61d8a332014-05-14 11:47:19 -07005210A case with a RecvStmt may assign the result of a RecvExpr to one or
5211two variables, which may be declared using a
Robert Griesemer4ed666e2009-08-27 16:45:42 -07005212<a href="#Short_variable_declarations">short variable declaration</a>.
Robert Griesemer61d8a332014-05-14 11:47:19 -07005213The RecvExpr must be a (possibly parenthesized) receive operation.
5214There can be at most one default case and it may appear anywhere
5215in the list of cases.
5216</p>
5217
5218<p>
5219Execution of a "select" statement proceeds in several steps:
5220</p>
5221
5222<ol>
5223<li>
5224For all the cases in the statement, the channel operands of receive operations
5225and the channel and right-hand-side expressions of send statements are
5226evaluated exactly once, in source order, upon entering the "select" statement.
5227The result is a set of channels to receive from or send to,
5228and the corresponding values to send.
5229Any side effects in that evaluation will occur irrespective of which (if any)
5230communication operation is selected to proceed.
5231Expressions on the left-hand side of a RecvStmt with a short variable declaration
5232or assignment are not yet evaluated.
5233</li>
5234
5235<li>
5236If one or more of the communications can proceed,
5237a single one that can proceed is chosen via a uniform pseudo-random selection.
5238Otherwise, if there is a default case, that case is chosen.
5239If there is no default case, the "select" statement blocks until
5240at least one of the communications can proceed.
5241</li>
5242
5243<li>
5244Unless the selected case is the default case, the respective communication
5245operation is executed.
5246</li>
5247
5248<li>
5249If the selected case is a RecvStmt with a short variable declaration or
5250an assignment, the left-hand side expressions are evaluated and the
5251received value (or values) are assigned.
5252</li>
5253
5254<li>
5255The statement list of the selected case is executed.
5256</li>
5257</ol>
5258
5259<p>
5260Since communication on <code>nil</code> channels can never proceed,
5261a select with only <code>nil</code> channels and no default case blocks forever.
Rob Pike96750f12009-02-27 16:47:48 -08005262</p>
Robert Griesemer2902a822008-09-17 13:57:11 -07005263
Robert Griesemerc2d55862009-02-19 16:49:10 -08005264<pre>
Robert Griesemer61d8a332014-05-14 11:47:19 -07005265var a []int
5266var c, c1, c2, c3, c4 chan int
Robert Griesemer130ac742009-12-10 16:43:01 -08005267var i1, i2 int
Robert Griesemerc2d55862009-02-19 16:49:10 -08005268select {
5269case i1 = &lt;-c1:
Robert Griesemer130ac742009-12-10 16:43:01 -08005270 print("received ", i1, " from c1\n")
Robert Griesemerc2d55862009-02-19 16:49:10 -08005271case c2 &lt;- i2:
Robert Griesemer130ac742009-12-10 16:43:01 -08005272 print("sent ", i2, " to c2\n")
Robert Griesemer6af887e2011-05-02 09:16:31 -07005273case i3, ok := (&lt;-c3): // same as: i3, ok := &lt;-c3
Russ Cox19d9a402011-01-27 15:34:28 -05005274 if ok {
5275 print("received ", i3, " from c3\n")
5276 } else {
5277 print("c3 is closed\n")
5278 }
Robert Griesemer61d8a332014-05-14 11:47:19 -07005279case a[f()] = &lt;-c4:
5280 // same as:
5281 // case t := &lt;-c4
5282 // a[f()] = t
Robert Griesemerc2d55862009-02-19 16:49:10 -08005283default:
Robert Griesemer130ac742009-12-10 16:43:01 -08005284 print("no communication\n")
Robert Griesemerc2d55862009-02-19 16:49:10 -08005285}
5286
5287for { // send random sequence of bits to c
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005288 select {
Robert Griesemerc2d55862009-02-19 16:49:10 -08005289 case c &lt;- 0: // note: no statement, no fallthrough, no folding of cases
5290 case c &lt;- 1:
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005291 }
Robert Griesemerc2d55862009-02-19 16:49:10 -08005292}
Rob Pike041d1162010-07-13 16:23:54 -07005293
David Symonds72a29792011-11-29 15:47:36 -08005294select {} // block forever
Robert Griesemerc2d55862009-02-19 16:49:10 -08005295</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005296
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005297
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005298<h3 id="Return_statements">Return statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005299
Rob Pike96750f12009-02-27 16:47:48 -08005300<p>
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005301A "return" statement in a function <code>F</code> terminates the execution
5302of <code>F</code>, and optionally provides one or more result values.
5303Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
5304are executed before <code>F</code> returns to its caller.
Rob Pike96750f12009-02-27 16:47:48 -08005305</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005306
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005307<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005308ReturnStmt = "return" [ ExpressionList ] .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005309</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005310
Robert Griesemer4b908332009-08-07 17:05:41 -07005311<p>
5312In a function without a result type, a "return" statement must not
5313specify any result values.
5314</p>
Rob Pike96750f12009-02-27 16:47:48 -08005315<pre>
Russ Cox9c08d652012-02-21 22:04:30 -05005316func noResult() {
Rob Pike96750f12009-02-27 16:47:48 -08005317 return
5318}
5319</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005320
Rob Pike96750f12009-02-27 16:47:48 -08005321<p>
Robert Griesemer4b908332009-08-07 17:05:41 -07005322There are three ways to return values from a function with a result
5323type:
Rob Pike96750f12009-02-27 16:47:48 -08005324</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005325
Robert Griesemer4b908332009-08-07 17:05:41 -07005326<ol>
5327 <li>The return value or values may be explicitly listed
5328 in the "return" statement. Each expression must be single-valued
Robert Griesemer440cc952010-06-07 17:40:21 -07005329 and <a href="#Assignability">assignable</a>
5330 to the corresponding element of the function's result type.
Robert Griesemerc2d55862009-02-19 16:49:10 -08005331<pre>
Russ Cox9c08d652012-02-21 22:04:30 -05005332func simpleF() int {
Rob Pike96750f12009-02-27 16:47:48 -08005333 return 2
Robert Griesemerc2d55862009-02-19 16:49:10 -08005334}
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005335
Russ Cox9c08d652012-02-21 22:04:30 -05005336func complexF1() (re float64, im float64) {
Rob Pike96750f12009-02-27 16:47:48 -08005337 return -7.0, -4.0
Robert Griesemerc2d55862009-02-19 16:49:10 -08005338}
5339</pre>
Robert Griesemer4b908332009-08-07 17:05:41 -07005340 </li>
5341 <li>The expression list in the "return" statement may be a single
5342 call to a multi-valued function. The effect is as if each value
5343 returned from that function were assigned to a temporary
5344 variable with the type of the respective value, followed by a
5345 "return" statement listing these variables, at which point the
5346 rules of the previous case apply.
Robert Griesemerc2d55862009-02-19 16:49:10 -08005347<pre>
Russ Cox9c08d652012-02-21 22:04:30 -05005348func complexF2() (re float64, im float64) {
5349 return complexF1()
Rob Pike96750f12009-02-27 16:47:48 -08005350}
5351</pre>
Robert Griesemer4b908332009-08-07 17:05:41 -07005352 </li>
Peter Mundy5928e1d2010-11-09 10:10:57 -08005353 <li>The expression list may be empty if the function's result
Robert Griesemer462a17e2013-03-22 15:36:04 -07005354 type specifies names for its <a href="#Function_types">result parameters</a>.
Rob Pikedb8c2b182010-06-11 21:30:03 -07005355 The result parameters act as ordinary local variables
Robert Griesemer4b908332009-08-07 17:05:41 -07005356 and the function may assign values to them as necessary.
5357 The "return" statement returns the values of these variables.
Rob Pike96750f12009-02-27 16:47:48 -08005358<pre>
Russ Cox9c08d652012-02-21 22:04:30 -05005359func complexF3() (re float64, im float64) {
Robert Griesemer130ac742009-12-10 16:43:01 -08005360 re = 7.0
5361 im = 4.0
5362 return
Robert Griesemerc2d55862009-02-19 16:49:10 -08005363}
Robert Griesemerfb64e0d2011-03-07 16:29:07 -08005364
Russ Coxd9877e22011-11-01 21:45:02 -04005365func (devnull) Write(p []byte) (n int, _ error) {
Robert Griesemerfb64e0d2011-03-07 16:29:07 -08005366 n = len(p)
5367 return
Charles L. Dorian44262d12011-11-01 15:13:33 +09005368}
Robert Griesemerc2d55862009-02-19 16:49:10 -08005369</pre>
Robert Griesemer4b908332009-08-07 17:05:41 -07005370 </li>
5371</ol>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005372
Rob Pikedb8c2b182010-06-11 21:30:03 -07005373<p>
Robert Griesemer462a17e2013-03-22 15:36:04 -07005374Regardless of how they are declared, all the result values are initialized to
5375the <a href="#The_zero_value">zero values</a> for their type upon entry to the
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005376function. A "return" statement that specifies results sets the result parameters before
5377any deferred functions are executed.
Rob Pikedb8c2b182010-06-11 21:30:03 -07005378</p>
5379
Robert Griesemerc97778f2014-03-05 11:59:53 -08005380<p>
5381Implementation restriction: A compiler may disallow an empty expression list
5382in a "return" statement if a different entity (constant, type, or variable)
5383with the same name as a result parameter is in
5384<a href="#Declarations_and_scope">scope</a> at the place of the return.
5385</p>
5386
5387<pre>
5388func f(n int) (res int, err error) {
5389 if _, err := f(n-1); err != nil {
5390 return // invalid return statement: err is shadowed
5391 }
5392 return
5393}
5394</pre>
Russ Cox5958dd62009-03-04 17:19:21 -08005395
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005396<h3 id="Break_statements">Break statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005397
Rob Pike96750f12009-02-27 16:47:48 -08005398<p>
5399A "break" statement terminates execution of the innermost
Robert Griesemer462a17e2013-03-22 15:36:04 -07005400<a href="#For_statements">"for"</a>,
5401<a href="#Switch_statements">"switch"</a>, or
Robert Griesemer94849d52014-05-28 08:43:47 -07005402<a href="#Select_statements">"select"</a> statement
5403within the same function.
Rob Pike96750f12009-02-27 16:47:48 -08005404</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005405
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005406<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08005407BreakStmt = "break" [ Label ] .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005408</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005409
Rob Pike96750f12009-02-27 16:47:48 -08005410<p>
5411If there is a label, it must be that of an enclosing
Robert Griesemer462a17e2013-03-22 15:36:04 -07005412"for", "switch", or "select" statement,
5413and that is the one whose execution terminates.
Rob Pike96750f12009-02-27 16:47:48 -08005414</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005415
Robert Griesemerc2d55862009-02-19 16:49:10 -08005416<pre>
Rob Pikecec09542013-09-17 07:41:11 +10005417OuterLoop:
5418 for i = 0; i &lt; n; i++ {
5419 for j = 0; j &lt; m; j++ {
5420 switch a[i][j] {
5421 case nil:
5422 state = Error
5423 break OuterLoop
5424 case item:
5425 state = Found
5426 break OuterLoop
5427 }
Russ Cox108564d2011-03-15 13:51:24 -04005428 }
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005429 }
Robert Griesemerc2d55862009-02-19 16:49:10 -08005430</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005431
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005432<h3 id="Continue_statements">Continue statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005433
Rob Pike96750f12009-02-27 16:47:48 -08005434<p>
5435A "continue" statement begins the next iteration of the
Robert Griesemer462a17e2013-03-22 15:36:04 -07005436innermost <a href="#For_statements">"for" loop</a> at its post statement.
Robert Griesemer94849d52014-05-28 08:43:47 -07005437The "for" loop must be within the same function.
Rob Pike96750f12009-02-27 16:47:48 -08005438</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005439
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005440<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08005441ContinueStmt = "continue" [ Label ] .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005442</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005443
Rob Pike96750f12009-02-27 16:47:48 -08005444<p>
Rob Pikede9219962010-04-28 13:18:40 -07005445If there is a label, it must be that of an enclosing
5446"for" statement, and that is the one whose execution
Robert Griesemer462a17e2013-03-22 15:36:04 -07005447advances.
Rob Pike96750f12009-02-27 16:47:48 -08005448</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005449
Rob Pikecec09542013-09-17 07:41:11 +10005450<pre>
5451RowLoop:
5452 for y, row := range rows {
5453 for x, data := range row {
5454 if data == endOfRow {
5455 continue RowLoop
5456 }
5457 row[x] = data + bias(x, y)
5458 }
5459 }
5460</pre>
5461
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005462<h3 id="Goto_statements">Goto statements</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005463
Rob Pike96750f12009-02-27 16:47:48 -08005464<p>
Robert Griesemer94849d52014-05-28 08:43:47 -07005465A "goto" statement transfers control to the statement with the corresponding label
5466within the same function.
Rob Pike96750f12009-02-27 16:47:48 -08005467</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005468
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005469<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005470GotoStmt = "goto" Label .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005471</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005472
Robert Griesemerc2d55862009-02-19 16:49:10 -08005473<pre>
5474goto Error
5475</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005476
Rob Pike96750f12009-02-27 16:47:48 -08005477<p>
5478Executing the "goto" statement must not cause any variables to come into
Russ Coxf4c7db02011-06-17 12:49:04 -04005479<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
5480For instance, this example:
Rob Pike96750f12009-02-27 16:47:48 -08005481</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005482
Robert Griesemerc2d55862009-02-19 16:49:10 -08005483<pre>
Russ Cox108564d2011-03-15 13:51:24 -04005484 goto L // BAD
5485 v := 3
Robert Griesemerc2d55862009-02-19 16:49:10 -08005486L:
5487</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005488
Rob Pike96750f12009-02-27 16:47:48 -08005489<p>
5490is erroneous because the jump to label <code>L</code> skips
5491the creation of <code>v</code>.
Russ Coxf4c7db02011-06-17 12:49:04 -04005492</p>
5493
5494<p>
5495A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
5496For instance, this example:
5497</p>
5498
5499<pre>
5500if n%2 == 1 {
5501 goto L1
5502}
5503for n &gt; 0 {
5504 f()
5505 n--
5506L1:
5507 f()
5508 n--
5509}
5510</pre>
5511
5512<p>
Charles L. Dorian44262d12011-11-01 15:13:33 +09005513is erroneous because the label <code>L1</code> is inside
Russ Coxf4c7db02011-06-17 12:49:04 -04005514the "for" statement's block but the <code>goto</code> is not.
Rob Pike96750f12009-02-27 16:47:48 -08005515</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005516
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005517<h3 id="Fallthrough_statements">Fallthrough statements</h3>
Robert Griesemeraed247f2008-10-08 17:05:30 -07005518
Rob Pike96750f12009-02-27 16:47:48 -08005519<p>
5520A "fallthrough" statement transfers control to the first statement of the
Shenghou Maca9876d2015-12-31 11:25:51 -05005521next case clause in an <a href="#Expression_switches">expression "switch" statement</a>.
Robert Griesemer67a6b4f2013-03-01 16:45:14 -08005522It may be used only as the final non-empty statement in such a clause.
Rob Pike96750f12009-02-27 16:47:48 -08005523</p>
Robert Griesemeraed247f2008-10-08 17:05:30 -07005524
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005525<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005526FallthroughStmt = "fallthrough" .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005527</pre>
Robert Griesemeraed247f2008-10-08 17:05:30 -07005528
5529
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005530<h3 id="Defer_statements">Defer statements</h3>
Robert Griesemer4a903e02009-01-27 09:29:40 -08005531
Rob Pike96750f12009-02-27 16:47:48 -08005532<p>
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005533A "defer" statement invokes a function whose execution is deferred
5534to the moment the surrounding function returns, either because the
5535surrounding function executed a <a href="#Return_statements">return statement</a>,
5536reached the end of its <a href="#Function_declarations">function body</a>,
5537or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>.
Rob Pike96750f12009-02-27 16:47:48 -08005538</p>
Robert Griesemer4a903e02009-01-27 09:29:40 -08005539
Robert Griesemerf7ac31362009-07-10 16:06:40 -07005540<pre class="ebnf">
Rob Pike11417162009-03-24 17:45:53 -07005541DeferStmt = "defer" Expression .
Robert Griesemerc2d55862009-02-19 16:49:10 -08005542</pre>
Robert Griesemer4a903e02009-01-27 09:29:40 -08005543
Rob Pike96750f12009-02-27 16:47:48 -08005544<p>
Robert Griesemer25dd0022012-11-29 11:46:25 -08005545The expression must be a function or method call; it cannot be parenthesized.
5546Calls of built-in functions are restricted as for
5547<a href="#Expression_statements">expression statements</a>.
5548</p>
5549
5550<p>
Robert Griesemerb4eb22d2014-09-19 13:32:07 -07005551Each time a "defer" statement
Rob Pike633a2ce2012-01-23 08:40:13 -08005552executes, the function value and parameters to the call are
5553<a href="#Calls">evaluated as usual</a>
Robert Griesemerb4eb22d2014-09-19 13:32:07 -07005554and saved anew but the actual function is not invoked.
5555Instead, deferred functions are invoked immediately before
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005556the surrounding function returns, in the reverse order
Robert Griesemer206fd782018-09-21 21:03:35 -07005557they were deferred. That is, if the surrounding function
5558returns through an explicit <a href="#Return_statements">return statement</a>,
5559deferred functions are executed <i>after</i> any result parameters are set
5560by that return statement but <i>before</i> the function returns to its caller.
Robert Griesemerb4eb22d2014-09-19 13:32:07 -07005561If a deferred function value evaluates
5562to <code>nil</code>, execution <a href="#Handling_panics">panics</a>
Rob Pike651bb8e2014-09-19 14:13:51 -07005563when the function is invoked, not when the "defer" statement is executed.
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005564</p>
5565
5566<p>
5567For instance, if the deferred function is
Rob Pike5bb29fb2010-03-25 17:59:59 -07005568a <a href="#Function_literals">function literal</a> and the surrounding
Robert Griesemer48f0cd22010-03-23 17:30:14 -07005569function has <a href="#Function_types">named result parameters</a> that
5570are in scope within the literal, the deferred function may access and modify
5571the result parameters before they are returned.
Rob Pike633a2ce2012-01-23 08:40:13 -08005572If the deferred function has any return values, they are discarded when
5573the function completes.
Rob Pike15970c82012-10-16 11:27:20 +11005574(See also the section on <a href="#Handling_panics">handling panics</a>.)
5575</p>
5576
Robert Griesemerc2d55862009-02-19 16:49:10 -08005577<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08005578lock(l)
5579defer unlock(l) // unlocking happens before surrounding function returns
Robert Griesemer4a903e02009-01-27 09:29:40 -08005580
Robert Griesemerc2d55862009-02-19 16:49:10 -08005581// prints 3 2 1 0 before surrounding function returns
5582for i := 0; i &lt;= 3; i++ {
Robert Griesemer130ac742009-12-10 16:43:01 -08005583 defer fmt.Print(i)
Robert Griesemerc2d55862009-02-19 16:49:10 -08005584}
Robert Griesemer48f0cd22010-03-23 17:30:14 -07005585
Robert Griesemer206fd782018-09-21 21:03:35 -07005586// f returns 42
Robert Griesemer48f0cd22010-03-23 17:30:14 -07005587func f() (result int) {
5588 defer func() {
Robert Griesemer206fd782018-09-21 21:03:35 -07005589 // result is accessed after it was set to 6 by the return statement
5590 result *= 7
Robert Griesemer48f0cd22010-03-23 17:30:14 -07005591 }()
Robert Griesemer206fd782018-09-21 21:03:35 -07005592 return 6
Robert Griesemer48f0cd22010-03-23 17:30:14 -07005593}
Robert Griesemerc2d55862009-02-19 16:49:10 -08005594</pre>
Robert Griesemer4a903e02009-01-27 09:29:40 -08005595
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005596<h2 id="Built-in_functions">Built-in functions</h2>
5597
5598<p>
Rob Pike72970872010-03-04 12:35:16 -08005599Built-in functions are
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005600<a href="#Predeclared_identifiers">predeclared</a>.
5601They are called like any other function but some of them
5602accept a type instead of an expression as the first argument.
5603</p>
5604
Russ Cox2a5f0c62009-12-04 10:23:12 -08005605<p>
5606The built-in functions do not have standard Go types,
5607so they can only appear in <a href="#Calls">call expressions</a>;
5608they cannot be used as function values.
5609</p>
5610
Russ Cox9f2cb862011-03-11 14:47:02 -05005611<h3 id="Close">Close</h3>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005612
5613<p>
Robert Griesemerdc60c5a2010-07-14 16:09:22 -07005614For a channel <code>c</code>, the built-in function <code>close(c)</code>
Russ Coxf58ed4e2011-10-13 16:58:04 -04005615records that no more values will be sent on the channel.
5616It is an error if <code>c</code> is a receive-only channel.
5617Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
5618Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>.
Robert Griesemerdc60c5a2010-07-14 16:09:22 -07005619After calling <code>close</code>, and after any previously
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005620sent values have been received, receive operations will return
Robert Griesemerdc60c5a2010-07-14 16:09:22 -07005621the zero value for the channel's type without blocking.
Russ Cox9f2cb862011-03-11 14:47:02 -05005622The multi-valued <a href="#Receive_operator">receive operation</a>
5623returns a received value along with an indication of whether the channel is closed.
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005624</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005625
Robert Griesemerdc60c5a2010-07-14 16:09:22 -07005626
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005627<h3 id="Length_and_capacity">Length and capacity</h3>
Robert Griesemer7a4ed4f2008-09-03 15:15:51 -07005628
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005629<p>
5630The built-in functions <code>len</code> and <code>cap</code> take arguments
5631of various types and return a result of type <code>int</code>.
5632The implementation guarantees that the result always fits into an <code>int</code>.
5633</p>
5634
Rob Pikeff70f092009-02-20 13:36:14 -08005635<pre class="grammar">
Robert Griesemer54731032011-05-12 09:15:59 -07005636Call Argument type Result
Robert Griesemer7a4ed4f2008-09-03 15:15:51 -07005637
Robert Griesemer54731032011-05-12 09:15:59 -07005638len(s) string type string length in bytes
5639 [n]T, *[n]T array length (== n)
5640 []T slice length
5641 map[K]T map length (number of defined keys)
5642 chan T number of elements queued in channel buffer
Robert Griesemer4dc25282008-09-09 10:37:19 -07005643
Robert Griesemer54731032011-05-12 09:15:59 -07005644cap(s) [n]T, *[n]T array length (== n)
5645 []T slice capacity
5646 chan T channel buffer capacity
Robert Griesemerc2d55862009-02-19 16:49:10 -08005647</pre>
Robert Griesemer4dc25282008-09-09 10:37:19 -07005648
Robert Griesemerc2d55862009-02-19 16:49:10 -08005649<p>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005650The capacity of a slice is the number of elements for which there is
5651space allocated in the underlying array.
5652At any time the following relationship holds:
5653</p>
Robert Griesemer633957b2009-01-06 13:23:20 -08005654
Robert Griesemerc2d55862009-02-19 16:49:10 -08005655<pre>
Anthony Martin0122a662011-02-08 14:51:15 -080056560 &lt;= len(s) &lt;= cap(s)
Robert Griesemerc2d55862009-02-19 16:49:10 -08005657</pre>
Robert Griesemer667ef6c2008-09-10 13:00:32 -07005658
Russ Coxf4429182010-07-01 17:49:47 -07005659<p>
Shenghou Maa0b5b462013-01-22 03:18:20 +08005660The length of a <code>nil</code> slice, map or channel is 0.
Rob Pike82e2db72014-01-04 10:52:59 -08005661The capacity of a <code>nil</code> slice or channel is 0.
Robert Griesemer0c2e6b32010-07-13 11:54:57 -07005662</p>
5663
5664<p>
Robert Griesemer54731032011-05-12 09:15:59 -07005665The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
5666<code>s</code> is a string constant. The expressions <code>len(s)</code> and
5667<code>cap(s)</code> are constants if the type of <code>s</code> is an array
5668or pointer to an array and the expression <code>s</code> does not contain
Robert Griesemer87169812014-03-03 20:07:34 -08005669<a href="#Receive_operator">channel receives</a> or (non-constant)
Robert Griesemer54731032011-05-12 09:15:59 -07005670<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated.
5671Otherwise, invocations of <code>len</code> and <code>cap</code> are not
5672constant and <code>s</code> is evaluated.
Russ Coxf4429182010-07-01 17:49:47 -07005673</p>
Robert Griesemer4dc25282008-09-09 10:37:19 -07005674
Robert Griesemer87169812014-03-03 20:07:34 -08005675<pre>
5676const (
5677 c1 = imag(2i) // imag(2i) = 2.0 is a constant
5678 c2 = len([10]float64{2}) // [10]float64{2} contains no function calls
5679 c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls
5680 c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued
Shenghou Mac0abdd92014-12-26 02:50:33 -05005681 c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call
Robert Griesemer87169812014-03-03 20:07:34 -08005682)
5683var z complex128
5684</pre>
Robert Griesemer54731032011-05-12 09:15:59 -07005685
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005686<h3 id="Allocation">Allocation</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005687
Rob Pike96750f12009-02-27 16:47:48 -08005688<p>
Robert Griesemer6962c152014-10-16 15:08:49 -07005689The built-in function <code>new</code> takes a type <code>T</code>,
5690allocates storage for a <a href="#Variables">variable</a> of that type
5691at run time, and returns a value of type <code>*T</code>
5692<a href="#Pointer_types">pointing</a> to it.
5693The variable is initialized as described in the section on
Robert Griesemer462a17e2013-03-22 15:36:04 -07005694<a href="#The_zero_value">initial values</a>.
Rob Pike96750f12009-02-27 16:47:48 -08005695</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005696
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005697<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08005698new(T)
5699</pre>
Robert Griesemer4dc25282008-09-09 10:37:19 -07005700
Rob Pike96750f12009-02-27 16:47:48 -08005701<p>
Robert Griesemer4dc25282008-09-09 10:37:19 -07005702For instance
Rob Pike96750f12009-02-27 16:47:48 -08005703</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005704
Robert Griesemerc2d55862009-02-19 16:49:10 -08005705<pre>
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005706type S struct { a int; b float64 }
Robert Griesemerc2d55862009-02-19 16:49:10 -08005707new(S)
5708</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005709
Rob Pike96750f12009-02-27 16:47:48 -08005710<p>
Robert Griesemer6962c152014-10-16 15:08:49 -07005711allocates storage for a variable of type <code>S</code>,
Rob Pike96750f12009-02-27 16:47:48 -08005712initializes it (<code>a=0</code>, <code>b=0.0</code>),
5713and returns a value of type <code>*S</code> containing the address
Robert Griesemer6962c152014-10-16 15:08:49 -07005714of the location.
Rob Pike96750f12009-02-27 16:47:48 -08005715</p>
5716
Russ Cox7c4f7cc2009-08-20 11:11:03 -07005717<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07005718
Robert Griesemerc2d55862009-02-19 16:49:10 -08005719<p>
Rob Pike96750f12009-02-27 16:47:48 -08005720The built-in function <code>make</code> takes a type <code>T</code>,
5721which must be a slice, map or channel type,
5722optionally followed by a type-specific list of expressions.
5723It returns a value of type <code>T</code> (not <code>*T</code>).
Robert Griesemer462a17e2013-03-22 15:36:04 -07005724The memory is initialized as described in the section on
5725<a href="#The_zero_value">initial values</a>.
Rob Pike96750f12009-02-27 16:47:48 -08005726</p>
Robert Griesemer633957b2009-01-06 13:23:20 -08005727
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005728<pre class="grammar">
Robert Griesemerdf674ff2010-05-04 17:31:40 -07005729Call Type T Result
5730
5731make(T, n) slice slice of type T with length n and capacity n
5732make(T, n, m) slice slice of type T with length n and capacity m
5733
5734make(T) map map of type T
Robert Griesemerb0e5a0c2017-04-11 16:10:09 -07005735make(T, n) map map of type T with initial space for approximately n elements
Robert Griesemerdf674ff2010-05-04 17:31:40 -07005736
Robert Griesemer97aa90d2014-05-07 10:40:39 -07005737make(T) channel unbuffered channel of type T
5738make(T, n) channel buffered channel of type T, buffer size n
Robert Griesemerc2d55862009-02-19 16:49:10 -08005739</pre>
Robert Griesemer633957b2009-01-06 13:23:20 -08005740
Robert Griesemer633957b2009-01-06 13:23:20 -08005741
Rob Pike96750f12009-02-27 16:47:48 -08005742<p>
griesemer9690d242017-08-30 15:10:12 +02005743Each of the size arguments <code>n</code> and <code>m</code> must be of integer type
5744or an untyped <a href="#Constants">constant</a>.
5745A constant size argument must be non-negative and <a href="#Representability">representable</a>
5746by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>.
Robert Griesemer39067062012-12-12 11:06:26 -08005747If both <code>n</code> and <code>m</code> are provided and are constant, then
Robert Griesemer3bde0002012-10-19 10:11:06 -07005748<code>n</code> must be no larger than <code>m</code>.
5749If <code>n</code> is negative or larger than <code>m</code> at run time,
5750a <a href="#Run_time_panics">run-time panic</a> occurs.
Rob Pike96750f12009-02-27 16:47:48 -08005751</p>
Robert Griesemer633957b2009-01-06 13:23:20 -08005752
Robert Griesemerc2d55862009-02-19 16:49:10 -08005753<pre>
David Symonds72a29792011-11-29 15:47:36 -08005754s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100
Robert Griesemer3bde0002012-10-19 10:11:06 -07005755s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000
Robert Griesemer39067062012-12-12 11:06:26 -08005756s := make([]int, 1&lt;&lt;63) // illegal: len(s) is not representable by a value of type int
Oling Cat018e89f2013-01-24 20:46:33 +11005757s := make([]int, 10, 0) // illegal: len(s) > cap(s)
David Symonds72a29792011-11-29 15:47:36 -08005758c := make(chan int, 10) // channel with a buffer size of 10
Robert Griesemerb0e5a0c2017-04-11 16:10:09 -07005759m := make(map[string]int, 100) // map with initial space for approximately 100 elements
Robert Griesemerc2d55862009-02-19 16:49:10 -08005760</pre>
Robert Griesemer633957b2009-01-06 13:23:20 -08005761
Robert Griesemerb0e5a0c2017-04-11 16:10:09 -07005762<p>
5763Calling <code>make</code> with a map type and size hint <code>n</code> will
5764create a map with initial space to hold <code>n</code> map elements.
5765The precise behavior is implementation-dependent.
5766</p>
5767
Robert Griesemer164a7bc2009-09-30 12:00:25 -07005768
Robert Griesemer07e983a2010-10-25 16:50:31 -07005769<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005770
5771<p>
Robert Griesemer0c494712012-09-28 15:55:38 -07005772The built-in functions <code>append</code> and <code>copy</code> assist in
5773common slice operations.
5774For both functions, the result is independent of whether the memory referenced
5775by the arguments overlaps.
Robert Griesemer07e983a2010-10-25 16:50:31 -07005776</p>
5777
5778<p>
Robert Griesemer95b81372011-06-12 12:09:50 -07005779The <a href="#Function_types">variadic</a> function <code>append</code>
5780appends zero or more values <code>x</code>
Robert Griesemer0f7acf12011-04-19 14:38:49 -07005781to <code>s</code> of type <code>S</code>, which must be a slice type, and
5782returns the resulting slice, also of type <code>S</code>.
Robert Griesemer95b81372011-06-12 12:09:50 -07005783The values <code>x</code> are passed to a parameter of type <code>...T</code>
5784where <code>T</code> is the <a href="#Slice_types">element type</a> of
5785<code>S</code> and the respective
5786<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply.
Luuk van Dijk77fac212011-10-12 15:59:23 +02005787As a special case, <code>append</code> also accepts a first argument
5788assignable to type <code>[]byte</code> with a second argument of
5789string type followed by <code>...</code>. This form appends the
5790bytes of the string.
Robert Griesemer07e983a2010-10-25 16:50:31 -07005791</p>
5792
5793<pre class="grammar">
Robert Griesemer0f7acf12011-04-19 14:38:49 -07005794append(s S, x ...T) S // T is the element type of S
Robert Griesemer07e983a2010-10-25 16:50:31 -07005795</pre>
5796
5797<p>
5798If the capacity of <code>s</code> is not large enough to fit the additional
Robert Griesemer15da9972013-10-16 16:16:54 -07005799values, <code>append</code> allocates a new, sufficiently large underlying
5800array that fits both the existing slice elements and the additional values.
5801Otherwise, <code>append</code> re-uses the underlying array.
Robert Griesemer07e983a2010-10-25 16:50:31 -07005802</p>
5803
5804<pre>
5805s0 := []int{0, 0}
Robert Griesemer0c494712012-09-28 15:55:38 -07005806s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2}
5807s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7}
5808s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
5809s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
Robert Griesemer0f7acf12011-04-19 14:38:49 -07005810
5811var t []interface{}
David Symonds583b29c2014-12-04 09:29:29 +11005812t = append(t, 42, 3.1415, "foo") // t == []interface{}{42, 3.1415, "foo"}
Luuk van Dijk77fac212011-10-12 15:59:23 +02005813
5814var b []byte
Robert Griesemer0c494712012-09-28 15:55:38 -07005815b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' }
Robert Griesemer07e983a2010-10-25 16:50:31 -07005816</pre>
5817
5818<p>
5819The function <code>copy</code> copies slice elements from
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005820a source <code>src</code> to a destination <code>dst</code> and returns the
Robert Griesemer0c494712012-09-28 15:55:38 -07005821number of elements copied.
Robert Griesemer7bc03712010-06-07 15:49:39 -07005822Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be
Robert Griesemer425bbad2010-10-25 16:41:06 -07005823<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>.
Nigel Tao703b0922011-05-15 16:04:37 -07005824The number of elements copied is the minimum of
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005825<code>len(src)</code> and <code>len(dst)</code>.
Robert Griesemer425bbad2010-10-25 16:41:06 -07005826As a special case, <code>copy</code> also accepts a destination argument assignable
5827to type <code>[]byte</code> with a source argument of a string type.
5828This form copies the bytes from the string into the byte slice.
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005829</p>
5830
5831<pre class="grammar">
5832copy(dst, src []T) int
Robert Griesemer425bbad2010-10-25 16:41:06 -07005833copy(dst []byte, src string) int
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005834</pre>
5835
5836<p>
5837Examples:
5838</p>
5839
5840<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08005841var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
5842var s = make([]int, 6)
Robert Griesemer425bbad2010-10-25 16:41:06 -07005843var b = make([]byte, 5)
5844n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5}
5845n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5}
5846n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello")
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08005847</pre>
5848
Robert Griesemer3e0c0a82011-10-17 12:53:10 -07005849
5850<h3 id="Deletion_of_map_elements">Deletion of map elements</h3>
5851
5852<p>
5853The built-in function <code>delete</code> removes the element with key
5854<code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The
5855type of <code>k</code> must be <a href="#Assignability">assignable</a>
5856to the key type of <code>m</code>.
5857</p>
5858
5859<pre class="grammar">
5860delete(m, k) // remove element m[k] from map m
5861</pre>
5862
5863<p>
Robert Griesemera9a49fe2012-12-12 13:08:35 -08005864If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code>
5865does not exist, <code>delete</code> is a no-op.
Robert Griesemer3e0c0a82011-10-17 12:53:10 -07005866</p>
5867
5868
Russ Cox0201e372012-02-29 15:20:11 -05005869<h3 id="Complex_numbers">Manipulating complex numbers</h3>
Rob Pike72970872010-03-04 12:35:16 -08005870
5871<p>
5872Three functions assemble and disassemble complex numbers.
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005873The built-in function <code>complex</code> constructs a complex
Rob Pike72970872010-03-04 12:35:16 -08005874value from a floating-point real and imaginary part, while
5875<code>real</code> and <code>imag</code>
5876extract the real and imaginary parts of a complex value.
5877</p>
5878
5879<pre class="grammar">
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005880complex(realPart, imaginaryPart floatT) complexT
Rob Pike72970872010-03-04 12:35:16 -08005881real(complexT) floatT
5882imag(complexT) floatT
5883</pre>
5884
5885<p>
5886The type of the arguments and return value correspond.
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005887For <code>complex</code>, the two arguments must be of the same
Rob Pike72970872010-03-04 12:35:16 -08005888floating-point type and the return type is the complex type
5889with the corresponding floating-point constituents:
Robert Griesemer98aa8222015-07-29 15:42:04 -07005890<code>complex64</code> for <code>float32</code> arguments, and
5891<code>complex128</code> for <code>float64</code> arguments.
Robert Griesemer26d22602018-10-02 15:55:38 -07005892If one of the arguments evaluates to an untyped constant, it is first implicitly
Robert Griesemer98aa8222015-07-29 15:42:04 -07005893<a href="#Conversions">converted</a> to the type of the other argument.
5894If both arguments evaluate to untyped constants, they must be non-complex
5895numbers or their imaginary parts must be zero, and the return value of
5896the function is an untyped complex constant.
5897</p>
5898
5899<p>
5900For <code>real</code> and <code>imag</code>, the argument must be
5901of complex type, and the return type is the corresponding floating-point
5902type: <code>float32</code> for a <code>complex64</code> argument, and
5903<code>float64</code> for a <code>complex128</code> argument.
5904If the argument evaluates to an untyped constant, it must be a number,
5905and the return value of the function is an untyped floating-point constant.
5906</p>
5907
5908<p>
5909The <code>real</code> and <code>imag</code> functions together form the inverse of
5910<code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>,
5911<code>z&nbsp;==&nbsp;Z(complex(real(z),&nbsp;imag(z)))</code>.
Rob Pike72970872010-03-04 12:35:16 -08005912</p>
5913
5914<p>
5915If the operands of these functions are all constants, the return
5916value is a constant.
5917</p>
5918
5919<pre>
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005920var a = complex(2, -2) // complex128
Robert Griesemer98aa8222015-07-29 15:42:04 -07005921const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005922x := float32(math.Cos(math.Pi/2)) // float32
5923var c64 = complex(5, -x) // complex64
Robert Griesemer5567b872016-10-14 11:27:11 -07005924var s uint = complex(1, 0) // untyped complex constant 1 + 0i can be converted to uint
5925_ = complex(1, 2&lt;&lt;s) // illegal: 2 assumes floating-point type, cannot shift
Robert Griesemerb94c0d22011-01-19 23:07:21 -05005926var rl = real(c64) // float32
Robert Griesemer98aa8222015-07-29 15:42:04 -07005927var im = imag(a) // float64
5928const c = imag(b) // untyped constant -1.4
Robert Griesemer5567b872016-10-14 11:27:11 -07005929_ = imag(3 &lt;&lt; s) // illegal: 3 assumes complex type, cannot shift
Rob Pike72970872010-03-04 12:35:16 -08005930</pre>
5931
Rob Pike5bb29fb2010-03-25 17:59:59 -07005932<h3 id="Handling_panics">Handling panics</h3>
5933
5934<p> Two built-in functions, <code>panic</code> and <code>recover</code>,
5935assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
Charles L. Dorian44262d12011-11-01 15:13:33 +09005936and program-defined error conditions.
Rob Pike5bb29fb2010-03-25 17:59:59 -07005937</p>
5938
5939<pre class="grammar">
5940func panic(interface{})
5941func recover() interface{}
5942</pre>
5943
5944<p>
Rob Pikec34050f2013-03-12 14:28:16 -07005945While executing a function <code>F</code>,
5946an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
5947terminates the execution of <code>F</code>.
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005948Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
Rob Pikec34050f2013-03-12 14:28:16 -07005949are then executed as usual.
5950Next, any deferred functions run by <code>F's</code> caller are run,
5951and so on up to any deferred by the top-level function in the executing goroutine.
5952At that point, the program is terminated and the error
Robert Griesemer1e8e14c2012-11-01 10:13:48 -07005953condition is reported, including the value of the argument to <code>panic</code>.
5954This termination sequence is called <i>panicking</i>.
Rob Pike5bb29fb2010-03-25 17:59:59 -07005955</p>
5956
Robert Griesemer76f32282011-02-04 08:43:21 -08005957<pre>
5958panic(42)
5959panic("unreachable")
5960panic(Error("cannot parse"))
5961</pre>
5962
Rob Pike5bb29fb2010-03-25 17:59:59 -07005963<p>
5964The <code>recover</code> function allows a program to manage behavior
Rob Pikec34050f2013-03-12 14:28:16 -07005965of a panicking goroutine.
5966Suppose a function <code>G</code> defers a function <code>D</code> that calls
5967<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
5968is executing.
5969When the running of deferred functions reaches <code>D</code>,
5970the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>.
5971If <code>D</code> returns normally, without starting a new
5972<code>panic</code>, the panicking sequence stops. In that case,
5973the state of functions called between <code>G</code> and the call to <code>panic</code>
5974is discarded, and normal execution resumes.
5975Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
5976execution terminates by returning to its caller.
Rob Pike5bb29fb2010-03-25 17:59:59 -07005977</p>
5978
5979<p>
Rob Pikec34050f2013-03-12 14:28:16 -07005980The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds:
5981</p>
5982<ul>
5983<li>
5984<code>panic</code>'s argument was <code>nil</code>;
5985</li>
5986<li>
5987the goroutine is not panicking;
5988</li>
5989<li>
5990<code>recover</code> was not called directly by a deferred function.
5991</li>
5992</ul>
5993
5994<p>
Robert Griesemer76f32282011-02-04 08:43:21 -08005995The <code>protect</code> function in the example below invokes
5996the function argument <code>g</code> and protects callers from
5997run-time panics raised by <code>g</code>.
Rob Pike5bb29fb2010-03-25 17:59:59 -07005998</p>
5999
6000<pre>
Robert Griesemer76f32282011-02-04 08:43:21 -08006001func protect(g func()) {
Rob Pike5bb29fb2010-03-25 17:59:59 -07006002 defer func() {
Charles L. Dorian44262d12011-11-01 15:13:33 +09006003 log.Println("done") // Println executes normally even if there is a panic
Rob Pike5bb29fb2010-03-25 17:59:59 -07006004 if x := recover(); x != nil {
Rob Pike966bf712011-03-01 13:54:22 -08006005 log.Printf("run time panic: %v", x)
Rob Pike5bb29fb2010-03-25 17:59:59 -07006006 }
Rob Pikee6b1d422011-04-05 11:01:25 -07006007 }()
Robert Griesemer76f32282011-02-04 08:43:21 -08006008 log.Println("start")
6009 g()
Rob Pike5bb29fb2010-03-25 17:59:59 -07006010}
6011</pre>
6012
Robert Griesemer1a8ebcc2009-11-18 19:15:25 -08006013
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006014<h3 id="Bootstrapping">Bootstrapping</h3>
6015
Robert Griesemer5eb36242009-09-16 11:05:14 -07006016<p>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006017Current implementations provide several built-in functions useful during
6018bootstrapping. These functions are documented for completeness but are not
6019guaranteed to stay in the language. They do not return a result.
Robert Griesemer5eb36242009-09-16 11:05:14 -07006020</p>
6021
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006022<pre class="grammar">
Robert Griesemerd4d4ff02009-10-19 13:13:59 -07006023Function Behavior
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006024
6025print prints all arguments; formatting of arguments is implementation-specific
6026println like print but prints spaces between arguments and a newline at the end
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006027</pre>
6028
Robert Griesemer50f67ad2017-04-27 17:54:49 -07006029<p>
6030Implementation restriction: <code>print</code> and <code>println</code> need not
6031accept arbitrary argument types, but printing of boolean, numeric, and string
Robert Griesemer86f5f7f2017-04-28 10:32:31 -07006032<a href="#Types">types</a> must be supported.
Robert Griesemer50f67ad2017-04-27 17:54:49 -07006033</p>
Robert Griesemer164a7bc2009-09-30 12:00:25 -07006034
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006035<h2 id="Packages">Packages</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006036
Rob Pike46596852009-03-02 16:17:29 -08006037<p>
6038Go programs are constructed by linking together <i>packages</i>.
Robert Griesemer326ef132009-09-28 19:21:15 -07006039A package in turn is constructed from one or more source files
6040that together declare constants, types, variables and functions
6041belonging to the package and which are accessible in all files
6042of the same package. Those elements may be
6043<a href="#Exported_identifiers">exported</a> and used in another package.
Rob Pike46596852009-03-02 16:17:29 -08006044</p>
6045
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006046<h3 id="Source_file_organization">Source file organization</h3>
Rob Pike46596852009-03-02 16:17:29 -08006047
6048<p>
6049Each source file consists of a package clause defining the package
6050to which it belongs, followed by a possibly empty set of import
6051declarations that declare packages whose contents it wishes to use,
6052followed by a possibly empty set of declarations of functions,
Robert Griesemer0a162a12009-08-19 16:44:04 -07006053types, variables, and constants.
Rob Pike46596852009-03-02 16:17:29 -08006054</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006055
Robert Griesemerf7ac31362009-07-10 16:06:40 -07006056<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08006057SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
Robert Griesemerc2d55862009-02-19 16:49:10 -08006058</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006059
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006060<h3 id="Package_clause">Package clause</h3>
Rob Pike46596852009-03-02 16:17:29 -08006061
Robert Griesemerc2d55862009-02-19 16:49:10 -08006062<p>
Rob Pike46596852009-03-02 16:17:29 -08006063A package clause begins each source file and defines the package
6064to which the file belongs.
6065</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006066
Robert Griesemerf7ac31362009-07-10 16:06:40 -07006067<pre class="ebnf">
Robert Griesemer4e56b332009-09-10 10:14:00 -07006068PackageClause = "package" PackageName .
6069PackageName = identifier .
Robert Griesemerc2d55862009-02-19 16:49:10 -08006070</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006071
Robert Griesemer4e56b332009-09-10 10:14:00 -07006072<p>
6073The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
6074</p>
6075
Rob Pike46596852009-03-02 16:17:29 -08006076<pre>
6077package math
6078</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006079
Rob Pike46596852009-03-02 16:17:29 -08006080<p>
6081A set of files sharing the same PackageName form the implementation of a package.
6082An implementation may require that all source files for a package inhabit the same directory.
6083</p>
6084
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006085<h3 id="Import_declarations">Import declarations</h3>
Rob Pike46596852009-03-02 16:17:29 -08006086
6087<p>
Robert Griesemer103c9db2012-03-01 13:57:49 -08006088An import declaration states that the source file containing the declaration
6089depends on functionality of the <i>imported</i> package
6090(<a href="#Program_initialization_and_execution">§Program initialization and execution</a>)
Rob Pikeb51ad9c2012-09-23 05:03:43 +10006091and enables access to <a href="#Exported_identifiers">exported</a> identifiers
Robert Griesemer103c9db2012-03-01 13:57:49 -08006092of that package.
6093The import names an identifier (PackageName) to be used for access and an ImportPath
Rob Pike3aec2e42009-09-25 17:00:22 -07006094that specifies the package to be imported.
Rob Pike46596852009-03-02 16:17:29 -08006095</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006096
Robert Griesemerf7ac31362009-07-10 16:06:40 -07006097<pre class="ebnf">
Robert Griesemer130ac742009-12-10 16:43:01 -08006098ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
Robert Griesemer997851e2009-09-25 15:36:25 -07006099ImportSpec = [ "." | PackageName ] ImportPath .
Robert Griesemer130ac742009-12-10 16:43:01 -08006100ImportPath = string_lit .
Robert Griesemerc2d55862009-02-19 16:49:10 -08006101</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006102
Robert Griesemerc2d55862009-02-19 16:49:10 -08006103<p>
Rob Pike3aec2e42009-09-25 17:00:22 -07006104The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
Robert Griesemer103c9db2012-03-01 13:57:49 -08006105to access exported identifiers of the package within the importing source file.
Rob Pike3aec2e42009-09-25 17:00:22 -07006106It is declared in the <a href="#Blocks">file block</a>.
6107If the PackageName is omitted, it defaults to the identifier specified in the
Robert Griesemer556506e2011-02-22 09:34:13 -08006108<a href="#Package_clause">package clause</a> of the imported package.
Rob Pike3aec2e42009-09-25 17:00:22 -07006109If an explicit period (<code>.</code>) appears instead of a name, all the
Robert Griesemer103c9db2012-03-01 13:57:49 -08006110package's exported identifiers declared in that package's
6111<a href="#Blocks">package block</a> will be declared in the importing source
Rob Pike227fe5f2014-01-14 15:16:01 -08006112file's file block and must be accessed without a qualifier.
Rob Pike46596852009-03-02 16:17:29 -08006113</p>
Russ Cox16b95ba2009-08-20 10:22:52 -07006114
Robert Griesemerc2d55862009-02-19 16:49:10 -08006115<p>
Rob Pike3aec2e42009-09-25 17:00:22 -07006116The interpretation of the ImportPath is implementation-dependent but
6117it is typically a substring of the full file name of the compiled
6118package and may be relative to a repository of installed packages.
6119</p>
6120
6121<p>
Robert Griesemerac4055b2012-02-22 23:51:25 -08006122Implementation restriction: A compiler may restrict ImportPaths to
6123non-empty strings using only characters belonging to
Suriyaa Sundararuban1041ac82018-06-13 07:06:04 +00006124<a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a>
Robert Griesemerac4055b2012-02-22 23:51:25 -08006125L, M, N, P, and S general categories (the Graphic characters without
Russ Coxfad10f92012-02-23 22:46:04 -05006126spaces) and may also exclude the characters
6127<code>!"#$%&amp;'()*,:;&lt;=&gt;?[\]^`{|}</code>
6128and the Unicode replacement character U+FFFD.
Robert Griesemerac4055b2012-02-22 23:51:25 -08006129</p>
6130
6131<p>
Rob Pike3aec2e42009-09-25 17:00:22 -07006132Assume we have compiled a package containing the package clause
6133<code>package math</code>, which exports function <code>Sin</code>, and
6134installed the compiled package in the file identified by
Rob Pike46596852009-03-02 16:17:29 -08006135<code>"lib/math"</code>.
Rob Pike227fe5f2014-01-14 15:16:01 -08006136This table illustrates how <code>Sin</code> is accessed in files
Rob Pike3aec2e42009-09-25 17:00:22 -07006137that import the package after the
6138various types of import declaration.
Rob Pike46596852009-03-02 16:17:29 -08006139</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006140
Rob Pike46596852009-03-02 16:17:29 -08006141<pre class="grammar">
Robert Griesemer997851e2009-09-25 15:36:25 -07006142Import declaration Local name of Sin
Rob Pike46596852009-03-02 16:17:29 -08006143
Rob Pike46596852009-03-02 16:17:29 -08006144import "lib/math" math.Sin
Rob Pikeb51ad9c2012-09-23 05:03:43 +10006145import m "lib/math" m.Sin
Rob Pike46596852009-03-02 16:17:29 -08006146import . "lib/math" Sin
6147</pre>
6148
Robert Griesemer997851e2009-09-25 15:36:25 -07006149<p>
Rob Pike3aec2e42009-09-25 17:00:22 -07006150An import declaration declares a dependency relation between
6151the importing and imported package.
Robert Griesemer4be38dd2013-03-04 12:59:40 -08006152It is illegal for a package to import itself, directly or indirectly,
6153or to directly import a package without
Robert Griesemer997851e2009-09-25 15:36:25 -07006154referring to any of its exported identifiers. To import a package solely for
6155its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
6156identifier as explicit package name:
6157</p>
6158
6159<pre>
6160import _ "lib/math"
6161</pre>
6162
6163
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006164<h3 id="An_example_package">An example package</h3>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006165
Robert Griesemerc2d55862009-02-19 16:49:10 -08006166<p>
Rob Pike46596852009-03-02 16:17:29 -08006167Here is a complete Go package that implements a concurrent prime sieve.
6168</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006169
Robert Griesemerc2d55862009-02-19 16:49:10 -08006170<pre>
6171package main
6172
Rob Pike46596852009-03-02 16:17:29 -08006173import "fmt"
6174
Robert Griesemer3c7271f2011-05-24 14:18:44 -07006175// Send the sequence 2, 3, 4, … to channel 'ch'.
Robert Griesemere1e76192009-09-25 14:11:03 -07006176func generate(ch chan&lt;- int) {
Robert Griesemerc2d55862009-02-19 16:49:10 -08006177 for i := 2; ; i++ {
Robert Griesemer130ac742009-12-10 16:43:01 -08006178 ch &lt;- i // Send 'i' to channel 'ch'.
Robert Griesemerc2d55862009-02-19 16:49:10 -08006179 }
6180}
6181
Fazlul Shahriar330139e2009-11-30 21:23:58 -08006182// Copy the values from channel 'src' to channel 'dst',
Robert Griesemerc2d55862009-02-19 16:49:10 -08006183// removing those divisible by 'prime'.
Robert Griesemere1e76192009-09-25 14:11:03 -07006184func filter(src &lt;-chan int, dst chan&lt;- int, prime int) {
David Symonds72a29792011-11-29 15:47:36 -08006185 for i := range src { // Loop over values received from 'src'.
Robert Griesemere1e76192009-09-25 14:11:03 -07006186 if i%prime != 0 {
Robert Griesemer130ac742009-12-10 16:43:01 -08006187 dst &lt;- i // Send 'i' to channel 'dst'.
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006188 }
6189 }
Robert Griesemerc2d55862009-02-19 16:49:10 -08006190}
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006191
Robert Griesemerc2d55862009-02-19 16:49:10 -08006192// The prime sieve: Daisy-chain filter processes together.
6193func sieve() {
Robert Griesemer130ac742009-12-10 16:43:01 -08006194 ch := make(chan int) // Create a new channel.
6195 go generate(ch) // Start generate() as a subprocess.
Robert Griesemerc2d55862009-02-19 16:49:10 -08006196 for {
Robert Griesemer130ac742009-12-10 16:43:01 -08006197 prime := &lt;-ch
6198 fmt.Print(prime, "\n")
6199 ch1 := make(chan int)
6200 go filter(ch, ch1, prime)
6201 ch = ch1
Robert Griesemerc2d55862009-02-19 16:49:10 -08006202 }
6203}
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006204
Robert Griesemerc2d55862009-02-19 16:49:10 -08006205func main() {
Robert Griesemer130ac742009-12-10 16:43:01 -08006206 sieve()
Robert Griesemerc2d55862009-02-19 16:49:10 -08006207}
6208</pre>
Robert Griesemer67153582008-12-16 14:45:09 -08006209
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006210<h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006211
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006212<h3 id="The_zero_value">The zero value</h3>
Rob Pike8f2330d2009-02-25 16:20:44 -08006213<p>
Robert Griesemer6962c152014-10-16 15:08:49 -07006214When storage is allocated for a <a href="#Variables">variable</a>,
6215either through a declaration or a call of <code>new</code>, or when
6216a new value is created, either through a composite literal or a call
6217of <code>make</code>,
6218and no explicit initialization is provided, the variable or value is
6219given a default value. Each element of such a variable or value is
Robert Griesemeref45e642009-08-21 11:25:00 -07006220set to the <i>zero value</i> for its type: <code>false</code> for booleans,
griesemera9f832a2017-08-24 15:20:18 +02006221<code>0</code> for numeric types, <code>""</code>
Robert Griesemer19b1d352009-09-24 19:36:48 -07006222for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
Rob Pikeff70f092009-02-20 13:36:14 -08006223This initialization is done recursively, so for instance each element of an
Rob Pike8f2330d2009-02-25 16:20:44 -08006224array of structs will have its fields zeroed if no value is specified.
6225</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08006226<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006227These two simple declarations are equivalent:
Rob Pike8f2330d2009-02-25 16:20:44 -08006228</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006229
Robert Griesemerc2d55862009-02-19 16:49:10 -08006230<pre>
Robert Griesemer130ac742009-12-10 16:43:01 -08006231var i int
6232var i int = 0
Robert Griesemerc2d55862009-02-19 16:49:10 -08006233</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006234
Rob Pike8f2330d2009-02-25 16:20:44 -08006235<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006236After
Rob Pike8f2330d2009-02-25 16:20:44 -08006237</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006238
Robert Griesemerc2d55862009-02-19 16:49:10 -08006239<pre>
Robert Griesemerb94c0d22011-01-19 23:07:21 -05006240type T struct { i int; f float64; next *T }
Robert Griesemer130ac742009-12-10 16:43:01 -08006241t := new(T)
Robert Griesemerc2d55862009-02-19 16:49:10 -08006242</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006243
Rob Pike8f2330d2009-02-25 16:20:44 -08006244<p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006245the following holds:
Rob Pike8f2330d2009-02-25 16:20:44 -08006246</p>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006247
Robert Griesemerc2d55862009-02-19 16:49:10 -08006248<pre>
6249t.i == 0
6250t.f == 0.0
6251t.next == nil
6252</pre>
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006253
Rob Pike96750f12009-02-27 16:47:48 -08006254<p>
6255The same would also be true after
6256</p>
6257
6258<pre>
6259var t T
6260</pre>
6261
Robert Griesemera4366982014-05-20 13:51:39 -07006262<h3 id="Package_initialization">Package initialization</h3>
Robert Griesemer259f0ff2014-09-29 12:44:50 -07006263
Rob Pike8f2330d2009-02-25 16:20:44 -08006264<p>
Robert Griesemer259f0ff2014-09-29 12:44:50 -07006265Within a package, package-level variables are initialized in
6266<i>declaration order</i> but after any of the variables
6267they <i>depend</i> on.
6268</p>
6269
6270<p>
6271More precisely, a package-level variable is considered <i>ready for
6272initialization</i> if it is not yet initialized and either has
6273no <a href="#Variable_declarations">initialization expression</a> or
6274its initialization expression has no dependencies on uninitialized variables.
6275Initialization proceeds by repeatedly initializing the next package-level
6276variable that is earliest in declaration order and ready for initialization,
6277until there are no variables ready for initialization.
6278</p>
6279
6280<p>
6281If any variables are still uninitialized when this
6282process ends, those variables are part of one or more initialization cycles,
6283and the program is not valid.
6284</p>
6285
6286<p>
6287The declaration order of variables declared in multiple files is determined
6288by the order in which the files are presented to the compiler: Variables
6289declared in the first file are declared before any of the variables declared
6290in the second file, and so on.
Rob Pike96750f12009-02-27 16:47:48 -08006291</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006292
6293<p>
6294Dependency analysis does not rely on the actual values of the
6295variables, only on lexical <i>references</i> to them in the source,
Robert Griesemer259f0ff2014-09-29 12:44:50 -07006296analyzed transitively. For instance, if a variable <code>x</code>'s
6297initialization expression refers to a function whose body refers to
6298variable <code>y</code> then <code>x</code> depends on <code>y</code>.
Robert Griesemera4366982014-05-20 13:51:39 -07006299Specifically:
6300</p>
6301
6302<ul>
6303<li>
6304A reference to a variable or function is an identifier denoting that
6305variable or function.
6306</li>
6307
6308<li>
6309A reference to a method <code>m</code> is a
6310<a href="#Method_values">method value</a> or
Robin Eklindcac006a2014-08-30 10:27:01 -07006311<a href="#Method_expressions">method expression</a> of the form
Robert Griesemera4366982014-05-20 13:51:39 -07006312<code>t.m</code>, where the (static) type of <code>t</code> is
6313not an interface type, and the method <code>m</code> is in the
6314<a href="#Method_sets">method set</a> of <code>t</code>.
6315It is immaterial whether the resulting function value
6316<code>t.m</code> is invoked.
6317</li>
6318
6319<li>
Robin Eklindcac006a2014-08-30 10:27:01 -07006320A variable, function, or method <code>x</code> depends on a variable
Robert Griesemera4366982014-05-20 13:51:39 -07006321<code>y</code> if <code>x</code>'s initialization expression or body
6322(for functions and methods) contains a reference to <code>y</code>
6323or to a function or method that depends on <code>y</code>.
6324</li>
6325</ul>
6326
6327<p>
6328Dependency analysis is performed per package; only references referring
6329to variables, functions, and methods declared in the current package
6330are considered.
Robert Griesemera4366982014-05-20 13:51:39 -07006331</p>
6332
6333<p>
6334For example, given the declarations
6335</p>
6336
Rob Pike96750f12009-02-27 16:47:48 -08006337<pre>
Robert Griesemera4366982014-05-20 13:51:39 -07006338var (
6339 a = c + b
6340 b = f()
6341 c = f()
6342 d = 3
6343)
6344
6345func f() int {
6346 d++
6347 return d
6348}
Rob Pike96750f12009-02-27 16:47:48 -08006349</pre>
Robert Griesemera4366982014-05-20 13:51:39 -07006350
Rob Pike96750f12009-02-27 16:47:48 -08006351<p>
Robert Griesemera4366982014-05-20 13:51:39 -07006352the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>.
Rob Pike8f2330d2009-02-25 16:20:44 -08006353</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006354
Robert Griesemerc2d55862009-02-19 16:49:10 -08006355<p>
Robert Griesemera4366982014-05-20 13:51:39 -07006356Variables may also be initialized using functions named <code>init</code>
6357declared in the package block, with no arguments and no result parameters.
Rob Pike8cb91842009-09-15 11:56:39 -07006358</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006359
6360<pre>
6361func init() { … }
6362</pre>
6363
Rob Pike8cb91842009-09-15 11:56:39 -07006364<p>
Robert Griesemera6563902016-08-25 21:01:17 -07006365Multiple such functions may be defined per package, even within a single
6366source file. In the package block, the <code>init</code> identifier can
6367be used only to declare <code>init</code> functions, yet the identifier
6368itself is not <a href="#Declarations_and_scope">declared</a>. Thus
Robert Griesemera4366982014-05-20 13:51:39 -07006369<code>init</code> functions cannot be referred to from anywhere
6370in a program.
Rob Pike8f2330d2009-02-25 16:20:44 -08006371</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006372
Robert Griesemerc2d55862009-02-19 16:49:10 -08006373<p>
Robert Griesemera4366982014-05-20 13:51:39 -07006374A package with no imports is initialized by assigning initial values
6375to all its package-level variables followed by calling all <code>init</code>
Robert Griesemerc00043b2014-05-20 17:46:08 -07006376functions in the order they appear in the source, possibly in multiple files,
6377as presented to the compiler.
Robert Griesemerdf49fb32008-08-28 17:47:53 -07006378If a package has imports, the imported packages are initialized
Robert Griesemer566e3b22008-09-26 16:41:50 -07006379before initializing the package itself. If multiple packages import
Robert Griesemera4366982014-05-20 13:51:39 -07006380a package, the imported package will be initialized only once.
6381The importing of packages, by construction, guarantees that there
6382can be no cyclic initialization dependencies.
Rob Pike8f2330d2009-02-25 16:20:44 -08006383</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006384
Robert Griesemerc2d55862009-02-19 16:49:10 -08006385<p>
Robert Griesemera4366982014-05-20 13:51:39 -07006386Package initialization&mdash;variable initialization and the invocation of
6387<code>init</code> functions&mdash;happens in a single goroutine,
6388sequentially, one package at a time.
6389An <code>init</code> function may launch other goroutines, which can run
6390concurrently with the initialization code. However, initialization
6391always sequences
6392the <code>init</code> functions: it will not invoke the next one
6393until the previous one has returned.
Rob Pike8f2330d2009-02-25 16:20:44 -08006394</p>
Robert Griesemera4366982014-05-20 13:51:39 -07006395
Robert Griesemer259f0ff2014-09-29 12:44:50 -07006396<p>
6397To ensure reproducible initialization behavior, build systems are encouraged
6398to present multiple files belonging to the same package in lexical file name
6399order to a compiler.
6400</p>
6401
Robert Griesemera4366982014-05-20 13:51:39 -07006402
6403<h3 id="Program_execution">Program execution</h3>
Robert Griesemerc2d55862009-02-19 16:49:10 -08006404<p>
Russ Coxa6736ca2011-02-03 13:40:51 -05006405A complete program is created by linking a single, unimported package
6406called the <i>main package</i> with all the packages it imports, transitively.
6407The main package must
6408have package name <code>main</code> and
Charles L. Dorian44262d12011-11-01 15:13:33 +09006409declare a function <code>main</code> that takes no
Russ Coxa6736ca2011-02-03 13:40:51 -05006410arguments and returns no value.
Rob Pike8f2330d2009-02-25 16:20:44 -08006411</p>
Robert Griesemer4dc25282008-09-09 10:37:19 -07006412
Robert Griesemerc2d55862009-02-19 16:49:10 -08006413<pre>
Robert Griesemer3c7271f2011-05-24 14:18:44 -07006414func main() { … }
Robert Griesemerc2d55862009-02-19 16:49:10 -08006415</pre>
Robert Griesemer4dc25282008-09-09 10:37:19 -07006416
Rob Pike8f2330d2009-02-25 16:20:44 -08006417<p>
Russ Coxa6736ca2011-02-03 13:40:51 -05006418Program execution begins by initializing the main package and then
6419invoking the function <code>main</code>.
Robert Griesemer7f1d62d2014-05-19 08:54:19 -07006420When that function invocation returns, the program exits.
Russ Coxa6736ca2011-02-03 13:40:51 -05006421It does not wait for other (non-<code>main</code>) goroutines to complete.
Rob Pike811dd252009-03-04 20:39:39 -08006422</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006423
Russ Coxd9877e22011-11-01 21:45:02 -04006424<h2 id="Errors">Errors</h2>
6425
6426<p>
6427The predeclared type <code>error</code> is defined as
6428</p>
6429
6430<pre>
6431type error interface {
6432 Error() string
6433}
6434</pre>
6435
6436<p>
6437It is the conventional interface for representing an error condition,
6438with the nil value representing no error.
6439For instance, a function to read data from a file might be defined:
6440</p>
6441
6442<pre>
6443func Read(f *File, b []byte) (n int, err error)
6444</pre>
6445
Evan Shaw21110c72010-04-22 10:14:53 -07006446<h2 id="Run_time_panics">Run-time panics</h2>
Rob Pike5bb29fb2010-03-25 17:59:59 -07006447
6448<p>
6449Execution errors such as attempting to index an array out
6450of bounds trigger a <i>run-time panic</i> equivalent to a call of
6451the built-in function <a href="#Handling_panics"><code>panic</code></a>
6452with a value of the implementation-defined interface type <code>runtime.Error</code>.
Charles L. Dorian9a358df2011-12-08 22:27:14 -05006453That type satisfies the predeclared interface type
Russ Coxd9877e22011-11-01 21:45:02 -04006454<a href="#Errors"><code>error</code></a>.
6455The exact error values that
6456represent distinct run-time error conditions are unspecified.
Rob Pike5bb29fb2010-03-25 17:59:59 -07006457</p>
6458
6459<pre>
6460package runtime
6461
6462type Error interface {
Russ Coxd9877e22011-11-01 21:45:02 -04006463 error
6464 // and perhaps other methods
Rob Pike5bb29fb2010-03-25 17:59:59 -07006465}
6466</pre>
6467
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006468<h2 id="System_considerations">System considerations</h2>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006469
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006470<h3 id="Package_unsafe">Package <code>unsafe</code></h3>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006471
Robert Griesemerc2d55862009-02-19 16:49:10 -08006472<p>
griesemerddc64de2017-10-17 13:38:10 -07006473The built-in package <code>unsafe</code>, known to the compiler
6474and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>,
Rob Pike96750f12009-02-27 16:47:48 -08006475provides facilities for low-level programming including operations
6476that violate the type system. A package using <code>unsafe</code>
Robert Griesemer5361b742014-10-23 09:45:11 -07006477must be vetted manually for type safety and may not be portable.
6478The package provides the following interface:
Rob Pikef27e9f02009-02-23 19:22:05 -08006479</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006480
Rob Pikeff70f092009-02-20 13:36:14 -08006481<pre class="grammar">
Robert Griesemerc2d55862009-02-19 16:49:10 -08006482package unsafe
Robert Griesemer52c02c22009-02-11 13:46:30 -08006483
Robert Griesemer98b4f6a2009-05-12 21:37:46 -07006484type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type
6485type Pointer *ArbitraryType
Robert Griesemer52c02c22009-02-11 13:46:30 -08006486
Robert Griesemereee70b02011-06-13 16:46:42 -07006487func Alignof(variable ArbitraryType) uintptr
Hong Ruiqi8374e672012-04-05 22:37:07 +10006488func Offsetof(selector ArbitraryType) uintptr
Robert Griesemereee70b02011-06-13 16:46:42 -07006489func Sizeof(variable ArbitraryType) uintptr
Robert Griesemerc2d55862009-02-19 16:49:10 -08006490</pre>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006491
Robert Griesemerc2d55862009-02-19 16:49:10 -08006492<p>
Robert Griesemere121de22013-10-07 10:43:28 -07006493A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
6494value may not be <a href="#Address_operators">dereferenced</a>.
Robert Griesemer5361b742014-10-23 09:45:11 -07006495Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to
Robert Griesemer86f5f7f2017-04-28 10:32:31 -07006496a type of underlying type <code>Pointer</code> and vice versa.
Robert Griesemer5361b742014-10-23 09:45:11 -07006497The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined.
Rob Pikef27e9f02009-02-23 19:22:05 -08006498</p>
Russ Cox81eb9302013-02-09 17:36:31 -05006499
6500<pre>
6501var f float64
6502bits = *(*uint64)(unsafe.Pointer(&amp;f))
6503
6504type ptr unsafe.Pointer
6505bits = *(*uint64)(ptr(&amp;f))
Robert Griesemere121de22013-10-07 10:43:28 -07006506
6507var p ptr = nil
Russ Cox81eb9302013-02-09 17:36:31 -05006508</pre>
6509
Robert Griesemerc2d55862009-02-19 16:49:10 -08006510<p>
Robert Griesemerc7631f52012-09-17 12:23:41 -07006511The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
6512of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
6513as if <code>v</code> was declared via <code>var v = x</code>.
Rob Pikef27e9f02009-02-23 19:22:05 -08006514</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08006515<p>
Robert Griesemer8c058b32012-09-18 11:25:53 -07006516The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
Robert Griesemer51338092013-03-07 20:11:37 -08006517<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
6518or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
6519If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
6520without pointer indirections through fields of the struct.
Rob Pike678625d2009-09-15 09:54:22 -07006521For a struct <code>s</code> with field <code>f</code>:
Rob Pikef27e9f02009-02-23 19:22:05 -08006522</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006523
Robert Griesemerc2d55862009-02-19 16:49:10 -08006524<pre>
Robert Griesemereee70b02011-06-13 16:46:42 -07006525uintptr(unsafe.Pointer(&amp;s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&amp;s.f))
Robert Griesemerc2d55862009-02-19 16:49:10 -08006526</pre>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006527
Robert Griesemerc2d55862009-02-19 16:49:10 -08006528<p>
Rob Pikef27e9f02009-02-23 19:22:05 -08006529Computer architectures may require memory addresses to be <i>aligned</i>;
6530that is, for addresses of a variable to be a multiple of a factor,
6531the variable's type's <i>alignment</i>. The function <code>Alignof</code>
6532takes an expression denoting a variable of any type and returns the
6533alignment of the (type of the) variable in bytes. For a variable
6534<code>x</code>:
6535</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006536
Robert Griesemerc2d55862009-02-19 16:49:10 -08006537<pre>
Robert Griesemereee70b02011-06-13 16:46:42 -07006538uintptr(unsafe.Pointer(&amp;x)) % unsafe.Alignof(x) == 0
Robert Griesemerc2d55862009-02-19 16:49:10 -08006539</pre>
Robert Griesemer533dfd62009-05-13 16:56:00 -07006540
Rob Pikef27e9f02009-02-23 19:22:05 -08006541<p>
6542Calls to <code>Alignof</code>, <code>Offsetof</code>, and
Robert Griesemereee70b02011-06-13 16:46:42 -07006543<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
Rob Pikef27e9f02009-02-23 19:22:05 -08006544</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006545
Russ Cox7c4f7cc2009-08-20 11:11:03 -07006546<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006547
Robert Griesemer997851e2009-09-25 15:36:25 -07006548<p>
Robert Griesemer462a17e2013-03-22 15:36:04 -07006549For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
Robert Griesemer997851e2009-09-25 15:36:25 -07006550</p>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006551
Rob Pikeff70f092009-02-20 13:36:14 -08006552<pre class="grammar">
Robert Griesemer777a96a2010-12-02 12:32:14 -08006553type size in bytes
Robert Griesemer52c02c22009-02-11 13:46:30 -08006554
Robert Griesemer777a96a2010-12-02 12:32:14 -08006555byte, uint8, int8 1
6556uint16, int16 2
6557uint32, int32, float32 4
6558uint64, int64, float64, complex64 8
6559complex128 16
Robert Griesemerc2d55862009-02-19 16:49:10 -08006560</pre>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006561
Robert Griesemerc2d55862009-02-19 16:49:10 -08006562<p>
Rob Pikef27e9f02009-02-23 19:22:05 -08006563The following minimal alignment properties are guaranteed:
Rob Pike4501d342009-02-19 17:31:36 -08006564</p>
Robert Griesemerc2d55862009-02-19 16:49:10 -08006565<ol>
Robert Griesemerdd916be2011-01-10 14:25:17 -08006566<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
Robert Griesemer3af480372010-05-14 13:11:48 -07006567</li>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006568
Rob Pikef27e9f02009-02-23 19:22:05 -08006569<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
Robert Griesemerdd916be2011-01-10 14:25:17 -08006570 all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
Robert Griesemer3af480372010-05-14 13:11:48 -07006571</li>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006572
Rob Pikef27e9f02009-02-23 19:22:05 -08006573<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
Robert Griesemere62aab12017-02-06 23:33:21 -08006574 the alignment of a variable of the array's element type.
Robert Griesemer3af480372010-05-14 13:11:48 -07006575</li>
Robert Griesemerc2d55862009-02-19 16:49:10 -08006576</ol>
Robert Griesemer52c02c22009-02-11 13:46:30 -08006577
Robert Griesemer1320ce02012-01-09 16:54:24 -08006578<p>
6579A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
6580</p>