Andrew Gerrand | 7cb21a7 | 2012-01-19 11:24:54 +1100 | [diff] [blame] | 1 | <!--{ |
| 2 | "Title": "The Go Programming Language Specification", |
yah01 | ee55dd6 | 2020-01-15 01:34:43 +0000 | [diff] [blame] | 3 | "Subtitle": "Version of Jan 14, 2020", |
Andrew Gerrand | 48ba6fe | 2013-10-04 09:45:06 +1000 | [diff] [blame] | 4 | "Path": "/ref/spec" |
Andrew Gerrand | 7cb21a7 | 2012-01-19 11:24:54 +1100 | [diff] [blame] | 5 | }--> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 7 | <h2 id="Introduction">Introduction</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 8 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 9 | <p> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 10 | This is a reference manual for the Go programming language. For |
Andrew Gerrand | 43ad89d | 2014-07-25 10:28:39 +1000 | [diff] [blame] | 11 | more information and other documents, see <a href="/">golang.org</a>. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 12 | </p> |
Robert Griesemer | 6715358 | 2008-12-16 14:45:09 -0800 | [diff] [blame] | 13 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 14 | <p> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 15 | Go is a general-purpose language designed with systems programming |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 16 | in mind. It is strongly typed and garbage-collected and has explicit |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 17 | support for concurrent programming. Programs are constructed from |
| 18 | <i>packages</i>, whose properties allow efficient management of |
griesemer | 0c5b00d | 2017-10-23 14:08:41 -0700 | [diff] [blame] | 19 | dependencies. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 20 | </p> |
| 21 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 22 | <p> |
Alberto Donizetti | 7d30af8 | 2019-12-13 12:07:06 +0100 | [diff] [blame] | 23 | The grammar is compact and simple to parse, allowing for easy analysis |
| 24 | by automatic tools such as integrated development environments. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 25 | </p> |
Larry Hosken | 698c6c0 | 2009-09-17 08:05:12 -0700 | [diff] [blame] | 26 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 27 | <h2 id="Notation">Notation</h2> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 28 | <p> |
Robert Griesemer | 4d23030 | 2008-12-17 15:39:15 -0800 | [diff] [blame] | 29 | The syntax is specified using Extended Backus-Naur Form (EBNF): |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 30 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 31 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 32 | <pre class="grammar"> |
Robert Griesemer | 32b822f | 2011-05-13 12:54:51 -0700 | [diff] [blame] | 33 | Production = production_name "=" [ Expression ] "." . |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 34 | Expression = Alternative { "|" Alternative } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 35 | Alternative = Term { Term } . |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 36 | Term = production_name | token [ "…" token ] | Group | Option | Repetition . |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 37 | Group = "(" Expression ")" . |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 38 | Option = "[" Expression "]" . |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 39 | Repetition = "{" Expression "}" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 40 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 41 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 42 | <p> |
| 43 | Productions are expressions constructed from terms and the following |
| 44 | operators, in increasing precedence: |
| 45 | </p> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 46 | <pre class="grammar"> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 47 | | alternation |
| 48 | () grouping |
| 49 | [] option (0 or 1 times) |
| 50 | {} repetition (0 to n times) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 51 | </pre> |
Robert Griesemer | 4d23030 | 2008-12-17 15:39:15 -0800 | [diff] [blame] | 52 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 53 | <p> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 54 | Lower-case production names are used to identify lexical tokens. |
Robert Griesemer | 7c1cb37 | 2012-02-29 10:39:20 -0800 | [diff] [blame] | 55 | Non-terminals are in CamelCase. Lexical tokens are enclosed in |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 56 | double quotes <code>""</code> or back quotes <code>``</code>. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 57 | </p> |
| 58 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 59 | <p> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 60 | The form <code>a … b</code> represents the set of characters from |
| 61 | <code>a</code> through <code>b</code> as alternatives. The horizontal |
Jeremy Jackins | 7e05426 | 2012-03-19 08:26:36 +1100 | [diff] [blame] | 62 | ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various |
Rob Pike | 8040f9b | 2012-02-13 14:38:31 +1100 | [diff] [blame] | 63 | enumerations or code snippets that are not further specified. The character <code>…</code> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 64 | (as opposed to the three characters <code>...</code>) is not a token of the Go |
| 65 | language. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 66 | </p> |
| 67 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 68 | <h2 id="Source_code_representation">Source code representation</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 69 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 70 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 71 | Source code is Unicode text encoded in |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 72 | <a href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 73 | canonicalized, so a single accented code point is distinct from the |
| 74 | same character constructed from combining an accent and a letter; |
| 75 | those are treated as two code points. For simplicity, this document |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 76 | will use the unqualified term <i>character</i> to refer to a Unicode code point |
| 77 | in the source text. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 78 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 79 | <p> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 80 | Each code point is distinct; for instance, upper and lower case letters |
| 81 | are different characters. |
| 82 | </p> |
Russ Cox | b7d9ffe | 2010-02-16 16:47:18 -0800 | [diff] [blame] | 83 | <p> |
Robert Griesemer | f42e883 | 2010-02-17 15:50:34 -0800 | [diff] [blame] | 84 | Implementation restriction: For compatibility with other tools, a |
| 85 | compiler may disallow the NUL character (U+0000) in the source text. |
Russ Cox | b7d9ffe | 2010-02-16 16:47:18 -0800 | [diff] [blame] | 86 | </p> |
Rob Pike | afac01d | 2012-09-06 10:37:13 -0700 | [diff] [blame] | 87 | <p> |
| 88 | Implementation restriction: For compatibility with other tools, a |
Rob Pike | 488350a | 2012-09-07 10:28:24 -0700 | [diff] [blame] | 89 | compiler 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 Pike | 548c65a | 2013-04-11 11:33:25 -0700 | [diff] [blame] | 91 | A byte order mark may be disallowed anywhere else in the source. |
Rob Pike | afac01d | 2012-09-06 10:37:13 -0700 | [diff] [blame] | 92 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 93 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 94 | <h3 id="Characters">Characters</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 95 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 96 | <p> |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 97 | The following terms are used to denote specific Unicode character classes: |
| 98 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 99 | <pre class="ebnf"> |
Robert Griesemer | 0e8032c | 2011-05-05 09:03:00 -0700 | [diff] [blame] | 100 | newline = /* the Unicode code point U+000A */ . |
| 101 | unicode_char = /* an arbitrary Unicode code point except newline */ . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 102 | unicode_letter = /* a Unicode code point classified as "Letter" */ . |
Robert Griesemer | 212bdd9 | 2016-01-05 14:15:49 -0800 | [diff] [blame] | 103 | unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 104 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 105 | |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 106 | <p> |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 107 | In <a href="https://www.unicode.org/versions/Unicode8.0.0/">The Unicode Standard 8.0</a>, |
Robert Griesemer | 212bdd9 | 2016-01-05 14:15:49 -0800 | [diff] [blame] | 108 | Section 4.5 "General Category" defines a set of character categories. |
| 109 | Go treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo |
| 110 | as Unicode letters, and those in the Number category Nd as Unicode digits. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 111 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 112 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 113 | <h3 id="Letters_and_digits">Letters and digits</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 114 | |
| 115 | <p> |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 116 | The underscore character <code>_</code> (U+005F) is considered a letter. |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 117 | </p> |
| 118 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 119 | letter = unicode_letter | "_" . |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 120 | decimal_digit = "0" … "9" . |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 121 | binary_digit = "0" | "1" . |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 122 | octal_digit = "0" … "7" . |
| 123 | hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 124 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 125 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 126 | <h2 id="Lexical_elements">Lexical elements</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 127 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 128 | <h3 id="Comments">Comments</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 129 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 130 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 131 | Comments serve as program documentation. There are two forms: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 132 | </p> |
| 133 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 134 | <ol> |
| 135 | <li> |
| 136 | <i>Line comments</i> start with the character sequence <code>//</code> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 137 | and stop at the end of the line. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 138 | </li> |
| 139 | <li> |
| 140 | <i>General comments</i> start with the character sequence <code>/*</code> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 141 | and stop with the first subsequent character sequence <code>*/</code>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 142 | </li> |
| 143 | </ol> |
| 144 | |
| 145 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 146 | A comment cannot start inside a <a href="#Rune_literals">rune</a> or |
| 147 | <a href="#String_literals">string literal</a>, or inside a comment. |
| 148 | A general comment containing no newlines acts like a space. |
| 149 | Any other comment acts like a newline. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 150 | </p> |
| 151 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 152 | <h3 id="Tokens">Tokens</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 153 | |
| 154 | <p> |
| 155 | Tokens form the vocabulary of the Go language. |
Robert Griesemer | eb109a7 | 2009-12-28 14:40:42 -0800 | [diff] [blame] | 156 | There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 157 | and punctuation</i>, and <i>literals</i>. <i>White space</i>, formed from |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 158 | spaces (U+0020), horizontal tabs (U+0009), |
| 159 | carriage returns (U+000D), and newlines (U+000A), |
| 160 | is ignored except as it separates tokens |
Robert Griesemer | 0e66a13 | 2010-09-27 18:59:11 -0700 | [diff] [blame] | 161 | that would otherwise combine into a single token. Also, a newline or end of file |
Robert Griesemer | eb109a7 | 2009-12-28 14:40:42 -0800 | [diff] [blame] | 162 | may trigger the insertion of a <a href="#Semicolons">semicolon</a>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 163 | While breaking the input into tokens, |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 164 | the next token is the longest sequence of characters that form a |
| 165 | valid token. |
| 166 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 167 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 168 | <h3 id="Semicolons">Semicolons</h3> |
| 169 | |
| 170 | <p> |
| 171 | The formal grammar uses semicolons <code>";"</code> as terminators in |
| 172 | a number of productions. Go programs may omit most of these semicolons |
| 173 | using the following two rules: |
| 174 | </p> |
| 175 | |
| 176 | <ol> |
| 177 | <li> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 178 | When the input is broken into tokens, a semicolon is automatically inserted |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 179 | into the token stream immediately after a line's final token if that token is |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 180 | <ul> |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 181 | <li>an |
| 182 | <a href="#Identifiers">identifier</a> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 183 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 184 | |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 185 | <li>an |
| 186 | <a href="#Integer_literals">integer</a>, |
| 187 | <a href="#Floating-point_literals">floating-point</a>, |
| 188 | <a href="#Imaginary_literals">imaginary</a>, |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 189 | <a href="#Rune_literals">rune</a>, or |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 190 | <a href="#String_literals">string</a> literal |
| 191 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 192 | |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 193 | <li>one of the <a href="#Keywords">keywords</a> |
| 194 | <code>break</code>, |
| 195 | <code>continue</code>, |
| 196 | <code>fallthrough</code>, or |
| 197 | <code>return</code> |
| 198 | </li> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 199 | |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 200 | <li>one of the <a href="#Operators_and_punctuation">operators and punctuation</a> |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 201 | <code>++</code>, |
| 202 | <code>--</code>, |
| 203 | <code>)</code>, |
| 204 | <code>]</code>, or |
| 205 | <code>}</code> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 206 | </li> |
| 207 | </ul> |
| 208 | </li> |
| 209 | |
| 210 | <li> |
| 211 | To allow complex statements to occupy a single line, a semicolon |
| 212 | may be omitted before a closing <code>")"</code> or <code>"}"</code>. |
| 213 | </li> |
| 214 | </ol> |
| 215 | |
| 216 | <p> |
| 217 | To reflect idiomatic use, code examples in this document elide semicolons |
| 218 | using these rules. |
| 219 | </p> |
| 220 | |
| 221 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 222 | <h3 id="Identifiers">Identifiers</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 223 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 224 | <p> |
| 225 | Identifiers name program entities such as variables and types. |
| 226 | An identifier is a sequence of one or more letters and digits. |
| 227 | The first character in an identifier must be a letter. |
| 228 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 229 | <pre class="ebnf"> |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 230 | identifier = letter { letter | unicode_digit } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 231 | </pre> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 232 | <pre> |
| 233 | a |
| 234 | _x9 |
| 235 | ThisVariableIsExported |
| 236 | αβ |
| 237 | </pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 238 | |
| 239 | <p> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 240 | Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>. |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 241 | </p> |
| 242 | |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 243 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 244 | <h3 id="Keywords">Keywords</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 245 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 246 | <p> |
| 247 | The following keywords are reserved and may not be used as identifiers. |
| 248 | </p> |
| 249 | <pre class="grammar"> |
| 250 | break default func interface select |
| 251 | case defer go map struct |
| 252 | chan else goto package switch |
| 253 | const fallthrough if range type |
| 254 | continue for import return var |
| 255 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 256 | |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 257 | <h3 id="Operators_and_punctuation">Operators and punctuation</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 258 | |
| 259 | <p> |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 260 | The following character sequences represent <a href="#Operators">operators</a> |
| 261 | (including <a href="#assign_op">assignment operators</a>) and punctuation: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 262 | </p> |
| 263 | <pre class="grammar"> |
| 264 | + & += &= && == != ( ) |
| 265 | - | -= |= || < <= [ ] |
| 266 | * ^ *= ^= <- > >= { } |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 267 | / << /= <<= ++ = := , ; |
| 268 | % >> %= >>= -- ! ... . : |
Robert Griesemer | 0eb26fa | 2016-11-18 09:27:18 -0800 | [diff] [blame] | 269 | &^ &^= |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 270 | </pre> |
| 271 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 272 | <h3 id="Integer_literals">Integer literals</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 273 | |
| 274 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 275 | An integer literal is a sequence of digits representing an |
| 276 | <a href="#Constants">integer constant</a>. |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 277 | An optional prefix sets a non-decimal base: <code>0b</code> or <code>0B</code> |
| 278 | for binary, <code>0</code>, <code>0o</code>, or <code>0O</code> for octal, |
| 279 | and <code>0x</code> or <code>0X</code> for hexadecimal. |
| 280 | A single <code>0</code> is considered a decimal zero. |
| 281 | In hexadecimal literals, letters <code>a</code> through <code>f</code> |
| 282 | and <code>A</code> through <code>F</code> represent values 10 through 15. |
| 283 | </p> |
| 284 | |
| 285 | <p> |
| 286 | For readability, an underscore character <code>_</code> may appear after |
| 287 | a base prefix or between successive digits; such underscores do not change |
| 288 | the literal's value. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 289 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 290 | <pre class="ebnf"> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 291 | int_lit = decimal_lit | binary_lit | octal_lit | hex_lit . |
| 292 | decimal_lit = "0" | ( "1" … "9" ) [ [ "_" ] decimal_digits ] . |
| 293 | binary_lit = "0" ( "b" | "B" ) [ "_" ] binary_digits . |
| 294 | octal_lit = "0" [ "o" | "O" ] [ "_" ] octal_digits . |
| 295 | hex_lit = "0" ( "x" | "X" ) [ "_" ] hex_digits . |
| 296 | |
| 297 | decimal_digits = decimal_digit { [ "_" ] decimal_digit } . |
| 298 | binary_digits = binary_digit { [ "_" ] binary_digit } . |
| 299 | octal_digits = octal_digit { [ "_" ] octal_digit } . |
| 300 | hex_digits = hex_digit { [ "_" ] hex_digit } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 301 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 302 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 303 | <pre> |
| 304 | 42 |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 305 | 4_2 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 306 | 0600 |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 307 | 0_600 |
| 308 | 0o600 |
| 309 | 0O600 // second character is capital letter 'O' |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 310 | 0xBadFace |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 311 | 0xBad_Face |
| 312 | 0x_67_7a_2f_cc_40_c6 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 313 | 170141183460469231731687303715884105727 |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 314 | 170_141183_460469_231731_687303_715884_105727 |
| 315 | |
| 316 | _42 // an identifier, not an integer literal |
| 317 | 42_ // invalid: _ must separate successive digits |
| 318 | 4__2 // invalid: only one _ at a time |
| 319 | 0_xBadFace // invalid: _ must separate successive digits |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 320 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 321 | |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 322 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 323 | <h3 id="Floating-point_literals">Floating-point literals</h3> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 324 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 325 | <p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 326 | A floating-point literal is a decimal or hexadecimal representation of a |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 327 | <a href="#Constants">floating-point constant</a>. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 328 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 329 | |
| 330 | <p> |
| 331 | A decimal floating-point literal consists of an integer part (decimal digits), |
| 332 | a decimal point, a fractional part (decimal digits), and an exponent part |
| 333 | (<code>e</code> or <code>E</code> followed by an optional sign and decimal digits). |
| 334 | One of the integer part or the fractional part may be elided; one of the decimal point |
| 335 | or the exponent part may be elided. |
| 336 | An exponent value exp scales the mantissa (integer and fractional part) by 10<sup>exp</sup>. |
| 337 | </p> |
| 338 | |
| 339 | <p> |
| 340 | A hexadecimal floating-point literal consists of a <code>0x</code> or <code>0X</code> |
| 341 | prefix, an integer part (hexadecimal digits), a radix point, a fractional part (hexadecimal digits), |
| 342 | and an exponent part (<code>p</code> or <code>P</code> followed by an optional sign and decimal digits). |
| 343 | One of the integer part or the fractional part may be elided; the radix point may be elided as well, |
| 344 | but the exponent part is required. (This syntax matches the one given in IEEE 754-2008 §5.12.3.) |
| 345 | An exponent value exp scales the mantissa (integer and fractional part) by 2<sup>exp</sup>. |
| 346 | </p> |
| 347 | |
| 348 | <p> |
| 349 | For readability, an underscore character <code>_</code> may appear after |
| 350 | a base prefix or between successive digits; such underscores do not change |
| 351 | the literal value. |
| 352 | </p> |
| 353 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 354 | <pre class="ebnf"> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 355 | float_lit = decimal_float_lit | hex_float_lit . |
| 356 | |
| 357 | decimal_float_lit = decimal_digits "." [ decimal_digits ] [ decimal_exponent ] | |
| 358 | decimal_digits decimal_exponent | |
| 359 | "." decimal_digits [ decimal_exponent ] . |
| 360 | decimal_exponent = ( "e" | "E" ) [ "+" | "-" ] decimal_digits . |
| 361 | |
| 362 | hex_float_lit = "0" ( "x" | "X" ) hex_mantissa hex_exponent . |
| 363 | hex_mantissa = [ "_" ] hex_digits "." [ hex_digits ] | |
| 364 | [ "_" ] hex_digits | |
| 365 | "." hex_digits . |
| 366 | hex_exponent = ( "p" | "P" ) [ "+" | "-" ] decimal_digits . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 367 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 368 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 369 | <pre> |
| 370 | 0. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 371 | 72.40 |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 372 | 072.40 // == 72.40 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 373 | 2.71828 |
| 374 | 1.e+0 |
| 375 | 6.67428e-11 |
| 376 | 1E6 |
| 377 | .25 |
| 378 | .12345E+5 |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 379 | 1_5. // == 15.0 |
| 380 | 0.15e+0_2 // == 15.0 |
| 381 | |
| 382 | 0x1p-2 // == 0.25 |
| 383 | 0x2.p10 // == 2048.0 |
| 384 | 0x1.Fp+0 // == 1.9375 |
| 385 | 0X.8p-0 // == 0.5 |
| 386 | 0X_1FFFP-16 // == 0.1249847412109375 |
| 387 | 0x15e-2 // == 0x15e - 2 (integer subtraction) |
| 388 | |
| 389 | 0x.p1 // invalid: mantissa has no digits |
| 390 | 1p-2 // invalid: p exponent requires hexadecimal mantissa |
| 391 | 0x1.5e-2 // invalid: hexadecimal mantissa requires p exponent |
| 392 | 1_.5 // invalid: _ must separate successive digits |
| 393 | 1._5 // invalid: _ must separate successive digits |
| 394 | 1.5_e1 // invalid: _ must separate successive digits |
| 395 | 1.5e_1 // invalid: _ must separate successive digits |
| 396 | 1.5e1_ // invalid: _ must separate successive digits |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 397 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 398 | |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 399 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 400 | <h3 id="Imaginary_literals">Imaginary literals</h3> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 401 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 402 | <p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 403 | An imaginary literal represents the imaginary part of a |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 404 | <a href="#Constants">complex constant</a>. |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 405 | It consists of an <a href="#Integer_literals">integer</a> or |
| 406 | <a href="#Floating-point_literals">floating-point</a> literal |
| 407 | followed by the lower-case letter <code>i</code>. |
| 408 | The value of an imaginary literal is the value of the respective |
| 409 | integer or floating-point literal multiplied by the imaginary unit <i>i</i>. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 410 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 411 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 412 | <pre class="ebnf"> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 413 | imaginary_lit = (decimal_digits | int_lit | float_lit) "i" . |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 414 | </pre> |
| 415 | |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 416 | <p> |
| 417 | For backward compatibility, an imaginary literal's integer part consisting |
| 418 | entirely of decimal digits (and possibly underscores) is considered a decimal |
| 419 | integer, even if it starts with a leading <code>0</code>. |
| 420 | </p> |
| 421 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 422 | <pre> |
| 423 | 0i |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 424 | 0123i // == 123i for backward-compatibility |
| 425 | 0o123i // == 0o123 * 1i == 83i |
| 426 | 0xabci // == 0xabc * 1i == 2748i |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 427 | 0.i |
| 428 | 2.71828i |
| 429 | 1.e+0i |
| 430 | 6.67428e-11i |
| 431 | 1E6i |
| 432 | .25i |
| 433 | .12345E+5i |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 434 | 0x1p-2i // == 0x1p-2 * 1i == 0.25i |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 435 | </pre> |
| 436 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 437 | |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 438 | <h3 id="Rune_literals">Rune literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 439 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 440 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 441 | A rune literal represents a <a href="#Constants">rune constant</a>, |
| 442 | an integer value identifying a Unicode code point. |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 443 | A rune literal is expressed as one or more characters enclosed in single quotes, |
| 444 | as in <code>'x'</code> or <code>'\n'</code>. |
| 445 | Within the quotes, any character may appear except newline and unescaped single |
| 446 | quote. A single quoted character represents the Unicode value |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 447 | of the character itself, |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 448 | while multi-character sequences beginning with a backslash encode |
| 449 | values in various formats. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 450 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 451 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 452 | <p> |
| 453 | The simplest form represents the single character within the quotes; |
| 454 | since Go source text is Unicode characters encoded in UTF-8, multiple |
| 455 | UTF-8-encoded bytes may represent a single integer value. For |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 456 | instance, the literal <code>'a'</code> holds a single byte representing |
| 457 | a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while |
| 458 | <code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing |
| 459 | a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 460 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 461 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 462 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 463 | Several backslash escapes allow arbitrary values to be encoded as |
Oling Cat | 845f4d6 | 2012-09-05 14:53:13 +1000 | [diff] [blame] | 464 | ASCII text. There are four ways to represent the integer value |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 465 | as a numeric constant: <code>\x</code> followed by exactly two hexadecimal |
| 466 | digits; <code>\u</code> followed by exactly four hexadecimal digits; |
| 467 | <code>\U</code> followed by exactly eight hexadecimal digits, and a |
| 468 | plain backslash <code>\</code> followed by exactly three octal digits. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 469 | In each case the value of the literal is the value represented by |
| 470 | the digits in the corresponding base. |
| 471 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 472 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 473 | <p> |
| 474 | Although these representations all result in an integer, they have |
| 475 | different valid ranges. Octal escapes must represent a value between |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 476 | 0 and 255 inclusive. Hexadecimal escapes satisfy this condition |
| 477 | by construction. The escapes <code>\u</code> and <code>\U</code> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 478 | represent Unicode code points so within them some values are illegal, |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 479 | in particular those above <code>0x10FFFF</code> and surrogate halves. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 480 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 481 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 482 | <p> |
| 483 | After a backslash, certain single-character escapes represent special values: |
| 484 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 485 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 486 | <pre class="grammar"> |
| 487 | \a U+0007 alert or bell |
| 488 | \b U+0008 backspace |
| 489 | \f U+000C form feed |
| 490 | \n U+000A line feed or newline |
| 491 | \r U+000D carriage return |
| 492 | \t U+0009 horizontal tab |
| 493 | \v U+000b vertical tab |
| 494 | \\ U+005c backslash |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 495 | \' U+0027 single quote (valid escape only within rune literals) |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 496 | \" U+0022 double quote (valid escape only within string literals) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 497 | </pre> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 498 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 499 | <p> |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 500 | All other sequences starting with a backslash are illegal inside rune literals. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 501 | </p> |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 502 | <pre class="ebnf"> |
Robert Griesemer | c863db4 | 2013-01-07 18:02:58 -0800 | [diff] [blame] | 503 | rune_lit = "'" ( unicode_value | byte_value ) "'" . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 504 | unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . |
| 505 | byte_value = octal_byte_value | hex_byte_value . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 506 | octal_byte_value = `\` octal_digit octal_digit octal_digit . |
| 507 | hex_byte_value = `\` "x" hex_digit hex_digit . |
| 508 | little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit . |
| 509 | big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 510 | hex_digit hex_digit hex_digit hex_digit . |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 511 | escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 512 | </pre> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 513 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 514 | <pre> |
| 515 | 'a' |
| 516 | 'ä' |
| 517 | '本' |
| 518 | '\t' |
| 519 | '\000' |
| 520 | '\007' |
| 521 | '\377' |
| 522 | '\x07' |
| 523 | '\xff' |
| 524 | '\u12e4' |
| 525 | '\U00101234' |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 526 | '\'' // rune literal containing single quote character |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 527 | 'aa' // illegal: too many characters |
| 528 | '\xa' // illegal: too few hexadecimal digits |
| 529 | '\0' // illegal: too few octal digits |
| 530 | '\uDFFF' // illegal: surrogate half |
| 531 | '\U00110000' // illegal: invalid Unicode code point |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 532 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 533 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 534 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 535 | <h3 id="String_literals">String literals</h3> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 536 | |
| 537 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 538 | A string literal represents a <a href="#Constants">string constant</a> |
| 539 | obtained from concatenating a sequence of characters. There are two forms: |
| 540 | raw string literals and interpreted string literals. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 541 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 542 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 543 | <p> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 544 | Raw string literals are character sequences between back quotes, as in |
| 545 | <code>`foo`</code>. Within the quotes, any character may appear except |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 546 | back quote. The value of a raw string literal is the |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 547 | string composed of the uninterpreted (implicitly UTF-8-encoded) characters |
| 548 | between the quotes; |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 549 | in particular, backslashes have no special meaning and the string may |
Robert Griesemer | 11b7c89 | 2011-12-15 10:51:51 -0800 | [diff] [blame] | 550 | contain newlines. |
Ian Lance Taylor | 2a627da | 2014-05-16 12:20:03 -0700 | [diff] [blame] | 551 | Carriage return characters ('\r') inside raw string literals |
Rob Pike | c26ca91 | 2011-12-14 21:52:41 -0800 | [diff] [blame] | 552 | are discarded from the raw string value. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 553 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 554 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 555 | <p> |
| 556 | Interpreted string literals are character sequences between double |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 557 | quotes, as in <code>"bar"</code>. |
| 558 | Within the quotes, any character may appear except newline and unescaped double quote. |
| 559 | The text between the quotes forms the |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 560 | value of the literal, with backslash escapes interpreted as they |
Robin Eklind | f82097f | 2014-09-03 10:44:33 -0700 | [diff] [blame] | 561 | are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 562 | <code>\"</code> is legal), with the same restrictions. |
| 563 | The three-digit octal (<code>\</code><i>nnn</i>) |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 564 | and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 565 | <i>bytes</i> of the resulting string; all other escapes represent |
| 566 | the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 567 | Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent |
| 568 | a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>, |
| 569 | <code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 570 | the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 571 | U+00FF. |
| 572 | </p> |
| 573 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 574 | <pre class="ebnf"> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 575 | string_lit = raw_string_lit | interpreted_string_lit . |
Robert Griesemer | 0e8032c | 2011-05-05 09:03:00 -0700 | [diff] [blame] | 576 | raw_string_lit = "`" { unicode_char | newline } "`" . |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 577 | interpreted_string_lit = `"` { unicode_value | byte_value } `"` . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 578 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 579 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 580 | <pre> |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 581 | `abc` // same as "abc" |
Robert Griesemer | db7a622 | 2009-06-18 13:51:14 -0700 | [diff] [blame] | 582 | `\n |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 583 | \n` // same as "\\n\n\\n" |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 584 | "\n" |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 585 | "\"" // same as `"` |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 586 | "Hello, world!\n" |
| 587 | "日本語" |
| 588 | "\u65e5本\U00008a9e" |
| 589 | "\xff\u00FF" |
Robert Griesemer | 37a0975 | 2015-05-29 17:36:26 -0700 | [diff] [blame] | 590 | "\uD800" // illegal: surrogate half |
| 591 | "\U00110000" // illegal: invalid Unicode code point |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 592 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 593 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 594 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 595 | These examples all represent the same string: |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 596 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 597 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 598 | <pre> |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 599 | "日本語" // UTF-8 input text |
| 600 | `日本語` // UTF-8 input text as a raw literal |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 601 | "\u65e5\u672c\u8a9e" // the explicit Unicode code points |
| 602 | "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points |
| 603 | "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 604 | </pre> |
Robert Griesemer | cd49927 | 2008-09-29 12:09:00 -0700 | [diff] [blame] | 605 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 606 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 607 | If the source code represents a character as two code points, such as |
| 608 | a combining form involving an accent and a letter, the result will be |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 609 | an error if placed in a rune literal (it is not a single code |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 610 | point), and will appear as two code points if placed in a string |
| 611 | literal. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 612 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 613 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 614 | |
| 615 | <h2 id="Constants">Constants</h2> |
| 616 | |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 617 | <p>There are <i>boolean constants</i>, |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 618 | <i>rune constants</i>, |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 619 | <i>integer constants</i>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 620 | <i>floating-point constants</i>, <i>complex constants</i>, |
Robert Griesemer | f331012 | 2013-07-25 09:35:55 -0700 | [diff] [blame] | 621 | and <i>string constants</i>. Rune, integer, floating-point, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 622 | and complex constants are |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 623 | collectively called <i>numeric constants</i>. |
| 624 | </p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 625 | |
| 626 | <p> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 627 | A constant value is represented by a |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 628 | <a href="#Rune_literals">rune</a>, |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 629 | <a href="#Integer_literals">integer</a>, |
| 630 | <a href="#Floating-point_literals">floating-point</a>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 631 | <a href="#Imaginary_literals">imaginary</a>, |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 632 | or |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 633 | <a href="#String_literals">string</a> literal, |
| 634 | an identifier denoting a constant, |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 635 | a <a href="#Constant_expressions">constant expression</a>, |
| 636 | a <a href="#Conversions">conversion</a> with a result that is a constant, or |
Russ Cox | f442918 | 2010-07-01 17:49:47 -0700 | [diff] [blame] | 637 | the result value of some built-in functions such as |
| 638 | <code>unsafe.Sizeof</code> applied to any value, |
| 639 | <code>cap</code> or <code>len</code> applied to |
| 640 | <a href="#Length_and_capacity">some expressions</a>, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 641 | <code>real</code> and <code>imag</code> applied to a complex constant |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 642 | and <code>complex</code> applied to numeric constants. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 643 | The boolean truth values are represented by the predeclared constants |
| 644 | <code>true</code> and <code>false</code>. The predeclared identifier |
| 645 | <a href="#Iota">iota</a> denotes an integer constant. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 646 | </p> |
| 647 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 648 | <p> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 649 | In general, complex constants are a form of |
| 650 | <a href="#Constant_expressions">constant expression</a> |
| 651 | and are discussed in that section. |
| 652 | </p> |
| 653 | |
| 654 | <p> |
Robert Griesemer | 55ecda4 | 2015-09-17 18:10:20 -0700 | [diff] [blame] | 655 | Numeric constants represent exact values of arbitrary precision and do not overflow. |
| 656 | Consequently, there are no constants denoting the IEEE-754 negative zero, infinity, |
| 657 | and not-a-number values. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 658 | </p> |
| 659 | |
| 660 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 661 | Constants may be <a href="#Types">typed</a> or <i>untyped</i>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 662 | Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>, |
| 663 | and certain <a href="#Constant_expressions">constant expressions</a> |
| 664 | containing only untyped constant operands are untyped. |
| 665 | </p> |
| 666 | |
| 667 | <p> |
| 668 | A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a> |
| 669 | or <a href="#Conversions">conversion</a>, or implicitly when used in a |
| 670 | <a href="#Variable_declarations">variable declaration</a> or an |
| 671 | <a href="#Assignments">assignment</a> or as an |
| 672 | operand in an <a href="#Expressions">expression</a>. |
| 673 | It is an error if the constant value |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 674 | cannot be <a href="#Representability">represented</a> as a value of the respective type. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 675 | </p> |
| 676 | |
| 677 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 678 | An untyped constant has a <i>default type</i> which is the type to which the |
| 679 | constant is implicitly converted in contexts where a typed value is required, |
| 680 | for instance, in a <a href="#Short_variable_declarations">short variable declaration</a> |
| 681 | such as <code>i := 0</code> where there is no explicit type. |
| 682 | The default type of an untyped constant is <code>bool</code>, <code>rune</code>, |
| 683 | <code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code> |
| 684 | respectively, depending on whether it is a boolean, rune, integer, floating-point, |
| 685 | complex, or string constant. |
| 686 | </p> |
| 687 | |
| 688 | <p> |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 689 | Implementation restriction: Although numeric constants have arbitrary |
| 690 | precision in the language, a compiler may implement them using an |
| 691 | internal representation with limited precision. That said, every |
| 692 | implementation must: |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 693 | </p> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 694 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 695 | <ul> |
| 696 | <li>Represent integer constants with at least 256 bits.</li> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 697 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 698 | <li>Represent floating-point constants, including the parts of |
| 699 | a complex constant, with a mantissa of at least 256 bits |
Robert Griesemer | 8fbfdad | 2015-12-10 11:18:41 -0800 | [diff] [blame] | 700 | and a signed binary exponent of at least 16 bits.</li> |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 701 | |
| 702 | <li>Give an error if unable to represent an integer constant |
| 703 | precisely.</li> |
| 704 | |
| 705 | <li>Give an error if unable to represent a floating-point or |
| 706 | complex constant due to overflow.</li> |
| 707 | |
| 708 | <li>Round to the nearest representable constant if unable to |
| 709 | represent a floating-point or complex constant due to limits |
| 710 | on precision.</li> |
| 711 | </ul> |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 712 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 713 | <p> |
| 714 | These requirements apply both to literal constants and to the result |
| 715 | of evaluating <a href="#Constant_expressions">constant |
| 716 | expressions</a>. |
| 717 | </p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 718 | |
Robert Griesemer | a083648 | 2019-02-04 15:33:19 -0800 | [diff] [blame] | 719 | |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 720 | <h2 id="Variables">Variables</h2> |
| 721 | |
| 722 | <p> |
| 723 | A variable is a storage location for holding a <i>value</i>. |
| 724 | The set of permissible values is determined by the |
| 725 | variable's <i><a href="#Types">type</a></i>. |
| 726 | </p> |
| 727 | |
| 728 | <p> |
| 729 | A <a href="#Variable_declarations">variable declaration</a> |
| 730 | or, for function parameters and results, the signature |
| 731 | of a <a href="#Function_declarations">function declaration</a> |
| 732 | or <a href="#Function_literals">function literal</a> reserves |
| 733 | storage for a named variable. |
| 734 | |
| 735 | Calling the built-in function <a href="#Allocation"><code>new</code></a> |
| 736 | or taking the address of a <a href="#Composite_literals">composite literal</a> |
| 737 | allocates storage for a variable at run time. |
| 738 | Such an anonymous variable is referred to via a (possibly implicit) |
| 739 | <a href="#Address_operators">pointer indirection</a>. |
| 740 | </p> |
| 741 | |
| 742 | <p> |
| 743 | <i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>, |
| 744 | and <a href="#Struct_types">struct</a> types have elements and fields that may |
| 745 | be <a href="#Address_operators">addressed</a> individually. Each such element |
| 746 | acts like a variable. |
| 747 | </p> |
| 748 | |
| 749 | <p> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 750 | The <i>static type</i> (or just <i>type</i>) of a variable is the |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 751 | type given in its declaration, the type provided in the |
| 752 | <code>new</code> call or composite literal, or the type of |
| 753 | an element of a structured variable. |
| 754 | Variables of interface type also have a distinct <i>dynamic type</i>, |
| 755 | which is the concrete type of the value assigned to the variable at run time |
| 756 | (unless the value is the predeclared identifier <code>nil</code>, |
| 757 | which has no type). |
| 758 | The dynamic type may vary during execution but values stored in interface |
| 759 | variables are always <a href="#Assignability">assignable</a> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 760 | to the static type of the variable. |
| 761 | </p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 762 | |
| 763 | <pre> |
| 764 | var x interface{} // x is nil and has static type interface{} |
| 765 | var v *T // v has value nil, static type *T |
| 766 | x = 42 // x has value 42 and dynamic type int |
| 767 | x = v // x has value (*T)(nil) and dynamic type *T |
| 768 | </pre> |
| 769 | |
| 770 | <p> |
| 771 | A variable's value is retrieved by referring to the variable in an |
| 772 | <a href="#Expressions">expression</a>; it is the most recent value |
| 773 | <a href="#Assignments">assigned</a> to the variable. |
| 774 | If a variable has not yet been assigned a value, its value is the |
| 775 | <a href="#The_zero_value">zero value</a> for its type. |
| 776 | </p> |
| 777 | |
| 778 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 779 | <h2 id="Types">Types</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 780 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 781 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 782 | A type determines a set of values together with operations and methods specific |
| 783 | to those values. A type may be denoted by a <i>type name</i>, if it has one, |
| 784 | or specified using a <i>type literal</i>, which composes a type from existing types. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 785 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 786 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 787 | <pre class="ebnf"> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 788 | Type = TypeName | TypeLit | "(" Type ")" . |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 789 | TypeName = identifier | QualifiedIdent . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 790 | TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType | |
| 791 | SliceType | MapType | ChannelType . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 792 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 793 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 794 | <p> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 795 | The language <a href="#Predeclared_identifiers">predeclares</a> certain type names. |
| 796 | Others are introduced with <a href="#Type_declarations">type declarations</a>. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 797 | <i>Composite types</i>—array, struct, pointer, function, |
| 798 | interface, slice, map, and channel types—may be constructed using |
| 799 | type literals. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 800 | </p> |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 801 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 802 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 803 | Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code> |
Robert Griesemer | 8d77d2c | 2014-03-05 19:37:44 -0800 | [diff] [blame] | 804 | is one of the predeclared boolean, numeric, or string types, or a type literal, |
| 805 | the corresponding underlying |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 806 | type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type |
| 807 | is the underlying type of the type to which <code>T</code> refers in its |
| 808 | <a href="#Type_declarations">type declaration</a>. |
| 809 | </p> |
| 810 | |
| 811 | <pre> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 812 | type ( |
| 813 | A1 = string |
| 814 | A2 = A1 |
| 815 | ) |
| 816 | |
| 817 | type ( |
| 818 | B1 string |
| 819 | B2 B1 |
| 820 | B3 []B1 |
| 821 | B4 B3 |
| 822 | ) |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 823 | </pre> |
| 824 | |
| 825 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 826 | The underlying type of <code>string</code>, <code>A1</code>, <code>A2</code>, <code>B1</code>, |
| 827 | and <code>B2</code> is <code>string</code>. |
| 828 | The underlying type of <code>[]B1</code>, <code>B3</code>, and <code>B4</code> is <code>[]B1</code>. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 829 | </p> |
| 830 | |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 831 | <h3 id="Method_sets">Method sets</h3> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 832 | <p> |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 833 | A type may have a <i>method set</i> associated with it. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 834 | The method set of an <a href="#Interface_types">interface type</a> is its interface. |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 835 | The method set of any other type <code>T</code> consists of all |
| 836 | <a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>. |
| 837 | The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code> |
| 838 | is the set of all methods declared with receiver <code>*T</code> or <code>T</code> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 839 | (that is, it also contains the method set of <code>T</code>). |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 840 | Further rules apply to structs containing embedded fields, as described |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 841 | in the section on <a href="#Struct_types">struct types</a>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 842 | Any other type has an empty method set. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 843 | In a method set, each method must have a |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 844 | <a href="#Uniqueness_of_identifiers">unique</a> |
| 845 | non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 846 | </p> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 847 | |
Russ Cox | fd2a511 | 2012-02-08 14:28:51 -0500 | [diff] [blame] | 848 | <p> |
| 849 | The method set of a type determines the interfaces that the |
| 850 | type <a href="#Interface_types">implements</a> |
| 851 | and the methods that can be <a href="#Calls">called</a> |
| 852 | using a receiver of that type. |
| 853 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 854 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 855 | <h3 id="Boolean_types">Boolean types</h3> |
| 856 | |
Stefan Nilsson | c50074e | 2012-02-29 15:07:52 -0800 | [diff] [blame] | 857 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 858 | A <i>boolean type</i> represents the set of Boolean truth values |
| 859 | denoted by the predeclared constants <code>true</code> |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 860 | and <code>false</code>. The predeclared boolean type is <code>bool</code>; |
| 861 | it is a <a href="#Type_definitions">defined type</a>. |
Stefan Nilsson | c50074e | 2012-02-29 15:07:52 -0800 | [diff] [blame] | 862 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 863 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 864 | <h3 id="Numeric_types">Numeric types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 865 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 866 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 867 | A <i>numeric type</i> represents sets of integer or floating-point values. |
| 868 | The predeclared architecture-independent numeric types are: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 869 | </p> |
Robert Griesemer | ebf14c6 | 2008-10-30 14:50:23 -0700 | [diff] [blame] | 870 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 871 | <pre class="grammar"> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 872 | uint8 the set of all unsigned 8-bit integers (0 to 255) |
| 873 | uint16 the set of all unsigned 16-bit integers (0 to 65535) |
| 874 | uint32 the set of all unsigned 32-bit integers (0 to 4294967295) |
| 875 | uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615) |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 876 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 877 | int8 the set of all signed 8-bit integers (-128 to 127) |
| 878 | int16 the set of all signed 16-bit integers (-32768 to 32767) |
| 879 | int32 the set of all signed 32-bit integers (-2147483648 to 2147483647) |
| 880 | int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807) |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 881 | |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 882 | float32 the set of all IEEE-754 32-bit floating-point numbers |
| 883 | float64 the set of all IEEE-754 64-bit floating-point numbers |
| 884 | |
| 885 | complex64 the set of all complex numbers with float32 real and imaginary parts |
| 886 | complex128 the set of all complex numbers with float64 real and imaginary parts |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 887 | |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 888 | byte alias for uint8 |
Russ Cox | d7f050a | 2011-12-09 00:11:43 -0500 | [diff] [blame] | 889 | rune alias for int32 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 890 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 891 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 892 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 893 | The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 894 | <a href="https://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 895 | </p> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 896 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 897 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 898 | There is also a set of predeclared numeric types with implementation-specific sizes: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 899 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 900 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 901 | <pre class="grammar"> |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 902 | uint either 32 or 64 bits |
Robert Griesemer | 97025eb | 2011-01-13 10:24:04 -0800 | [diff] [blame] | 903 | int same size as uint |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 904 | uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 905 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 906 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 907 | <p> |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 908 | To avoid portability issues all numeric types are <a href="#Type_definitions">defined |
| 909 | types</a> and thus distinct except |
| 910 | <code>byte</code>, which is an <a href="#Alias_declarations">alias</a> for <code>uint8</code>, and |
Russ Cox | d7f050a | 2011-12-09 00:11:43 -0500 | [diff] [blame] | 911 | <code>rune</code>, which is an alias for <code>int32</code>. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 912 | Explicit conversions |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 913 | are required when different numeric types are mixed in an expression |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 914 | or assignment. For instance, <code>int32</code> and <code>int</code> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 915 | are not the same type even though they may have the same size on a |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 916 | particular architecture. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 917 | |
| 918 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 919 | <h3 id="String_types">String types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 920 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 921 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 922 | A <i>string type</i> represents the set of string values. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 923 | A string value is a (possibly empty) sequence of bytes. |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 924 | The number of bytes is called the length of the string and is never negative. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 925 | Strings are immutable: once created, |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 926 | it is impossible to change the contents of a string. |
griesemer | 4a2391e | 2017-09-19 14:35:15 +0200 | [diff] [blame] | 927 | The predeclared string type is <code>string</code>; |
| 928 | it is a <a href="#Type_definitions">defined type</a>. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 929 | </p> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 930 | |
| 931 | <p> |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 932 | The length of a string <code>s</code> can be discovered using |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 933 | the built-in function <a href="#Length_and_capacity"><code>len</code></a>. |
| 934 | The length is a compile-time constant if the string is a constant. |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 935 | A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a> |
| 936 | 0 through <code>len(s)-1</code>. |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 937 | It is illegal to take the address of such an element; if |
| 938 | <code>s[i]</code> is the <code>i</code>'th byte of a |
| 939 | string, <code>&s[i]</code> is invalid. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 940 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 941 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 942 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 943 | <h3 id="Array_types">Array types</h3> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 944 | |
| 945 | <p> |
| 946 | An array is a numbered sequence of elements of a single |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 947 | type, called the element type. |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 948 | The number of elements is called the length of the array and is never negative. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 949 | </p> |
| 950 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 951 | <pre class="ebnf"> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 952 | ArrayType = "[" ArrayLength "]" ElementType . |
| 953 | ArrayLength = Expression . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 954 | ElementType = Type . |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 955 | </pre> |
| 956 | |
| 957 | <p> |
Robert Griesemer | 2c83f1e | 2014-05-22 12:23:25 -0700 | [diff] [blame] | 958 | The length is part of the array's type; it must evaluate to a |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 959 | non-negative <a href="#Constants">constant</a> |
| 960 | <a href="#Representability">representable</a> by a value |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 961 | of type <code>int</code>. |
| 962 | The length of array <code>a</code> can be discovered |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 963 | using the built-in function <a href="#Length_and_capacity"><code>len</code></a>. |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 964 | The elements can be addressed by integer <a href="#Index_expressions">indices</a> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 965 | 0 through <code>len(a)-1</code>. |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 966 | Array types are always one-dimensional but may be composed to form |
| 967 | multi-dimensional types. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 968 | </p> |
| 969 | |
| 970 | <pre> |
| 971 | [32]byte |
| 972 | [2*N] struct { x, y int32 } |
| 973 | [1000]*float64 |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 974 | [3][5]int |
| 975 | [2][2][2]float64 // same as [2]([2]([2]float64)) |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 976 | </pre> |
| 977 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 978 | <h3 id="Slice_types">Slice types</h3> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 979 | |
| 980 | <p> |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 981 | A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and |
Robert Griesemer | b34f055 | 2013-04-02 23:17:37 -0700 | [diff] [blame] | 982 | provides access to a numbered sequence of elements from that array. |
| 983 | A slice type denotes the set of all slices of arrays of its element type. |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 984 | The number of elements is called the length of the slice and is never negative. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 985 | The value of an uninitialized slice is <code>nil</code>. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 986 | </p> |
| 987 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 988 | <pre class="ebnf"> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 989 | SliceType = "[" "]" ElementType . |
| 990 | </pre> |
| 991 | |
| 992 | <p> |
Robert Griesemer | de578dc | 2018-11-12 11:25:58 -0800 | [diff] [blame] | 993 | The length of a slice <code>s</code> can be discovered by the built-in function |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 994 | <a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 995 | execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a> |
| 996 | 0 through <code>len(s)-1</code>. The slice index of a |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 997 | given element may be less than the index of the same element in the |
| 998 | underlying array. |
| 999 | </p> |
| 1000 | <p> |
| 1001 | A slice, once initialized, is always associated with an underlying |
Rob Pike | 7ec0856 | 2010-01-09 07:32:26 +1100 | [diff] [blame] | 1002 | array that holds its elements. A slice therefore shares storage |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1003 | with its array and with other slices of the same array; by contrast, |
| 1004 | distinct arrays always represent distinct storage. |
| 1005 | </p> |
| 1006 | <p> |
| 1007 | The array underlying a slice may extend past the end of the slice. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 1008 | The <i>capacity</i> is a measure of that extent: it is the sum of |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1009 | the length of the slice and the length of the array beyond the slice; |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 1010 | a slice of length up to that capacity can be created by |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 1011 | <a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1012 | The capacity of a slice <code>a</code> can be discovered using the |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1013 | built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>. |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1014 | </p> |
| 1015 | |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1016 | <p> |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1017 | A new, initialized slice value for a given element type <code>T</code> is |
| 1018 | made using the built-in function |
| 1019 | <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| 1020 | which takes a slice type |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 1021 | and parameters specifying the length and optionally the capacity. |
| 1022 | A slice created with <code>make</code> always allocates a new, hidden array |
| 1023 | to which the returned slice value refers. That is, executing |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1024 | </p> |
| 1025 | |
| 1026 | <pre> |
| 1027 | make([]T, length, capacity) |
| 1028 | </pre> |
| 1029 | |
| 1030 | <p> |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 1031 | produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a> |
| 1032 | it, so these two expressions are equivalent: |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1033 | </p> |
| 1034 | |
| 1035 | <pre> |
| 1036 | make([]int, 50, 100) |
| 1037 | new([100]int)[0:50] |
| 1038 | </pre> |
| 1039 | |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 1040 | <p> |
| 1041 | Like arrays, slices are always one-dimensional but may be composed to construct |
| 1042 | higher-dimensional objects. |
| 1043 | With arrays of arrays, the inner arrays are, by construction, always the same length; |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 1044 | however with slices of slices (or arrays of slices), the inner lengths may vary dynamically. |
| 1045 | Moreover, the inner slices must be initialized individually. |
Rob Pike | ff6a8fd | 2009-11-20 15:47:15 -0800 | [diff] [blame] | 1046 | </p> |
Russ Cox | 461dd91 | 2009-03-04 14:44:51 -0800 | [diff] [blame] | 1047 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1048 | <h3 id="Struct_types">Struct types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1049 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1050 | <p> |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1051 | A struct is a sequence of named elements, called fields, each of which has a |
| 1052 | name and a type. Field names may be specified explicitly (IdentifierList) or |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1053 | implicitly (EmbeddedField). |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1054 | Within a struct, non-<a href="#Blank_identifier">blank</a> field names must |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1055 | be <a href="#Uniqueness_of_identifiers">unique</a>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1056 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1057 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1058 | <pre class="ebnf"> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1059 | StructType = "struct" "{" { FieldDecl ";" } "}" . |
| 1060 | FieldDecl = (IdentifierList Type | EmbeddedField) [ Tag ] . |
| 1061 | EmbeddedField = [ "*" ] TypeName . |
| 1062 | Tag = string_lit . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1063 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1064 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1065 | <pre> |
| 1066 | // An empty struct. |
| 1067 | struct {} |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1068 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1069 | // A struct with 6 fields. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1070 | struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1071 | x, y int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1072 | u float32 |
| 1073 | _ float32 // padding |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1074 | A *[]int |
| 1075 | F func() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1076 | } |
| 1077 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 1078 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1079 | <p> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1080 | A field declared with a type but no explicit field name is called an <i>embedded field</i>. |
| 1081 | An embedded field must be specified as |
Russ Cox | bee2d5b | 2010-09-30 14:59:41 -0400 | [diff] [blame] | 1082 | a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>, |
Ian Lance Taylor | 3e804ba | 2009-08-17 11:40:57 -0700 | [diff] [blame] | 1083 | and <code>T</code> itself may not be |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1084 | a pointer type. The unqualified type name acts as the field name. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1085 | </p> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 1086 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1087 | <pre> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1088 | // A struct with four embedded fields of types T1, *T2, P.T3 and *P.T4 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1089 | struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1090 | T1 // field name is T1 |
| 1091 | *T2 // field name is T2 |
| 1092 | P.T3 // field name is T3 |
| 1093 | *P.T4 // field name is T4 |
| 1094 | x, y int // field names are x and y |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1095 | } |
| 1096 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 1097 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1098 | <p> |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1099 | The following declaration is illegal because field names must be unique |
| 1100 | in a struct type: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1101 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 1102 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1103 | <pre> |
| 1104 | struct { |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1105 | T // conflicts with embedded field *T and *P.T |
| 1106 | *T // conflicts with embedded field T and *P.T |
| 1107 | *P.T // conflicts with embedded field T and *T |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1108 | } |
| 1109 | </pre> |
Robert Griesemer | 1f3e842 | 2008-09-29 18:41:30 -0700 | [diff] [blame] | 1110 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1111 | <p> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1112 | A field or <a href="#Method_declarations">method</a> <code>f</code> of an |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1113 | embedded field in a struct <code>x</code> is called <i>promoted</i> if |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1114 | <code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes |
| 1115 | that field or method <code>f</code>. |
| 1116 | </p> |
| 1117 | |
| 1118 | <p> |
| 1119 | Promoted fields act like ordinary fields |
| 1120 | of a struct except that they cannot be used as field names in |
| 1121 | <a href="#Composite_literals">composite literals</a> of the struct. |
| 1122 | </p> |
| 1123 | |
| 1124 | <p> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 1125 | Given a struct type <code>S</code> and a <a href="#Type_definitions">defined type</a> |
| 1126 | <code>T</code>, promoted methods are included in the method set of the struct as follows: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1127 | </p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1128 | <ul> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1129 | <li> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1130 | If <code>S</code> contains an embedded field <code>T</code>, |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1131 | the <a href="#Method_sets">method sets</a> of <code>S</code> |
| 1132 | and <code>*S</code> both include promoted methods with receiver |
| 1133 | <code>T</code>. The method set of <code>*S</code> also |
| 1134 | includes promoted methods with receiver <code>*T</code>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1135 | </li> |
Robin Eklind | 1d46fc4 | 2012-12-11 12:17:53 -0500 | [diff] [blame] | 1136 | |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1137 | <li> |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1138 | If <code>S</code> contains an embedded field <code>*T</code>, |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1139 | the method sets of <code>S</code> and <code>*S</code> both |
| 1140 | include promoted methods with receiver <code>T</code> or |
| 1141 | <code>*T</code>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1142 | </li> |
| 1143 | </ul> |
Robert Griesemer | 787adb6 | 2012-06-04 14:24:10 -0700 | [diff] [blame] | 1144 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1145 | <p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1146 | A field declaration may be followed by an optional string literal <i>tag</i>, |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 1147 | which becomes an attribute for all the fields in the corresponding |
Robert Griesemer | 0436a89 | 2016-04-22 16:35:29 -0700 | [diff] [blame] | 1148 | field declaration. An empty tag string is equivalent to an absent tag. |
| 1149 | The tags are made visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a> |
Emil Hessman | 1314131 | 2014-01-03 22:48:03 -0800 | [diff] [blame] | 1150 | and take part in <a href="#Type_identity">type identity</a> for structs |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1151 | but are otherwise ignored. |
| 1152 | </p> |
Robert Griesemer | 2e90e54 | 2008-10-30 15:52:37 -0700 | [diff] [blame] | 1153 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1154 | <pre> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1155 | struct { |
Robert Griesemer | 7305b55 | 2015-11-30 14:18:09 -0800 | [diff] [blame] | 1156 | x, y float64 "" // an empty tag string is like an absent tag |
| 1157 | name string "any string is permitted as a tag" |
| 1158 | _ [4]byte "ceci n'est pas un champ de structure" |
| 1159 | } |
| 1160 | |
| 1161 | // A struct corresponding to a TimeStamp protocol buffer. |
| 1162 | // The tag strings define the protocol buffer field numbers; |
| 1163 | // they follow the convention outlined by the reflect package. |
| 1164 | struct { |
| 1165 | microsec uint64 `protobuf:"1"` |
| 1166 | serverIP6 uint64 `protobuf:"2"` |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1167 | } |
| 1168 | </pre> |
Robert Griesemer | 2e90e54 | 2008-10-30 15:52:37 -0700 | [diff] [blame] | 1169 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1170 | <h3 id="Pointer_types">Pointer types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1171 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1172 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 1173 | A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1174 | type, called the <i>base type</i> of the pointer. |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 1175 | The value of an uninitialized pointer is <code>nil</code>. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1176 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1177 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1178 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1179 | PointerType = "*" BaseType . |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 1180 | BaseType = Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1181 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1182 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1183 | <pre> |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1184 | *Point |
| 1185 | *[4]int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1186 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1187 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1188 | <h3 id="Function_types">Function types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1189 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1190 | <p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 1191 | A function type denotes the set of all functions with the same parameter |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 1192 | and result types. The value of an uninitialized variable of function type |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1193 | is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1194 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1195 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1196 | <pre class="ebnf"> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1197 | FunctionType = "func" Signature . |
| 1198 | Signature = Parameters [ Result ] . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1199 | Result = Parameters | Type . |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1200 | Parameters = "(" [ ParameterList [ "," ] ] ")" . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1201 | ParameterList = ParameterDecl { "," ParameterDecl } . |
Russ Cox | 9562592 | 2010-06-12 11:37:13 -0700 | [diff] [blame] | 1202 | ParameterDecl = [ IdentifierList ] [ "..." ] Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1203 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1204 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1205 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1206 | Within a list of parameters or results, the names (IdentifierList) |
| 1207 | must either all be present or all be absent. If present, each name |
Robert Griesemer | 85e451e | 2012-11-29 14:47:47 -0800 | [diff] [blame] | 1208 | stands for one item (parameter or result) of the specified type and |
| 1209 | all non-<a href="#Blank_identifier">blank</a> names in the signature |
| 1210 | must be <a href="#Uniqueness_of_identifiers">unique</a>. |
| 1211 | If absent, each type stands for one item of that type. |
| 1212 | Parameter and result |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1213 | lists are always parenthesized except that if there is exactly |
Robert Griesemer | 73ca127 | 2010-07-09 13:02:54 -0700 | [diff] [blame] | 1214 | one unnamed result it may be written as an unparenthesized type. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1215 | </p> |
Russ Cox | 9562592 | 2010-06-12 11:37:13 -0700 | [diff] [blame] | 1216 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 1217 | <p> |
Robert Griesemer | 57c81ef | 2015-12-15 13:13:38 -0800 | [diff] [blame] | 1218 | The final incoming parameter in a function signature may have |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 1219 | a type prefixed with <code>...</code>. |
| 1220 | A function with such a parameter is called <i>variadic</i> and |
| 1221 | may be invoked with zero or more arguments for that parameter. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1222 | </p> |
Robert Griesemer | 2bfa957 | 2008-10-24 13:13:12 -0700 | [diff] [blame] | 1223 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1224 | <pre> |
Russ Cox | 4687169 | 2010-01-26 10:25:56 -0800 | [diff] [blame] | 1225 | func() |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1226 | func(x int) int |
| 1227 | func(a, _ int, z float32) bool |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1228 | func(a, b int, z float32) (bool) |
Robert Griesemer | 953f2de | 2012-03-01 10:35:15 -0800 | [diff] [blame] | 1229 | func(prefix string, values ...int) |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1230 | func(a, b int, z float64, opt ...interface{}) (success bool) |
| 1231 | func(int, int, float64) (float64, *[]int) |
Russ Cox | 4687169 | 2010-01-26 10:25:56 -0800 | [diff] [blame] | 1232 | func(n int) func(p *T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1233 | </pre> |
Robert Griesemer | 2b9fe0e | 2009-01-30 14:48:29 -0800 | [diff] [blame] | 1234 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1235 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1236 | <h3 id="Interface_types">Interface types</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1237 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1238 | <p> |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 1239 | An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>. |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1240 | A variable of interface type can store a value of any type with a method set |
| 1241 | that is any superset of the interface. Such a type is said to |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1242 | <i>implement the interface</i>. |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 1243 | The value of an uninitialized variable of interface type is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1244 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1245 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1246 | <pre class="ebnf"> |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1247 | InterfaceType = "interface" "{" { ( MethodSpec | InterfaceTypeName ) ";" } "}" . |
| 1248 | MethodSpec = MethodName Signature . |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1249 | MethodName = identifier . |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1250 | InterfaceTypeName = TypeName . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1251 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1252 | |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1253 | <p> |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1254 | An interface type may specify methods <i>explicitly</i> through method specifications, |
| 1255 | or it may <i>embed</i> methods of other interfaces through interface type names. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 1256 | </p> |
| 1257 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1258 | <pre> |
Robert Griesemer | 39d4178 | 2019-07-30 16:16:03 -0700 | [diff] [blame] | 1259 | // A simple File interface. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1260 | interface { |
Robert Griesemer | 39d4178 | 2019-07-30 16:16:03 -0700 | [diff] [blame] | 1261 | Read([]byte) (int, error) |
| 1262 | Write([]byte) (int, error) |
| 1263 | Close() error |
| 1264 | } |
| 1265 | </pre> |
| 1266 | |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1267 | <p> |
| 1268 | The name of each explicitly specified method must be <a href="#Uniqueness_of_identifiers">unique</a> |
| 1269 | and not <a href="#Blank_identifier">blank</a>. |
| 1270 | </p> |
| 1271 | |
Robert Griesemer | 39d4178 | 2019-07-30 16:16:03 -0700 | [diff] [blame] | 1272 | <pre> |
| 1273 | interface { |
| 1274 | String() string |
| 1275 | String() string // illegal: String not unique |
| 1276 | _(x int) // illegal: method must have non-blank name |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1277 | } |
| 1278 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1279 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1280 | <p> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1281 | More than one type may implement an interface. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1282 | For instance, if two types <code>S1</code> and <code>S2</code> |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 1283 | have the method set |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1284 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1285 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1286 | <pre> |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1287 | func (p T) Read(p []byte) (n int, err error) |
| 1288 | func (p T) Write(p []byte) (n int, err error) |
| 1289 | func (p T) Close() error |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1290 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1291 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1292 | <p> |
| 1293 | (where <code>T</code> stands for either <code>S1</code> or <code>S2</code>) |
| 1294 | then the <code>File</code> interface is implemented by both <code>S1</code> and |
| 1295 | <code>S2</code>, regardless of what other methods |
| 1296 | <code>S1</code> and <code>S2</code> may have or share. |
| 1297 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1298 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1299 | <p> |
| 1300 | A type implements any interface comprising any subset of its methods |
| 1301 | and may therefore implement several distinct interfaces. For |
| 1302 | instance, all types implement the <i>empty interface</i>: |
| 1303 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1304 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1305 | <pre> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1306 | interface{} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1307 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1308 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1309 | <p> |
| 1310 | Similarly, consider this interface specification, |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 1311 | which appears within a <a href="#Type_declarations">type declaration</a> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1312 | to define an interface called <code>Locker</code>: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1313 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1314 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1315 | <pre> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1316 | type Locker interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1317 | Lock() |
| 1318 | Unlock() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1319 | } |
| 1320 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1321 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1322 | <p> |
| 1323 | If <code>S1</code> and <code>S2</code> also implement |
| 1324 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1325 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1326 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 1327 | func (p T) Lock() { … } |
| 1328 | func (p T) Unlock() { … } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1329 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 1330 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1331 | <p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1332 | they implement the <code>Locker</code> interface as well |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1333 | as the <code>File</code> interface. |
| 1334 | </p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1335 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1336 | <p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1337 | An interface <code>T</code> may use a (possibly qualified) interface type |
| 1338 | name <code>E</code> in place of a method specification. This is called |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1339 | <i>embedding</i> interface <code>E</code> in <code>T</code>. |
| 1340 | The <a href="#Method_sets">method set</a> of <code>T</code> is the <i>union</i> |
| 1341 | of the method sets of <code>T</code>’s explicitly declared methods and of |
| 1342 | <code>T</code>’s embedded interfaces. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1343 | </p> |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1344 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1345 | <pre> |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1346 | type Reader interface { |
| 1347 | Read(p []byte) (n int, err error) |
| 1348 | Close() error |
| 1349 | } |
| 1350 | |
| 1351 | type Writer interface { |
| 1352 | Write(p []byte) (n int, err error) |
| 1353 | Close() error |
| 1354 | } |
| 1355 | |
| 1356 | // ReadWriter's methods are Read, Write, and Close. |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1357 | type ReadWriter interface { |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1358 | Reader // includes methods of Reader in ReadWriter's method set |
| 1359 | Writer // includes methods of Writer in ReadWriter's method set |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1360 | } |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1361 | </pre> |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1362 | |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1363 | <p> |
| 1364 | A <i>union</i> of method sets contains the (exported and non-exported) |
| 1365 | methods of each method set exactly once, and methods with the |
| 1366 | <a href="#Uniqueness_of_identifiers">same</a> names must |
| 1367 | have <a href="#Type_identity">identical</a> signatures. |
| 1368 | </p> |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1369 | |
Robert Griesemer | bc405df | 2019-08-14 17:37:20 -0700 | [diff] [blame] | 1370 | <pre> |
| 1371 | type ReadCloser interface { |
| 1372 | Reader // includes methods of Reader in ReadCloser's method set |
| 1373 | Close() // illegal: signatures of Reader.Close and Close are different |
Robert Griesemer | bb29c5a | 2014-09-25 12:49:42 -0700 | [diff] [blame] | 1374 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1375 | </pre> |
Robert Griesemer | 38c232f | 2009-02-11 15:09:15 -0800 | [diff] [blame] | 1376 | |
Russ Cox | 388816a | 2012-02-08 14:35:00 -0500 | [diff] [blame] | 1377 | <p> |
Russ Cox | 7c5d640 | 2012-02-08 15:37:58 -0500 | [diff] [blame] | 1378 | An interface type <code>T</code> may not embed itself |
| 1379 | or any interface type that embeds <code>T</code>, recursively. |
Russ Cox | 388816a | 2012-02-08 14:35:00 -0500 | [diff] [blame] | 1380 | </p> |
| 1381 | |
| 1382 | <pre> |
| 1383 | // illegal: Bad cannot embed itself |
| 1384 | type Bad interface { |
| 1385 | Bad |
| 1386 | } |
| 1387 | |
| 1388 | // illegal: Bad1 cannot embed itself using Bad2 |
| 1389 | type Bad1 interface { |
| 1390 | Bad2 |
| 1391 | } |
| 1392 | type Bad2 interface { |
| 1393 | Bad1 |
| 1394 | } |
| 1395 | </pre> |
| 1396 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1397 | <h3 id="Map_types">Map types</h3> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1398 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1399 | <p> |
| 1400 | A map is an unordered group of elements of one type, called the |
Robert Griesemer | 0660d24 | 2009-11-15 17:42:27 -0800 | [diff] [blame] | 1401 | element type, indexed by a set of unique <i>keys</i> of another type, |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1402 | called the key type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1403 | The value of an uninitialized map is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1404 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1405 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1406 | <pre class="ebnf"> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1407 | MapType = "map" "[" KeyType "]" ElementType . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1408 | KeyType = Type . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1409 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1410 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1411 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 1412 | The <a href="#Comparison_operators">comparison operators</a> |
| 1413 | <code>==</code> and <code>!=</code> must be fully defined |
Robert Griesemer | 9c3d876 | 2012-01-30 15:31:33 -0800 | [diff] [blame] | 1414 | for operands of the key type; thus the key type must not be a function, map, or |
| 1415 | slice. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 1416 | If the key type is an interface type, these |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1417 | comparison operators must be defined for the dynamic key values; |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 1418 | failure will cause a <a href="#Run_time_panics">run-time panic</a>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1419 | |
| 1420 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1421 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1422 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1423 | map[string]int |
| 1424 | map[*T]struct{ x, y float64 } |
| 1425 | map[string]interface{} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1426 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1427 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1428 | <p> |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1429 | The number of map elements is called its length. |
| 1430 | For a map <code>m</code>, it can be discovered using the |
Robert Griesemer | cc06593 | 2012-09-14 11:31:56 -0700 | [diff] [blame] | 1431 | built-in function <a href="#Length_and_capacity"><code>len</code></a> |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 1432 | and may change during execution. Elements may be added during execution |
| 1433 | using <a href="#Assignments">assignments</a> and retrieved with |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 1434 | <a href="#Index_expressions">index expressions</a>; they may be removed with the |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 1435 | <a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1436 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1437 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1438 | A new, empty map value is made using the built-in |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 1439 | function <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
| 1440 | which takes the map type and an optional capacity hint as arguments: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1441 | </p> |
| 1442 | |
| 1443 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1444 | make(map[string]int) |
| 1445 | make(map[string]int, 100) |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1446 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1447 | |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1448 | <p> |
| 1449 | The initial capacity does not bound its size: |
| 1450 | maps grow to accommodate the number of items |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 1451 | stored in them, with the exception of <code>nil</code> maps. |
| 1452 | A <code>nil</code> map is equivalent to an empty map except that no elements |
| 1453 | may be added. |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1454 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1455 | <h3 id="Channel_types">Channel types</h3> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1456 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1457 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1458 | A channel provides a mechanism for |
| 1459 | <a href="#Go_statements">concurrently executing functions</a> |
| 1460 | to communicate by |
| 1461 | <a href="#Send_statements">sending</a> and |
| 1462 | <a href="#Receive_operator">receiving</a> |
| 1463 | values of a specified element type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1464 | The value of an uninitialized channel is <code>nil</code>. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1465 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1466 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1467 | <pre class="ebnf"> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1468 | ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1469 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1470 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1471 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1472 | The optional <code><-</code> operator specifies the channel <i>direction</i>, |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1473 | <i>send</i> or <i>receive</i>. If no direction is given, the channel is |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1474 | <i>bidirectional</i>. |
Russ Cox | b7ba523 | 2018-11-13 10:23:01 -0500 | [diff] [blame] | 1475 | A channel may be constrained only to send or only to receive by |
| 1476 | <a href="#Assignments">assignment</a> or |
| 1477 | explicit <a href="#Conversions">conversion</a>. |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1478 | </p> |
| 1479 | |
| 1480 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1481 | chan T // can be used to send and receive values of type T |
| 1482 | chan<- float64 // can only be used to send float64s |
| 1483 | <-chan int // can only be used to receive ints |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1484 | </pre> |
| 1485 | |
| 1486 | <p> |
| 1487 | The <code><-</code> operator associates with the leftmost <code>chan</code> |
| 1488 | possible: |
Robert Griesemer | 1c369bd | 2010-01-27 09:35:39 -0800 | [diff] [blame] | 1489 | </p> |
| 1490 | |
| 1491 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1492 | chan<- chan int // same as chan<- (chan int) |
| 1493 | chan<- <-chan int // same as chan<- (<-chan int) |
| 1494 | <-chan <-chan int // same as <-chan (<-chan int) |
Robert Griesemer | 1c369bd | 2010-01-27 09:35:39 -0800 | [diff] [blame] | 1495 | chan (<-chan int) |
| 1496 | </pre> |
| 1497 | |
| 1498 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1499 | A new, initialized channel |
Robert Griesemer | 56ca697 | 2010-05-07 18:22:40 -0700 | [diff] [blame] | 1500 | value can be made using the built-in function |
| 1501 | <a href="#Making_slices_maps_and_channels"><code>make</code></a>, |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1502 | which takes the channel type and an optional <i>capacity</i> as arguments: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1503 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1504 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1505 | <pre> |
Rob Pike | da38974 | 2009-03-02 19:13:40 -0800 | [diff] [blame] | 1506 | make(chan int, 100) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1507 | </pre> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1508 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1509 | <p> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1510 | The capacity, in number of elements, sets the size of the buffer in the channel. |
| 1511 | If the capacity is zero or absent, the channel is unbuffered and communication |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 1512 | succeeds only when both a sender and receiver are ready. Otherwise, the channel |
| 1513 | is buffered and communication succeeds without blocking if the buffer |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1514 | is not full (sends) or not empty (receives). |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 1515 | A <code>nil</code> channel is never ready for communication. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1516 | </p> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1517 | |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 1518 | <p> |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 1519 | A channel may be closed with the built-in function |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1520 | <a href="#Close"><code>close</code></a>. |
| 1521 | The multi-valued assignment form of the |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 1522 | <a href="#Receive_operator">receive operator</a> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 1523 | reports whether a received value was sent before |
| 1524 | the channel was closed. |
| 1525 | </p> |
| 1526 | |
| 1527 | <p> |
| 1528 | A single channel may be used in |
| 1529 | <a href="#Send_statements">send statements</a>, |
| 1530 | <a href="#Receive_operator">receive operations</a>, |
| 1531 | and calls to the built-in functions |
| 1532 | <a href="#Length_and_capacity"><code>cap</code></a> and |
| 1533 | <a href="#Length_and_capacity"><code>len</code></a> |
| 1534 | by any number of goroutines without further synchronization. |
| 1535 | Channels act as first-in-first-out queues. |
| 1536 | For example, if one goroutine sends values on a channel |
| 1537 | and a second goroutine receives them, the values are |
| 1538 | received in the order sent. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 1539 | </p> |
| 1540 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 1541 | <h2 id="Properties_of_types_and_values">Properties of types and values</h2> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1542 | |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1543 | <h3 id="Type_identity">Type identity</h3> |
| 1544 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 1545 | <p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1546 | Two types are either <i>identical</i> or <i>different</i>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1547 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1548 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1549 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1550 | A <a href="#Type_definitions">defined type</a> is always different from any other type. |
| 1551 | Otherwise, two types are identical if their <a href="#Types">underlying</a> type literals are |
| 1552 | structurally equivalent; that is, they have the same literal structure and corresponding |
| 1553 | components have identical types. In detail: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 1554 | </p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1555 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1556 | <ul> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1557 | <li>Two array types are identical if they have identical element types and |
| 1558 | the same array length.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1559 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1560 | <li>Two slice types are identical if they have identical element types.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1561 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1562 | <li>Two struct types are identical if they have the same sequence of fields, |
Russ Cox | e495351 | 2010-06-21 12:42:33 -0700 | [diff] [blame] | 1563 | and if corresponding fields have the same names, and identical types, |
| 1564 | and identical tags. |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1565 | <a href="#Exported_identifiers">Non-exported</a> field names from different |
| 1566 | packages are always different.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1567 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1568 | <li>Two pointer types are identical if they have identical base types.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1569 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1570 | <li>Two function types are identical if they have the same number of parameters |
Russ Cox | 9562592 | 2010-06-12 11:37:13 -0700 | [diff] [blame] | 1571 | and result values, corresponding parameter and result types are |
| 1572 | identical, and either both functions are variadic or neither is. |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1573 | Parameter and result names are not required to match.</li> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 1574 | |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1575 | <li>Two interface types are identical if they have the same set of methods |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 1576 | with the same names and identical function types. |
| 1577 | <a href="#Exported_identifiers">Non-exported</a> method names from different |
| 1578 | packages are always different. The order of the methods is irrelevant.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1579 | |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 1580 | <li>Two map types are identical if they have identical key and element types.</li> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1581 | |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 1582 | <li>Two channel types are identical if they have identical element types and |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1583 | the same direction.</li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1584 | </ul> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1585 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1586 | <p> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1587 | Given the declarations |
| 1588 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1589 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1590 | <pre> |
| 1591 | type ( |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1592 | A0 = []string |
| 1593 | A1 = A0 |
| 1594 | A2 = struct{ a, b int } |
| 1595 | A3 = int |
| 1596 | A4 = func(A3, float64) *A0 |
| 1597 | A5 = func(x int, _ float64) *[]string |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1598 | ) |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1599 | |
| 1600 | type ( |
| 1601 | B0 A0 |
| 1602 | B1 []string |
| 1603 | B2 struct{ a, b int } |
| 1604 | B3 struct{ a, c int } |
| 1605 | B4 func(int, float64) *B0 |
| 1606 | B5 func(x int, y float64) *A1 |
| 1607 | ) |
| 1608 | |
| 1609 | type C0 = B0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1610 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1611 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1612 | <p> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1613 | these types are identical: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1614 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1615 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1616 | <pre> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1617 | A0, A1, and []string |
| 1618 | A2 and struct{ a, b int } |
| 1619 | A3 and int |
| 1620 | A4, func(int, float64) *[]string, and A5 |
| 1621 | |
Robert Griesemer | c13e0e8 | 2018-01-11 10:41:03 -0800 | [diff] [blame] | 1622 | B0 and C0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1623 | []int and []int |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1624 | struct{ a, b *T5 } and struct{ a, b *T5 } |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1625 | func(x int, y float64) *[]string, func(int, float64) (result *[]string), and A5 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 1626 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1627 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 1628 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1629 | <code>B0</code> and <code>B1</code> are different because they are new types |
| 1630 | created by distinct <a href="#Type_definitions">type definitions</a>; |
| 1631 | <code>func(int, float64) *B0</code> and <code>func(x int, y float64) *[]string</code> |
| 1632 | are different because <code>B0</code> is different from <code>[]string</code>. |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 1633 | </p> |
| 1634 | |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 1635 | |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 1636 | <h3 id="Assignability">Assignability</h3> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1637 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1638 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 1639 | A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code> |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 1640 | ("<code>x</code> is assignable to <code>T</code>") if one of the following conditions applies: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1641 | </p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1642 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1643 | <ul> |
| 1644 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1645 | <code>x</code>'s type is identical to <code>T</code>. |
| 1646 | </li> |
| 1647 | <li> |
Rob Pike | 68f1609 | 2010-09-01 10:40:50 +1000 | [diff] [blame] | 1648 | <code>x</code>'s type <code>V</code> and <code>T</code> have identical |
| 1649 | <a href="#Types">underlying types</a> and at least one of <code>V</code> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1650 | or <code>T</code> is not a <a href="#Type_definitions">defined</a> type. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1651 | </li> |
| 1652 | <li> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1653 | <code>T</code> is an interface type and |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1654 | <code>x</code> <a href="#Interface_types">implements</a> <code>T</code>. |
Robert Griesemer | e2cb60b | 2009-06-19 13:03:01 -0700 | [diff] [blame] | 1655 | </li> |
| 1656 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1657 | <code>x</code> is a bidirectional channel value, <code>T</code> is a channel type, |
| 1658 | <code>x</code>'s type <code>V</code> and <code>T</code> have identical element types, |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 1659 | and at least one of <code>V</code> or <code>T</code> is not a defined type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1660 | </li> |
| 1661 | <li> |
| 1662 | <code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code> |
| 1663 | is a pointer, function, slice, map, channel, or interface type. |
| 1664 | </li> |
| 1665 | <li> |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 1666 | <code>x</code> is an untyped <a href="#Constants">constant</a> |
| 1667 | <a href="#Representability">representable</a> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 1668 | by a value of type <code>T</code>. |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1669 | </li> |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 1670 | </ul> |
| 1671 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1672 | |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 1673 | <h3 id="Representability">Representability</h3> |
| 1674 | |
| 1675 | <p> |
| 1676 | A <a href="#Constants">constant</a> <code>x</code> is <i>representable</i> |
| 1677 | by a value of type <code>T</code> if one of the following conditions applies: |
| 1678 | </p> |
| 1679 | |
| 1680 | <ul> |
| 1681 | <li> |
| 1682 | <code>x</code> is in the set of values <a href="#Types">determined</a> by <code>T</code>. |
| 1683 | </li> |
| 1684 | |
| 1685 | <li> |
| 1686 | <code>T</code> is a floating-point type and <code>x</code> can be rounded to <code>T</code>'s |
| 1687 | precision without overflow. Rounding uses IEEE 754 round-to-even rules but with an IEEE |
| 1688 | negative zero further simplified to an unsigned zero. Note that constant values never result |
| 1689 | in an IEEE negative zero, NaN, or infinity. |
| 1690 | </li> |
| 1691 | |
| 1692 | <li> |
| 1693 | <code>T</code> is a complex type, and <code>x</code>'s |
| 1694 | <a href="#Complex_numbers">components</a> <code>real(x)</code> and <code>imag(x)</code> |
| 1695 | are representable by values of <code>T</code>'s component type (<code>float32</code> or |
| 1696 | <code>float64</code>). |
| 1697 | </li> |
| 1698 | </ul> |
| 1699 | |
| 1700 | <pre> |
| 1701 | x T x is representable by a value of T because |
| 1702 | |
| 1703 | 'a' byte 97 is in the set of byte values |
| 1704 | 97 rune rune is an alias for int32, and 97 is in the set of 32-bit integers |
| 1705 | "foo" string "foo" is in the set of string values |
| 1706 | 1024 int16 1024 is in the set of 16-bit integers |
| 1707 | 42.0 byte 42 is in the set of unsigned 8-bit integers |
| 1708 | 1e10 uint64 10000000000 is in the set of unsigned 64-bit integers |
| 1709 | 2.718281828459045 float32 2.718281828459045 rounds to 2.7182817 which is in the set of float32 values |
| 1710 | -1e-1000 float64 -1e-1000 rounds to IEEE -0.0 which is further simplified to 0.0 |
| 1711 | 0i int 0 is an integer value |
| 1712 | (42 + 0i) float32 42.0 (with zero imaginary part) is in the set of float32 values |
| 1713 | </pre> |
| 1714 | |
| 1715 | <pre> |
| 1716 | x T x is not representable by a value of T because |
| 1717 | |
| 1718 | 0 bool 0 is not in the set of boolean values |
| 1719 | 'a' string 'a' is a rune, it is not in the set of string values |
| 1720 | 1024 byte 1024 is not in the set of unsigned 8-bit integers |
| 1721 | -1 uint16 -1 is not in the set of unsigned 16-bit integers |
| 1722 | 1.1 int 1.1 is not an integer value |
| 1723 | 42i float32 (0 + 42i) is not in the set of float32 values |
| 1724 | 1e1000 float64 1e1000 overflows to IEEE +Inf after rounding |
| 1725 | </pre> |
| 1726 | |
| 1727 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1728 | <h2 id="Blocks">Blocks</h2> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1729 | |
| 1730 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1731 | A <i>block</i> is a possibly empty sequence of declarations and statements |
| 1732 | within matching brace brackets. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1733 | </p> |
| 1734 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1735 | <pre class="ebnf"> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1736 | Block = "{" StatementList "}" . |
| 1737 | StatementList = { Statement ";" } . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1738 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 1739 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1740 | <p> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1741 | In addition to explicit blocks in the source code, there are implicit blocks: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1742 | </p> |
| 1743 | |
| 1744 | <ol> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1745 | <li>The <i>universe block</i> encompasses all Go source text.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1746 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1747 | <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1748 | Go source text for that package.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1749 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1750 | <li>Each file has a <i>file block</i> containing all Go source text |
| 1751 | in that file.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1752 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1753 | <li>Each <a href="#If_statements">"if"</a>, |
| 1754 | <a href="#For_statements">"for"</a>, and |
| 1755 | <a href="#Switch_statements">"switch"</a> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1756 | statement is considered to be in its own implicit block.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1757 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 1758 | <li>Each clause in a <a href="#Switch_statements">"switch"</a> |
| 1759 | or <a href="#Select_statements">"select"</a> statement |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1760 | acts as an implicit block.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1761 | </ol> |
| 1762 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1763 | <p> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1764 | Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1765 | </p> |
| 1766 | |
| 1767 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1768 | <h2 id="Declarations_and_scope">Declarations and scope</h2> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1769 | |
| 1770 | <p> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1771 | A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a |
| 1772 | <a href="#Constant_declarations">constant</a>, |
| 1773 | <a href="#Type_declarations">type</a>, |
| 1774 | <a href="#Variable_declarations">variable</a>, |
| 1775 | <a href="#Function_declarations">function</a>, |
| 1776 | <a href="#Labeled_statements">label</a>, or |
| 1777 | <a href="#Import_declarations">package</a>. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1778 | Every identifier in a program must be declared. |
| 1779 | No identifier may be declared twice in the same block, and |
| 1780 | no identifier may be declared in both the file and package block. |
| 1781 | </p> |
| 1782 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1783 | <p> |
| 1784 | The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier |
| 1785 | in a declaration, but it does not introduce a binding and thus is not declared. |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 1786 | In the package block, the identifier <code>init</code> may only be used for |
| 1787 | <a href="#Package_initialization"><code>init</code> function</a> declarations, |
| 1788 | and like the blank identifier it does not introduce a new binding. |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1789 | </p> |
| 1790 | |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1791 | <pre class="ebnf"> |
| 1792 | Declaration = ConstDecl | TypeDecl | VarDecl . |
| 1793 | TopLevelDecl = Declaration | FunctionDecl | MethodDecl . |
| 1794 | </pre> |
| 1795 | |
| 1796 | <p> |
| 1797 | The <i>scope</i> of a declared identifier is the extent of source text in which |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1798 | the identifier denotes the specified constant, type, variable, function, label, or package. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1799 | </p> |
| 1800 | |
| 1801 | <p> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1802 | Go is lexically scoped using <a href="#Blocks">blocks</a>: |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1803 | </p> |
| 1804 | |
| 1805 | <ol> |
Robert Griesemer | 4cc71e3 | 2013-10-03 16:38:22 -0700 | [diff] [blame] | 1806 | <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1807 | |
| 1808 | <li>The scope of an identifier denoting a constant, type, variable, |
Robert Griesemer | 967a2b3 | 2011-03-03 15:24:28 -0800 | [diff] [blame] | 1809 | or function (but not method) declared at top level (outside any |
| 1810 | function) is the package block.</li> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1811 | |
Robert Griesemer | e126763 | 2012-11-21 14:40:50 -0800 | [diff] [blame] | 1812 | <li>The scope of the package name of an imported package is the file block |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1813 | of the file containing the import declaration.</li> |
| 1814 | |
Robert Griesemer | 85e451e | 2012-11-29 14:47:47 -0800 | [diff] [blame] | 1815 | <li>The scope of an identifier denoting a method receiver, function parameter, |
| 1816 | or result variable is the function body.</li> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1817 | |
| 1818 | <li>The scope of a constant or variable identifier declared |
| 1819 | inside a function begins at the end of the ConstSpec or VarSpec |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 1820 | (ShortVarDecl for short variable declarations) |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1821 | and ends at the end of the innermost containing block.</li> |
| 1822 | |
| 1823 | <li>The scope of a type identifier declared inside a function |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 1824 | begins at the identifier in the TypeSpec |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1825 | and ends at the end of the innermost containing block.</li> |
| 1826 | </ol> |
| 1827 | |
| 1828 | <p> |
| 1829 | An identifier declared in a block may be redeclared in an inner block. |
| 1830 | While the identifier of the inner declaration is in scope, it denotes |
| 1831 | the entity declared by the inner declaration. |
| 1832 | </p> |
| 1833 | |
| 1834 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1835 | The <a href="#Package_clause">package clause</a> is not a declaration; the package name |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1836 | does not appear in any scope. Its purpose is to identify the files belonging |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 1837 | to the same <a href="#Packages">package</a> and to specify the default package name for import |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1838 | declarations. |
| 1839 | </p> |
| 1840 | |
| 1841 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1842 | <h3 id="Label_scopes">Label scopes</h3> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1843 | |
| 1844 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1845 | Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 1846 | used in the <a href="#Break_statements">"break"</a>, |
| 1847 | <a href="#Continue_statements">"continue"</a>, and |
| 1848 | <a href="#Goto_statements">"goto"</a> statements. |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 1849 | It is illegal to define a label that is never used. |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 1850 | In contrast to other identifiers, labels are not block scoped and do |
| 1851 | not conflict with identifiers that are not labels. The scope of a label |
| 1852 | is the body of the function in which it is declared and excludes |
| 1853 | the body of any nested function. |
| 1854 | </p> |
| 1855 | |
| 1856 | |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1857 | <h3 id="Blank_identifier">Blank identifier</h3> |
| 1858 | |
| 1859 | <p> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 1860 | The <i>blank identifier</i> is represented by the underscore character <code>_</code>. |
| 1861 | It serves as an anonymous placeholder instead of a regular (non-blank) |
| 1862 | identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>, |
| 1863 | as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1864 | </p> |
| 1865 | |
| 1866 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1867 | <h3 id="Predeclared_identifiers">Predeclared identifiers</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1868 | |
| 1869 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1870 | The following identifiers are implicitly declared in the |
| 1871 | <a href="#Blocks">universe block</a>: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1872 | </p> |
| 1873 | <pre class="grammar"> |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 1874 | Types: |
| 1875 | bool byte complex64 complex128 error float32 float64 |
| 1876 | int int8 int16 int32 int64 rune string |
| 1877 | uint uint8 uint16 uint32 uint64 uintptr |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1878 | |
| 1879 | Constants: |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1880 | true false iota |
| 1881 | |
| 1882 | Zero value: |
| 1883 | nil |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1884 | |
| 1885 | Functions: |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 1886 | append cap close complex copy delete imag len |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 1887 | make new panic print println real recover |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1888 | </pre> |
| 1889 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1890 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1891 | <h3 id="Exported_identifiers">Exported identifiers</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1892 | |
| 1893 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1894 | An identifier may be <i>exported</i> to permit access to it from another package. |
| 1895 | An identifier is exported if both: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1896 | </p> |
| 1897 | <ol> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1898 | <li>the first character of the identifier's name is a Unicode upper case |
| 1899 | letter (Unicode class "Lu"); and</li> |
| 1900 | <li>the identifier is declared in the <a href="#Blocks">package block</a> |
| 1901 | or it is a <a href="#Struct_types">field name</a> or |
| 1902 | <a href="#MethodName">method name</a>.</li> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1903 | </ol> |
| 1904 | <p> |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1905 | All other identifiers are not exported. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1906 | </p> |
| 1907 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 1908 | |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1909 | <h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1910 | |
| 1911 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 1912 | Given a set of identifiers, an identifier is called <i>unique</i> if it is |
| 1913 | <i>different</i> from every other in the set. |
| 1914 | Two identifiers are different if they are spelled differently, or if they |
| 1915 | appear in different <a href="#Packages">packages</a> and are not |
Shenghou Ma | 2195f1a | 2012-03-30 14:04:03 +0800 | [diff] [blame] | 1916 | <a href="#Exported_identifiers">exported</a>. Otherwise, they are the same. |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 1917 | </p> |
| 1918 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1919 | <h3 id="Constant_declarations">Constant declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1920 | |
| 1921 | <p> |
| 1922 | A constant declaration binds a list of identifiers (the names of |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1923 | the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>. |
| 1924 | The number of identifiers must be equal |
| 1925 | to the number of expressions, and the <i>n</i>th identifier on |
| 1926 | the left is bound to the value of the <i>n</i>th expression on the |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1927 | right. |
| 1928 | </p> |
| 1929 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 1930 | <pre class="ebnf"> |
Robert Griesemer | 87f4e36 | 2016-11-04 12:38:53 -0700 | [diff] [blame] | 1931 | ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1932 | ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1933 | |
| 1934 | IdentifierList = identifier { "," identifier } . |
| 1935 | ExpressionList = Expression { "," Expression } . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1936 | </pre> |
| 1937 | |
| 1938 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1939 | If the type is present, all constants take the type specified, and |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 1940 | the expressions must be <a href="#Assignability">assignable</a> to that type. |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 1941 | If the type is omitted, the constants take the |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1942 | individual types of the corresponding expressions. |
| 1943 | If the expression values are untyped <a href="#Constants">constants</a>, |
| 1944 | the declared constants remain untyped and the constant identifiers |
| 1945 | denote the constant values. For instance, if the expression is a |
| 1946 | floating-point literal, the constant identifier denotes a floating-point |
| 1947 | constant, even if the literal's fractional part is zero. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1948 | </p> |
| 1949 | |
| 1950 | <pre> |
| 1951 | const Pi float64 = 3.14159265358979323846 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1952 | const zero = 0.0 // untyped floating-point constant |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1953 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1954 | size int64 = 1024 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 1955 | eof = -1 // untyped integer constant |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1956 | ) |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1957 | const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 1958 | const u, v float32 = 0, 3 // u = 0.0, v = 3.0 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1959 | </pre> |
| 1960 | |
| 1961 | <p> |
| 1962 | Within a parenthesized <code>const</code> declaration list the |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1963 | expression list may be omitted from any but the first ConstSpec. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1964 | Such an empty list is equivalent to the textual substitution of the |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 1965 | first preceding non-empty expression list and its type if any. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 1966 | Omitting the list of expressions is therefore equivalent to |
| 1967 | repeating the previous list. The number of identifiers must be equal |
| 1968 | to the number of expressions in the previous list. |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 1969 | Together with the <a href="#Iota"><code>iota</code> constant generator</a> |
| 1970 | this mechanism permits light-weight declaration of sequential values: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1971 | </p> |
| 1972 | |
| 1973 | <pre> |
| 1974 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1975 | Sunday = iota |
| 1976 | Monday |
| 1977 | Tuesday |
| 1978 | Wednesday |
| 1979 | Thursday |
| 1980 | Friday |
| 1981 | Partyday |
| 1982 | numberOfDays // this constant is not exported |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1983 | ) |
| 1984 | </pre> |
| 1985 | |
| 1986 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 1987 | <h3 id="Iota">Iota</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1988 | |
| 1989 | <p> |
Robert Griesemer | 39f009c | 2010-04-29 10:57:27 -0700 | [diff] [blame] | 1990 | Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 1991 | <code>iota</code> represents successive untyped integer <a href="#Constants"> |
griesemer | 52dd399 | 2017-10-18 15:31:42 -0700 | [diff] [blame] | 1992 | constants</a>. Its value is the index of the respective <a href="#ConstSpec">ConstSpec</a> |
| 1993 | in that constant declaration, starting at zero. |
Robert Griesemer | 39f009c | 2010-04-29 10:57:27 -0700 | [diff] [blame] | 1994 | It can be used to construct a set of related constants: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 1995 | </p> |
| 1996 | |
| 1997 | <pre> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 1998 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 1999 | c0 = iota // c0 == 0 |
| 2000 | c1 = iota // c1 == 1 |
| 2001 | c2 = iota // c2 == 2 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2002 | ) |
| 2003 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2004 | const ( |
| 2005 | a = 1 << iota // a == 1 (iota == 0) |
| 2006 | b = 1 << iota // b == 2 (iota == 1) |
| 2007 | c = 3 // c == 3 (iota == 2, unused) |
| 2008 | d = 1 << iota // d == 8 (iota == 3) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2009 | ) |
| 2010 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2011 | const ( |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2012 | u = iota * 42 // u == 0 (untyped integer constant) |
| 2013 | v float64 = iota * 42 // v == 42.0 (float64 constant) |
| 2014 | w = iota * 42 // w == 84 (untyped integer constant) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2015 | ) |
| 2016 | |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2017 | const x = iota // x == 0 |
| 2018 | const y = iota // y == 0 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2019 | </pre> |
| 2020 | |
| 2021 | <p> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2022 | By definition, multiple uses of <code>iota</code> in the same ConstSpec all have the same value: |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2023 | </p> |
| 2024 | |
| 2025 | <pre> |
| 2026 | const ( |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2027 | bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0 (iota == 0) |
| 2028 | bit1, mask1 // bit1 == 2, mask1 == 1 (iota == 1) |
| 2029 | _, _ // (iota == 2, unused) |
| 2030 | bit3, mask3 // bit3 == 8, mask3 == 7 (iota == 3) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2031 | ) |
| 2032 | </pre> |
| 2033 | |
| 2034 | <p> |
griesemer | 85177f4 | 2017-10-19 11:48:54 -0700 | [diff] [blame] | 2035 | This last example exploits the <a href="#Constant_declarations">implicit repetition</a> |
| 2036 | of the last non-empty expression list. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2037 | </p> |
| 2038 | |
| 2039 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2040 | <h3 id="Type_declarations">Type declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2041 | |
| 2042 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2043 | A type declaration binds an identifier, the <i>type name</i>, to a <a href="#Types">type</a>. |
Robert Griesemer | c0bd4f3 | 2017-02-06 15:57:00 -0800 | [diff] [blame] | 2044 | Type declarations come in two forms: alias declarations and type definitions. |
Rob Pike | cae9a9f | 2020-01-13 16:03:12 +1100 | [diff] [blame] | 2045 | </p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2046 | |
| 2047 | <pre class="ebnf"> |
| 2048 | TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) . |
| 2049 | TypeSpec = AliasDecl | TypeDef . |
| 2050 | </pre> |
| 2051 | |
| 2052 | <h4 id="Alias_declarations">Alias declarations</h4> |
| 2053 | |
| 2054 | <p> |
| 2055 | An alias declaration binds an identifier to the given type. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2056 | </p> |
| 2057 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2058 | <pre class="ebnf"> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2059 | AliasDecl = identifier "=" Type . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2060 | </pre> |
| 2061 | |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2062 | <p> |
| 2063 | Within the <a href="#Declarations_and_scope">scope</a> of |
| 2064 | the identifier, it serves as an <i>alias</i> for the type. |
| 2065 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2066 | |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2067 | <pre> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2068 | type ( |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2069 | nodeList = []*Node // nodeList and []*Node are identical types |
| 2070 | Polar = polar // Polar and polar denote identical types |
| 2071 | ) |
| 2072 | </pre> |
| 2073 | |
| 2074 | |
| 2075 | <h4 id="Type_definitions">Type definitions</h4> |
| 2076 | |
| 2077 | <p> |
Robert Griesemer | c0bd4f3 | 2017-02-06 15:57:00 -0800 | [diff] [blame] | 2078 | A type definition creates a new, distinct type with the same |
| 2079 | <a href="#Types">underlying type</a> and operations as the given type, |
| 2080 | and binds an identifier to it. |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2081 | </p> |
| 2082 | |
| 2083 | <pre class="ebnf"> |
| 2084 | TypeDef = identifier Type . |
| 2085 | </pre> |
| 2086 | |
| 2087 | <p> |
| 2088 | The new type is called a <i>defined type</i>. |
| 2089 | It is <a href="#Type_identity">different</a> from any other type, |
| 2090 | including the type it is created from. |
| 2091 | </p> |
| 2092 | |
| 2093 | <pre> |
| 2094 | type ( |
| 2095 | Point struct{ x, y float64 } // Point and struct{ x, y float64 } are different types |
| 2096 | polar Point // polar and Point denote different types |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2097 | ) |
| 2098 | |
| 2099 | type TreeNode struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2100 | left, right *TreeNode |
| 2101 | value *Comparable |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2102 | } |
| 2103 | |
Rob Pike | 217408a | 2011-11-09 14:22:44 -0800 | [diff] [blame] | 2104 | type Block interface { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2105 | BlockSize() int |
| 2106 | Encrypt(src, dst []byte) |
| 2107 | Decrypt(src, dst []byte) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2108 | } |
| 2109 | </pre> |
| 2110 | |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2111 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2112 | A defined type may have <a href="#Method_declarations">methods</a> associated with it. |
| 2113 | It does not inherit any methods bound to the given type, |
| 2114 | but the <a href="#Method_sets">method set</a> |
Robert Griesemer | d4a1619 | 2010-04-01 12:48:34 -0700 | [diff] [blame] | 2115 | of an interface type or of elements of a composite type remains unchanged: |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2116 | </p> |
| 2117 | |
| 2118 | <pre> |
Rob Pike | bdbe0de | 2011-05-25 06:00:07 +1000 | [diff] [blame] | 2119 | // A Mutex is a data type with two methods, Lock and Unlock. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2120 | type Mutex struct { /* Mutex fields */ } |
| 2121 | func (m *Mutex) Lock() { /* Lock implementation */ } |
| 2122 | func (m *Mutex) Unlock() { /* Unlock implementation */ } |
| 2123 | |
| 2124 | // NewMutex has the same composition as Mutex but its method set is empty. |
| 2125 | type NewMutex Mutex |
| 2126 | |
griesemer | 5abc8c89 | 2017-08-11 16:51:40 +0200 | [diff] [blame] | 2127 | // The method set of PtrMutex's underlying type *Mutex remains unchanged, |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 2128 | // but the method set of PtrMutex is empty. |
| 2129 | type PtrMutex *Mutex |
| 2130 | |
Robert Griesemer | f5b3c14 | 2010-04-27 17:52:44 -0700 | [diff] [blame] | 2131 | // The method set of *PrintableMutex contains the methods |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2132 | // Lock and Unlock bound to its embedded field Mutex. |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2133 | type PrintableMutex struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2134 | Mutex |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2135 | } |
Robert Griesemer | 735e00d | 2010-03-31 16:37:22 -0700 | [diff] [blame] | 2136 | |
Rob Pike | 217408a | 2011-11-09 14:22:44 -0800 | [diff] [blame] | 2137 | // MyBlock is an interface type that has the same method set as Block. |
| 2138 | type MyBlock Block |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2139 | </pre> |
| 2140 | |
| 2141 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2142 | Type definitions may be used to define different boolean, numeric, |
| 2143 | or string types and associate methods with them: |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2144 | </p> |
| 2145 | |
| 2146 | <pre> |
| 2147 | type TimeZone int |
| 2148 | |
| 2149 | const ( |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2150 | EST TimeZone = -(5 + iota) |
| 2151 | CST |
| 2152 | MST |
| 2153 | PST |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2154 | ) |
| 2155 | |
| 2156 | func (tz TimeZone) String() string { |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2157 | return fmt.Sprintf("GMT%+dh", tz) |
Robert Griesemer | fc61b77 | 2009-09-28 14:10:20 -0700 | [diff] [blame] | 2158 | } |
| 2159 | </pre> |
| 2160 | |
| 2161 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2162 | <h3 id="Variable_declarations">Variable declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2163 | |
| 2164 | <p> |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2165 | A variable declaration creates one or more <a href="#Variables">variables</a>, |
| 2166 | binds corresponding identifiers to them, and gives each a type and an initial value. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2167 | </p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2168 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2169 | <pre class="ebnf"> |
Robert Griesemer | 87f4e36 | 2016-11-04 12:38:53 -0700 | [diff] [blame] | 2170 | VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) . |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2171 | VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2172 | </pre> |
| 2173 | |
| 2174 | <pre> |
| 2175 | var i int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2176 | var U, V, W float64 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2177 | var k = 0 |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2178 | var x, y float32 = -1, -2 |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2179 | var ( |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 2180 | i int |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2181 | u, v, s = 2.0, 3.0, "bar" |
| 2182 | ) |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 2183 | var re, im = complexSqrt(-1) |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2184 | var _, found = entries[name] // map lookup; only interested in "found" |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2185 | </pre> |
| 2186 | |
| 2187 | <p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2188 | If a list of expressions is given, the variables are initialized |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2189 | with the expressions following the rules for <a href="#Assignments">assignments</a>. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 2190 | Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2191 | </p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2192 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2193 | <p> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2194 | If a type is present, each variable is given that type. |
| 2195 | Otherwise, each variable is given the type of the corresponding |
| 2196 | initialization value in the assignment. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 2197 | If that value is an untyped constant, it is first implicitly |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2198 | <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 2199 | if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>. |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2200 | The predeclared value <code>nil</code> cannot be used to initialize a variable |
| 2201 | with no explicit type. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2202 | </p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2203 | |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2204 | <pre> |
Brad Fitzpatrick | 5f029de | 2014-12-22 07:58:26 -0800 | [diff] [blame] | 2205 | var d = math.Sin(0.5) // d is float64 |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 2206 | var i = 42 // i is int |
| 2207 | var t, ok = x.(T) // t is T, ok is bool |
| 2208 | var n = nil // illegal |
| 2209 | </pre> |
Robert Griesemer | 2c9e163 | 2012-02-28 17:44:24 -0800 | [diff] [blame] | 2210 | |
| 2211 | <p> |
| 2212 | Implementation restriction: A compiler may make it illegal to declare a variable |
| 2213 | inside a <a href="#Function_declarations">function body</a> if the variable is |
| 2214 | never used. |
| 2215 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2216 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2217 | <h3 id="Short_variable_declarations">Short variable declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2218 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2219 | <p> |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 2220 | A <i>short variable declaration</i> uses the syntax: |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2221 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2222 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2223 | <pre class="ebnf"> |
Robert Griesemer | e1b8cb8 | 2009-07-16 20:31:41 -0700 | [diff] [blame] | 2224 | ShortVarDecl = IdentifierList ":=" ExpressionList . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2225 | </pre> |
| 2226 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2227 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2228 | It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a> |
Robert Griesemer | 2c9e163 | 2012-02-28 17:44:24 -0800 | [diff] [blame] | 2229 | with initializer expressions but no types: |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2230 | </p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2231 | |
| 2232 | <pre class="grammar"> |
| 2233 | "var" IdentifierList = ExpressionList . |
| 2234 | </pre> |
| 2235 | |
| 2236 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2237 | i, j := 0, 10 |
| 2238 | f := func() int { return 7 } |
| 2239 | ch := make(chan int) |
Dina Garmash | 8a2b5f1 | 2018-08-30 16:59:29 -0400 | [diff] [blame] | 2240 | r, w, _ := os.Pipe() // os.Pipe() returns a connected pair of Files and an error, if any |
| 2241 | _, y, _ := coord(p) // coord() returns three values; only interested in y coordinate |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2242 | </pre> |
| 2243 | |
| 2244 | <p> |
Robert Griesemer | 85789da | 2015-08-04 11:29:28 -0700 | [diff] [blame] | 2245 | Unlike regular variable declarations, a short variable declaration may <i>redeclare</i> |
| 2246 | variables provided they were originally declared earlier in the same block |
Robert Griesemer | 120cf67 | 2016-11-17 16:39:11 -0800 | [diff] [blame] | 2247 | (or the parameter lists if the block is the function body) with the same type, |
Robert Griesemer | 85789da | 2015-08-04 11:29:28 -0700 | [diff] [blame] | 2248 | and at least one of the non-<a href="#Blank_identifier">blank</a> variables is new. |
| 2249 | As a consequence, redeclaration can only appear in a multi-variable short declaration. |
| 2250 | Redeclaration does not introduce a new variable; it just assigns a new value to the original. |
Rob Pike | 2a1683a | 2009-04-19 20:04:15 -0700 | [diff] [blame] | 2251 | </p> |
| 2252 | |
| 2253 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2254 | field1, offset := nextField(str, 0) |
| 2255 | field2, offset := nextField(str, offset) // redeclares offset |
Robert Griesemer | f1cc0f4 | 2013-01-09 11:31:32 -0800 | [diff] [blame] | 2256 | a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere |
Rob Pike | 2a1683a | 2009-04-19 20:04:15 -0700 | [diff] [blame] | 2257 | </pre> |
| 2258 | |
| 2259 | <p> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2260 | Short variable declarations may appear only inside functions. |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 2261 | In some contexts such as the initializers for |
| 2262 | <a href="#If_statements">"if"</a>, |
| 2263 | <a href="#For_statements">"for"</a>, or |
| 2264 | <a href="#Switch_statements">"switch"</a> statements, |
| 2265 | they can be used to declare local temporary variables. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2266 | </p> |
| 2267 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2268 | <h3 id="Function_declarations">Function declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2269 | |
| 2270 | <p> |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2271 | A function declaration binds an identifier, the <i>function name</i>, |
| 2272 | to a function. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2273 | </p> |
| 2274 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2275 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2276 | FunctionDecl = "func" FunctionName Signature [ FunctionBody ] . |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2277 | FunctionName = identifier . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2278 | FunctionBody = Block . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2279 | </pre> |
| 2280 | |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2281 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2282 | If the function's <a href="#Function_types">signature</a> declares |
| 2283 | result parameters, the function body's statement list must end in |
| 2284 | a <a href="#Terminating_statements">terminating statement</a>. |
| 2285 | </p> |
| 2286 | |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2287 | <pre> |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2288 | func IndexRune(s string, r rune) int { |
| 2289 | for i, c := range s { |
| 2290 | if c == r { |
| 2291 | return i |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2292 | } |
| 2293 | } |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2294 | // invalid: missing return statement |
Rob Pike | d020891 | 2013-03-22 10:03:55 -0700 | [diff] [blame] | 2295 | } |
| 2296 | </pre> |
| 2297 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2298 | <p> |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2299 | A function declaration may omit the body. Such a declaration provides the |
| 2300 | signature for a function implemented outside Go, such as an assembly routine. |
| 2301 | </p> |
| 2302 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2303 | <pre> |
| 2304 | func min(x int, y int) int { |
| 2305 | if x < y { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2306 | return x |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2307 | } |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2308 | return y |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2309 | } |
Robert Griesemer | 4023dce | 2009-08-14 17:41:52 -0700 | [diff] [blame] | 2310 | |
| 2311 | func flushICache(begin, end uintptr) // implemented externally |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2312 | </pre> |
| 2313 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2314 | <h3 id="Method_declarations">Method declarations</h3> |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2315 | |
| 2316 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2317 | A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>. |
| 2318 | A method declaration binds an identifier, the <i>method name</i>, to a method, |
| 2319 | and associates the method with the receiver's <i>base type</i>. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2320 | </p> |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2321 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2322 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2323 | MethodDecl = "func" Receiver MethodName Signature [ FunctionBody ] . |
Robert Griesemer | 56c9b51 | 2017-02-02 15:43:56 -0800 | [diff] [blame] | 2324 | Receiver = Parameters . |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2325 | </pre> |
| 2326 | |
| 2327 | <p> |
Paolo Martini | 3549178 | 2015-07-17 17:26:08 +0200 | [diff] [blame] | 2328 | The receiver is specified via an extra parameter section preceding the method |
Robert Griesemer | 57c81ef | 2015-12-15 13:13:38 -0800 | [diff] [blame] | 2329 | name. That parameter section must declare a single non-variadic parameter, the receiver. |
Robert Griesemer | bb3e211 | 2018-10-16 16:50:25 -0700 | [diff] [blame] | 2330 | Its type must be a <a href="#Type_definitions">defined</a> type <code>T</code> or a |
| 2331 | pointer to a defined type <code>T</code>. <code>T</code> is called the receiver |
| 2332 | <i>base type</i>. A receiver base type cannot be a pointer or interface type and |
| 2333 | it must be defined in the same package as the method. |
| 2334 | The method is said to be <i>bound</i> to its receiver base type and the method name |
Robert Griesemer | 05614bf | 2015-08-04 11:52:01 -0700 | [diff] [blame] | 2335 | is visible only within <a href="#Selectors">selectors</a> for type <code>T</code> |
| 2336 | or <code>*T</code>. |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2337 | </p> |
| 2338 | |
| 2339 | <p> |
Robert Griesemer | 85e451e | 2012-11-29 14:47:47 -0800 | [diff] [blame] | 2340 | A non-<a href="#Blank_identifier">blank</a> receiver identifier must be |
| 2341 | <a href="#Uniqueness_of_identifiers">unique</a> in the method signature. |
| 2342 | If the receiver's value is not referenced inside the body of the method, |
| 2343 | its identifier may be omitted in the declaration. The same applies in |
| 2344 | general to parameters of functions and methods. |
| 2345 | </p> |
| 2346 | |
| 2347 | <p> |
| 2348 | For a base type, the non-blank names of methods bound to it must be unique. |
Robert Griesemer | b1d9ae9 | 2012-02-12 20:03:30 -0800 | [diff] [blame] | 2349 | If the base type is a <a href="#Struct_types">struct type</a>, |
| 2350 | the non-blank method and field names must be distinct. |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2351 | </p> |
| 2352 | |
| 2353 | <p> |
Robert Griesemer | bb3e211 | 2018-10-16 16:50:25 -0700 | [diff] [blame] | 2354 | Given defined type <code>Point</code>, the declarations |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2355 | </p> |
| 2356 | |
| 2357 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2358 | func (p *Point) Length() float64 { |
| 2359 | return math.Sqrt(p.x * p.x + p.y * p.y) |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2360 | } |
| 2361 | |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2362 | func (p *Point) Scale(factor float64) { |
| 2363 | p.x *= factor |
| 2364 | p.y *= factor |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2365 | } |
| 2366 | </pre> |
| 2367 | |
| 2368 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 2369 | bind the methods <code>Length</code> and <code>Scale</code>, |
| 2370 | with receiver type <code>*Point</code>, |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2371 | to the base type <code>Point</code>. |
| 2372 | </p> |
| 2373 | |
| 2374 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2375 | The type of a method is the type of a function with the receiver as first |
| 2376 | argument. For instance, the method <code>Scale</code> has type |
| 2377 | </p> |
| 2378 | |
| 2379 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2380 | func(p *Point, factor float64) |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2381 | </pre> |
| 2382 | |
| 2383 | <p> |
| 2384 | However, a function declared this way is not a method. |
| 2385 | </p> |
| 2386 | |
Rob Pike | a9ed30f | 2009-02-23 19:26:07 -0800 | [diff] [blame] | 2387 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2388 | <h2 id="Expressions">Expressions</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2389 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2390 | <p> |
| 2391 | An expression specifies the computation of a value by applying |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 2392 | operators and functions to operands. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2393 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2394 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2395 | <h3 id="Operands">Operands</h3> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2396 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2397 | <p> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2398 | Operands denote the elementary values in an expression. An operand may be a |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 2399 | literal, a (possibly <a href="#Qualified_identifiers">qualified</a>) |
| 2400 | non-<a href="#Blank_identifier">blank</a> identifier denoting a |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2401 | <a href="#Constant_declarations">constant</a>, |
| 2402 | <a href="#Variable_declarations">variable</a>, or |
| 2403 | <a href="#Function_declarations">function</a>, |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2404 | or a parenthesized expression. |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 2405 | </p> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2406 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 2407 | <p> |
| 2408 | The <a href="#Blank_identifier">blank identifier</a> may appear as an |
| 2409 | operand only on the left-hand side of an <a href="#Assignments">assignment</a>. |
| 2410 | </p> |
| 2411 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2412 | <pre class="ebnf"> |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2413 | Operand = Literal | OperandName | "(" Expression ")" . |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 2414 | Literal = BasicLit | CompositeLit | FunctionLit . |
| 2415 | BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit . |
yah01 | ee55dd6 | 2020-01-15 01:34:43 +0000 | [diff] [blame] | 2416 | OperandName = identifier | QualifiedIdent . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2417 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2418 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2419 | <h3 id="Qualified_identifiers">Qualified identifiers</h3> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2420 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2421 | <p> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2422 | A qualified identifier is an identifier qualified with a package name prefix. |
| 2423 | Both the package name and the identifier must not be |
| 2424 | <a href="#Blank_identifier">blank</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2425 | </p> |
Robert Griesemer | 337af31 | 2008-11-17 18:11:36 -0800 | [diff] [blame] | 2426 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2427 | <pre class="ebnf"> |
Robert Griesemer | 809e06b | 2012-06-26 11:49:19 -0700 | [diff] [blame] | 2428 | QualifiedIdent = PackageName "." identifier . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2429 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2430 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2431 | <p> |
Robert Griesemer | da63371 | 2012-02-29 09:06:05 -0800 | [diff] [blame] | 2432 | A qualified identifier accesses an identifier in a different package, which |
| 2433 | must be <a href="#Import_declarations">imported</a>. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2434 | The identifier must be <a href="#Exported_identifiers">exported</a> and |
| 2435 | declared in the <a href="#Blocks">package block</a> of that package. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2436 | </p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2437 | |
| 2438 | <pre> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2439 | math.Sin // denotes the Sin function in package math |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2440 | </pre> |
Robert Griesemer | ad71110 | 2008-09-11 17:48:20 -0700 | [diff] [blame] | 2441 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2442 | <h3 id="Composite_literals">Composite literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2443 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2444 | <p> |
| 2445 | Composite literals construct values for structs, arrays, slices, and maps |
| 2446 | and create a new value each time they are evaluated. |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2447 | They consist of the type of the literal followed by a brace-bound list of elements. |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2448 | Each element may optionally be preceded by a corresponding key. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2449 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2450 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2451 | <pre class="ebnf"> |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2452 | CompositeLit = LiteralType LiteralValue . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2453 | LiteralType = StructType | ArrayType | "[" "..." "]" ElementType | |
Robert Griesemer | 07cc644 | 2010-07-29 18:13:41 -0700 | [diff] [blame] | 2454 | SliceType | MapType | TypeName . |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2455 | LiteralValue = "{" [ ElementList [ "," ] ] "}" . |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2456 | ElementList = KeyedElement { "," KeyedElement } . |
| 2457 | KeyedElement = [ Key ":" ] Element . |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2458 | Key = FieldName | Expression | LiteralValue . |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 2459 | FieldName = identifier . |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2460 | Element = Expression | LiteralValue . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2461 | </pre> |
Robert Griesemer | 0976e34 | 2008-09-03 13:37:44 -0700 | [diff] [blame] | 2462 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2463 | <p> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2464 | The LiteralType's underlying type must be a struct, array, slice, or map type |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2465 | (the grammar enforces this constraint except when the type is given |
| 2466 | as a TypeName). |
Robert Griesemer | 3b02242 | 2015-09-11 16:20:23 -0700 | [diff] [blame] | 2467 | The types of the elements and keys must be <a href="#Assignability">assignable</a> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2468 | to the respective field, element, and key types of the literal type; |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2469 | there is no additional conversion. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2470 | The key is interpreted as a field name for struct literals, |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 2471 | an index for array and slice literals, and a key for map literals. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2472 | For map literals, all elements must have a key. It is an error |
| 2473 | to specify multiple elements with the same field name or |
Robert Griesemer | 369d108 | 2017-03-24 09:19:46 -0700 | [diff] [blame] | 2474 | constant key value. For non-constant map keys, see the section on |
| 2475 | <a href="#Order_of_evaluation">evaluation order</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2476 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2477 | |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2478 | <p> |
| 2479 | For struct literals the following rules apply: |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 2480 | </p> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2481 | <ul> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2482 | <li>A key must be a field name declared in the struct type. |
Robert Griesemer | d3b1565 | 2009-11-16 08:58:55 -0800 | [diff] [blame] | 2483 | </li> |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2484 | <li>An element list that does not contain any keys must |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2485 | list an element for each struct field in the |
| 2486 | order in which the fields are declared. |
| 2487 | </li> |
| 2488 | <li>If any element has a key, every element must have a key. |
| 2489 | </li> |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2490 | <li>An element list that contains keys does not need to |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2491 | have an element for each struct field. Omitted fields |
| 2492 | get the zero value for that field. |
| 2493 | </li> |
| 2494 | <li>A literal may omit the element list; such a literal evaluates |
Robert Griesemer | 369a974 | 2012-10-31 15:07:25 -0700 | [diff] [blame] | 2495 | to the zero value for its type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2496 | </li> |
| 2497 | <li>It is an error to specify an element for a non-exported |
| 2498 | field of a struct belonging to a different package. |
| 2499 | </li> |
| 2500 | </ul> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2501 | |
| 2502 | <p> |
| 2503 | Given the declarations |
| 2504 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2505 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2506 | type Point3D struct { x, y, z float64 } |
| 2507 | type Line struct { p, q Point3D } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2508 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2509 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2510 | <p> |
| 2511 | one may write |
| 2512 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2513 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2514 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2515 | origin := Point3D{} // zero value for Point3D |
| 2516 | line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2517 | </pre> |
| 2518 | |
Robert Griesemer | cfe9211 | 2009-06-18 13:29:40 -0700 | [diff] [blame] | 2519 | <p> |
| 2520 | For array and slice literals the following rules apply: |
| 2521 | </p> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2522 | <ul> |
| 2523 | <li>Each element has an associated integer index marking |
| 2524 | its position in the array. |
| 2525 | </li> |
Robert Griesemer | a016ecf | 2016-10-05 15:59:09 -0700 | [diff] [blame] | 2526 | <li>An element with a key uses the key as its index. The |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 2527 | key must be a non-negative constant |
| 2528 | <a href="#Representability">representable</a> by |
Robert Griesemer | a016ecf | 2016-10-05 15:59:09 -0700 | [diff] [blame] | 2529 | a value of type <code>int</code>; and if it is typed |
| 2530 | it must be of integer type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2531 | </li> |
| 2532 | <li>An element without a key uses the previous element's index plus one. |
| 2533 | If the first element has no key, its index is zero. |
| 2534 | </li> |
| 2535 | </ul> |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2536 | |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2537 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 2538 | <a href="#Address_operators">Taking the address</a> of a composite literal |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 2539 | generates a pointer to a unique <a href="#Variables">variable</a> initialized |
| 2540 | with the literal's value. |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2541 | </p> |
Robert Griesemer | eebb9db | 2019-05-09 17:35:29 -0700 | [diff] [blame] | 2542 | |
Rob Pike | 37ab838 | 2009-03-18 22:58:36 -0700 | [diff] [blame] | 2543 | <pre> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 2544 | var pointer *Point3D = &Point3D{y: 1000} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2545 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2546 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2547 | <p> |
Robert Griesemer | eebb9db | 2019-05-09 17:35:29 -0700 | [diff] [blame] | 2548 | Note that the <a href="#The_zero_value">zero value</a> for a slice or map |
| 2549 | type is not the same as an initialized but empty value of the same type. |
| 2550 | Consequently, taking the address of an empty slice or map composite literal |
| 2551 | does not have the same effect as allocating a new slice or map value with |
| 2552 | <a href="#Allocation">new</a>. |
| 2553 | </p> |
| 2554 | |
| 2555 | <pre> |
Rob Pike | cae9a9f | 2020-01-13 16:03:12 +1100 | [diff] [blame] | 2556 | p1 := &[]int{} // p1 points to an initialized, empty slice with value []int{} and length 0 |
Robert Griesemer | eebb9db | 2019-05-09 17:35:29 -0700 | [diff] [blame] | 2557 | p2 := new([]int) // p2 points to an uninitialized slice with value nil and length 0 |
| 2558 | </pre> |
| 2559 | |
| 2560 | <p> |
Robert Griesemer | c720875 | 2015-09-22 17:47:38 -0700 | [diff] [blame] | 2561 | The length of an array literal is the length specified in the literal type. |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 2562 | If fewer elements than the length are provided in the literal, the missing |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 2563 | elements are set to the zero value for the array element type. |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2564 | It is an error to provide elements with index values outside the index range |
| 2565 | of the array. The notation <code>...</code> specifies an array length equal |
| 2566 | to the maximum element index plus one. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2567 | </p> |
Robert Griesemer | b90b213 | 2008-09-19 15:49:55 -0700 | [diff] [blame] | 2568 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2569 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 2570 | buffer := [10]string{} // len(buffer) == 10 |
| 2571 | intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6 |
| 2572 | days := [...]string{"Sat", "Sun"} // len(days) == 2 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2573 | </pre> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2574 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2575 | <p> |
| 2576 | A slice literal describes the entire underlying array literal. |
Robert Griesemer | a656390 | 2016-08-25 21:01:17 -0700 | [diff] [blame] | 2577 | Thus the length and capacity of a slice literal are the maximum |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2578 | element index plus one. A slice literal has the form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2579 | </p> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2580 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2581 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 2582 | []T{x1, x2, … xn} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2583 | </pre> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2584 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2585 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 2586 | and is shorthand for a slice operation applied to an array: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2587 | </p> |
Robert Griesemer | 91bbd64 | 2009-01-07 09:31:35 -0800 | [diff] [blame] | 2588 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2589 | <pre> |
Russ Cox | 4dfe976 | 2011-12-02 12:30:20 -0500 | [diff] [blame] | 2590 | tmp := [n]T{x1, x2, … xn} |
| 2591 | tmp[0 : n] |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2592 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2593 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2594 | <p> |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2595 | Within a composite literal of array, slice, or map type <code>T</code>, |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2596 | elements or map keys that are themselves composite literals may elide the respective |
| 2597 | literal type if it is identical to the element or key type of <code>T</code>. |
| 2598 | Similarly, elements or keys that are addresses of composite literals may elide |
| 2599 | the <code>&T</code> when the element or key type is <code>*T</code>. |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2600 | </p> |
| 2601 | |
| 2602 | <pre> |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2603 | [...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}} |
| 2604 | [][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}} |
| 2605 | [][]Point{{{0, 1}, {1, 2}}} // same as [][]Point{[]Point{Point{0, 1}, Point{1, 2}}} |
| 2606 | map[string]Point{"orig": {0, 0}} // same as map[string]Point{"orig": Point{0, 0}} |
Robert Griesemer | 7727dee | 2015-01-08 16:01:31 -0800 | [diff] [blame] | 2607 | map[Point]string{{0, 0}: "orig"} // same as map[Point]string{Point{0, 0}: "orig"} |
Robert Griesemer | 120cf67 | 2016-11-17 16:39:11 -0800 | [diff] [blame] | 2608 | |
| 2609 | type PPoint *Point |
| 2610 | [2]*Point{{1.5, -3.5}, {}} // same as [2]*Point{&Point{1.5, -3.5}, &Point{}} |
| 2611 | [2]PPoint{{1.5, -3.5}, {}} // same as [2]PPoint{PPoint(&Point{1.5, -3.5}), PPoint(&Point{})} |
Robert Griesemer | a12141e | 2010-10-22 08:58:52 -0700 | [diff] [blame] | 2612 | </pre> |
| 2613 | |
| 2614 | <p> |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2615 | A parsing ambiguity arises when a composite literal using the |
Robert Griesemer | a36b5b9 | 2014-02-27 08:57:30 -0800 | [diff] [blame] | 2616 | TypeName form of the LiteralType appears as an operand between the |
| 2617 | <a href="#Keywords">keyword</a> and the opening brace of the block |
| 2618 | of an "if", "for", or "switch" statement, and the composite literal |
| 2619 | is not enclosed in parentheses, square brackets, or curly braces. |
| 2620 | In this rare case, the opening brace of the literal is erroneously parsed |
| 2621 | as the one introducing the block of statements. To resolve the ambiguity, |
| 2622 | the composite literal must appear within parentheses. |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2623 | </p> |
| 2624 | |
| 2625 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 2626 | if x == (T{a,b,c}[i]) { … } |
| 2627 | if (x == T{a,b,c}[i]) { … } |
Russ Cox | 7a5e97b | 2009-03-03 15:40:30 -0800 | [diff] [blame] | 2628 | </pre> |
| 2629 | |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2630 | <p> |
| 2631 | Examples of valid array, slice, and map literals: |
| 2632 | </p> |
| 2633 | |
| 2634 | <pre> |
| 2635 | // list of prime numbers |
Andrew Bonventre | 7974f08 | 2018-03-19 21:50:42 +0000 | [diff] [blame] | 2636 | primes := []int{2, 3, 5, 7, 9, 2147483647} |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2637 | |
| 2638 | // vowels[ch] is true if ch is a vowel |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2639 | vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true} |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2640 | |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2641 | // the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1} |
| 2642 | filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1} |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2643 | |
| 2644 | // frequencies in Hz for equal-tempered scale (A4 = 440Hz) |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2645 | noteFrequency := map[string]float32{ |
Robert Griesemer | 838cf12 | 2009-05-22 10:25:06 -0700 | [diff] [blame] | 2646 | "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83, |
| 2647 | "G0": 24.50, "A0": 27.50, "B0": 30.87, |
| 2648 | } |
| 2649 | </pre> |
| 2650 | |
| 2651 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2652 | <h3 id="Function_literals">Function literals</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2653 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2654 | <p> |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 2655 | A function literal represents an anonymous <a href="#Function_declarations">function</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2656 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2657 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2658 | <pre class="ebnf"> |
Robert Griesemer | 851e98f | 2018-02-01 14:08:45 -0800 | [diff] [blame] | 2659 | FunctionLit = "func" Signature FunctionBody . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2660 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2661 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2662 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 2663 | func(a, b int, z float64) bool { return a*b < int(z) } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2664 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2665 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2666 | <p> |
| 2667 | A function literal can be assigned to a variable or invoked directly. |
| 2668 | </p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2669 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2670 | <pre> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2671 | f := func(x, y int) int { return x + y } |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 2672 | func(ch chan int) { ch <- ACK }(replyChan) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2673 | </pre> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2674 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2675 | <p> |
| 2676 | Function literals are <i>closures</i>: they may refer to variables |
Robert Griesemer | d8a764c | 2009-02-06 17:01:10 -0800 | [diff] [blame] | 2677 | defined in a surrounding function. Those variables are then shared between |
| 2678 | the surrounding function and the function literal, and they survive as long |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2679 | as they are accessible. |
| 2680 | </p> |
Robert Griesemer | 7231ceb | 2008-09-08 15:01:04 -0700 | [diff] [blame] | 2681 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2682 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2683 | <h3 id="Primary_expressions">Primary expressions</h3> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2684 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 2685 | <p> |
| 2686 | Primary expressions are the operands for unary and binary expressions. |
| 2687 | </p> |
| 2688 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 2689 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2690 | PrimaryExpr = |
| 2691 | Operand | |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 2692 | Conversion | |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2693 | MethodExpr | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2694 | PrimaryExpr Selector | |
| 2695 | PrimaryExpr Index | |
| 2696 | PrimaryExpr Slice | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2697 | PrimaryExpr TypeAssertion | |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 2698 | PrimaryExpr Arguments . |
Robert Griesemer | 57b3461 | 2008-10-10 12:45:44 -0700 | [diff] [blame] | 2699 | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2700 | Selector = "." identifier . |
| 2701 | Index = "[" Expression "]" . |
Robert Griesemer | 5583e8a | 2016-02-23 10:42:06 -0800 | [diff] [blame] | 2702 | Slice = "[" [ Expression ] ":" [ Expression ] "]" | |
| 2703 | "[" [ Expression ] ":" Expression ":" Expression "]" . |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 2704 | TypeAssertion = "." "(" Type ")" . |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 2705 | Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2706 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2707 | |
| 2708 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2709 | <pre> |
| 2710 | x |
| 2711 | 2 |
| 2712 | (s + ".txt") |
| 2713 | f(3.1415, true) |
Rob Pike | 426335f | 2009-03-02 17:52:52 -0800 | [diff] [blame] | 2714 | Point{1, 2} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2715 | m["foo"] |
| 2716 | s[i : j + 1] |
| 2717 | obj.color |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2718 | f.p[i].x() |
| 2719 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2720 | |
| 2721 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 2722 | <h3 id="Selectors">Selectors</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2723 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2724 | <p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2725 | For a <a href="#Primary_expressions">primary expression</a> <code>x</code> |
| 2726 | that is not a <a href="#Package_clause">package name</a>, the |
| 2727 | <i>selector expression</i> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2728 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 2729 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2730 | <pre> |
| 2731 | x.f |
| 2732 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2733 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2734 | <p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2735 | denotes the field or method <code>f</code> of the value <code>x</code> |
| 2736 | (or sometimes <code>*x</code>; see below). |
| 2737 | The identifier <code>f</code> is called the (field or method) <i>selector</i>; |
| 2738 | it must not be the <a href="#Blank_identifier">blank identifier</a>. |
| 2739 | The type of the selector expression is the type of <code>f</code>. |
| 2740 | If <code>x</code> is a package name, see the section on |
| 2741 | <a href="#Qualified_identifiers">qualified identifiers</a>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2742 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2743 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2744 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2745 | A selector <code>f</code> may denote a field or method <code>f</code> of |
| 2746 | a type <code>T</code>, or it may refer |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2747 | to a field or method <code>f</code> of a nested |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2748 | <a href="#Struct_types">embedded field</a> of <code>T</code>. |
| 2749 | The number of embedded fields traversed |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2750 | to reach <code>f</code> is called its <i>depth</i> in <code>T</code>. |
| 2751 | The depth of a field or method <code>f</code> |
| 2752 | declared in <code>T</code> is zero. |
| 2753 | The depth of a field or method <code>f</code> declared in |
Robert Griesemer | f8b4123 | 2017-01-10 16:19:14 -0800 | [diff] [blame] | 2754 | an embedded field <code>A</code> in <code>T</code> is the |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2755 | depth of <code>f</code> in <code>A</code> plus one. |
| 2756 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2757 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2758 | <p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2759 | The following rules apply to selectors: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2760 | </p> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2761 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2762 | <ol> |
| 2763 | <li> |
| 2764 | For a value <code>x</code> of type <code>T</code> or <code>*T</code> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2765 | where <code>T</code> is not a pointer or interface type, |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2766 | <code>x.f</code> denotes the field or method at the shallowest depth |
| 2767 | in <code>T</code> where there |
| 2768 | is such an <code>f</code>. |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 2769 | If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a> |
| 2770 | with shallowest depth, the selector expression is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2771 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2772 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2773 | <li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2774 | For a value <code>x</code> of type <code>I</code> where <code>I</code> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2775 | is an interface type, <code>x.f</code> denotes the actual method with name |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2776 | <code>f</code> of the dynamic value of <code>x</code>. |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2777 | If there is no method with name <code>f</code> in the |
| 2778 | <a href="#Method_sets">method set</a> of <code>I</code>, the selector |
| 2779 | expression is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2780 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2781 | |
| 2782 | <li> |
Robert Griesemer | 9b49ac0 | 2018-01-22 16:20:01 -0800 | [diff] [blame] | 2783 | As an exception, if the type of <code>x</code> is a <a href="#Type_definitions">defined</a> |
| 2784 | pointer type and <code>(*x).f</code> is a valid selector expression denoting a field |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2785 | (but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>. |
| 2786 | </li> |
| 2787 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2788 | <li> |
| 2789 | In all other cases, <code>x.f</code> is illegal. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 2790 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2791 | |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2792 | <li> |
Russ Cox | 6e15683 | 2013-03-20 16:54:07 -0400 | [diff] [blame] | 2793 | If <code>x</code> is of pointer type and has the value |
| 2794 | <code>nil</code> and <code>x.f</code> denotes a struct field, |
| 2795 | assigning to or evaluating <code>x.f</code> |
| 2796 | causes a <a href="#Run_time_panics">run-time panic</a>. |
| 2797 | </li> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2798 | |
Russ Cox | 6e15683 | 2013-03-20 16:54:07 -0400 | [diff] [blame] | 2799 | <li> |
| 2800 | If <code>x</code> is of interface type and has the value |
| 2801 | <code>nil</code>, <a href="#Calls">calling</a> or |
| 2802 | <a href="#Method_values">evaluating</a> the method <code>x.f</code> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2803 | causes a <a href="#Run_time_panics">run-time panic</a>. |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 2804 | </li> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2805 | </ol> |
Robert Griesemer | 71de83b | 2012-06-28 12:22:24 -0700 | [diff] [blame] | 2806 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2807 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2808 | For example, given the declarations: |
| 2809 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2810 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2811 | <pre> |
| 2812 | type T0 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2813 | x int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2814 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2815 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2816 | func (*T0) M0() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2817 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2818 | type T1 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2819 | y int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2820 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2821 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2822 | func (T1) M1() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2823 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2824 | type T2 struct { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 2825 | z int |
| 2826 | T1 |
| 2827 | *T0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2828 | } |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2829 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2830 | func (*T2) M2() |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2831 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2832 | type Q *T2 |
| 2833 | |
| 2834 | var t T2 // with t.T0 != nil |
| 2835 | var p *T2 // with p != nil and (*p).T0 != nil |
| 2836 | var q Q = p |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2837 | </pre> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2838 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 2839 | <p> |
| 2840 | one may write: |
| 2841 | </p> |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2842 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2843 | <pre> |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2844 | t.z // t.z |
| 2845 | t.y // t.T1.y |
Robert Griesemer | f9ec929 | 2015-05-18 11:18:58 -0700 | [diff] [blame] | 2846 | t.x // (*t.T0).x |
Robert Griesemer | 071c91b | 2008-10-23 12:04:45 -0700 | [diff] [blame] | 2847 | |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2848 | p.z // (*p).z |
| 2849 | p.y // (*p).T1.y |
| 2850 | p.x // (*(*p).T0).x |
| 2851 | |
| 2852 | q.x // (*(*q).T0).x (*q).x is a valid field selector |
| 2853 | |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2854 | p.M0() // ((*p).T0).M0() M0 expects *T0 receiver |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2855 | p.M1() // ((*p).T1).M1() M1 expects T1 receiver |
Robert Griesemer | 02d7448 | 2015-07-31 11:15:11 -0700 | [diff] [blame] | 2856 | p.M2() // p.M2() M2 expects *T2 receiver |
| 2857 | t.M2() // (&t).M2() M2 expects *T2 receiver, see section on Calls |
Robert Griesemer | 40818cf | 2014-11-11 13:19:47 -0800 | [diff] [blame] | 2858 | </pre> |
| 2859 | |
| 2860 | <p> |
| 2861 | but the following is invalid: |
| 2862 | </p> |
| 2863 | |
| 2864 | <pre> |
| 2865 | q.M0() // (*q).M0 is valid but not a field selector |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 2866 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 2867 | |
| 2868 | |
Robert Griesemer | f852034 | 2014-08-28 08:53:25 -0700 | [diff] [blame] | 2869 | <h3 id="Method_expressions">Method expressions</h3> |
| 2870 | |
| 2871 | <p> |
| 2872 | If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| 2873 | <code>T.M</code> is a function that is callable as a regular function |
| 2874 | with the same arguments as <code>M</code> prefixed by an additional |
| 2875 | argument that is the receiver of the method. |
| 2876 | </p> |
| 2877 | |
| 2878 | <pre class="ebnf"> |
| 2879 | MethodExpr = ReceiverType "." MethodName . |
griesemer | f2d5251 | 2017-10-25 11:26:02 -0700 | [diff] [blame] | 2880 | ReceiverType = Type . |
Robert Griesemer | f852034 | 2014-08-28 08:53:25 -0700 | [diff] [blame] | 2881 | </pre> |
| 2882 | |
| 2883 | <p> |
| 2884 | Consider a struct type <code>T</code> with two methods, |
| 2885 | <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| 2886 | <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| 2887 | </p> |
| 2888 | |
| 2889 | <pre> |
| 2890 | type T struct { |
| 2891 | a int |
| 2892 | } |
| 2893 | func (tv T) Mv(a int) int { return 0 } // value receiver |
| 2894 | func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| 2895 | |
| 2896 | var t T |
| 2897 | </pre> |
| 2898 | |
| 2899 | <p> |
| 2900 | The expression |
| 2901 | </p> |
| 2902 | |
| 2903 | <pre> |
| 2904 | T.Mv |
| 2905 | </pre> |
| 2906 | |
| 2907 | <p> |
| 2908 | yields a function equivalent to <code>Mv</code> but |
| 2909 | with an explicit receiver as its first argument; it has signature |
| 2910 | </p> |
| 2911 | |
| 2912 | <pre> |
| 2913 | func(tv T, a int) int |
| 2914 | </pre> |
| 2915 | |
| 2916 | <p> |
| 2917 | That function may be called normally with an explicit receiver, so |
| 2918 | these five invocations are equivalent: |
| 2919 | </p> |
| 2920 | |
| 2921 | <pre> |
| 2922 | t.Mv(7) |
| 2923 | T.Mv(t, 7) |
| 2924 | (T).Mv(t, 7) |
| 2925 | f1 := T.Mv; f1(t, 7) |
| 2926 | f2 := (T).Mv; f2(t, 7) |
| 2927 | </pre> |
| 2928 | |
| 2929 | <p> |
| 2930 | Similarly, the expression |
| 2931 | </p> |
| 2932 | |
| 2933 | <pre> |
| 2934 | (*T).Mp |
| 2935 | </pre> |
| 2936 | |
| 2937 | <p> |
| 2938 | yields a function value representing <code>Mp</code> with signature |
| 2939 | </p> |
| 2940 | |
| 2941 | <pre> |
| 2942 | func(tp *T, f float32) float32 |
| 2943 | </pre> |
| 2944 | |
| 2945 | <p> |
| 2946 | For a method with a value receiver, one can derive a function |
| 2947 | with an explicit pointer receiver, so |
| 2948 | </p> |
| 2949 | |
| 2950 | <pre> |
| 2951 | (*T).Mv |
| 2952 | </pre> |
| 2953 | |
| 2954 | <p> |
| 2955 | yields a function value representing <code>Mv</code> with signature |
| 2956 | </p> |
| 2957 | |
| 2958 | <pre> |
| 2959 | func(tv *T, a int) int |
| 2960 | </pre> |
| 2961 | |
| 2962 | <p> |
| 2963 | Such a function indirects through the receiver to create a value |
| 2964 | to pass as the receiver to the underlying method; |
| 2965 | the method does not overwrite the value whose address is passed in |
| 2966 | the function call. |
| 2967 | </p> |
| 2968 | |
| 2969 | <p> |
| 2970 | The final case, a value-receiver function for a pointer-receiver method, |
| 2971 | is illegal because pointer-receiver methods are not in the method set |
| 2972 | of the value type. |
| 2973 | </p> |
| 2974 | |
| 2975 | <p> |
| 2976 | Function values derived from methods are called with function call syntax; |
| 2977 | the receiver is provided as the first argument to the call. |
| 2978 | That is, given <code>f := T.Mv</code>, <code>f</code> is invoked |
| 2979 | as <code>f(t, 7)</code> not <code>t.f(7)</code>. |
| 2980 | To construct a function that binds the receiver, use a |
| 2981 | <a href="#Function_literals">function literal</a> or |
| 2982 | <a href="#Method_values">method value</a>. |
| 2983 | </p> |
| 2984 | |
| 2985 | <p> |
| 2986 | It is legal to derive a function value from a method of an interface type. |
| 2987 | The resulting function takes an explicit receiver of that interface type. |
| 2988 | </p> |
| 2989 | |
| 2990 | <h3 id="Method_values">Method values</h3> |
| 2991 | |
| 2992 | <p> |
| 2993 | If the expression <code>x</code> has static type <code>T</code> and |
| 2994 | <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>, |
| 2995 | <code>x.M</code> is called a <i>method value</i>. |
| 2996 | The method value <code>x.M</code> is a function value that is callable |
| 2997 | with the same arguments as a method call of <code>x.M</code>. |
| 2998 | The expression <code>x</code> is evaluated and saved during the evaluation of the |
| 2999 | method value; the saved copy is then used as the receiver in any calls, |
| 3000 | which may be executed later. |
| 3001 | </p> |
| 3002 | |
| 3003 | <p> |
| 3004 | The type <code>T</code> may be an interface or non-interface type. |
| 3005 | </p> |
| 3006 | |
| 3007 | <p> |
| 3008 | As in the discussion of <a href="#Method_expressions">method expressions</a> above, |
| 3009 | consider a struct type <code>T</code> with two methods, |
| 3010 | <code>Mv</code>, whose receiver is of type <code>T</code>, and |
| 3011 | <code>Mp</code>, whose receiver is of type <code>*T</code>. |
| 3012 | </p> |
| 3013 | |
| 3014 | <pre> |
| 3015 | type T struct { |
| 3016 | a int |
| 3017 | } |
| 3018 | func (tv T) Mv(a int) int { return 0 } // value receiver |
| 3019 | func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver |
| 3020 | |
| 3021 | var t T |
| 3022 | var pt *T |
| 3023 | func makeT() T |
| 3024 | </pre> |
| 3025 | |
| 3026 | <p> |
| 3027 | The expression |
| 3028 | </p> |
| 3029 | |
| 3030 | <pre> |
| 3031 | t.Mv |
| 3032 | </pre> |
| 3033 | |
| 3034 | <p> |
| 3035 | yields a function value of type |
| 3036 | </p> |
| 3037 | |
| 3038 | <pre> |
| 3039 | func(int) int |
| 3040 | </pre> |
| 3041 | |
| 3042 | <p> |
| 3043 | These two invocations are equivalent: |
| 3044 | </p> |
| 3045 | |
| 3046 | <pre> |
| 3047 | t.Mv(7) |
| 3048 | f := t.Mv; f(7) |
| 3049 | </pre> |
| 3050 | |
| 3051 | <p> |
| 3052 | Similarly, the expression |
| 3053 | </p> |
| 3054 | |
| 3055 | <pre> |
| 3056 | pt.Mp |
| 3057 | </pre> |
| 3058 | |
| 3059 | <p> |
| 3060 | yields a function value of type |
| 3061 | </p> |
| 3062 | |
| 3063 | <pre> |
| 3064 | func(float32) float32 |
| 3065 | </pre> |
| 3066 | |
| 3067 | <p> |
| 3068 | As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver |
| 3069 | using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>. |
| 3070 | </p> |
| 3071 | |
| 3072 | <p> |
| 3073 | As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver |
| 3074 | using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>. |
| 3075 | </p> |
| 3076 | |
| 3077 | <pre> |
| 3078 | f := t.Mv; f(7) // like t.Mv(7) |
| 3079 | f := pt.Mp; f(7) // like pt.Mp(7) |
| 3080 | f := pt.Mv; f(7) // like (*pt).Mv(7) |
| 3081 | f := t.Mp; f(7) // like (&t).Mp(7) |
| 3082 | f := makeT().Mp // invalid: result of makeT() is not addressable |
| 3083 | </pre> |
| 3084 | |
| 3085 | <p> |
| 3086 | Although the examples above use non-interface types, it is also legal to create a method value |
| 3087 | from a value of interface type. |
| 3088 | </p> |
| 3089 | |
| 3090 | <pre> |
| 3091 | var i interface { M(int) } = myVal |
| 3092 | f := i.M; f(7) // like i.M(7) |
| 3093 | </pre> |
| 3094 | |
| 3095 | |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 3096 | <h3 id="Index_expressions">Index expressions</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3097 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3098 | <p> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 3099 | A primary expression of the form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3100 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3101 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3102 | <pre> |
| 3103 | a[x] |
| 3104 | </pre> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 3105 | |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3106 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3107 | denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>. |
| 3108 | The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively. |
| 3109 | The following rules apply: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3110 | </p> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3111 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3112 | <p> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 3113 | If <code>a</code> is not a map: |
| 3114 | </p> |
| 3115 | <ul> |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 3116 | <li>the index <code>x</code> must be of integer type or an untyped constant</li> |
| 3117 | <li>a constant index must be non-negative and |
| 3118 | <a href="#Representability">representable</a> by a value of type <code>int</code></li> |
| 3119 | <li>a constant index that is untyped is given type <code>int</code></li> |
| 3120 | <li>the index <code>x</code> is <i>in range</i> if <code>0 <= x < len(a)</code>, |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 3121 | otherwise it is <i>out of range</i></li> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 3122 | </ul> |
| 3123 | |
| 3124 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3125 | For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3126 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3127 | <ul> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3128 | <li>a <a href="#Constants">constant</a> index must be in range</li> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3129 | <li>if <code>x</code> is out of range at run time, |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3130 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3131 | <li><code>a[x]</code> is the array element at index <code>x</code> and the type of |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3132 | <code>a[x]</code> is the element type of <code>A</code></li> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3133 | </ul> |
| 3134 | |
| 3135 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3136 | For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type: |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3137 | </p> |
| 3138 | <ul> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3139 | <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li> |
| 3140 | </ul> |
| 3141 | |
| 3142 | <p> |
| 3143 | For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>: |
| 3144 | </p> |
| 3145 | <ul> |
| 3146 | <li>if <code>x</code> is out of range at run time, |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3147 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
| 3148 | <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3149 | <code>a[x]</code> is the element type of <code>S</code></li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3150 | </ul> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3151 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3152 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3153 | For <code>a</code> of <a href="#String_types">string type</a>: |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3154 | </p> |
| 3155 | <ul> |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 3156 | <li>a <a href="#Constants">constant</a> index must be in range |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3157 | if the string <code>a</code> is also constant</li> |
| 3158 | <li>if <code>x</code> is out of range at run time, |
| 3159 | a <a href="#Run_time_panics">run-time panic</a> occurs</li> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3160 | <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3161 | <code>a[x]</code> is <code>byte</code></li> |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 3162 | <li><code>a[x]</code> may not be assigned to</li> |
Russ Cox | eaa92e0 | 2009-06-25 14:43:55 -0700 | [diff] [blame] | 3163 | </ul> |
| 3164 | |
| 3165 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3166 | For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3167 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3168 | <ul> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3169 | <li><code>x</code>'s type must be |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3170 | <a href="#Assignability">assignable</a> |
| 3171 | to the key type of <code>M</code></li> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3172 | <li>if the map contains an entry with key <code>x</code>, |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 3173 | <code>a[x]</code> is the map element with key <code>x</code> |
| 3174 | and the type of <code>a[x]</code> is the element type of <code>M</code></li> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 3175 | <li>if the map is <code>nil</code> or does not contain such an entry, |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 3176 | <code>a[x]</code> is the <a href="#The_zero_value">zero value</a> |
Robert Griesemer | 4de1d1d | 2018-01-03 10:33:11 -0800 | [diff] [blame] | 3177 | for the element type of <code>M</code></li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3178 | </ul> |
Robert Griesemer | bbfe312 | 2008-10-09 17:12:09 -0700 | [diff] [blame] | 3179 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3180 | <p> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3181 | Otherwise <code>a[x]</code> is illegal. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3182 | </p> |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 3183 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3184 | <p> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3185 | An index expression on a map <code>a</code> of type <code>map[K]V</code> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3186 | used in an <a href="#Assignments">assignment</a> or initialization of the special form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3187 | </p> |
| 3188 | |
| 3189 | <pre> |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3190 | v, ok = a[x] |
| 3191 | v, ok := a[x] |
| 3192 | var v, ok = a[x] |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3193 | </pre> |
| 3194 | |
| 3195 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3196 | yields an additional untyped boolean value. The value of <code>ok</code> is |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3197 | <code>true</code> if the key <code>x</code> is present in the map, and |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3198 | <code>false</code> otherwise. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3199 | </p> |
| 3200 | |
| 3201 | <p> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 3202 | Assigning to an element of a <code>nil</code> map causes a |
| 3203 | <a href="#Run_time_panics">run-time panic</a>. |
| 3204 | </p> |
| 3205 | |
Robert Griesemer | 29f1ca5 | 2010-03-23 14:01:51 -0700 | [diff] [blame] | 3206 | |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3207 | <h3 id="Slice_expressions">Slice expressions</h3> |
| 3208 | |
| 3209 | <p> |
| 3210 | Slice expressions construct a substring or slice from a string, array, pointer |
| 3211 | to array, or slice. There are two variants: a simple form that specifies a low |
| 3212 | and high bound, and a full form that also specifies a bound on the capacity. |
| 3213 | </p> |
| 3214 | |
| 3215 | <h4>Simple slice expressions</h4> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3216 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3217 | <p> |
Russ Cox | 8a8445b | 2011-12-02 13:11:30 -0500 | [diff] [blame] | 3218 | For a string, array, pointer to array, or slice <code>a</code>, the primary expression |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3219 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3220 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3221 | <pre> |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3222 | a[low : high] |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3223 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3224 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3225 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3226 | constructs a substring or slice. The <i>indices</i> <code>low</code> and |
| 3227 | <code>high</code> select which elements of operand <code>a</code> appear |
| 3228 | in the result. The result has indices starting at 0 and length equal to |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3229 | <code>high</code> - <code>low</code>. |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3230 | After slicing the array <code>a</code> |
| 3231 | </p> |
| 3232 | |
| 3233 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3234 | a := [5]int{1, 2, 3, 4, 5} |
| 3235 | s := a[1:4] |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3236 | </pre> |
| 3237 | |
| 3238 | <p> |
| 3239 | the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3240 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3241 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3242 | <pre> |
| 3243 | s[0] == 2 |
| 3244 | s[1] == 3 |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3245 | s[2] == 4 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3246 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3247 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3248 | <p> |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 3249 | For convenience, any of the indices may be omitted. A missing <code>low</code> |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3250 | index defaults to zero; a missing <code>high</code> index defaults to the length of the |
| 3251 | sliced operand: |
Scott Lawrence | 0c1695b | 2010-09-07 14:30:17 -0700 | [diff] [blame] | 3252 | </p> |
| 3253 | |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3254 | <pre> |
Robert Hencke | 58d18e2 | 2013-10-03 12:46:02 -0700 | [diff] [blame] | 3255 | a[2:] // same as a[2 : len(a)] |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 3256 | a[:3] // same as a[0 : 3] |
| 3257 | a[:] // same as a[0 : len(a)] |
Robert Griesemer | 9e5bf27 | 2010-09-07 16:32:35 -0700 | [diff] [blame] | 3258 | </pre> |
| 3259 | |
Scott Lawrence | 0c1695b | 2010-09-07 14:30:17 -0700 | [diff] [blame] | 3260 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3261 | If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for |
| 3262 | <code>(*a)[low : high]</code>. |
| 3263 | </p> |
| 3264 | |
| 3265 | <p> |
| 3266 | For arrays or strings, the indices are <i>in range</i> if |
| 3267 | <code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>, |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3268 | otherwise they are <i>out of range</i>. |
| 3269 | For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length. |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 3270 | A <a href="#Constants">constant</a> index must be non-negative and |
| 3271 | <a href="#Representability">representable</a> by a value of type |
Robert Griesemer | 6ffd235 | 2014-03-06 17:11:13 -0800 | [diff] [blame] | 3272 | <code>int</code>; for arrays or constant strings, constant indices must also be in range. |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3273 | If both indices are constant, they must satisfy <code>low <= high</code>. |
| 3274 | If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3275 | </p> |
| 3276 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3277 | <p> |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3278 | Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice, |
| 3279 | the result of the slice operation is a non-constant value of the same type as the operand. |
| 3280 | For untyped string operands the result is a non-constant value of type <code>string</code>. |
Robert Griesemer | c423e95 | 2010-09-02 10:16:31 -0700 | [diff] [blame] | 3281 | If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a> |
| 3282 | and the result of the slice operation is a slice with the same element type as the array. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3283 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3284 | |
Robert Griesemer | 2961d22 | 2013-07-31 22:25:47 -0700 | [diff] [blame] | 3285 | <p> |
| 3286 | If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result |
griesemer | 2ac43d5 | 2017-08-29 15:48:07 +0200 | [diff] [blame] | 3287 | is a <code>nil</code> slice. Otherwise, if the result is a slice, it shares its underlying |
| 3288 | array with the operand. |
Rob Pike | 15e6ce2 | 2013-08-15 13:15:55 +1000 | [diff] [blame] | 3289 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3290 | |
Robert Griesemer | 1e3ffb0 | 2019-05-14 10:22:04 -0700 | [diff] [blame] | 3291 | <pre> |
| 3292 | var a [10]int |
Rob Pike | cae9a9f | 2020-01-13 16:03:12 +1100 | [diff] [blame] | 3293 | s1 := a[3:7] // underlying array of s1 is array a; &s1[2] == &a[5] |
| 3294 | s2 := s1[1:4] // underlying array of s2 is underlying array of s1 which is array a; &s2[1] == &a[5] |
Robert Griesemer | 1e3ffb0 | 2019-05-14 10:22:04 -0700 | [diff] [blame] | 3295 | s2[1] = 42 // s2[1] == s1[2] == a[5] == 42; they all refer to the same underlying array element |
| 3296 | </pre> |
| 3297 | |
| 3298 | |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3299 | <h4>Full slice expressions</h4> |
| 3300 | |
| 3301 | <p> |
| 3302 | For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression |
| 3303 | </p> |
| 3304 | |
| 3305 | <pre> |
| 3306 | a[low : high : max] |
| 3307 | </pre> |
| 3308 | |
| 3309 | <p> |
| 3310 | constructs a slice of the same type, and with the same length and elements as the simple slice |
| 3311 | expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity |
| 3312 | by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0. |
| 3313 | After slicing the array <code>a</code> |
| 3314 | </p> |
| 3315 | |
| 3316 | <pre> |
| 3317 | a := [5]int{1, 2, 3, 4, 5} |
| 3318 | t := a[1:3:5] |
| 3319 | </pre> |
| 3320 | |
| 3321 | <p> |
| 3322 | the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements |
| 3323 | </p> |
| 3324 | |
| 3325 | <pre> |
| 3326 | t[0] == 2 |
| 3327 | t[1] == 3 |
| 3328 | </pre> |
| 3329 | |
| 3330 | <p> |
| 3331 | As for simple slice expressions, if <code>a</code> is a pointer to an array, |
| 3332 | <code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>. |
| 3333 | If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>. |
| 3334 | </p> |
| 3335 | |
| 3336 | <p> |
| 3337 | The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>, |
| 3338 | otherwise they are <i>out of range</i>. |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 3339 | A <a href="#Constants">constant</a> index must be non-negative and |
| 3340 | <a href="#Representability">representable</a> by a value of type |
Robert Griesemer | 6ffd235 | 2014-03-06 17:11:13 -0800 | [diff] [blame] | 3341 | <code>int</code>; for arrays, constant indices must also be in range. |
Robert Griesemer | e333b96 | 2013-09-11 17:18:52 -0700 | [diff] [blame] | 3342 | If multiple indices are constant, the constants that are present must be in range relative to each |
| 3343 | other. |
| 3344 | If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
| 3345 | </p> |
| 3346 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3347 | <h3 id="Type_assertions">Type assertions</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3348 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3349 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3350 | For an expression <code>x</code> of <a href="#Interface_types">interface type</a> |
| 3351 | and a type <code>T</code>, the primary expression |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3352 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3353 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3354 | <pre> |
| 3355 | x.(T) |
| 3356 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3357 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3358 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3359 | asserts that <code>x</code> is not <code>nil</code> |
Russ Cox | b89a54e | 2009-05-20 18:16:04 -0700 | [diff] [blame] | 3360 | and that the value stored in <code>x</code> is of type <code>T</code>. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3361 | The notation <code>x.(T)</code> is called a <i>type assertion</i>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3362 | </p> |
| 3363 | <p> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3364 | More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3365 | that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a> |
| 3366 | to the type <code>T</code>. |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3367 | In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>; |
| 3368 | otherwise the type assertion is invalid since it is not possible for <code>x</code> |
| 3369 | to store a value of type <code>T</code>. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3370 | If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3371 | of <code>x</code> implements the interface <code>T</code>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3372 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3373 | <p> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 3374 | If the type assertion holds, the value of the expression is the value |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 3375 | stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false, |
| 3376 | a <a href="#Run_time_panics">run-time panic</a> occurs. |
| 3377 | In other words, even though the dynamic type of <code>x</code> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 3378 | is known only at run time, the type of <code>x.(T)</code> is |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3379 | known to be <code>T</code> in a correct program. |
| 3380 | </p> |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3381 | |
| 3382 | <pre> |
Robert Griesemer | 023bb03 | 2016-10-19 09:56:53 -0700 | [diff] [blame] | 3383 | var x interface{} = 7 // x has dynamic type int and value 7 |
| 3384 | i := x.(int) // i has type int and value 7 |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3385 | |
| 3386 | type I interface { m() } |
Robert Griesemer | 023bb03 | 2016-10-19 09:56:53 -0700 | [diff] [blame] | 3387 | |
| 3388 | func f(y I) { |
| 3389 | s := y.(string) // illegal: string does not implement I (missing method m) |
| 3390 | r := y.(io.Reader) // r has type io.Reader and the dynamic type of y must implement both I and io.Reader |
| 3391 | … |
| 3392 | } |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 3393 | </pre> |
| 3394 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3395 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3396 | A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3397 | </p> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3398 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3399 | <pre> |
| 3400 | v, ok = x.(T) |
| 3401 | v, ok := x.(T) |
Rob Pike | d553707 | 2009-08-22 00:04:04 -0700 | [diff] [blame] | 3402 | var v, ok = x.(T) |
Robert Griesemer | 507051d | 2016-08-24 11:33:55 -0700 | [diff] [blame] | 3403 | var v, ok T1 = x.(T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3404 | </pre> |
Robert Griesemer | 434c605 | 2008-11-07 13:34:37 -0800 | [diff] [blame] | 3405 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3406 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 3407 | yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code> |
| 3408 | if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is |
| 3409 | the <a href="#The_zero_value">zero value</a> for type <code>T</code>. |
Robert Griesemer | 1e38ecd | 2018-10-23 14:54:59 -0700 | [diff] [blame] | 3410 | No <a href="#Run_time_panics">run-time panic</a> occurs in this case. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3411 | </p> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 3412 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3413 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3414 | <h3 id="Calls">Calls</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3415 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3416 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 3417 | Given an expression <code>f</code> of function type |
| 3418 | <code>F</code>, |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3419 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3420 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3421 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3422 | f(a1, a2, … an) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3423 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3424 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3425 | <p> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3426 | calls <code>f</code> with arguments <code>a1, a2, … an</code>. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3427 | Except for one special case, arguments must be single-valued expressions |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3428 | <a href="#Assignability">assignable</a> to the parameter types of |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3429 | <code>F</code> and are evaluated before the function is called. |
| 3430 | The type of the expression is the result type |
| 3431 | of <code>F</code>. |
| 3432 | A method invocation is similar but the method itself |
| 3433 | is specified as a selector upon a value of the receiver type for |
| 3434 | the method. |
| 3435 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3436 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3437 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 3438 | math.Atan2(x, y) // function call |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3439 | var pt *Point |
Robert Griesemer | ccc713c | 2014-10-27 16:31:15 -0700 | [diff] [blame] | 3440 | pt.Scale(3.5) // method call with receiver pt |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3441 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3442 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3443 | <p> |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3444 | In a function call, the function value and arguments are evaluated in |
| 3445 | <a href="#Order_of_evaluation">the usual order</a>. |
| 3446 | After they are evaluated, the parameters of the call are passed by value to the function |
| 3447 | and the called function begins execution. |
| 3448 | The return parameters of the function are passed by value |
| 3449 | back to the calling function when the function returns. |
| 3450 | </p> |
| 3451 | |
| 3452 | <p> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3453 | Calling a <code>nil</code> function value |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3454 | causes a <a href="#Run_time_panics">run-time panic</a>. |
| 3455 | </p> |
| 3456 | |
| 3457 | <p> |
Russ Cox | 1b3083e | 2013-02-09 14:46:55 -0500 | [diff] [blame] | 3458 | As a special case, if the return values of a function or method |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3459 | <code>g</code> are equal in number and individually |
| 3460 | assignable to the parameters of another function or method |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3461 | <code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code> |
| 3462 | will invoke <code>f</code> after binding the return values of |
| 3463 | <code>g</code> to the parameters of <code>f</code> in order. The call |
Russ Cox | 1b3083e | 2013-02-09 14:46:55 -0500 | [diff] [blame] | 3464 | of <code>f</code> must contain no parameters other than the call of <code>g</code>, |
| 3465 | and <code>g</code> must have at least one return value. |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3466 | If <code>f</code> has a final <code>...</code> parameter, it is |
| 3467 | assigned the return values of <code>g</code> that remain after |
| 3468 | assignment of regular parameters. |
| 3469 | </p> |
| 3470 | |
| 3471 | <pre> |
| 3472 | func Split(s string, pos int) (string, string) { |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 3473 | return s[0:pos], s[pos:] |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3474 | } |
| 3475 | |
| 3476 | func Join(s, t string) string { |
| 3477 | return s + t |
| 3478 | } |
| 3479 | |
| 3480 | if Join(Split(value, len(value)/2)) != value { |
Robert Griesemer | 7fc4e37 | 2011-02-01 12:51:10 -0800 | [diff] [blame] | 3481 | log.Panic("test fails") |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 3482 | } |
| 3483 | </pre> |
| 3484 | |
| 3485 | <p> |
Robert Griesemer | 2a838d6 | 2011-02-08 13:31:01 -0800 | [diff] [blame] | 3486 | A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a> |
| 3487 | of (the type of) <code>x</code> contains <code>m</code> and the |
Robert Griesemer | 63f0149 | 2010-05-28 14:17:30 -0700 | [diff] [blame] | 3488 | argument list can be assigned to the parameter list of <code>m</code>. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 3489 | If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method |
Robert Griesemer | 56809d0 | 2009-05-20 11:02:48 -0700 | [diff] [blame] | 3490 | set contains <code>m</code>, <code>x.m()</code> is shorthand |
| 3491 | for <code>(&x).m()</code>: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3492 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3493 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3494 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3495 | var p Point |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3496 | p.Scale(3.5) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3497 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3498 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3499 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3500 | There is no distinct method type and there are no method literals. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3501 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3502 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3503 | <h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3504 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3505 | <p> |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3506 | If <code>f</code> is <a href="#Function_types">variadic</a> with a final |
| 3507 | parameter <code>p</code> of type <code>...T</code>, then within <code>f</code> |
| 3508 | the type of <code>p</code> is equivalent to type <code>[]T</code>. |
| 3509 | If <code>f</code> is invoked with no actual arguments for <code>p</code>, |
| 3510 | the value passed to <code>p</code> is <code>nil</code>. |
| 3511 | Otherwise, the value passed is a new slice |
| 3512 | of type <code>[]T</code> with a new underlying array whose successive elements |
| 3513 | are the actual arguments, which all must be <a href="#Assignability">assignable</a> |
| 3514 | to <code>T</code>. The length and capacity of the slice is therefore |
| 3515 | the number of arguments bound to <code>p</code> and may differ for each |
| 3516 | call site. |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3517 | </p> |
Robert Griesemer | 69e26bf | 2008-11-04 16:46:45 -0800 | [diff] [blame] | 3518 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3519 | <p> |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3520 | Given the function and calls |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3521 | </p> |
| 3522 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 3523 | func Greeting(prefix string, who ...string) |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3524 | Greeting("nobody") |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3525 | Greeting("hello:", "Joe", "Anna", "Eileen") |
| 3526 | </pre> |
| 3527 | |
| 3528 | <p> |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3529 | within <code>Greeting</code>, <code>who</code> will have the value |
Robert Griesemer | a766277 | 2014-03-06 10:35:05 -0800 | [diff] [blame] | 3530 | <code>nil</code> in the first call, and |
| 3531 | <code>[]string{"Joe", "Anna", "Eileen"}</code> in the second. |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3532 | </p> |
| 3533 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3534 | <p> |
Robert Griesemer | 1024b25 | 2019-03-13 09:48:33 -0700 | [diff] [blame] | 3535 | If the final argument is assignable to a slice type <code>[]T</code>, it is |
Robert Griesemer | 904adfd | 2010-10-27 10:44:31 -0700 | [diff] [blame] | 3536 | passed unchanged as the value for a <code>...T</code> parameter if the argument |
| 3537 | is followed by <code>...</code>. In this case no new slice is created. |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3538 | </p> |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3539 | |
| 3540 | <p> |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3541 | Given the slice <code>s</code> and call |
Rob Pike | b81065d | 2010-01-27 13:14:40 -0800 | [diff] [blame] | 3542 | </p> |
Robert Griesemer | 69e26bf | 2008-11-04 16:46:45 -0800 | [diff] [blame] | 3543 | |
Robert Griesemer | ac771a8 | 2010-09-24 14:08:28 -0700 | [diff] [blame] | 3544 | <pre> |
| 3545 | s := []string{"James", "Jasmine"} |
| 3546 | Greeting("goodbye:", s...) |
| 3547 | </pre> |
| 3548 | |
| 3549 | <p> |
| 3550 | within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code> |
| 3551 | with the same underlying array. |
| 3552 | </p> |
| 3553 | |
| 3554 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3555 | <h3 id="Operators">Operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3556 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3557 | <p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3558 | Operators combine operands into expressions. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3559 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3560 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 3561 | <pre class="ebnf"> |
Matthew Dempsky | abb818b | 2015-04-20 17:17:24 -0700 | [diff] [blame] | 3562 | Expression = UnaryExpr | Expression binary_op Expression . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3563 | UnaryExpr = PrimaryExpr | unary_op UnaryExpr . |
Robert Griesemer | 57b3461 | 2008-10-10 12:45:44 -0700 | [diff] [blame] | 3564 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3565 | binary_op = "||" | "&&" | rel_op | add_op | mul_op . |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3566 | rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . |
| 3567 | add_op = "+" | "-" | "|" | "^" . |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3568 | mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" . |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3569 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3570 | unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3571 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3572 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3573 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3574 | Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3575 | For other binary operators, the operand types must be <a href="#Type_identity">identical</a> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3576 | unless the operation involves shifts or untyped <a href="#Constants">constants</a>. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3577 | For operations involving constants only, see the section on |
| 3578 | <a href="#Constant_expressions">constant expressions</a>. |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 3579 | </p> |
Robert Griesemer | c8e1876 | 2008-09-12 12:26:22 -0700 | [diff] [blame] | 3580 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3581 | <p> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3582 | Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3583 | and the other operand is not, the constant is implicitly <a href="#Conversions">converted</a> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3584 | to the type of the other operand. |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3585 | </p> |
Robert Griesemer | 7539c85 | 2009-07-31 18:05:07 -0700 | [diff] [blame] | 3586 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3587 | <p> |
Robert Griesemer | a10b4cf | 2019-02-05 14:33:24 -0800 | [diff] [blame] | 3588 | The right operand in a shift expression must have integer type |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 3589 | or be an untyped constant <a href="#Representability">representable</a> by a |
| 3590 | value of type <code>uint</code>. |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3591 | If the left operand of a non-constant shift expression is an untyped constant, |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3592 | it is first implicitly converted to the type it would assume if the shift expression were |
Robert Griesemer | 58e21dd | 2013-03-15 13:55:50 -0700 | [diff] [blame] | 3593 | replaced by its left operand alone. |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3594 | </p> |
Robert Griesemer | a6b546f | 2008-10-20 11:46:40 -0700 | [diff] [blame] | 3595 | |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3596 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 3597 | var s uint = 33 |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 3598 | var i = 1<<s // 1 has type int |
| 3599 | var j int32 = 1<<s // 1 has type int32; j == 0 |
| 3600 | var k = uint64(1<<s) // 1 has type uint64; k == 1<<33 |
| 3601 | var m int = 1.0<<s // 1.0 has type int; m == 0 if ints are 32bits in size |
| 3602 | var n = 1.0<<s == j // 1.0 has type int32; n == true |
| 3603 | var o = 1<<s == 2<<s // 1 and 2 have type int; o == true if ints are 32bits in size |
| 3604 | var p = 1<<s == 1<<33 // illegal if ints are 32bits in size: 1 has type int, but 1<<33 overflows int |
| 3605 | var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift |
| 3606 | var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift |
| 3607 | var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift |
| 3608 | var v float32 = 1<<s // illegal: 1 has type float32, cannot shift |
| 3609 | var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression |
| 3610 | var x = a[1.0<<s] // 1.0 has type int; x == a[0] if ints are 32bits in size |
| 3611 | var a = make([]byte, 1.0<<s) // 1.0 has type int; len(a) == 0 if ints are 32bits in size |
Rob Pike | 83cbca5 | 2009-08-21 14:18:08 -0700 | [diff] [blame] | 3612 | </pre> |
Robert Griesemer | 18b05c1 | 2009-01-26 09:34:19 -0800 | [diff] [blame] | 3613 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3614 | |
| 3615 | <h4 id="Operator_precedence">Operator precedence</h4> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3616 | <p> |
Russ Cox | ec9b042 | 2009-07-09 16:44:13 -0700 | [diff] [blame] | 3617 | Unary operators have the highest precedence. |
| 3618 | As the <code>++</code> and <code>--</code> operators form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3619 | statements, not expressions, they fall |
Russ Cox | ec9b042 | 2009-07-09 16:44:13 -0700 | [diff] [blame] | 3620 | outside the operator hierarchy. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3621 | As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>. |
| 3622 | <p> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3623 | There are five precedence levels for binary operators. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3624 | Multiplication operators bind strongest, followed by addition |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3625 | operators, comparison operators, <code>&&</code> (logical AND), |
| 3626 | and finally <code>||</code> (logical OR): |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3627 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3628 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3629 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3630 | Precedence Operator |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 3631 | 5 * / % << >> & &^ |
| 3632 | 4 + - | ^ |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 3633 | 3 == != < <= > >= |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3634 | 2 && |
| 3635 | 1 || |
| 3636 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3637 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3638 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3639 | Binary operators of the same precedence associate from left to right. |
Robert Griesemer | d36d191 | 2009-09-18 11:58:35 -0700 | [diff] [blame] | 3640 | For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3641 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3642 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3643 | <pre> |
| 3644 | +x |
| 3645 | 23 + 3*x[i] |
| 3646 | x <= f() |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3647 | ^a >> b |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3648 | f() || g() |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3649 | x == y+1 && <-chanPtr > 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3650 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3651 | |
| 3652 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3653 | <h3 id="Arithmetic_operators">Arithmetic operators</h3> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3654 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3655 | Arithmetic operators apply to numeric values and yield a result of the same |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3656 | type as the first operand. The four standard arithmetic operators (<code>+</code>, |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3657 | <code>-</code>, <code>*</code>, <code>/</code>) apply to integer, |
| 3658 | floating-point, and complex types; <code>+</code> also applies to strings. |
| 3659 | The bitwise logical and shift operators apply to integers only. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3660 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3661 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3662 | <pre class="grammar"> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 3663 | + sum integers, floats, complex values, strings |
| 3664 | - difference integers, floats, complex values |
| 3665 | * product integers, floats, complex values |
| 3666 | / quotient integers, floats, complex values |
Rob Pike | 307ec21 | 2009-03-12 15:53:56 -0700 | [diff] [blame] | 3667 | % remainder integers |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3668 | |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3669 | & bitwise AND integers |
| 3670 | | bitwise OR integers |
| 3671 | ^ bitwise XOR integers |
| 3672 | &^ bit clear (AND NOT) integers |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3673 | |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3674 | << left shift integer << unsigned integer |
| 3675 | >> right shift integer >> unsigned integer |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3676 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3677 | |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3678 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3679 | <h4 id="Integer_operators">Integer operators</h4> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3680 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3681 | <p> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3682 | For two integer values <code>x</code> and <code>y</code>, the integer quotient |
| 3683 | <code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following |
| 3684 | relationships: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3685 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3686 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3687 | <pre> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3688 | x = q*y + r and |r| < |y| |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3689 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3690 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3691 | <p> |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3692 | with <code>x / y</code> truncated towards zero |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 3693 | (<a href="https://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>). |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3694 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3695 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3696 | <pre> |
| 3697 | x y x / y x % y |
| 3698 | 5 3 1 2 |
| 3699 | -5 3 -1 -2 |
| 3700 | 5 -3 -1 2 |
| 3701 | -5 -3 1 -2 |
| 3702 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3703 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3704 | <p> |
Robert Griesemer | 18d527b | 2018-01-16 21:30:46 -0800 | [diff] [blame] | 3705 | The one exception to this rule is that if the dividend <code>x</code> is |
| 3706 | the most negative value for the int type of <code>x</code>, the quotient |
| 3707 | <code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>) |
| 3708 | due to two's-complement <a href="#Integer_overflow">integer overflow</a>: |
Robert Griesemer | bb7eb40 | 2011-05-02 17:23:18 -0700 | [diff] [blame] | 3709 | </p> |
| 3710 | |
| 3711 | <pre> |
| 3712 | x, q |
| 3713 | int8 -128 |
| 3714 | int16 -32768 |
| 3715 | int32 -2147483648 |
| 3716 | int64 -9223372036854775808 |
| 3717 | </pre> |
| 3718 | |
| 3719 | <p> |
Robert Griesemer | ddddd39 | 2012-10-19 10:12:09 -0700 | [diff] [blame] | 3720 | If the divisor is a <a href="#Constants">constant</a>, it must not be zero. |
| 3721 | If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs. |
Matthew Dempsky | 80a87a9 | 2013-01-06 16:56:06 -0800 | [diff] [blame] | 3722 | If the dividend is non-negative and the divisor is a constant power of 2, |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 3723 | the division may be replaced by a right shift, and computing the remainder may |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3724 | be replaced by a bitwise AND operation: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3725 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3726 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3727 | <pre> |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3728 | x x / 4 x % 4 x >> 2 x & 3 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3729 | 11 2 3 2 3 |
| 3730 | -11 -2 -3 -3 1 |
| 3731 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3732 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3733 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3734 | The shift operators shift the left operand by the shift count specified by the |
Robert Griesemer | 6fcc2d8 | 2019-09-04 08:42:12 -0700 | [diff] [blame] | 3735 | right operand, which must be non-negative. If the shift count is negative at run time, |
Robert Griesemer | a10b4cf | 2019-02-05 14:33:24 -0800 | [diff] [blame] | 3736 | a <a href="#Run_time_panics">run-time panic</a> occurs. |
| 3737 | The shift operators implement arithmetic shifts if the left operand is a signed |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 3738 | integer and logical shifts if it is an unsigned integer. |
| 3739 | There is no upper limit on the shift count. Shifts behave |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3740 | as if the left operand is shifted <code>n</code> times by 1 for a shift |
| 3741 | count of <code>n</code>. |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 3742 | As a result, <code>x << 1</code> is the same as <code>x*2</code> |
| 3743 | and <code>x >> 1</code> is the same as |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 3744 | <code>x/2</code> but truncated towards negative infinity. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3745 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3746 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3747 | <p> |
| 3748 | For integer operands, the unary operators |
| 3749 | <code>+</code>, <code>-</code>, and <code>^</code> are defined as |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3750 | follows: |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3751 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3752 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3753 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3754 | +x is 0 + x |
| 3755 | -x negation is 0 - x |
Russ Cox | d83dc4f | 2009-05-29 16:04:16 -0700 | [diff] [blame] | 3756 | ^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x |
| 3757 | and m = -1 for signed x |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3758 | </pre> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3759 | |
| 3760 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3761 | <h4 id="Integer_overflow">Integer overflow</h4> |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3762 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3763 | <p> |
| 3764 | For unsigned integer values, the operations <code>+</code>, |
| 3765 | <code>-</code>, <code>*</code>, and <code><<</code> are |
| 3766 | computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 3767 | the <a href="#Numeric_types">unsigned integer</a>'s type. |
| 3768 | Loosely speaking, these unsigned integer operations |
Robert Griesemer | 8c916a2 | 2018-01-09 12:42:28 -0800 | [diff] [blame] | 3769 | discard high bits upon overflow, and programs may rely on "wrap around". |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3770 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3771 | <p> |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3772 | For signed integers, the operations <code>+</code>, |
Robert Griesemer | 18d527b | 2018-01-16 21:30:46 -0800 | [diff] [blame] | 3773 | <code>-</code>, <code>*</code>, <code>/</code>, and <code><<</code> may legally |
Robert Griesemer | 9dfb2ea | 2008-12-12 10:30:10 -0800 | [diff] [blame] | 3774 | overflow and the resulting value exists and is deterministically defined |
| 3775 | by the signed integer representation, the operation, and its operands. |
Russ Cox | b7ba523 | 2018-11-13 10:23:01 -0500 | [diff] [blame] | 3776 | Overflow does not cause a <a href="#Run_time_panics">run-time panic</a>. |
Robert Griesemer | 18d527b | 2018-01-16 21:30:46 -0800 | [diff] [blame] | 3777 | A compiler may not optimize code under the assumption that overflow does |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3778 | not occur. For instance, it may not assume that <code>x < x + 1</code> is always true. |
| 3779 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3780 | |
| 3781 | |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3782 | <h4 id="Floating_point_operators">Floating-point operators</h4> |
| 3783 | |
| 3784 | <p> |
| 3785 | For floating-point and complex numbers, |
| 3786 | <code>+x</code> is the same as <code>x</code>, |
| 3787 | while <code>-x</code> is the negation of <code>x</code>. |
| 3788 | The result of a floating-point or complex division by zero is not specified beyond the |
| 3789 | IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a> |
| 3790 | occurs is implementation-specific. |
| 3791 | </p> |
| 3792 | |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3793 | <p> |
| 3794 | An implementation may combine multiple floating-point operations into a single |
| 3795 | fused operation, possibly across statements, and produce a result that differs |
| 3796 | from the value obtained by executing and rounding the instructions individually. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 3797 | An explicit floating-point type <a href="#Conversions">conversion</a> rounds to |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3798 | the precision of the target type, preventing fusion that would discard that rounding. |
| 3799 | </p> |
| 3800 | |
| 3801 | <p> |
| 3802 | For instance, some architectures provide a "fused multiply and add" (FMA) instruction |
| 3803 | that computes <code>x*y + z</code> without rounding the intermediate result <code>x*y</code>. |
| 3804 | These examples show when a Go implementation can use that instruction: |
| 3805 | </p> |
| 3806 | |
| 3807 | <pre> |
| 3808 | // FMA allowed for computing r, because x*y is not explicitly rounded: |
| 3809 | r = x*y + z |
| 3810 | r = z; r += x*y |
| 3811 | t = x*y; r = t + z |
| 3812 | *p = x*y; r = *p + z |
| 3813 | r = x*y + float64(z) |
| 3814 | |
| 3815 | // FMA disallowed for computing r, because it would omit rounding of x*y: |
| 3816 | r = float64(x*y) + z |
| 3817 | r = z; r += float64(x*y) |
| 3818 | t = float64(x*y); r = t + z |
| 3819 | </pre> |
Robert Griesemer | 3dd3ab4 | 2015-08-04 15:04:39 -0700 | [diff] [blame] | 3820 | |
| 3821 | <h4 id="String_concatenation">String concatenation</h4> |
| 3822 | |
| 3823 | <p> |
| 3824 | Strings can be concatenated using the <code>+</code> operator |
| 3825 | or the <code>+=</code> assignment operator: |
| 3826 | </p> |
| 3827 | |
| 3828 | <pre> |
| 3829 | s := "hi" + string(c) |
| 3830 | s += " and good bye" |
| 3831 | </pre> |
| 3832 | |
| 3833 | <p> |
| 3834 | String addition creates a new string by concatenating the operands. |
| 3835 | </p> |
| 3836 | |
| 3837 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3838 | <h3 id="Comparison_operators">Comparison operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3839 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3840 | <p> |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3841 | Comparison operators compare two operands and yield an untyped boolean value. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3842 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3843 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3844 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3845 | == equal |
| 3846 | != not equal |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 3847 | < less |
| 3848 | <= less or equal |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3849 | > greater |
| 3850 | >= greater or equal |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3851 | </pre> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3852 | |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3853 | <p> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3854 | In any comparison, the first operand |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 3855 | must be <a href="#Assignability">assignable</a> |
| 3856 | to the type of the second operand, or vice versa. |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3857 | </p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 3858 | <p> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3859 | The equality operators <code>==</code> and <code>!=</code> apply |
| 3860 | to operands that are <i>comparable</i>. |
| 3861 | The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code> |
| 3862 | apply to operands that are <i>ordered</i>. |
| 3863 | These terms and the result of the comparisons are defined as follows: |
Rob Pike | 5af7de3 | 2009-02-24 15:17:59 -0800 | [diff] [blame] | 3864 | </p> |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3865 | |
| 3866 | <ul> |
| 3867 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3868 | Boolean values are comparable. |
| 3869 | Two boolean values are equal if they are either both |
| 3870 | <code>true</code> or both <code>false</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3871 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3872 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3873 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3874 | Integer values are comparable and ordered, in the usual way. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3875 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3876 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3877 | <li> |
Robert Griesemer | 94b6011 | 2017-04-11 13:39:24 -0700 | [diff] [blame] | 3878 | Floating-point values are comparable and ordered, |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3879 | as defined by the IEEE-754 standard. |
| 3880 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3881 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3882 | <li> |
| 3883 | Complex values are comparable. |
| 3884 | Two complex values <code>u</code> and <code>v</code> are |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3885 | equal if both <code>real(u) == real(v)</code> and |
| 3886 | <code>imag(u) == imag(v)</code>. |
| 3887 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3888 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3889 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3890 | String values are comparable and ordered, lexically byte-wise. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3891 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3892 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3893 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3894 | Pointer values are comparable. |
Robert Griesemer | 1320ce0 | 2012-01-09 16:54:24 -0800 | [diff] [blame] | 3895 | Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>. |
| 3896 | Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3897 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3898 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3899 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3900 | Channel values are comparable. |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 3901 | Two channel values are equal if they were created by the same call to |
| 3902 | <a href="#Making_slices_maps_and_channels"><code>make</code></a> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3903 | or if both have value <code>nil</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3904 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3905 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3906 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3907 | Interface values are comparable. |
| 3908 | Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types |
| 3909 | and equal dynamic values or if both have value <code>nil</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3910 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3911 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3912 | <li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3913 | A value <code>x</code> of non-interface type <code>X</code> and |
| 3914 | a value <code>t</code> of interface type <code>T</code> are comparable when values |
| 3915 | of type <code>X</code> are comparable and |
| 3916 | <code>X</code> implements <code>T</code>. |
| 3917 | They are equal if <code>t</code>'s dynamic type is identical to <code>X</code> |
| 3918 | and <code>t</code>'s dynamic value is equal to <code>x</code>. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3919 | </li> |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3920 | |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3921 | <li> |
Robert Griesemer | 3908467 | 2012-02-16 14:13:17 -0800 | [diff] [blame] | 3922 | Struct values are comparable if all their fields are comparable. |
| 3923 | Two struct values are equal if their corresponding |
| 3924 | non-<a href="#Blank_identifier">blank</a> fields are equal. |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3925 | </li> |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 3926 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3927 | <li> |
| 3928 | Array values are comparable if values of the array element type are comparable. |
| 3929 | Two array values are equal if their corresponding elements are equal. |
Robert Griesemer | 1d282a8 | 2010-06-03 16:55:50 -0700 | [diff] [blame] | 3930 | </li> |
| 3931 | </ul> |
Robert Griesemer | a329471 | 2009-01-05 11:17:26 -0800 | [diff] [blame] | 3932 | |
Russ Cox | 83f648c | 2011-12-12 22:21:46 -0500 | [diff] [blame] | 3933 | <p> |
| 3934 | A comparison of two interface values with identical dynamic types |
| 3935 | causes a <a href="#Run_time_panics">run-time panic</a> if values |
| 3936 | of that type are not comparable. This behavior applies not only to direct interface |
| 3937 | value comparisons but also when comparing arrays of interface values |
| 3938 | or structs with interface-valued fields. |
| 3939 | </p> |
| 3940 | |
| 3941 | <p> |
| 3942 | Slice, map, and function values are not comparable. |
| 3943 | However, as a special case, a slice, map, or function value may |
| 3944 | be compared to the predeclared identifier <code>nil</code>. |
| 3945 | Comparison of pointer, channel, and interface values to <code>nil</code> |
| 3946 | is also allowed and follows from the general rules above. |
| 3947 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3948 | |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3949 | <pre> |
Matthew Dempsky | ff85f86 | 2015-10-20 15:05:22 -0700 | [diff] [blame] | 3950 | const c = 3 < 4 // c is the untyped boolean constant true |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3951 | |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3952 | type MyBool bool |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3953 | var x, y int |
| 3954 | var ( |
Matthew Dempsky | ff85f86 | 2015-10-20 15:05:22 -0700 | [diff] [blame] | 3955 | // The result of a comparison is an untyped boolean. |
Robert Griesemer | c729ed6 | 2013-03-11 09:16:29 -0700 | [diff] [blame] | 3956 | // The usual assignment rules apply. |
| 3957 | b3 = x == y // b3 has type bool |
| 3958 | b4 bool = x == y // b4 has type bool |
| 3959 | b5 MyBool = x == y // b5 has type MyBool |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 3960 | ) |
| 3961 | </pre> |
| 3962 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3963 | <h3 id="Logical_operators">Logical operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3964 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3965 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 3966 | Logical operators apply to <a href="#Boolean_types">boolean</a> values |
| 3967 | and yield a result of the same type as the operands. |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3968 | The right operand is evaluated conditionally. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3969 | </p> |
Robert Griesemer | 41d65ac | 2008-09-04 15:17:27 -0700 | [diff] [blame] | 3970 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 3971 | <pre class="grammar"> |
Russ Cox | 1b4e37a | 2012-09-12 12:05:24 -0400 | [diff] [blame] | 3972 | && conditional AND p && q is "if p then q else false" |
| 3973 | || conditional OR p || q is "if p then true else q" |
| 3974 | ! NOT !p is "not p" |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 3975 | </pre> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 3976 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3977 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 3978 | <h3 id="Address_operators">Address operators</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 3979 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 3980 | <p> |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3981 | For an operand <code>x</code> of type <code>T</code>, the address operation |
| 3982 | <code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>. |
| 3983 | The operand must be <i>addressable</i>, |
Russ Cox | e7561de | 2010-05-24 14:31:43 -0700 | [diff] [blame] | 3984 | that is, either a variable, pointer indirection, or slice indexing |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3985 | operation; or a field selector of an addressable struct operand; |
Russ Cox | e7561de | 2010-05-24 14:31:43 -0700 | [diff] [blame] | 3986 | or an array indexing operation of an addressable array. |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3987 | As an exception to the addressability requirement, <code>x</code> may also be a |
Robert Griesemer | 614b02d | 2013-01-02 18:11:49 -0800 | [diff] [blame] | 3988 | (possibly parenthesized) |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3989 | <a href="#Composite_literals">composite literal</a>. |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 3990 | If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>, |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 3991 | then the evaluation of <code>&x</code> does too. |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3992 | </p> |
Russ Cox | 5ce78b7 | 2013-08-15 14:33:26 -0400 | [diff] [blame] | 3993 | |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3994 | <p> |
| 3995 | For an operand <code>x</code> of pointer type <code>*T</code>, the pointer |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 3996 | indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed |
Robert Griesemer | 0e1d941 | 2011-01-26 11:21:23 -0800 | [diff] [blame] | 3997 | to by <code>x</code>. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 3998 | If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code> |
| 3999 | will cause a <a href="#Run_time_panics">run-time panic</a>. |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4000 | </p> |
| 4001 | |
| 4002 | <pre> |
| 4003 | &x |
| 4004 | &a[f(2)] |
Robert Griesemer | 614b02d | 2013-01-02 18:11:49 -0800 | [diff] [blame] | 4005 | &Point{2, 3} |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4006 | *p |
| 4007 | *pf(x) |
Russ Cox | 5ce78b7 | 2013-08-15 14:33:26 -0400 | [diff] [blame] | 4008 | |
| 4009 | var x *int = nil |
| 4010 | *x // causes a run-time panic |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 4011 | &*x // causes a run-time panic |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4012 | </pre> |
| 4013 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4014 | |
| 4015 | <h3 id="Receive_operator">Receive operator</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4016 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4017 | <p> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4018 | For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>, |
| 4019 | the value of the receive operation <code><-ch</code> is the value received |
Robert Griesemer | cc3f21c | 2012-12-03 14:23:41 -0800 | [diff] [blame] | 4020 | from the channel <code>ch</code>. The channel direction must permit receive operations, |
| 4021 | and the type of the receive operation is the element type of the channel. |
| 4022 | The expression blocks until a value is available. |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 4023 | Receiving from a <code>nil</code> channel blocks forever. |
Robert Griesemer | ab5c762 | 2013-05-31 11:21:37 -0700 | [diff] [blame] | 4024 | A receive operation on a <a href="#Close">closed</a> channel can always proceed |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 4025 | immediately, yielding the element type's <a href="#The_zero_value">zero value</a> |
| 4026 | after any previously sent values have been received. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 4027 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4028 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4029 | <pre> |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4030 | v1 := <-ch |
| 4031 | v2 = <-ch |
| 4032 | f(<-ch) |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4033 | <-strobe // wait until clock pulse and discard received value |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4034 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4035 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 4036 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 4037 | A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 4038 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4039 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4040 | <pre> |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4041 | x, ok = <-ch |
| 4042 | x, ok := <-ch |
| 4043 | var x, ok = <-ch |
Robert Griesemer | 507051d | 2016-08-24 11:33:55 -0700 | [diff] [blame] | 4044 | var x, ok T = <-ch |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4045 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4046 | |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 4047 | <p> |
Robert Griesemer | c0fca13 | 2014-08-05 11:31:32 -0700 | [diff] [blame] | 4048 | yields an additional untyped boolean result reporting whether the |
Robert Griesemer | 689931c | 2012-06-25 11:28:24 -0700 | [diff] [blame] | 4049 | communication succeeded. The value of <code>ok</code> is <code>true</code> |
| 4050 | if the value received was delivered by a successful send operation to the |
| 4051 | channel, or <code>false</code> if it is a zero value generated because the |
| 4052 | channel is closed and empty. |
Rob Pike | df3183f | 2009-02-26 16:37:23 -0800 | [diff] [blame] | 4053 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4054 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4055 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4056 | <h3 id="Conversions">Conversions</h3> |
| 4057 | |
| 4058 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4059 | A conversion changes the <a href="#Types">type</a> of an expression |
| 4060 | to the type specified by the conversion. |
| 4061 | A conversion may appear literally in the source, or it may be <i>implied</i> |
| 4062 | by the context in which an expression appears. |
| 4063 | </p> |
| 4064 | |
| 4065 | <p> |
| 4066 | An <i>explicit</i> conversion is an expression of the form <code>T(x)</code> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4067 | where <code>T</code> is a type and <code>x</code> is an expression |
| 4068 | that can be converted to type <code>T</code>. |
| 4069 | </p> |
| 4070 | |
| 4071 | <pre class="ebnf"> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 4072 | Conversion = Type "(" Expression [ "," ] ")" . |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 4073 | </pre> |
| 4074 | |
| 4075 | <p> |
Robert Griesemer | 3188ffc | 2012-10-03 13:46:37 -0700 | [diff] [blame] | 4076 | If the type starts with the operator <code>*</code> or <code><-</code>, |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 4077 | or if the type starts with the keyword <code>func</code> |
| 4078 | and has no result list, it must be parenthesized when |
| 4079 | necessary to avoid ambiguity: |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 4080 | </p> |
| 4081 | |
| 4082 | <pre> |
| 4083 | *Point(p) // same as *(Point(p)) |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 4084 | (*Point)(p) // p is converted to *Point |
Robert Griesemer | 934a520 | 2010-05-24 14:58:26 -0700 | [diff] [blame] | 4085 | <-chan int(c) // same as <-(chan int(c)) |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 4086 | (<-chan int)(c) // c is converted to <-chan int |
Robert Griesemer | 3188ffc | 2012-10-03 13:46:37 -0700 | [diff] [blame] | 4087 | func()(x) // function signature func() x |
Russ Cox | 71c941b | 2013-02-11 07:48:14 -0500 | [diff] [blame] | 4088 | (func())(x) // x is converted to func() |
| 4089 | (func() int)(x) // x is converted to func() int |
| 4090 | func() int(x) // x is converted to func() int (unambiguous) |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4091 | </pre> |
| 4092 | |
| 4093 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4094 | A <a href="#Constants">constant</a> value <code>x</code> can be converted to |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 4095 | type <code>T</code> if <code>x</code> is <a href="#Representability">representable</a> |
| 4096 | by a value of <code>T</code>. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4097 | As a special case, an integer constant <code>x</code> can be explicitly converted to a |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 4098 | <a href="#String_types">string type</a> using the |
| 4099 | <a href="#Conversions_to_and_from_a_string_type">same rule</a> |
| 4100 | as for non-constant <code>x</code>. |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4101 | </p> |
| 4102 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4103 | <p> |
| 4104 | Converting a constant yields a typed constant as result. |
| 4105 | </p> |
| 4106 | |
| 4107 | <pre> |
| 4108 | uint(iota) // iota value of type uint |
| 4109 | float32(2.718281828) // 2.718281828 of type float32 |
| 4110 | complex128(1) // 1.0 + 0.0i of type complex128 |
Russ Cox | 7576179 | 2013-02-11 07:47:41 -0500 | [diff] [blame] | 4111 | float32(0.49999999) // 0.5 of type float32 |
Robert Griesemer | 55ecda4 | 2015-09-17 18:10:20 -0700 | [diff] [blame] | 4112 | float64(-1e-1000) // 0.0 of type float64 |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4113 | string('x') // "x" of type string |
| 4114 | string(0x266c) // "♬" of type string |
| 4115 | MyString("foo" + "bar") // "foobar" of type MyString |
| 4116 | string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant |
| 4117 | (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type |
| 4118 | int(1.2) // illegal: 1.2 cannot be represented as an int |
| 4119 | string(65.0) // illegal: 65.0 is not an integer constant |
| 4120 | </pre> |
| 4121 | |
| 4122 | <p> |
| 4123 | A non-constant value <code>x</code> can be converted to type <code>T</code> |
| 4124 | in any of these cases: |
Robert Griesemer | 63f0149 | 2010-05-28 14:17:30 -0700 | [diff] [blame] | 4125 | </p> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4126 | |
| 4127 | <ul> |
| 4128 | <li> |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 4129 | <code>x</code> is <a href="#Assignability">assignable</a> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4130 | to <code>T</code>. |
| 4131 | </li> |
| 4132 | <li> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 4133 | ignoring struct tags (see below), |
| 4134 | <code>x</code>'s type and <code>T</code> have <a href="#Type_identity">identical</a> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4135 | <a href="#Types">underlying types</a>. |
| 4136 | </li> |
| 4137 | <li> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 4138 | ignoring struct tags (see below), |
Robert Griesemer | 866f63e | 2017-02-09 13:22:37 -0800 | [diff] [blame] | 4139 | <code>x</code>'s type and <code>T</code> are pointer types |
| 4140 | that are not <a href="#Type_definitions">defined types</a>, |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4141 | and their pointer base types have identical underlying types. |
| 4142 | </li> |
| 4143 | <li> |
| 4144 | <code>x</code>'s type and <code>T</code> are both integer or floating |
| 4145 | point types. |
| 4146 | </li> |
| 4147 | <li> |
| 4148 | <code>x</code>'s type and <code>T</code> are both complex types. |
| 4149 | </li> |
| 4150 | <li> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 4151 | <code>x</code> is an integer or a slice of bytes or runes |
| 4152 | and <code>T</code> is a string type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4153 | </li> |
| 4154 | <li> |
Robert Griesemer | 60a6ae8 | 2012-09-26 10:31:57 -0700 | [diff] [blame] | 4155 | <code>x</code> is a string and <code>T</code> is a slice of bytes or runes. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4156 | </li> |
| 4157 | </ul> |
| 4158 | |
| 4159 | <p> |
Robert Griesemer | 5c7a005 | 2016-06-03 13:21:55 -0700 | [diff] [blame] | 4160 | <a href="#Struct_types">Struct tags</a> are ignored when comparing struct types |
| 4161 | for identity for the purpose of conversion: |
| 4162 | </p> |
| 4163 | |
| 4164 | <pre> |
| 4165 | type Person struct { |
| 4166 | Name string |
| 4167 | Address *struct { |
| 4168 | Street string |
| 4169 | City string |
| 4170 | } |
| 4171 | } |
| 4172 | |
| 4173 | var data *struct { |
| 4174 | Name string `json:"name"` |
| 4175 | Address *struct { |
| 4176 | Street string `json:"street"` |
| 4177 | City string `json:"city"` |
| 4178 | } `json:"address"` |
| 4179 | } |
| 4180 | |
| 4181 | var person = (*Person)(data) // ignoring tags, the underlying types are identical |
| 4182 | </pre> |
| 4183 | |
| 4184 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4185 | Specific rules apply to (non-constant) conversions between numeric types or |
| 4186 | to and from a string type. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4187 | These conversions may change the representation of <code>x</code> |
| 4188 | and incur a run-time cost. |
| 4189 | All other conversions only change the type but not the representation |
| 4190 | of <code>x</code>. |
| 4191 | </p> |
| 4192 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4193 | <p> |
| 4194 | There is no linguistic mechanism to convert between pointers and integers. |
| 4195 | The package <a href="#Package_unsafe"><code>unsafe</code></a> |
| 4196 | implements this functionality under |
| 4197 | restricted circumstances. |
| 4198 | </p> |
| 4199 | |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4200 | <h4>Conversions between numeric types</h4> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4201 | |
| 4202 | <p> |
| 4203 | For the conversion of non-constant numeric values, the following rules apply: |
| 4204 | </p> |
| 4205 | |
Robert Griesemer | 63f0149 | 2010-05-28 14:17:30 -0700 | [diff] [blame] | 4206 | <ol> |
| 4207 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4208 | When converting between integer types, if the value is a signed integer, it is |
| 4209 | sign extended to implicit infinite precision; otherwise it is zero extended. |
| 4210 | It is then truncated to fit in the result type's size. |
| 4211 | For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4212 | The conversion always yields a valid value; there is no indication of overflow. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4213 | </li> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4214 | <li> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4215 | When converting a floating-point number to an integer, the fraction is discarded |
| 4216 | (truncation towards zero). |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4217 | </li> |
| 4218 | <li> |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4219 | When converting an integer or floating-point number to a floating-point type, |
| 4220 | or a complex number to another complex type, the result value is rounded |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4221 | to the precision specified by the destination type. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4222 | For instance, the value of a variable <code>x</code> of type <code>float32</code> |
| 4223 | may be stored using additional precision beyond that of an IEEE-754 32-bit number, |
| 4224 | but float32(x) represents the result of rounding <code>x</code>'s value to |
| 4225 | 32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits |
Evan Shaw | cb4e9f8 | 2010-05-23 11:21:47 -0700 | [diff] [blame] | 4226 | of precision, but <code>float32(x + 0.1)</code> does not. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4227 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4228 | </ol> |
| 4229 | |
| 4230 | <p> |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4231 | In all non-constant conversions involving floating-point or complex values, |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4232 | if the result type cannot represent the value the conversion |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4233 | succeeds but the result value is implementation-dependent. |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4234 | </p> |
| 4235 | |
Robert Griesemer | 2769356 | 2011-06-13 16:47:33 -0700 | [diff] [blame] | 4236 | <h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4> |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4237 | |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4238 | <ol> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4239 | <li> |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4240 | Converting a signed or unsigned integer value to a string type yields a |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 4241 | string containing the UTF-8 representation of the integer. Values outside |
| 4242 | the range of valid Unicode code points are converted to <code>"\uFFFD"</code>. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4243 | |
| 4244 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4245 | string('a') // "a" |
Rémy Oudompheng | 2b4cc6c | 2012-07-11 20:26:51 +0200 | [diff] [blame] | 4246 | string(-1) // "\ufffd" == "\xef\xbf\xbd" |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4247 | string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4248 | type MyString string |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4249 | MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4250 | </pre> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4251 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4252 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4253 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4254 | Converting a slice of bytes to a string type yields |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4255 | a string whose successive bytes are the elements of the slice. |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4256 | |
| 4257 | <pre> |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4258 | string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" |
| 4259 | string([]byte{}) // "" |
| 4260 | string([]byte(nil)) // "" |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4261 | |
| 4262 | type MyBytes []byte |
| 4263 | string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø" |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4264 | </pre> |
| 4265 | </li> |
| 4266 | |
| 4267 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4268 | Converting a slice of runes to a string type yields |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4269 | a string that is the concatenation of the individual rune values |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4270 | converted to strings. |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4271 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4272 | <pre> |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4273 | string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" |
| 4274 | string([]rune{}) // "" |
| 4275 | string([]rune(nil)) // "" |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4276 | |
| 4277 | type MyRunes []rune |
| 4278 | string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔" |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4279 | </pre> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4280 | </li> |
| 4281 | |
| 4282 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4283 | Converting a value of a string type to a slice of bytes type |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4284 | yields a slice whose successive elements are the bytes of the string. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4285 | |
| 4286 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4287 | []byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4288 | []byte("") // []byte{} |
| 4289 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4290 | MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'} |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4291 | </pre> |
| 4292 | </li> |
| 4293 | |
| 4294 | <li> |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4295 | Converting a value of a string type to a slice of runes type |
| 4296 | yields a slice containing the individual Unicode code points of the string. |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4297 | |
Rob Pike | 1811fac | 2010-02-17 11:26:09 +1100 | [diff] [blame] | 4298 | <pre> |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 4299 | []rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4} |
Robert Griesemer | de47f68 | 2013-06-21 16:11:13 -0700 | [diff] [blame] | 4300 | []rune("") // []rune{} |
| 4301 | |
Russ Cox | 6e3e380 | 2011-11-22 12:30:02 -0500 | [diff] [blame] | 4302 | MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4} |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4303 | </pre> |
| 4304 | </li> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4305 | </ol> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4306 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 4307 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4308 | <h3 id="Constant_expressions">Constant expressions</h3> |
Robert Griesemer | b90b213 | 2008-09-19 15:49:55 -0700 | [diff] [blame] | 4309 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4310 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4311 | Constant expressions may contain only <a href="#Constants">constant</a> |
Robert Griesemer | ea7c57a | 2012-10-17 11:08:42 -0700 | [diff] [blame] | 4312 | operands and are evaluated at compile time. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4313 | </p> |
| 4314 | |
| 4315 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4316 | Untyped boolean, numeric, and string constants may be used as operands |
| 4317 | wherever it is legal to use an operand of boolean, numeric, or string type, |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4318 | respectively. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4319 | </p> |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 4320 | |
| 4321 | <p> |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4322 | A constant <a href="#Comparison_operators">comparison</a> always yields |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 4323 | an untyped boolean constant. If the left operand of a constant |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4324 | <a href="#Operators">shift expression</a> is an untyped constant, the |
| 4325 | result is an integer constant; otherwise it is a constant of the same |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 4326 | type as the left operand, which must be of |
| 4327 | <a href="#Numeric_types">integer type</a>. |
Bryan C. Mills | df48003 | 2018-04-13 11:57:13 -0400 | [diff] [blame] | 4328 | </p> |
| 4329 | |
| 4330 | <p> |
| 4331 | Any other operation on untyped constants results in an untyped constant of the |
| 4332 | same kind; that is, a boolean, integer, floating-point, complex, or string |
| 4333 | constant. |
| 4334 | If the untyped operands of a binary operation (other than a shift) are of |
| 4335 | different kinds, the result is of the operand's kind that appears later in this |
| 4336 | list: integer, rune, floating-point, complex. |
| 4337 | For example, an untyped integer constant divided by an |
| 4338 | untyped complex constant yields an untyped complex constant. |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4339 | </p> |
| 4340 | |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4341 | <pre> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4342 | const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant) |
| 4343 | const b = 15 / 4 // b == 3 (untyped integer constant) |
| 4344 | const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant) |
Robert Griesemer | 2ae61d5 | 2012-11-17 11:16:07 -0800 | [diff] [blame] | 4345 | const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division) |
| 4346 | const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division) |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4347 | const d = 1 << 3.0 // d == 8 (untyped integer constant) |
| 4348 | const e = 1.0 << 3 // e == 8 (untyped integer constant) |
Robert Griesemer | 2d846f6 | 2013-05-08 10:42:08 -0700 | [diff] [blame] | 4349 | const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32) |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4350 | const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant) |
Russ Cox | ef1c535 | 2011-12-09 00:13:19 -0500 | [diff] [blame] | 4351 | const h = "foo" > "bar" // h == true (untyped boolean constant) |
| 4352 | const j = true // j == true (untyped boolean constant) |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 4353 | const k = 'w' + 1 // k == 'x' (untyped rune constant) |
Russ Cox | ef1c535 | 2011-12-09 00:13:19 -0500 | [diff] [blame] | 4354 | const l = "hi" // l == "hi" (untyped string constant) |
| 4355 | const m = string(k) // m == "x" (type string) |
Robert Hencke | 1084ab9 | 2011-12-10 10:04:33 -0800 | [diff] [blame] | 4356 | const Σ = 1 - 0.707i // (untyped complex constant) |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4357 | const Δ = Σ + 2.0e-4 // (untyped complex constant) |
| 4358 | const Φ = iota*1i - 1/1i // (untyped complex constant) |
Robert Griesemer | 32d1278 | 2011-05-23 14:12:42 -0700 | [diff] [blame] | 4359 | </pre> |
| 4360 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4361 | <p> |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4362 | Applying the built-in function <code>complex</code> to untyped |
Rob Pike | 9dfc6f6 | 2012-08-29 14:46:57 -0700 | [diff] [blame] | 4363 | integer, rune, or floating-point constants yields |
Russ Cox | a933635 | 2011-12-08 21:48:19 -0500 | [diff] [blame] | 4364 | an untyped complex constant. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4365 | </p> |
| 4366 | |
| 4367 | <pre> |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4368 | const ic = complex(0, c) // ic == 3.75i (untyped complex constant) |
Mihai Borobocea | 8183ed1 | 2013-12-30 13:29:56 -0800 | [diff] [blame] | 4369 | const iΘ = complex(0, Θ) // iΘ == 1i (type complex128) |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 4370 | </pre> |
| 4371 | |
| 4372 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4373 | Constant expressions are always evaluated exactly; intermediate values and the |
| 4374 | constants themselves may require precision significantly larger than supported |
| 4375 | by any predeclared type in the language. The following are legal declarations: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4376 | </p> |
| 4377 | |
| 4378 | <pre> |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4379 | const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant) |
| 4380 | const Four int8 = Huge >> 98 // Four == 4 (type int8) |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 4381 | </pre> |
| 4382 | |
| 4383 | <p> |
Robert Griesemer | ddddd39 | 2012-10-19 10:12:09 -0700 | [diff] [blame] | 4384 | The divisor of a constant division or remainder operation must not be zero: |
| 4385 | </p> |
| 4386 | |
| 4387 | <pre> |
| 4388 | 3.14 / 0.0 // illegal: division by zero |
| 4389 | </pre> |
| 4390 | |
| 4391 | <p> |
griesemer | b40831b | 2017-08-21 15:47:51 +0200 | [diff] [blame] | 4392 | The values of <i>typed</i> constants must always be accurately |
| 4393 | <a href="#Representability">representable</a> by values |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4394 | of the constant type. The following constant expressions are illegal: |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4395 | </p> |
| 4396 | |
| 4397 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4398 | uint(-1) // -1 cannot be represented as a uint |
| 4399 | int(3.14) // 3.14 cannot be represented as an int |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4400 | int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64 |
| 4401 | Four * 300 // operand 300 cannot be represented as an int8 (type of Four) |
| 4402 | Four * 100 // product 400 cannot be represented as an int8 (type of Four) |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4403 | </pre> |
| 4404 | |
| 4405 | <p> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4406 | The mask used by the unary bitwise complement operator <code>^</code> matches |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4407 | the rule for non-constants: the mask is all 1s for unsigned constants |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4408 | and -1 for signed and untyped constants. |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4409 | </p> |
| 4410 | |
| 4411 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4412 | ^1 // untyped integer constant, equal to -2 |
Robert Griesemer | 462860b | 2012-12-12 14:25:40 -0800 | [diff] [blame] | 4413 | uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4414 | ^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE) |
| 4415 | int8(^1) // same as int8(-2) |
| 4416 | ^int8(1) // same as -1 ^ int8(1) = -2 |
Rob Pike | 21d0349 | 2009-03-24 19:16:42 -0700 | [diff] [blame] | 4417 | </pre> |
| 4418 | |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 4419 | <p> |
| 4420 | Implementation restriction: A compiler may use rounding while |
| 4421 | computing untyped floating-point or complex constant expressions; see |
| 4422 | the implementation restriction in the section |
| 4423 | on <a href="#Constants">constants</a>. This rounding may cause a |
| 4424 | floating-point constant expression to be invalid in an integer |
| 4425 | context, even if it would be integral when calculated using infinite |
Robert Griesemer | d8c6dac | 2015-06-23 14:17:59 -0700 | [diff] [blame] | 4426 | precision, and vice versa. |
Ian Lance Taylor | 9126c65 | 2012-02-13 11:25:56 -0800 | [diff] [blame] | 4427 | </p> |
| 4428 | |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4429 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4430 | <h3 id="Order_of_evaluation">Order of evaluation</h3> |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4431 | |
| 4432 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 4433 | At package level, <a href="#Package_initialization">initialization dependencies</a> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4434 | determine the evaluation order of individual initialization expressions in |
| 4435 | <a href="#Variable_declarations">variable declarations</a>. |
| 4436 | Otherwise, when evaluating the <a href="#Operands">operands</a> of an |
| 4437 | expression, assignment, or |
Robert Griesemer | f05a91e | 2012-08-09 11:50:16 -0700 | [diff] [blame] | 4438 | <a href="#Return_statements">return statement</a>, |
| 4439 | all function calls, method calls, and |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4440 | communication operations are evaluated in lexical left-to-right |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 4441 | order. |
| 4442 | </p> |
| 4443 | |
| 4444 | <p> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4445 | For example, in the (function-local) assignment |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4446 | </p> |
| 4447 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4448 | y[f()], ok = g(h(), i()+x[j()], <-c), k() |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4449 | </pre> |
| 4450 | <p> |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4451 | the function calls and communication happen in the order |
| 4452 | <code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>, |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4453 | <code><-c</code>, <code>g()</code>, and <code>k()</code>. |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4454 | However, the order of those events compared to the evaluation |
| 4455 | and indexing of <code>x</code> and the evaluation |
| 4456 | of <code>y</code> is not specified. |
Rob Pike | c956e90 | 2009-04-14 20:10:49 -0700 | [diff] [blame] | 4457 | </p> |
| 4458 | |
Robert Griesemer | f05a91e | 2012-08-09 11:50:16 -0700 | [diff] [blame] | 4459 | <pre> |
| 4460 | a := 1 |
Shenghou Ma | bdac989 | 2013-06-11 02:52:07 +0800 | [diff] [blame] | 4461 | f := func() int { a++; return a } |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4462 | x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified |
| 4463 | m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified |
| 4464 | n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified |
Robert Griesemer | f05a91e | 2012-08-09 11:50:16 -0700 | [diff] [blame] | 4465 | </pre> |
| 4466 | |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 4467 | <p> |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4468 | At package level, initialization dependencies override the left-to-right rule |
| 4469 | for individual initialization expressions, but not for operands within each |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 4470 | expression: |
Robert Griesemer | dbe5f88 | 2014-05-07 08:50:52 -0700 | [diff] [blame] | 4471 | </p> |
| 4472 | |
| 4473 | <pre> |
| 4474 | var a, b, c = f() + v(), g(), sqr(u()) + v() |
| 4475 | |
| 4476 | func f() int { return c } |
| 4477 | func g() int { return a } |
| 4478 | func sqr(x int) int { return x*x } |
| 4479 | |
| 4480 | // functions u and v are independent of all other variables and functions |
| 4481 | </pre> |
| 4482 | |
| 4483 | <p> |
| 4484 | The function calls happen in the order |
| 4485 | <code>u()</code>, <code>sqr()</code>, <code>v()</code>, |
| 4486 | <code>f()</code>, <code>v()</code>, and <code>g()</code>. |
| 4487 | </p> |
| 4488 | |
| 4489 | <p> |
Rob Pike | 4fe4192 | 2009-11-07 22:00:59 -0800 | [diff] [blame] | 4490 | Floating-point operations within a single expression are evaluated according to |
| 4491 | the associativity of the operators. Explicit parentheses affect the evaluation |
| 4492 | by overriding the default associativity. |
| 4493 | In the expression <code>x + (y + z)</code> the addition <code>y + z</code> |
| 4494 | is performed before adding <code>x</code>. |
| 4495 | </p> |
| 4496 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4497 | <h2 id="Statements">Statements</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4498 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4499 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4500 | Statements control execution. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4501 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4502 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4503 | <pre class="ebnf"> |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4504 | Statement = |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 4505 | Declaration | LabeledStmt | SimpleStmt | |
| 4506 | GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt | |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4507 | FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt | |
| 4508 | DeferStmt . |
Robert Griesemer | 7abfcd9 | 2008-10-07 17:14:30 -0700 | [diff] [blame] | 4509 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4510 | SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4511 | </pre> |
Robert Griesemer | 7271e04 | 2008-10-09 20:05:24 -0700 | [diff] [blame] | 4512 | |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4513 | <h3 id="Terminating_statements">Terminating statements</h3> |
| 4514 | |
| 4515 | <p> |
Robert Griesemer | f3f507b | 2017-12-21 15:17:35 -0800 | [diff] [blame] | 4516 | A <i>terminating statement</i> prevents execution of all statements that lexically |
| 4517 | appear after it in the same <a href="#Blocks">block</a>. The following statements |
| 4518 | are terminating: |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4519 | </p> |
| 4520 | |
| 4521 | <ol> |
| 4522 | <li> |
| 4523 | A <a href="#Return_statements">"return"</a> or |
| 4524 | <a href="#Goto_statements">"goto"</a> statement. |
| 4525 | <!-- ul below only for regular layout --> |
| 4526 | <ul> </ul> |
| 4527 | </li> |
| 4528 | |
| 4529 | <li> |
| 4530 | A call to the built-in function |
| 4531 | <a href="#Handling_panics"><code>panic</code></a>. |
| 4532 | <!-- ul below only for regular layout --> |
| 4533 | <ul> </ul> |
| 4534 | </li> |
| 4535 | |
| 4536 | <li> |
| 4537 | A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement. |
| 4538 | <!-- ul below only for regular layout --> |
| 4539 | <ul> </ul> |
| 4540 | </li> |
| 4541 | |
| 4542 | <li> |
| 4543 | An <a href="#If_statements">"if" statement</a> in which: |
| 4544 | <ul> |
| 4545 | <li>the "else" branch is present, and</li> |
| 4546 | <li>both branches are terminating statements.</li> |
| 4547 | </ul> |
| 4548 | </li> |
| 4549 | |
| 4550 | <li> |
| 4551 | A <a href="#For_statements">"for" statement</a> in which: |
| 4552 | <ul> |
| 4553 | <li>there are no "break" statements referring to the "for" statement, and</li> |
| 4554 | <li>the loop condition is absent.</li> |
| 4555 | </ul> |
| 4556 | </li> |
| 4557 | |
| 4558 | <li> |
| 4559 | A <a href="#Switch_statements">"switch" statement</a> in which: |
| 4560 | <ul> |
| 4561 | <li>there are no "break" statements referring to the "switch" statement,</li> |
| 4562 | <li>there is a default case, and</li> |
| 4563 | <li>the statement lists in each case, including the default, end in a terminating |
| 4564 | statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough" |
| 4565 | statement</a>.</li> |
| 4566 | </ul> |
| 4567 | </li> |
| 4568 | |
| 4569 | <li> |
| 4570 | A <a href="#Select_statements">"select" statement</a> in which: |
| 4571 | <ul> |
| 4572 | <li>there are no "break" statements referring to the "select" statement, and</li> |
| 4573 | <li>the statement lists in each case, including the default if present, |
| 4574 | end in a terminating statement.</li> |
| 4575 | </ul> |
| 4576 | </li> |
| 4577 | |
| 4578 | <li> |
| 4579 | A <a href="#Labeled_statements">labeled statement</a> labeling |
| 4580 | a terminating statement. |
| 4581 | </li> |
| 4582 | </ol> |
| 4583 | |
| 4584 | <p> |
| 4585 | All other statements are not terminating. |
| 4586 | </p> |
| 4587 | |
| 4588 | <p> |
| 4589 | A <a href="#Blocks">statement list</a> ends in a terminating statement if the list |
Robert Griesemer | b5ddbb9 | 2016-02-26 15:52:13 -0800 | [diff] [blame] | 4590 | is not empty and its final non-empty statement is terminating. |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4591 | </p> |
| 4592 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4593 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4594 | <h3 id="Empty_statements">Empty statements</h3> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4595 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4596 | <p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4597 | The empty statement does nothing. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4598 | </p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4599 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4600 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4601 | EmptyStmt = . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4602 | </pre> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4603 | |
| 4604 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4605 | <h3 id="Labeled_statements">Labeled statements</h3> |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4606 | |
| 4607 | <p> |
| 4608 | A labeled statement may be the target of a <code>goto</code>, |
| 4609 | <code>break</code> or <code>continue</code> statement. |
| 4610 | </p> |
| 4611 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4612 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4613 | LabeledStmt = Label ":" Statement . |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4614 | Label = identifier . |
| 4615 | </pre> |
| 4616 | |
| 4617 | <pre> |
Robert Griesemer | 7fc4e37 | 2011-02-01 12:51:10 -0800 | [diff] [blame] | 4618 | Error: log.Panic("error encountered") |
Robert Griesemer | dea4394 | 2009-03-16 17:36:52 -0700 | [diff] [blame] | 4619 | </pre> |
| 4620 | |
| 4621 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4622 | <h3 id="Expression_statements">Expression statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4623 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4624 | <p> |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4625 | With the exception of specific built-in functions, |
| 4626 | function and method <a href="#Calls">calls</a> and |
| 4627 | <a href="#Receive_operator">receive operations</a> |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4628 | can appear in statement context. Such statements may be parenthesized. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4629 | </p> |
| 4630 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4631 | <pre class="ebnf"> |
Robert Griesemer | c134718 | 2011-04-29 12:20:31 -0700 | [diff] [blame] | 4632 | ExpressionStmt = Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4633 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4634 | |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4635 | <p> |
| 4636 | The following built-in functions are not permitted in statement context: |
| 4637 | </p> |
| 4638 | |
| 4639 | <pre> |
| 4640 | append cap complex imag len make new real |
| 4641 | unsafe.Alignof unsafe.Offsetof unsafe.Sizeof |
| 4642 | </pre> |
| 4643 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4644 | <pre> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4645 | h(x+y) |
| 4646 | f.Close() |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 4647 | <-ch |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4648 | (<-ch) |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 4649 | len("foo") // illegal if len is the built-in function |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4650 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4651 | |
| 4652 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4653 | <h3 id="Send_statements">Send statements</h3> |
| 4654 | |
| 4655 | <p> |
| 4656 | A send statement sends a value on a channel. |
Robert Griesemer | cc3f21c | 2012-12-03 14:23:41 -0800 | [diff] [blame] | 4657 | The channel expression must be of <a href="#Channel_types">channel type</a>, |
| 4658 | the channel direction must permit send operations, |
| 4659 | and the type of the value to be sent must be <a href="#Assignability">assignable</a> |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4660 | to the channel's element type. |
| 4661 | </p> |
| 4662 | |
| 4663 | <pre class="ebnf"> |
| 4664 | SendStmt = Channel "<-" Expression . |
| 4665 | Channel = Expression . |
| 4666 | </pre> |
| 4667 | |
| 4668 | <p> |
| 4669 | Both the channel and the value expression are evaluated before communication |
Russ Cox | e7a138b | 2012-02-08 15:24:48 -0500 | [diff] [blame] | 4670 | begins. Communication blocks until the send can proceed. |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4671 | A send on an unbuffered channel can proceed if a receiver is ready. |
| 4672 | A send on a buffered channel can proceed if there is room in the buffer. |
Russ Cox | e7a138b | 2012-02-08 15:24:48 -0500 | [diff] [blame] | 4673 | A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>. |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 4674 | A send on a <code>nil</code> channel blocks forever. |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4675 | </p> |
| 4676 | |
| 4677 | <pre> |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 4678 | ch <- 3 // send value 3 to channel ch |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4679 | </pre> |
| 4680 | |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 4681 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4682 | <h3 id="IncDec_statements">IncDec statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4683 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4684 | <p> |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4685 | The "++" and "--" statements increment or decrement their operands |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 4686 | by the untyped <a href="#Constants">constant</a> <code>1</code>. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 4687 | As with an assignment, the operand must be <a href="#Address_operators">addressable</a> |
| 4688 | or a map index expression. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4689 | </p> |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4690 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4691 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4692 | IncDecStmt = Expression ( "++" | "--" ) . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4693 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4694 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4695 | <p> |
Robert Griesemer | 506c008 | 2009-09-08 15:41:14 -0700 | [diff] [blame] | 4696 | The following <a href="#Assignments">assignment statements</a> are semantically |
Robert Griesemer | 52a5480 | 2008-09-30 13:02:50 -0700 | [diff] [blame] | 4697 | equivalent: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4698 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4699 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 4700 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4701 | IncDec statement Assignment |
| 4702 | x++ x += 1 |
| 4703 | x-- x -= 1 |
| 4704 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4705 | |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 4706 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4707 | <h3 id="Assignments">Assignments</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4708 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4709 | <pre class="ebnf"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4710 | Assignment = ExpressionList assign_op ExpressionList . |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 4711 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4712 | assign_op = [ add_op | mul_op ] "=" . |
| 4713 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4714 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4715 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4716 | Each left-hand side operand must be <a href="#Address_operators">addressable</a>, |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4717 | a map index expression, or (for <code>=</code> assignments only) the |
| 4718 | <a href="#Blank_identifier">blank identifier</a>. |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4719 | Operands may be parenthesized. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4720 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4721 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4722 | <pre> |
| 4723 | x = 1 |
| 4724 | *p = f() |
| 4725 | a[i] = 23 |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 4726 | (k) = <-ch // same as: k = <-ch |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4727 | </pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4728 | |
| 4729 | <p> |
| 4730 | An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code> |
Robert Griesemer | 26e726c | 2017-03-10 17:17:23 -0800 | [diff] [blame] | 4731 | <code>y</code> where <i>op</i> is a binary <a href="#Arithmetic_operators">arithmetic operator</a> |
| 4732 | is equivalent to <code>x</code> <code>=</code> <code>x</code> <i>op</i> |
Robert Griesemer | 637d598 | 2015-06-11 13:21:46 -0700 | [diff] [blame] | 4733 | <code>(y)</code> but evaluates <code>x</code> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4734 | only once. The <i>op</i><code>=</code> construct is a single token. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4735 | In assignment operations, both the left- and right-hand expression lists |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4736 | must contain exactly one single-valued expression, and the left-hand |
| 4737 | expression must not be the blank identifier. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4738 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4739 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4740 | <pre> |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 4741 | a[i] <<= 2 |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 4742 | i &^= 1<<n |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4743 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4744 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4745 | <p> |
| 4746 | A tuple assignment assigns the individual elements of a multi-valued |
| 4747 | operation to a list of variables. There are two forms. In the |
| 4748 | first, the right hand operand is a single multi-valued expression |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4749 | such as a function call, a <a href="#Channel_types">channel</a> or |
| 4750 | <a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4751 | The number of operands on the left |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 4752 | hand side must match the number of values. For instance, if |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4753 | <code>f</code> is a function returning two values, |
| 4754 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4755 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4756 | <pre> |
| 4757 | x, y = f() |
| 4758 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4759 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4760 | <p> |
| 4761 | assigns the first value to <code>x</code> and the second to <code>y</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4762 | In the second form, the number of operands on the left must equal the number |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 4763 | of expressions on the right, each of which must be single-valued, and the |
| 4764 | <i>n</i>th expression on the right is assigned to the <i>n</i>th |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4765 | operand on the left: |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4766 | </p> |
| 4767 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4768 | <pre> |
| 4769 | one, two, three = '一', '二', '三' |
| 4770 | </pre> |
| 4771 | |
| 4772 | <p> |
| 4773 | The <a href="#Blank_identifier">blank identifier</a> provides a way to |
| 4774 | ignore right-hand side values in an assignment: |
| 4775 | </p> |
| 4776 | |
| 4777 | <pre> |
| 4778 | _ = x // evaluate x but ignore it |
| 4779 | x, _ = f() // evaluate f() but ignore second result value |
| 4780 | </pre> |
| 4781 | |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4782 | <p> |
| 4783 | The assignment proceeds in two phases. |
Robert Griesemer | 9c9e811 | 2012-12-10 11:55:57 -0800 | [diff] [blame] | 4784 | First, the operands of <a href="#Index_expressions">index expressions</a> |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4785 | and <a href="#Address_operators">pointer indirections</a> |
| 4786 | (including implicit pointer indirections in <a href="#Selectors">selectors</a>) |
| 4787 | on the left and the expressions on the right are all |
| 4788 | <a href="#Order_of_evaluation">evaluated in the usual order</a>. |
| 4789 | Second, the assignments are carried out in left-to-right order. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4790 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4791 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4792 | <pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4793 | a, b = b, a // exchange a and b |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4794 | |
| 4795 | x := []int{1, 2, 3} |
| 4796 | i := 0 |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4797 | i, x[i] = 1, 2 // set i = 1, x[0] = 2 |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4798 | |
| 4799 | i = 0 |
| 4800 | x[i], i = 2, 1 // set x[0] = 2, i = 1 |
| 4801 | |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4802 | x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end) |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4803 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 4804 | x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5. |
Russ Cox | fa53811 | 2011-10-13 15:44:17 -0400 | [diff] [blame] | 4805 | |
| 4806 | type Point struct { x, y int } |
| 4807 | var p *Point |
| 4808 | x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7 |
Robert Griesemer | 2dde4f5 | 2012-05-24 10:59:48 -0700 | [diff] [blame] | 4809 | |
| 4810 | i = 2 |
| 4811 | x = []int{3, 5, 7} |
| 4812 | for i, x[i] = range x { // set i, x[2] = 0, x[0] |
| 4813 | break |
| 4814 | } |
| 4815 | // after this loop, i == 0 and x == []int{3, 5, 3} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4816 | </pre> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4817 | |
| 4818 | <p> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4819 | In assignments, each value must be <a href="#Assignability">assignable</a> |
| 4820 | to the type of the operand to which it is assigned, with the following special cases: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4821 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4822 | |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4823 | <ol> |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4824 | <li> |
| 4825 | Any typed value may be assigned to the blank identifier. |
| 4826 | </li> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4827 | |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4828 | <li> |
| 4829 | If an untyped constant |
| 4830 | is assigned to a variable of interface type or the blank identifier, |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4831 | the constant is first implicitly <a href="#Conversions">converted</a> to its |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4832 | <a href="#Constants">default type</a>. |
| 4833 | </li> |
| 4834 | |
| 4835 | <li> |
| 4836 | If an untyped boolean value is assigned to a variable of interface type or |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4837 | the blank identifier, it is first implicitly converted to type <code>bool</code>. |
Robert Griesemer | 47094dc | 2014-09-30 11:44:29 -0700 | [diff] [blame] | 4838 | </li> |
Robert Griesemer | f57bf7a | 2013-11-12 21:06:54 -0500 | [diff] [blame] | 4839 | </ol> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4840 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4841 | <h3 id="If_statements">If statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4842 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4843 | <p> |
| 4844 | "If" statements specify the conditional execution of two branches |
| 4845 | according to the value of a boolean expression. If the expression |
| 4846 | evaluates to true, the "if" branch is executed, otherwise, if |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4847 | present, the "else" branch is executed. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4848 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4849 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4850 | <pre class="ebnf"> |
Russ Cox | 58e19aa | 2011-07-14 17:15:52 -0400 | [diff] [blame] | 4851 | IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4852 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4853 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4854 | <pre> |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4855 | if x > max { |
| 4856 | x = max |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4857 | } |
| 4858 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4859 | |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4860 | <p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4861 | The expression may be preceded by a simple statement, which |
| 4862 | executes before the expression is evaluated. |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 4863 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4864 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4865 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4866 | if x := f(); x < y { |
| 4867 | return x |
Robert Griesemer | a1368a6 | 2011-02-22 15:31:57 -0800 | [diff] [blame] | 4868 | } else if x > z { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4869 | return z |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4870 | } else { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4871 | return y |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4872 | } |
| 4873 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4874 | |
| 4875 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4876 | <h3 id="Switch_statements">Switch statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4877 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4878 | <p> |
| 4879 | "Switch" statements provide multi-way execution. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4880 | An expression or type specifier is compared to the "cases" |
| 4881 | inside the "switch" to determine which branch |
| 4882 | to execute. |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4883 | </p> |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4884 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4885 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 4886 | SwitchStmt = ExprSwitchStmt | TypeSwitchStmt . |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4887 | </pre> |
| 4888 | |
Rob Pike | afee1c5 | 2009-03-20 17:41:25 -0700 | [diff] [blame] | 4889 | <p> |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4890 | There are two forms: expression switches and type switches. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4891 | In an expression switch, the cases contain expressions that are compared |
| 4892 | against the value of the switch expression. |
| 4893 | In a type switch, the cases contain types that are compared against the |
| 4894 | type of a specially annotated switch expression. |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4895 | The switch expression is evaluated exactly once in a switch statement. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4896 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4897 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4898 | <h4 id="Expression_switches">Expression switches</h4> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4899 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4900 | <p> |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4901 | In an expression switch, |
| 4902 | the switch expression is evaluated and |
| 4903 | the case expressions, which need not be constants, |
Robert Griesemer | 4f18549 | 2009-05-01 17:00:16 -0700 | [diff] [blame] | 4904 | are evaluated left-to-right and top-to-bottom; the first one that equals the |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4905 | switch expression |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4906 | triggers execution of the statements of the associated case; |
| 4907 | the other cases are skipped. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4908 | If no case matches and there is a "default" case, |
| 4909 | its statements are executed. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4910 | There can be at most one default case and it may appear anywhere in the |
| 4911 | "switch" statement. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 4912 | A missing switch expression is equivalent to the boolean value |
| 4913 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4914 | </p> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4915 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 4916 | <pre class="ebnf"> |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 4917 | ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 4918 | ExprCaseClause = ExprSwitchCase ":" StatementList . |
Robert Griesemer | 091cba8 | 2009-03-19 08:39:40 -0700 | [diff] [blame] | 4919 | ExprSwitchCase = "case" ExpressionList | "default" . |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4920 | </pre> |
| 4921 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4922 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4923 | If the switch expression evaluates to an untyped constant, it is first implicitly |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4924 | <a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>; |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4925 | if it is an untyped boolean value, it is first implicitly converted to type <code>bool</code>. |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4926 | The predeclared untyped value <code>nil</code> cannot be used as a switch expression. |
| 4927 | </p> |
| 4928 | |
| 4929 | <p> |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 4930 | If a case expression is untyped, it is first implicitly <a href="#Conversions">converted</a> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4931 | to the type of the switch expression. |
| 4932 | For each (possibly converted) case expression <code>x</code> and the value <code>t</code> |
| 4933 | of the switch expression, <code>x == t</code> must be a valid <a href="#Comparison_operators">comparison</a>. |
| 4934 | </p> |
| 4935 | |
| 4936 | <p> |
| 4937 | In other words, the switch expression is treated as if it were used to declare and |
| 4938 | initialize a temporary variable <code>t</code> without explicit type; it is that |
| 4939 | value of <code>t</code> against which each case expression <code>x</code> is tested |
| 4940 | for equality. |
| 4941 | </p> |
| 4942 | |
| 4943 | <p> |
Robert Griesemer | 67a6b4f | 2013-03-01 16:45:14 -0800 | [diff] [blame] | 4944 | In a case or default clause, the last non-empty statement |
| 4945 | may be a (possibly <a href="#Labeled_statements">labeled</a>) |
| 4946 | <a href="#Fallthrough_statements">"fallthrough" statement</a> to |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4947 | indicate that control should flow from the end of this clause to |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 4948 | the first statement of the next clause. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4949 | Otherwise control flows to the end of the "switch" statement. |
Robert Griesemer | 67a6b4f | 2013-03-01 16:45:14 -0800 | [diff] [blame] | 4950 | A "fallthrough" statement may appear as the last statement of all |
| 4951 | but the last clause of an expression switch. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4952 | </p> |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 4953 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4954 | <p> |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4955 | The switch expression may be preceded by a simple statement, which |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 4956 | executes before the expression is evaluated. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 4957 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4958 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4959 | <pre> |
| 4960 | switch tag { |
Rob Pike | 65ec16b | 2009-05-29 15:46:03 -0700 | [diff] [blame] | 4961 | default: s3() |
| 4962 | case 0, 1, 2, 3: s1() |
| 4963 | case 4, 5, 6, 7: s2() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4964 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4965 | |
Andrew Gerrand | 10b77f7 | 2010-03-29 13:12:08 +1100 | [diff] [blame] | 4966 | switch x := f(); { // missing switch expression means "true" |
Rob Pike | 65ec16b | 2009-05-29 15:46:03 -0700 | [diff] [blame] | 4967 | case x < 0: return -x |
| 4968 | default: return x |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4969 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4970 | |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 4971 | switch { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 4972 | case x < y: f1() |
| 4973 | case x < z: f2() |
| 4974 | case x == 4: f3() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 4975 | } |
| 4976 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 4977 | |
Robert Griesemer | 2d9378c | 2015-07-27 13:30:16 -0700 | [diff] [blame] | 4978 | <p> |
| 4979 | Implementation restriction: A compiler may disallow multiple case |
| 4980 | expressions evaluating to the same constant. |
| 4981 | For instance, the current compilers disallow duplicate integer, |
| 4982 | floating point, or string constants in case expressions. |
| 4983 | </p> |
| 4984 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 4985 | <h4 id="Type_switches">Type switches</h4> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4986 | |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 4987 | <p> |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 4988 | A type switch compares types rather than values. It is otherwise similar |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 4989 | to an expression switch. It is marked by a special switch expression that |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 4990 | has the form of a <a href="#Type_assertions">type assertion</a> |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 4991 | using the reserved word <code>type</code> rather than an actual type: |
| 4992 | </p> |
| 4993 | |
| 4994 | <pre> |
| 4995 | switch x.(type) { |
| 4996 | // cases |
| 4997 | } |
| 4998 | </pre> |
| 4999 | |
| 5000 | <p> |
| 5001 | Cases then match actual types <code>T</code> against the dynamic type of the |
| 5002 | expression <code>x</code>. As with type assertions, <code>x</code> must be of |
| 5003 | <a href="#Interface_types">interface type</a>, and each non-interface type |
| 5004 | <code>T</code> listed in a case must implement the type of <code>x</code>. |
Robert Griesemer | 3d81d4a | 2016-05-31 13:32:34 -0700 | [diff] [blame] | 5005 | The types listed in the cases of a type switch must all be |
| 5006 | <a href="#Type_identity">different</a>. |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5007 | </p> |
| 5008 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5009 | <pre class="ebnf"> |
Rob Pike | f3a33bc | 2009-09-14 17:39:17 -0700 | [diff] [blame] | 5010 | TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" . |
Russ Cox | c1045db | 2009-12-23 13:48:44 -0800 | [diff] [blame] | 5011 | TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 5012 | TypeCaseClause = TypeSwitchCase ":" StatementList . |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 5013 | TypeSwitchCase = "case" TypeList | "default" . |
| 5014 | TypeList = Type { "," Type } . |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5015 | </pre> |
| 5016 | |
| 5017 | <p> |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5018 | The TypeSwitchGuard may include a |
| 5019 | <a href="#Short_variable_declarations">short variable declaration</a>. |
Robert Griesemer | f8555ea | 2016-08-18 13:14:30 -0700 | [diff] [blame] | 5020 | When that form is used, the variable is declared at the end of the |
| 5021 | TypeSwitchCase in the <a href="#Blocks">implicit block</a> of each clause. |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5022 | In clauses with a case listing exactly one type, the variable |
| 5023 | has that type; otherwise, the variable has the type of the expression |
| 5024 | in the TypeSwitchGuard. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5025 | </p> |
| 5026 | |
| 5027 | <p> |
griesemer | 84ac90e | 2017-08-24 15:05:53 +0200 | [diff] [blame] | 5028 | Instead of a type, a case may use the predeclared identifier |
| 5029 | <a href="#Predeclared_identifiers"><code>nil</code></a>; |
| 5030 | that case is selected when the expression in the TypeSwitchGuard |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 5031 | is a <code>nil</code> interface value. |
Robert Griesemer | 3d81d4a | 2016-05-31 13:32:34 -0700 | [diff] [blame] | 5032 | There may be at most one <code>nil</code> case. |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5033 | </p> |
| 5034 | |
| 5035 | <p> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 5036 | Given an expression <code>x</code> of type <code>interface{}</code>, |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 5037 | the following type switch: |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5038 | </p> |
| 5039 | |
| 5040 | <pre> |
Robert Griesemer | e919275 | 2009-12-01 16:15:53 -0800 | [diff] [blame] | 5041 | switch i := x.(type) { |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5042 | case nil: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5043 | printString("x is nil") // type of i is type of x (interface{}) |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5044 | case int: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5045 | printInt(i) // type of i is int |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5046 | case float64: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5047 | printFloat64(i) // type of i is float64 |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5048 | case func(int) float64: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5049 | printFunction(i) // type of i is func(int) float64 |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5050 | case bool, string: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5051 | printString("type is bool or string") // type of i is type of x (interface{}) |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5052 | default: |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5053 | printString("don't know the type") // type of i is type of x (interface{}) |
Rob Pike | 5a57849 | 2009-03-17 16:48:35 -0700 | [diff] [blame] | 5054 | } |
| 5055 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5056 | |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 5057 | <p> |
| 5058 | could be rewritten: |
| 5059 | </p> |
| 5060 | |
| 5061 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5062 | v := x // x is evaluated exactly once |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5063 | if v == nil { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5064 | i := v // type of i is type of x (interface{}) |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5065 | printString("x is nil") |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5066 | } else if i, isInt := v.(int); isInt { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5067 | printInt(i) // type of i is int |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5068 | } else if i, isFloat64 := v.(float64); isFloat64 { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5069 | printFloat64(i) // type of i is float64 |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5070 | } else if i, isFunc := v.(func(int) float64); isFunc { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5071 | printFunction(i) // type of i is func(int) float64 |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 5072 | } else { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5073 | _, isBool := v.(bool) |
| 5074 | _, isString := v.(string) |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5075 | if isBool || isString { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5076 | i := v // type of i is type of x (interface{}) |
| 5077 | printString("type is bool or string") |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5078 | } else { |
Robert Griesemer | 4856731 | 2012-12-06 09:17:20 -0800 | [diff] [blame] | 5079 | i := v // type of i is type of x (interface{}) |
| 5080 | printString("don't know the type") |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5081 | } |
Rob Pike | 70c1a10 | 2009-03-18 19:23:59 -0700 | [diff] [blame] | 5082 | } |
| 5083 | </pre> |
| 5084 | |
Robert Griesemer | aeaab59 | 2009-08-31 17:30:55 -0700 | [diff] [blame] | 5085 | <p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 5086 | The type switch guard may be preceded by a simple statement, which |
| 5087 | executes before the guard is evaluated. |
Robert Griesemer | 1f95f0d | 2009-08-27 16:44:17 -0700 | [diff] [blame] | 5088 | </p> |
Robert Griesemer | 9ecd30a | 2009-08-27 14:22:51 -0700 | [diff] [blame] | 5089 | |
| 5090 | <p> |
| 5091 | The "fallthrough" statement is not permitted in a type switch. |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 5092 | </p> |
| 5093 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5094 | <h3 id="For_statements">For statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5095 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5096 | <p> |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 5097 | A "for" statement specifies repeated execution of a block. There are three forms: |
| 5098 | The iteration may be controlled by a single condition, a "for" clause, or a "range" clause. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5099 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5100 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5101 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5102 | ForStmt = "for" [ Condition | ForClause | RangeClause ] Block . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5103 | Condition = Expression . |
| 5104 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5105 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 5106 | <h4 id="For_condition">For statements with single condition</h4> |
| 5107 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5108 | <p> |
| 5109 | In its simplest form, a "for" statement specifies the repeated execution of |
| 5110 | a block as long as a boolean condition evaluates to true. |
| 5111 | The condition is evaluated before each iteration. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 5112 | If the condition is absent, it is equivalent to the boolean value |
| 5113 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5114 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5115 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5116 | <pre> |
| 5117 | for a < b { |
| 5118 | a *= 2 |
| 5119 | } |
| 5120 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5121 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 5122 | <h4 id="For_clause">For statements with <code>for</code> clause</h4> |
| 5123 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5124 | <p> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 5125 | A "for" statement with a ForClause is also controlled by its condition, but |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5126 | additionally it may specify an <i>init</i> |
| 5127 | and a <i>post</i> statement, such as an assignment, |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 5128 | an increment or decrement statement. The init statement may be a |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 5129 | <a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not. |
Robert Griesemer | 2fa3e43f | 2014-09-25 12:52:05 -0700 | [diff] [blame] | 5130 | Variables declared by the init statement are re-used in each iteration. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5131 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5132 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5133 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5134 | ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] . |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5135 | InitStmt = SimpleStmt . |
| 5136 | PostStmt = SimpleStmt . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5137 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5138 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5139 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5140 | for i := 0; i < 10; i++ { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5141 | f(i) |
| 5142 | } |
| 5143 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 5144 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5145 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5146 | If non-empty, the init statement is executed once before evaluating the |
| 5147 | condition for the first iteration; |
| 5148 | the post statement is executed after each execution of the block (and |
| 5149 | only if the block was executed). |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5150 | Any element of the ForClause may be empty but the |
| 5151 | <a href="#Semicolons">semicolons</a> are |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5152 | required unless there is only a condition. |
Robert Griesemer | ab26623 | 2014-02-25 09:13:37 -0800 | [diff] [blame] | 5153 | If the condition is absent, it is equivalent to the boolean value |
| 5154 | <code>true</code>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5155 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5156 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5157 | <pre> |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 5158 | for cond { S() } is the same as for ; cond ; { S() } |
| 5159 | for { S() } is the same as for true { S() } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5160 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5161 | |
Robert Griesemer | b01f612 | 2016-11-18 10:49:29 -0800 | [diff] [blame] | 5162 | <h4 id="For_range">For statements with <code>range</code> clause</h4> |
| 5163 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5164 | <p> |
| 5165 | A "for" statement with a "range" clause |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5166 | iterates through all entries of an array, slice, string or map, |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5167 | or values received on a channel. For each entry it assigns <i>iteration values</i> |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5168 | to corresponding <i>iteration variables</i> if present and then executes the block. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5169 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5170 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5171 | <pre class="ebnf"> |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5172 | RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5173 | </pre> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5174 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5175 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5176 | The expression on the right in the "range" clause is called the <i>range expression</i>, |
Robert Griesemer | cc3f21c | 2012-12-03 14:23:41 -0800 | [diff] [blame] | 5177 | which may be an array, pointer to an array, slice, string, map, or channel permitting |
| 5178 | <a href="#Receive_operator">receive operations</a>. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5179 | As with an assignment, if present the operands on the left must be |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5180 | <a href="#Address_operators">addressable</a> or map index expressions; they |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5181 | denote the iteration variables. If the range expression is a channel, at most |
| 5182 | one iteration variable is permitted, otherwise there may be up to two. |
| 5183 | If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>, |
| 5184 | the range clause is equivalent to the same clause without that identifier. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5185 | </p> |
Rob Pike | 29d0f02 | 2011-01-05 11:39:57 -0800 | [diff] [blame] | 5186 | |
| 5187 | <p> |
griesemer | ada6557 | 2017-10-17 15:30:12 -0700 | [diff] [blame] | 5188 | The range expression <code>x</code> is evaluated once before beginning the loop, |
| 5189 | with one exception: if at most one iteration variable is present and |
| 5190 | <code>len(x)</code> is <a href="#Length_and_capacity">constant</a>, |
| 5191 | the range expression is not evaluated. |
Russ Cox | 61e02ee | 2013-02-15 14:39:28 -0500 | [diff] [blame] | 5192 | </p> |
| 5193 | |
| 5194 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5195 | Function calls on the left are evaluated once per iteration. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5196 | For each iteration, iteration values are produced as follows |
| 5197 | if the respective iteration variables are present: |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5198 | </p> |
| 5199 | |
| 5200 | <pre class="grammar"> |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5201 | Range expression 1st value 2nd value |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5202 | |
| 5203 | array or slice a [n]E, *[n]E, or []E index i int a[i] E |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 5204 | string s string type index i int see below rune |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5205 | map m map[K]V key k K m[k] V |
Shenghou Ma | ced5715 | 2013-01-17 23:11:25 +0800 | [diff] [blame] | 5206 | channel c chan E, <-chan E element e E |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5207 | </pre> |
| 5208 | |
| 5209 | <ol> |
| 5210 | <li> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5211 | For an array, pointer to array, or slice value <code>a</code>, the index iteration |
Russ Cox | 61e02ee | 2013-02-15 14:39:28 -0500 | [diff] [blame] | 5212 | values are produced in increasing order, starting at element index 0. |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5213 | If at most one iteration variable is present, the range loop produces |
Robert Griesemer | bb3a32e | 2013-05-20 13:27:53 -0700 | [diff] [blame] | 5214 | iteration values from 0 up to <code>len(a)-1</code> and does not index into the array |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5215 | or slice itself. For a <code>nil</code> slice, the number of iterations is 0. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5216 | </li> |
| 5217 | |
| 5218 | <li> |
| 5219 | For a string value, the "range" clause iterates over the Unicode code points |
| 5220 | in the string starting at byte index 0. On successive iterations, the index value will be the |
| 5221 | index of the first byte of successive UTF-8-encoded code points in the string, |
Robert Griesemer | b910a27 | 2011-11-01 01:09:22 -0400 | [diff] [blame] | 5222 | and the second value, of type <code>rune</code>, will be the value of |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5223 | the corresponding code point. If the iteration encounters an invalid |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5224 | UTF-8 sequence, the second value will be <code>0xFFFD</code>, |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5225 | the Unicode replacement character, and the next iteration will advance |
| 5226 | a single byte in the string. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5227 | </li> |
| 5228 | |
| 5229 | <li> |
Russ Cox | e40d6e0 | 2011-10-17 18:49:02 -0400 | [diff] [blame] | 5230 | The iteration order over maps is not specified |
| 5231 | and is not guaranteed to be the same from one iteration to the next. |
Robert Griesemer | 4e9c86a | 2017-06-28 10:15:24 -0700 | [diff] [blame] | 5232 | If a map entry that has not yet been reached is removed during iteration, |
| 5233 | the corresponding iteration value will not be produced. If a map entry is |
Shenghou Ma | ced5715 | 2013-01-17 23:11:25 +0800 | [diff] [blame] | 5234 | created during iteration, that entry may be produced during the iteration or |
| 5235 | may be skipped. The choice may vary for each entry created and from one |
| 5236 | iteration to the next. |
| 5237 | If the map is <code>nil</code>, the number of iterations is 0. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5238 | </li> |
| 5239 | |
| 5240 | <li> |
| 5241 | For channels, the iteration values produced are the successive values sent on |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5242 | the channel until the channel is <a href="#Close">closed</a>. If the channel |
| 5243 | is <code>nil</code>, the range expression blocks forever. |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5244 | </li> |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 5245 | </ol> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5246 | |
Rob Pike | 7aee71b | 2009-04-15 20:28:25 -0700 | [diff] [blame] | 5247 | <p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5248 | The iteration values are assigned to the respective |
| 5249 | iteration variables as in an <a href="#Assignments">assignment statement</a>. |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5250 | </p> |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5251 | |
Rob Pike | 94b67eb | 2009-03-24 17:40:47 -0700 | [diff] [blame] | 5252 | <p> |
Robert Griesemer | da63371 | 2012-02-29 09:06:05 -0800 | [diff] [blame] | 5253 | The iteration variables may be declared by the "range" clause using a form of |
Robert Griesemer | 2c9e163 | 2012-02-28 17:44:24 -0800 | [diff] [blame] | 5254 | <a href="#Short_variable_declarations">short variable declaration</a> |
| 5255 | (<code>:=</code>). |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5256 | In this case their types are set to the types of the respective iteration values |
Robert Griesemer | 2fa3e43f | 2014-09-25 12:52:05 -0700 | [diff] [blame] | 5257 | and their <a href="#Declarations_and_scope">scope</a> is the block of the "for" |
Robert Griesemer | 5474e16 | 2010-09-28 14:44:19 -0700 | [diff] [blame] | 5258 | statement; they are re-used in each iteration. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5259 | If the iteration variables are declared outside the "for" statement, |
| 5260 | after execution their values will be those of the last iteration. |
| 5261 | </p> |
Robert Griesemer | 30a1a8c | 2008-12-16 11:38:56 -0800 | [diff] [blame] | 5262 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5263 | <pre> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5264 | var testdata *struct { |
| 5265 | a *[7]int |
| 5266 | } |
| 5267 | for i, _ := range testdata.a { |
| 5268 | // testdata.a is never evaluated; len(testdata.a) is constant |
| 5269 | // i ranges from 0 to 6 |
| 5270 | f(i) |
| 5271 | } |
| 5272 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5273 | var a [10]string |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5274 | for i, s := range a { |
| 5275 | // type of i is int |
| 5276 | // type of s is string |
| 5277 | // s == a[i] |
| 5278 | g(i, s) |
| 5279 | } |
| 5280 | |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5281 | var key string |
Robert Griesemer | 9ead772 | 2020-01-13 13:01:28 -0800 | [diff] [blame] | 5282 | var val interface{} // element type of m is assignable to val |
Robert Griesemer | 63f54ae | 2013-07-11 14:41:46 -0700 | [diff] [blame] | 5283 | m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6} |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 5284 | for key, val = range m { |
| 5285 | h(key, val) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5286 | } |
| 5287 | // key == last map key encountered in iteration |
| 5288 | // val == map[key] |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5289 | |
| 5290 | var ch chan Work = producer() |
| 5291 | for w := range ch { |
| 5292 | doWork(w) |
| 5293 | } |
Robert Griesemer | 20ae6d9 | 2014-07-14 15:08:09 -0700 | [diff] [blame] | 5294 | |
| 5295 | // empty a channel |
| 5296 | for range ch {} |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5297 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5298 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5299 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5300 | <h3 id="Go_statements">Go statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5301 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5302 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5303 | A "go" statement starts the execution of a function call |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5304 | as an independent concurrent thread of control, or <i>goroutine</i>, |
| 5305 | within the same address space. |
| 5306 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5307 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5308 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5309 | GoStmt = "go" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5310 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5311 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5312 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5313 | The expression must be a function or method call; it cannot be parenthesized. |
| 5314 | Calls of built-in functions are restricted as for |
| 5315 | <a href="#Expression_statements">expression statements</a>. |
| 5316 | </p> |
| 5317 | |
| 5318 | <p> |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5319 | The function value and parameters are |
| 5320 | <a href="#Calls">evaluated as usual</a> |
| 5321 | in the calling goroutine, but |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5322 | unlike with a regular call, program execution does not wait |
Robert Griesemer | b9f8b9c | 2008-09-26 13:38:38 -0700 | [diff] [blame] | 5323 | for the invoked function to complete. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5324 | Instead, the function begins executing independently |
| 5325 | in a new goroutine. |
| 5326 | When the function terminates, its goroutine also terminates. |
| 5327 | If the function has any return values, they are discarded when the |
| 5328 | function completes. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5329 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5330 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5331 | <pre> |
| 5332 | go Server() |
Brad Fitzpatrick | e963510 | 2017-05-04 02:39:56 +0000 | [diff] [blame] | 5333 | go func(ch chan<- bool) { for { sleep(10); ch <- true }} (c) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5334 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5335 | |
| 5336 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5337 | <h3 id="Select_statements">Select statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5338 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5339 | <p> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5340 | A "select" statement chooses which of a set of possible |
| 5341 | <a href="#Send_statements">send</a> or |
| 5342 | <a href="#Receive_operator">receive</a> |
| 5343 | operations will proceed. |
| 5344 | It looks similar to a |
| 5345 | <a href="#Switch_statements">"switch"</a> statement but with the |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5346 | cases all referring to communication operations. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5347 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5348 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5349 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5350 | SelectStmt = "select" "{" { CommClause } "}" . |
Robert Griesemer | 9905cec | 2013-03-04 13:55:35 -0800 | [diff] [blame] | 5351 | CommClause = CommCase ":" StatementList . |
Robert Griesemer | b50ed02 | 2011-02-01 12:02:49 -0800 | [diff] [blame] | 5352 | CommCase = "case" ( SendStmt | RecvStmt ) | "default" . |
Robert Griesemer | d367972 | 2013-01-18 13:59:25 -0800 | [diff] [blame] | 5353 | RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr . |
Robert Griesemer | c134718 | 2011-04-29 12:20:31 -0700 | [diff] [blame] | 5354 | RecvExpr = Expression . |
Russ Cox | 6143918 | 2011-01-31 17:42:10 -0500 | [diff] [blame] | 5355 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5356 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5357 | <p> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5358 | A case with a RecvStmt may assign the result of a RecvExpr to one or |
| 5359 | two variables, which may be declared using a |
Robert Griesemer | 4ed666e | 2009-08-27 16:45:42 -0700 | [diff] [blame] | 5360 | <a href="#Short_variable_declarations">short variable declaration</a>. |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5361 | The RecvExpr must be a (possibly parenthesized) receive operation. |
| 5362 | There can be at most one default case and it may appear anywhere |
| 5363 | in the list of cases. |
| 5364 | </p> |
| 5365 | |
| 5366 | <p> |
| 5367 | Execution of a "select" statement proceeds in several steps: |
| 5368 | </p> |
| 5369 | |
| 5370 | <ol> |
| 5371 | <li> |
| 5372 | For all the cases in the statement, the channel operands of receive operations |
| 5373 | and the channel and right-hand-side expressions of send statements are |
| 5374 | evaluated exactly once, in source order, upon entering the "select" statement. |
| 5375 | The result is a set of channels to receive from or send to, |
| 5376 | and the corresponding values to send. |
| 5377 | Any side effects in that evaluation will occur irrespective of which (if any) |
| 5378 | communication operation is selected to proceed. |
| 5379 | Expressions on the left-hand side of a RecvStmt with a short variable declaration |
| 5380 | or assignment are not yet evaluated. |
| 5381 | </li> |
| 5382 | |
| 5383 | <li> |
| 5384 | If one or more of the communications can proceed, |
| 5385 | a single one that can proceed is chosen via a uniform pseudo-random selection. |
| 5386 | Otherwise, if there is a default case, that case is chosen. |
| 5387 | If there is no default case, the "select" statement blocks until |
| 5388 | at least one of the communications can proceed. |
| 5389 | </li> |
| 5390 | |
| 5391 | <li> |
| 5392 | Unless the selected case is the default case, the respective communication |
| 5393 | operation is executed. |
| 5394 | </li> |
| 5395 | |
| 5396 | <li> |
| 5397 | If the selected case is a RecvStmt with a short variable declaration or |
| 5398 | an assignment, the left-hand side expressions are evaluated and the |
| 5399 | received value (or values) are assigned. |
| 5400 | </li> |
| 5401 | |
| 5402 | <li> |
| 5403 | The statement list of the selected case is executed. |
| 5404 | </li> |
| 5405 | </ol> |
| 5406 | |
| 5407 | <p> |
| 5408 | Since communication on <code>nil</code> channels can never proceed, |
| 5409 | a select with only <code>nil</code> channels and no default case blocks forever. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5410 | </p> |
Robert Griesemer | 2902a82 | 2008-09-17 13:57:11 -0700 | [diff] [blame] | 5411 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5412 | <pre> |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5413 | var a []int |
| 5414 | var c, c1, c2, c3, c4 chan int |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5415 | var i1, i2 int |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5416 | select { |
| 5417 | case i1 = <-c1: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5418 | print("received ", i1, " from c1\n") |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5419 | case c2 <- i2: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5420 | print("sent ", i2, " to c2\n") |
Robert Griesemer | 6af887e | 2011-05-02 09:16:31 -0700 | [diff] [blame] | 5421 | case i3, ok := (<-c3): // same as: i3, ok := <-c3 |
Russ Cox | 19d9a40 | 2011-01-27 15:34:28 -0500 | [diff] [blame] | 5422 | if ok { |
| 5423 | print("received ", i3, " from c3\n") |
| 5424 | } else { |
| 5425 | print("c3 is closed\n") |
| 5426 | } |
Robert Griesemer | 61d8a33 | 2014-05-14 11:47:19 -0700 | [diff] [blame] | 5427 | case a[f()] = <-c4: |
| 5428 | // same as: |
| 5429 | // case t := <-c4 |
| 5430 | // a[f()] = t |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5431 | default: |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5432 | print("no communication\n") |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5433 | } |
| 5434 | |
| 5435 | for { // send random sequence of bits to c |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5436 | select { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5437 | case c <- 0: // note: no statement, no fallthrough, no folding of cases |
| 5438 | case c <- 1: |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5439 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5440 | } |
Rob Pike | 041d116 | 2010-07-13 16:23:54 -0700 | [diff] [blame] | 5441 | |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5442 | select {} // block forever |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5443 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5444 | |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5445 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5446 | <h3 id="Return_statements">Return statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5447 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5448 | <p> |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5449 | A "return" statement in a function <code>F</code> terminates the execution |
| 5450 | of <code>F</code>, and optionally provides one or more result values. |
| 5451 | Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> |
| 5452 | are executed before <code>F</code> returns to its caller. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5453 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5454 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5455 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5456 | ReturnStmt = "return" [ ExpressionList ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5457 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5458 | |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5459 | <p> |
| 5460 | In a function without a result type, a "return" statement must not |
| 5461 | specify any result values. |
| 5462 | </p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5463 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5464 | func noResult() { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5465 | return |
| 5466 | } |
| 5467 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5468 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5469 | <p> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5470 | There are three ways to return values from a function with a result |
| 5471 | type: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5472 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5473 | |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5474 | <ol> |
| 5475 | <li>The return value or values may be explicitly listed |
| 5476 | in the "return" statement. Each expression must be single-valued |
Robert Griesemer | 440cc95 | 2010-06-07 17:40:21 -0700 | [diff] [blame] | 5477 | and <a href="#Assignability">assignable</a> |
| 5478 | to the corresponding element of the function's result type. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5479 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5480 | func simpleF() int { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5481 | return 2 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5482 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5483 | |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5484 | func complexF1() (re float64, im float64) { |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5485 | return -7.0, -4.0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5486 | } |
| 5487 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5488 | </li> |
| 5489 | <li>The expression list in the "return" statement may be a single |
| 5490 | call to a multi-valued function. The effect is as if each value |
| 5491 | returned from that function were assigned to a temporary |
| 5492 | variable with the type of the respective value, followed by a |
| 5493 | "return" statement listing these variables, at which point the |
| 5494 | rules of the previous case apply. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5495 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5496 | func complexF2() (re float64, im float64) { |
| 5497 | return complexF1() |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5498 | } |
| 5499 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5500 | </li> |
Peter Mundy | 5928e1d | 2010-11-09 10:10:57 -0800 | [diff] [blame] | 5501 | <li>The expression list may be empty if the function's result |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5502 | type specifies names for its <a href="#Function_types">result parameters</a>. |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5503 | The result parameters act as ordinary local variables |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5504 | and the function may assign values to them as necessary. |
| 5505 | The "return" statement returns the values of these variables. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5506 | <pre> |
Russ Cox | 9c08d65 | 2012-02-21 22:04:30 -0500 | [diff] [blame] | 5507 | func complexF3() (re float64, im float64) { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5508 | re = 7.0 |
| 5509 | im = 4.0 |
| 5510 | return |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5511 | } |
Robert Griesemer | fb64e0d | 2011-03-07 16:29:07 -0800 | [diff] [blame] | 5512 | |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 5513 | func (devnull) Write(p []byte) (n int, _ error) { |
Robert Griesemer | fb64e0d | 2011-03-07 16:29:07 -0800 | [diff] [blame] | 5514 | n = len(p) |
| 5515 | return |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 5516 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5517 | </pre> |
Robert Griesemer | 4b90833 | 2009-08-07 17:05:41 -0700 | [diff] [blame] | 5518 | </li> |
| 5519 | </ol> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5520 | |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5521 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5522 | Regardless of how they are declared, all the result values are initialized to |
| 5523 | the <a href="#The_zero_value">zero values</a> for their type upon entry to the |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5524 | function. A "return" statement that specifies results sets the result parameters before |
| 5525 | any deferred functions are executed. |
Rob Pike | db8c2b18 | 2010-06-11 21:30:03 -0700 | [diff] [blame] | 5526 | </p> |
| 5527 | |
Robert Griesemer | c97778f | 2014-03-05 11:59:53 -0800 | [diff] [blame] | 5528 | <p> |
| 5529 | Implementation restriction: A compiler may disallow an empty expression list |
| 5530 | in a "return" statement if a different entity (constant, type, or variable) |
| 5531 | with the same name as a result parameter is in |
| 5532 | <a href="#Declarations_and_scope">scope</a> at the place of the return. |
| 5533 | </p> |
| 5534 | |
| 5535 | <pre> |
| 5536 | func f(n int) (res int, err error) { |
| 5537 | if _, err := f(n-1); err != nil { |
| 5538 | return // invalid return statement: err is shadowed |
| 5539 | } |
| 5540 | return |
| 5541 | } |
| 5542 | </pre> |
Russ Cox | 5958dd6 | 2009-03-04 17:19:21 -0800 | [diff] [blame] | 5543 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5544 | <h3 id="Break_statements">Break statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5545 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5546 | <p> |
| 5547 | A "break" statement terminates execution of the innermost |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5548 | <a href="#For_statements">"for"</a>, |
| 5549 | <a href="#Switch_statements">"switch"</a>, or |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5550 | <a href="#Select_statements">"select"</a> statement |
| 5551 | within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5552 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5553 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5554 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5555 | BreakStmt = "break" [ Label ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5556 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5557 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5558 | <p> |
| 5559 | If there is a label, it must be that of an enclosing |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5560 | "for", "switch", or "select" statement, |
| 5561 | and that is the one whose execution terminates. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5562 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5563 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5564 | <pre> |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 5565 | OuterLoop: |
| 5566 | for i = 0; i < n; i++ { |
| 5567 | for j = 0; j < m; j++ { |
| 5568 | switch a[i][j] { |
| 5569 | case nil: |
| 5570 | state = Error |
| 5571 | break OuterLoop |
| 5572 | case item: |
| 5573 | state = Found |
| 5574 | break OuterLoop |
| 5575 | } |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 5576 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5577 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5578 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5579 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5580 | <h3 id="Continue_statements">Continue statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5581 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5582 | <p> |
| 5583 | A "continue" statement begins the next iteration of the |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5584 | innermost <a href="#For_statements">"for" loop</a> at its post statement. |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5585 | The "for" loop must be within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5586 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5587 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5588 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5589 | ContinueStmt = "continue" [ Label ] . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5590 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5591 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5592 | <p> |
Rob Pike | de921996 | 2010-04-28 13:18:40 -0700 | [diff] [blame] | 5593 | If there is a label, it must be that of an enclosing |
| 5594 | "for" statement, and that is the one whose execution |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5595 | advances. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5596 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5597 | |
Rob Pike | cec0954 | 2013-09-17 07:41:11 +1000 | [diff] [blame] | 5598 | <pre> |
| 5599 | RowLoop: |
| 5600 | for y, row := range rows { |
| 5601 | for x, data := range row { |
| 5602 | if data == endOfRow { |
| 5603 | continue RowLoop |
| 5604 | } |
| 5605 | row[x] = data + bias(x, y) |
| 5606 | } |
| 5607 | } |
| 5608 | </pre> |
| 5609 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5610 | <h3 id="Goto_statements">Goto statements</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5611 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5612 | <p> |
Robert Griesemer | 94849d5 | 2014-05-28 08:43:47 -0700 | [diff] [blame] | 5613 | A "goto" statement transfers control to the statement with the corresponding label |
| 5614 | within the same function. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5615 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5616 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5617 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5618 | GotoStmt = "goto" Label . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5619 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5620 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5621 | <pre> |
| 5622 | goto Error |
| 5623 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5624 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5625 | <p> |
| 5626 | Executing the "goto" statement must not cause any variables to come into |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5627 | <a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto. |
| 5628 | For instance, this example: |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5629 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5630 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5631 | <pre> |
Russ Cox | 108564d | 2011-03-15 13:51:24 -0400 | [diff] [blame] | 5632 | goto L // BAD |
| 5633 | v := 3 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5634 | L: |
| 5635 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5636 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5637 | <p> |
| 5638 | is erroneous because the jump to label <code>L</code> skips |
| 5639 | the creation of <code>v</code>. |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5640 | </p> |
| 5641 | |
| 5642 | <p> |
| 5643 | A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block. |
| 5644 | For instance, this example: |
| 5645 | </p> |
| 5646 | |
| 5647 | <pre> |
| 5648 | if n%2 == 1 { |
| 5649 | goto L1 |
| 5650 | } |
| 5651 | for n > 0 { |
| 5652 | f() |
| 5653 | n-- |
| 5654 | L1: |
| 5655 | f() |
| 5656 | n-- |
| 5657 | } |
| 5658 | </pre> |
| 5659 | |
| 5660 | <p> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 5661 | is erroneous because the label <code>L1</code> is inside |
Russ Cox | f4c7db0 | 2011-06-17 12:49:04 -0400 | [diff] [blame] | 5662 | the "for" statement's block but the <code>goto</code> is not. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5663 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5664 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5665 | <h3 id="Fallthrough_statements">Fallthrough statements</h3> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5666 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5667 | <p> |
| 5668 | A "fallthrough" statement transfers control to the first statement of the |
Shenghou Ma | ca9876d | 2015-12-31 11:25:51 -0500 | [diff] [blame] | 5669 | next case clause in an <a href="#Expression_switches">expression "switch" statement</a>. |
Robert Griesemer | 67a6b4f | 2013-03-01 16:45:14 -0800 | [diff] [blame] | 5670 | It may be used only as the final non-empty statement in such a clause. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5671 | </p> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5672 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5673 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5674 | FallthroughStmt = "fallthrough" . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5675 | </pre> |
Robert Griesemer | aed247f | 2008-10-08 17:05:30 -0700 | [diff] [blame] | 5676 | |
| 5677 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5678 | <h3 id="Defer_statements">Defer statements</h3> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5679 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5680 | <p> |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5681 | A "defer" statement invokes a function whose execution is deferred |
| 5682 | to the moment the surrounding function returns, either because the |
| 5683 | surrounding function executed a <a href="#Return_statements">return statement</a>, |
| 5684 | reached the end of its <a href="#Function_declarations">function body</a>, |
| 5685 | or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5686 | </p> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5687 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 5688 | <pre class="ebnf"> |
Rob Pike | 1141716 | 2009-03-24 17:45:53 -0700 | [diff] [blame] | 5689 | DeferStmt = "defer" Expression . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5690 | </pre> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5691 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5692 | <p> |
Robert Griesemer | 25dd002 | 2012-11-29 11:46:25 -0800 | [diff] [blame] | 5693 | The expression must be a function or method call; it cannot be parenthesized. |
| 5694 | Calls of built-in functions are restricted as for |
| 5695 | <a href="#Expression_statements">expression statements</a>. |
| 5696 | </p> |
| 5697 | |
| 5698 | <p> |
Robert Griesemer | b4eb22d | 2014-09-19 13:32:07 -0700 | [diff] [blame] | 5699 | Each time a "defer" statement |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5700 | executes, the function value and parameters to the call are |
| 5701 | <a href="#Calls">evaluated as usual</a> |
Robert Griesemer | b4eb22d | 2014-09-19 13:32:07 -0700 | [diff] [blame] | 5702 | and saved anew but the actual function is not invoked. |
| 5703 | Instead, deferred functions are invoked immediately before |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5704 | the surrounding function returns, in the reverse order |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5705 | they were deferred. That is, if the surrounding function |
| 5706 | returns through an explicit <a href="#Return_statements">return statement</a>, |
| 5707 | deferred functions are executed <i>after</i> any result parameters are set |
| 5708 | by that return statement but <i>before</i> the function returns to its caller. |
Robert Griesemer | b4eb22d | 2014-09-19 13:32:07 -0700 | [diff] [blame] | 5709 | If a deferred function value evaluates |
| 5710 | to <code>nil</code>, execution <a href="#Handling_panics">panics</a> |
Rob Pike | 651bb8e | 2014-09-19 14:13:51 -0700 | [diff] [blame] | 5711 | when the function is invoked, not when the "defer" statement is executed. |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 5712 | </p> |
| 5713 | |
| 5714 | <p> |
| 5715 | For instance, if the deferred function is |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 5716 | a <a href="#Function_literals">function literal</a> and the surrounding |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5717 | function has <a href="#Function_types">named result parameters</a> that |
| 5718 | are in scope within the literal, the deferred function may access and modify |
| 5719 | the result parameters before they are returned. |
Rob Pike | 633a2ce | 2012-01-23 08:40:13 -0800 | [diff] [blame] | 5720 | If the deferred function has any return values, they are discarded when |
| 5721 | the function completes. |
Rob Pike | 15970c8 | 2012-10-16 11:27:20 +1100 | [diff] [blame] | 5722 | (See also the section on <a href="#Handling_panics">handling panics</a>.) |
| 5723 | </p> |
| 5724 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5725 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5726 | lock(l) |
| 5727 | defer unlock(l) // unlocking happens before surrounding function returns |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5728 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5729 | // prints 3 2 1 0 before surrounding function returns |
| 5730 | for i := 0; i <= 3; i++ { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5731 | defer fmt.Print(i) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5732 | } |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5733 | |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5734 | // f returns 42 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5735 | func f() (result int) { |
| 5736 | defer func() { |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5737 | // result is accessed after it was set to 6 by the return statement |
| 5738 | result *= 7 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5739 | }() |
Robert Griesemer | 206fd78 | 2018-09-21 21:03:35 -0700 | [diff] [blame] | 5740 | return 6 |
Robert Griesemer | 48f0cd2 | 2010-03-23 17:30:14 -0700 | [diff] [blame] | 5741 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5742 | </pre> |
Robert Griesemer | 4a903e0 | 2009-01-27 09:29:40 -0800 | [diff] [blame] | 5743 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5744 | <h2 id="Built-in_functions">Built-in functions</h2> |
| 5745 | |
| 5746 | <p> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 5747 | Built-in functions are |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5748 | <a href="#Predeclared_identifiers">predeclared</a>. |
| 5749 | They are called like any other function but some of them |
| 5750 | accept a type instead of an expression as the first argument. |
| 5751 | </p> |
| 5752 | |
Russ Cox | 2a5f0c6 | 2009-12-04 10:23:12 -0800 | [diff] [blame] | 5753 | <p> |
| 5754 | The built-in functions do not have standard Go types, |
| 5755 | so they can only appear in <a href="#Calls">call expressions</a>; |
| 5756 | they cannot be used as function values. |
| 5757 | </p> |
| 5758 | |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 5759 | <h3 id="Close">Close</h3> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5760 | |
| 5761 | <p> |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5762 | For a channel <code>c</code>, the built-in function <code>close(c)</code> |
Russ Cox | f58ed4e | 2011-10-13 16:58:04 -0400 | [diff] [blame] | 5763 | records that no more values will be sent on the channel. |
| 5764 | It is an error if <code>c</code> is a receive-only channel. |
| 5765 | Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>. |
| 5766 | Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>. |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5767 | After calling <code>close</code>, and after any previously |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5768 | sent values have been received, receive operations will return |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5769 | the zero value for the channel's type without blocking. |
Russ Cox | 9f2cb86 | 2011-03-11 14:47:02 -0500 | [diff] [blame] | 5770 | The multi-valued <a href="#Receive_operator">receive operation</a> |
| 5771 | returns a received value along with an indication of whether the channel is closed. |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5772 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5773 | |
Robert Griesemer | dc60c5a | 2010-07-14 16:09:22 -0700 | [diff] [blame] | 5774 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5775 | <h3 id="Length_and_capacity">Length and capacity</h3> |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 5776 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5777 | <p> |
| 5778 | The built-in functions <code>len</code> and <code>cap</code> take arguments |
| 5779 | of various types and return a result of type <code>int</code>. |
| 5780 | The implementation guarantees that the result always fits into an <code>int</code>. |
| 5781 | </p> |
| 5782 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 5783 | <pre class="grammar"> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5784 | Call Argument type Result |
Robert Griesemer | 7a4ed4f | 2008-09-03 15:15:51 -0700 | [diff] [blame] | 5785 | |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5786 | len(s) string type string length in bytes |
| 5787 | [n]T, *[n]T array length (== n) |
| 5788 | []T slice length |
| 5789 | map[K]T map length (number of defined keys) |
| 5790 | chan T number of elements queued in channel buffer |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5791 | |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5792 | cap(s) [n]T, *[n]T array length (== n) |
| 5793 | []T slice capacity |
| 5794 | chan T channel buffer capacity |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5795 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5796 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5797 | <p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5798 | The capacity of a slice is the number of elements for which there is |
| 5799 | space allocated in the underlying array. |
| 5800 | At any time the following relationship holds: |
| 5801 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5802 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5803 | <pre> |
Anthony Martin | 0122a66 | 2011-02-08 14:51:15 -0800 | [diff] [blame] | 5804 | 0 <= len(s) <= cap(s) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5805 | </pre> |
Robert Griesemer | 667ef6c | 2008-09-10 13:00:32 -0700 | [diff] [blame] | 5806 | |
Russ Cox | f442918 | 2010-07-01 17:49:47 -0700 | [diff] [blame] | 5807 | <p> |
Shenghou Ma | a0b5b46 | 2013-01-22 03:18:20 +0800 | [diff] [blame] | 5808 | The length of a <code>nil</code> slice, map or channel is 0. |
Rob Pike | 82e2db7 | 2014-01-04 10:52:59 -0800 | [diff] [blame] | 5809 | The capacity of a <code>nil</code> slice or channel is 0. |
Robert Griesemer | 0c2e6b3 | 2010-07-13 11:54:57 -0700 | [diff] [blame] | 5810 | </p> |
| 5811 | |
| 5812 | <p> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5813 | The expression <code>len(s)</code> is <a href="#Constants">constant</a> if |
| 5814 | <code>s</code> is a string constant. The expressions <code>len(s)</code> and |
| 5815 | <code>cap(s)</code> are constants if the type of <code>s</code> is an array |
| 5816 | or pointer to an array and the expression <code>s</code> does not contain |
Robert Griesemer | 8716981 | 2014-03-03 20:07:34 -0800 | [diff] [blame] | 5817 | <a href="#Receive_operator">channel receives</a> or (non-constant) |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5818 | <a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated. |
| 5819 | Otherwise, invocations of <code>len</code> and <code>cap</code> are not |
| 5820 | constant and <code>s</code> is evaluated. |
Russ Cox | f442918 | 2010-07-01 17:49:47 -0700 | [diff] [blame] | 5821 | </p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5822 | |
Robert Griesemer | 8716981 | 2014-03-03 20:07:34 -0800 | [diff] [blame] | 5823 | <pre> |
| 5824 | const ( |
| 5825 | c1 = imag(2i) // imag(2i) = 2.0 is a constant |
| 5826 | c2 = len([10]float64{2}) // [10]float64{2} contains no function calls |
| 5827 | c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls |
| 5828 | c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued |
Shenghou Ma | c0abdd9 | 2014-12-26 02:50:33 -0500 | [diff] [blame] | 5829 | c5 = len([10]float64{imag(z)}) // invalid: imag(z) is a (non-constant) function call |
Robert Griesemer | 8716981 | 2014-03-03 20:07:34 -0800 | [diff] [blame] | 5830 | ) |
| 5831 | var z complex128 |
| 5832 | </pre> |
Robert Griesemer | 5473103 | 2011-05-12 09:15:59 -0700 | [diff] [blame] | 5833 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5834 | <h3 id="Allocation">Allocation</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5835 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5836 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5837 | The built-in function <code>new</code> takes a type <code>T</code>, |
| 5838 | allocates storage for a <a href="#Variables">variable</a> of that type |
| 5839 | at run time, and returns a value of type <code>*T</code> |
| 5840 | <a href="#Pointer_types">pointing</a> to it. |
| 5841 | The variable is initialized as described in the section on |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5842 | <a href="#The_zero_value">initial values</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5843 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5844 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5845 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5846 | new(T) |
| 5847 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5848 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5849 | <p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 5850 | For instance |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5851 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5852 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5853 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 5854 | type S struct { a int; b float64 } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5855 | new(S) |
| 5856 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5857 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5858 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5859 | allocates storage for a variable of type <code>S</code>, |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5860 | initializes it (<code>a=0</code>, <code>b=0.0</code>), |
| 5861 | and returns a value of type <code>*S</code> containing the address |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 5862 | of the location. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5863 | </p> |
| 5864 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 5865 | <h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 5866 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5867 | <p> |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5868 | The built-in function <code>make</code> takes a type <code>T</code>, |
| 5869 | which must be a slice, map or channel type, |
| 5870 | optionally followed by a type-specific list of expressions. |
| 5871 | It returns a value of type <code>T</code> (not <code>*T</code>). |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 5872 | The memory is initialized as described in the section on |
| 5873 | <a href="#The_zero_value">initial values</a>. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5874 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5875 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5876 | <pre class="grammar"> |
Robert Griesemer | df674ff | 2010-05-04 17:31:40 -0700 | [diff] [blame] | 5877 | Call Type T Result |
| 5878 | |
| 5879 | make(T, n) slice slice of type T with length n and capacity n |
| 5880 | make(T, n, m) slice slice of type T with length n and capacity m |
| 5881 | |
| 5882 | make(T) map map of type T |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5883 | make(T, n) map map of type T with initial space for approximately n elements |
Robert Griesemer | df674ff | 2010-05-04 17:31:40 -0700 | [diff] [blame] | 5884 | |
Robert Griesemer | 97aa90d | 2014-05-07 10:40:39 -0700 | [diff] [blame] | 5885 | make(T) channel unbuffered channel of type T |
| 5886 | make(T, n) channel buffered channel of type T, buffer size n |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5887 | </pre> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5888 | |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5889 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5890 | <p> |
griesemer | 9690d24 | 2017-08-30 15:10:12 +0200 | [diff] [blame] | 5891 | Each of the size arguments <code>n</code> and <code>m</code> must be of integer type |
| 5892 | or an untyped <a href="#Constants">constant</a>. |
| 5893 | A constant size argument must be non-negative and <a href="#Representability">representable</a> |
| 5894 | by a value of type <code>int</code>; if it is an untyped constant it is given type <code>int</code>. |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 5895 | If both <code>n</code> and <code>m</code> are provided and are constant, then |
Robert Griesemer | 3bde000 | 2012-10-19 10:11:06 -0700 | [diff] [blame] | 5896 | <code>n</code> must be no larger than <code>m</code>. |
| 5897 | If <code>n</code> is negative or larger than <code>m</code> at run time, |
| 5898 | a <a href="#Run_time_panics">run-time panic</a> occurs. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 5899 | </p> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5900 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5901 | <pre> |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5902 | s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100 |
Robert Griesemer | 3bde000 | 2012-10-19 10:11:06 -0700 | [diff] [blame] | 5903 | s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000 |
Robert Griesemer | 3906706 | 2012-12-12 11:06:26 -0800 | [diff] [blame] | 5904 | s := make([]int, 1<<63) // illegal: len(s) is not representable by a value of type int |
Oling Cat | 018e89f | 2013-01-24 20:46:33 +1100 | [diff] [blame] | 5905 | s := make([]int, 10, 0) // illegal: len(s) > cap(s) |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 5906 | c := make(chan int, 10) // channel with a buffer size of 10 |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5907 | m := make(map[string]int, 100) // map with initial space for approximately 100 elements |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 5908 | </pre> |
Robert Griesemer | 633957b | 2009-01-06 13:23:20 -0800 | [diff] [blame] | 5909 | |
Robert Griesemer | b0e5a0c | 2017-04-11 16:10:09 -0700 | [diff] [blame] | 5910 | <p> |
| 5911 | Calling <code>make</code> with a map type and size hint <code>n</code> will |
| 5912 | create a map with initial space to hold <code>n</code> map elements. |
| 5913 | The precise behavior is implementation-dependent. |
| 5914 | </p> |
| 5915 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 5916 | |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5917 | <h3 id="Appending_and_copying_slices">Appending to and copying slices</h3> |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5918 | |
| 5919 | <p> |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5920 | The built-in functions <code>append</code> and <code>copy</code> assist in |
| 5921 | common slice operations. |
| 5922 | For both functions, the result is independent of whether the memory referenced |
| 5923 | by the arguments overlaps. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5924 | </p> |
| 5925 | |
| 5926 | <p> |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 5927 | The <a href="#Function_types">variadic</a> function <code>append</code> |
| 5928 | appends zero or more values <code>x</code> |
Robert Griesemer | 0f7acf1 | 2011-04-19 14:38:49 -0700 | [diff] [blame] | 5929 | to <code>s</code> of type <code>S</code>, which must be a slice type, and |
| 5930 | returns the resulting slice, also of type <code>S</code>. |
Robert Griesemer | 95b8137 | 2011-06-12 12:09:50 -0700 | [diff] [blame] | 5931 | The values <code>x</code> are passed to a parameter of type <code>...T</code> |
| 5932 | where <code>T</code> is the <a href="#Slice_types">element type</a> of |
| 5933 | <code>S</code> and the respective |
| 5934 | <a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply. |
Luuk van Dijk | 77fac21 | 2011-10-12 15:59:23 +0200 | [diff] [blame] | 5935 | As a special case, <code>append</code> also accepts a first argument |
| 5936 | assignable to type <code>[]byte</code> with a second argument of |
| 5937 | string type followed by <code>...</code>. This form appends the |
| 5938 | bytes of the string. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5939 | </p> |
| 5940 | |
| 5941 | <pre class="grammar"> |
Robert Griesemer | 0f7acf1 | 2011-04-19 14:38:49 -0700 | [diff] [blame] | 5942 | append(s S, x ...T) S // T is the element type of S |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5943 | </pre> |
| 5944 | |
| 5945 | <p> |
| 5946 | If the capacity of <code>s</code> is not large enough to fit the additional |
Robert Griesemer | 15da997 | 2013-10-16 16:16:54 -0700 | [diff] [blame] | 5947 | values, <code>append</code> allocates a new, sufficiently large underlying |
| 5948 | array that fits both the existing slice elements and the additional values. |
| 5949 | Otherwise, <code>append</code> re-uses the underlying array. |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5950 | </p> |
| 5951 | |
| 5952 | <pre> |
| 5953 | s0 := []int{0, 0} |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5954 | s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2} |
| 5955 | s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7} |
| 5956 | s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0} |
| 5957 | s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0} |
Robert Griesemer | 0f7acf1 | 2011-04-19 14:38:49 -0700 | [diff] [blame] | 5958 | |
| 5959 | var t []interface{} |
David Symonds | 583b29c | 2014-12-04 09:29:29 +1100 | [diff] [blame] | 5960 | t = append(t, 42, 3.1415, "foo") // t == []interface{}{42, 3.1415, "foo"} |
Luuk van Dijk | 77fac21 | 2011-10-12 15:59:23 +0200 | [diff] [blame] | 5961 | |
| 5962 | var b []byte |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5963 | b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' } |
Robert Griesemer | 07e983a | 2010-10-25 16:50:31 -0700 | [diff] [blame] | 5964 | </pre> |
| 5965 | |
| 5966 | <p> |
| 5967 | The function <code>copy</code> copies slice elements from |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5968 | a source <code>src</code> to a destination <code>dst</code> and returns the |
Robert Griesemer | 0c49471 | 2012-09-28 15:55:38 -0700 | [diff] [blame] | 5969 | number of elements copied. |
Robert Griesemer | 7bc0371 | 2010-06-07 15:49:39 -0700 | [diff] [blame] | 5970 | Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5971 | <a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>. |
Nigel Tao | 703b092 | 2011-05-15 16:04:37 -0700 | [diff] [blame] | 5972 | The number of elements copied is the minimum of |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5973 | <code>len(src)</code> and <code>len(dst)</code>. |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5974 | As a special case, <code>copy</code> also accepts a destination argument assignable |
| 5975 | to type <code>[]byte</code> with a source argument of a string type. |
| 5976 | This form copies the bytes from the string into the byte slice. |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5977 | </p> |
| 5978 | |
| 5979 | <pre class="grammar"> |
| 5980 | copy(dst, src []T) int |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5981 | copy(dst []byte, src string) int |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5982 | </pre> |
| 5983 | |
| 5984 | <p> |
| 5985 | Examples: |
| 5986 | </p> |
| 5987 | |
| 5988 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 5989 | var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7} |
| 5990 | var s = make([]int, 6) |
Robert Griesemer | 425bbad | 2010-10-25 16:41:06 -0700 | [diff] [blame] | 5991 | var b = make([]byte, 5) |
| 5992 | n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5} |
| 5993 | n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5} |
| 5994 | n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello") |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 5995 | </pre> |
| 5996 | |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 5997 | |
| 5998 | <h3 id="Deletion_of_map_elements">Deletion of map elements</h3> |
| 5999 | |
| 6000 | <p> |
| 6001 | The built-in function <code>delete</code> removes the element with key |
| 6002 | <code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The |
| 6003 | type of <code>k</code> must be <a href="#Assignability">assignable</a> |
| 6004 | to the key type of <code>m</code>. |
| 6005 | </p> |
| 6006 | |
| 6007 | <pre class="grammar"> |
| 6008 | delete(m, k) // remove element m[k] from map m |
| 6009 | </pre> |
| 6010 | |
| 6011 | <p> |
Robert Griesemer | a9a49fe | 2012-12-12 13:08:35 -0800 | [diff] [blame] | 6012 | If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code> |
| 6013 | does not exist, <code>delete</code> is a no-op. |
Robert Griesemer | 3e0c0a8 | 2011-10-17 12:53:10 -0700 | [diff] [blame] | 6014 | </p> |
| 6015 | |
| 6016 | |
Russ Cox | 0201e37 | 2012-02-29 15:20:11 -0500 | [diff] [blame] | 6017 | <h3 id="Complex_numbers">Manipulating complex numbers</h3> |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6018 | |
| 6019 | <p> |
| 6020 | Three functions assemble and disassemble complex numbers. |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6021 | The built-in function <code>complex</code> constructs a complex |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6022 | value from a floating-point real and imaginary part, while |
| 6023 | <code>real</code> and <code>imag</code> |
| 6024 | extract the real and imaginary parts of a complex value. |
| 6025 | </p> |
| 6026 | |
| 6027 | <pre class="grammar"> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6028 | complex(realPart, imaginaryPart floatT) complexT |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6029 | real(complexT) floatT |
| 6030 | imag(complexT) floatT |
| 6031 | </pre> |
| 6032 | |
| 6033 | <p> |
| 6034 | The type of the arguments and return value correspond. |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6035 | For <code>complex</code>, the two arguments must be of the same |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6036 | floating-point type and the return type is the complex type |
| 6037 | with the corresponding floating-point constituents: |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 6038 | <code>complex64</code> for <code>float32</code> arguments, and |
| 6039 | <code>complex128</code> for <code>float64</code> arguments. |
Robert Griesemer | 26d2260 | 2018-10-02 15:55:38 -0700 | [diff] [blame] | 6040 | If one of the arguments evaluates to an untyped constant, it is first implicitly |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 6041 | <a href="#Conversions">converted</a> to the type of the other argument. |
| 6042 | If both arguments evaluate to untyped constants, they must be non-complex |
| 6043 | numbers or their imaginary parts must be zero, and the return value of |
| 6044 | the function is an untyped complex constant. |
| 6045 | </p> |
| 6046 | |
| 6047 | <p> |
| 6048 | For <code>real</code> and <code>imag</code>, the argument must be |
| 6049 | of complex type, and the return type is the corresponding floating-point |
| 6050 | type: <code>float32</code> for a <code>complex64</code> argument, and |
| 6051 | <code>float64</code> for a <code>complex128</code> argument. |
| 6052 | If the argument evaluates to an untyped constant, it must be a number, |
| 6053 | and the return value of the function is an untyped floating-point constant. |
| 6054 | </p> |
| 6055 | |
| 6056 | <p> |
| 6057 | The <code>real</code> and <code>imag</code> functions together form the inverse of |
| 6058 | <code>complex</code>, so for a value <code>z</code> of a complex type <code>Z</code>, |
| 6059 | <code>z == Z(complex(real(z), imag(z)))</code>. |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6060 | </p> |
| 6061 | |
| 6062 | <p> |
| 6063 | If the operands of these functions are all constants, the return |
| 6064 | value is a constant. |
| 6065 | </p> |
| 6066 | |
| 6067 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6068 | var a = complex(2, -2) // complex128 |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 6069 | const b = complex(1.0, -1.4) // untyped complex constant 1 - 1.4i |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6070 | x := float32(math.Cos(math.Pi/2)) // float32 |
| 6071 | var c64 = complex(5, -x) // complex64 |
Robert Griesemer | a10b4cf | 2019-02-05 14:33:24 -0800 | [diff] [blame] | 6072 | var s int = complex(1, 0) // untyped complex constant 1 + 0i can be converted to int |
Robert Griesemer | 5567b87 | 2016-10-14 11:27:11 -0700 | [diff] [blame] | 6073 | _ = complex(1, 2<<s) // illegal: 2 assumes floating-point type, cannot shift |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6074 | var rl = real(c64) // float32 |
Robert Griesemer | 98aa822 | 2015-07-29 15:42:04 -0700 | [diff] [blame] | 6075 | var im = imag(a) // float64 |
| 6076 | const c = imag(b) // untyped constant -1.4 |
Robert Griesemer | 5567b87 | 2016-10-14 11:27:11 -0700 | [diff] [blame] | 6077 | _ = imag(3 << s) // illegal: 3 assumes complex type, cannot shift |
Rob Pike | 7297087 | 2010-03-04 12:35:16 -0800 | [diff] [blame] | 6078 | </pre> |
| 6079 | |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6080 | <h3 id="Handling_panics">Handling panics</h3> |
| 6081 | |
| 6082 | <p> Two built-in functions, <code>panic</code> and <code>recover</code>, |
| 6083 | assist in reporting and handling <a href="#Run_time_panics">run-time panics</a> |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 6084 | and program-defined error conditions. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6085 | </p> |
| 6086 | |
| 6087 | <pre class="grammar"> |
| 6088 | func panic(interface{}) |
| 6089 | func recover() interface{} |
| 6090 | </pre> |
| 6091 | |
| 6092 | <p> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 6093 | While executing a function <code>F</code>, |
| 6094 | an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a> |
| 6095 | terminates the execution of <code>F</code>. |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 6096 | Any functions <a href="#Defer_statements">deferred</a> by <code>F</code> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 6097 | are then executed as usual. |
| 6098 | Next, any deferred functions run by <code>F's</code> caller are run, |
| 6099 | and so on up to any deferred by the top-level function in the executing goroutine. |
| 6100 | At that point, the program is terminated and the error |
Robert Griesemer | 1e8e14c | 2012-11-01 10:13:48 -0700 | [diff] [blame] | 6101 | condition is reported, including the value of the argument to <code>panic</code>. |
| 6102 | This termination sequence is called <i>panicking</i>. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6103 | </p> |
| 6104 | |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6105 | <pre> |
| 6106 | panic(42) |
| 6107 | panic("unreachable") |
| 6108 | panic(Error("cannot parse")) |
| 6109 | </pre> |
| 6110 | |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6111 | <p> |
| 6112 | The <code>recover</code> function allows a program to manage behavior |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 6113 | of a panicking goroutine. |
| 6114 | Suppose a function <code>G</code> defers a function <code>D</code> that calls |
| 6115 | <code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code> |
| 6116 | is executing. |
| 6117 | When the running of deferred functions reaches <code>D</code>, |
| 6118 | the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>. |
| 6119 | If <code>D</code> returns normally, without starting a new |
| 6120 | <code>panic</code>, the panicking sequence stops. In that case, |
| 6121 | the state of functions called between <code>G</code> and the call to <code>panic</code> |
| 6122 | is discarded, and normal execution resumes. |
| 6123 | Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s |
| 6124 | execution terminates by returning to its caller. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6125 | </p> |
| 6126 | |
| 6127 | <p> |
Rob Pike | c34050f | 2013-03-12 14:28:16 -0700 | [diff] [blame] | 6128 | The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds: |
| 6129 | </p> |
| 6130 | <ul> |
| 6131 | <li> |
| 6132 | <code>panic</code>'s argument was <code>nil</code>; |
| 6133 | </li> |
| 6134 | <li> |
| 6135 | the goroutine is not panicking; |
| 6136 | </li> |
| 6137 | <li> |
| 6138 | <code>recover</code> was not called directly by a deferred function. |
| 6139 | </li> |
| 6140 | </ul> |
| 6141 | |
| 6142 | <p> |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6143 | The <code>protect</code> function in the example below invokes |
| 6144 | the function argument <code>g</code> and protects callers from |
| 6145 | run-time panics raised by <code>g</code>. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6146 | </p> |
| 6147 | |
| 6148 | <pre> |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6149 | func protect(g func()) { |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6150 | defer func() { |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 6151 | log.Println("done") // Println executes normally even if there is a panic |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6152 | if x := recover(); x != nil { |
Rob Pike | 966bf71 | 2011-03-01 13:54:22 -0800 | [diff] [blame] | 6153 | log.Printf("run time panic: %v", x) |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6154 | } |
Rob Pike | e6b1d42 | 2011-04-05 11:01:25 -0700 | [diff] [blame] | 6155 | }() |
Robert Griesemer | 76f3228 | 2011-02-04 08:43:21 -0800 | [diff] [blame] | 6156 | log.Println("start") |
| 6157 | g() |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6158 | } |
| 6159 | </pre> |
| 6160 | |
Robert Griesemer | 1a8ebcc | 2009-11-18 19:15:25 -0800 | [diff] [blame] | 6161 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6162 | <h3 id="Bootstrapping">Bootstrapping</h3> |
| 6163 | |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 6164 | <p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6165 | Current implementations provide several built-in functions useful during |
| 6166 | bootstrapping. These functions are documented for completeness but are not |
| 6167 | guaranteed to stay in the language. They do not return a result. |
Robert Griesemer | 5eb3624 | 2009-09-16 11:05:14 -0700 | [diff] [blame] | 6168 | </p> |
| 6169 | |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6170 | <pre class="grammar"> |
Robert Griesemer | d4d4ff0 | 2009-10-19 13:13:59 -0700 | [diff] [blame] | 6171 | Function Behavior |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6172 | |
| 6173 | print prints all arguments; formatting of arguments is implementation-specific |
| 6174 | println like print but prints spaces between arguments and a newline at the end |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6175 | </pre> |
| 6176 | |
Robert Griesemer | 50f67ad | 2017-04-27 17:54:49 -0700 | [diff] [blame] | 6177 | <p> |
| 6178 | Implementation restriction: <code>print</code> and <code>println</code> need not |
| 6179 | accept arbitrary argument types, but printing of boolean, numeric, and string |
Robert Griesemer | 86f5f7f | 2017-04-28 10:32:31 -0700 | [diff] [blame] | 6180 | <a href="#Types">types</a> must be supported. |
Robert Griesemer | 50f67ad | 2017-04-27 17:54:49 -0700 | [diff] [blame] | 6181 | </p> |
Robert Griesemer | 164a7bc | 2009-09-30 12:00:25 -0700 | [diff] [blame] | 6182 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6183 | <h2 id="Packages">Packages</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6184 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6185 | <p> |
| 6186 | Go programs are constructed by linking together <i>packages</i>. |
Robert Griesemer | 326ef13 | 2009-09-28 19:21:15 -0700 | [diff] [blame] | 6187 | A package in turn is constructed from one or more source files |
| 6188 | that together declare constants, types, variables and functions |
| 6189 | belonging to the package and which are accessible in all files |
| 6190 | of the same package. Those elements may be |
| 6191 | <a href="#Exported_identifiers">exported</a> and used in another package. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6192 | </p> |
| 6193 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6194 | <h3 id="Source_file_organization">Source file organization</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6195 | |
| 6196 | <p> |
| 6197 | Each source file consists of a package clause defining the package |
| 6198 | to which it belongs, followed by a possibly empty set of import |
| 6199 | declarations that declare packages whose contents it wishes to use, |
| 6200 | followed by a possibly empty set of declarations of functions, |
Robert Griesemer | 0a162a1 | 2009-08-19 16:44:04 -0700 | [diff] [blame] | 6201 | types, variables, and constants. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6202 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6203 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6204 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6205 | SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6206 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6207 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6208 | <h3 id="Package_clause">Package clause</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6209 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6210 | <p> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6211 | A package clause begins each source file and defines the package |
| 6212 | to which the file belongs. |
| 6213 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6214 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6215 | <pre class="ebnf"> |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 6216 | PackageClause = "package" PackageName . |
| 6217 | PackageName = identifier . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6218 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6219 | |
Robert Griesemer | 4e56b33 | 2009-09-10 10:14:00 -0700 | [diff] [blame] | 6220 | <p> |
| 6221 | The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>. |
| 6222 | </p> |
| 6223 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6224 | <pre> |
| 6225 | package math |
| 6226 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6227 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6228 | <p> |
| 6229 | A set of files sharing the same PackageName form the implementation of a package. |
| 6230 | An implementation may require that all source files for a package inhabit the same directory. |
| 6231 | </p> |
| 6232 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6233 | <h3 id="Import_declarations">Import declarations</h3> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6234 | |
| 6235 | <p> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6236 | An import declaration states that the source file containing the declaration |
| 6237 | depends on functionality of the <i>imported</i> package |
| 6238 | (<a href="#Program_initialization_and_execution">§Program initialization and execution</a>) |
Rob Pike | b51ad9c | 2012-09-23 05:03:43 +1000 | [diff] [blame] | 6239 | and enables access to <a href="#Exported_identifiers">exported</a> identifiers |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6240 | of that package. |
| 6241 | The import names an identifier (PackageName) to be used for access and an ImportPath |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6242 | that specifies the package to be imported. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6243 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6244 | |
Robert Griesemer | f7ac3136 | 2009-07-10 16:06:40 -0700 | [diff] [blame] | 6245 | <pre class="ebnf"> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6246 | ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6247 | ImportSpec = [ "." | PackageName ] ImportPath . |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6248 | ImportPath = string_lit . |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6249 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6250 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6251 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6252 | The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a> |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6253 | to access exported identifiers of the package within the importing source file. |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6254 | It is declared in the <a href="#Blocks">file block</a>. |
| 6255 | If the PackageName is omitted, it defaults to the identifier specified in the |
Robert Griesemer | 556506e | 2011-02-22 09:34:13 -0800 | [diff] [blame] | 6256 | <a href="#Package_clause">package clause</a> of the imported package. |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6257 | If an explicit period (<code>.</code>) appears instead of a name, all the |
Robert Griesemer | 103c9db | 2012-03-01 13:57:49 -0800 | [diff] [blame] | 6258 | package's exported identifiers declared in that package's |
| 6259 | <a href="#Blocks">package block</a> will be declared in the importing source |
Rob Pike | 227fe5f | 2014-01-14 15:16:01 -0800 | [diff] [blame] | 6260 | file's file block and must be accessed without a qualifier. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6261 | </p> |
Russ Cox | 16b95ba | 2009-08-20 10:22:52 -0700 | [diff] [blame] | 6262 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6263 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6264 | The interpretation of the ImportPath is implementation-dependent but |
| 6265 | it is typically a substring of the full file name of the compiled |
| 6266 | package and may be relative to a repository of installed packages. |
| 6267 | </p> |
| 6268 | |
| 6269 | <p> |
Robert Griesemer | ac4055b | 2012-02-22 23:51:25 -0800 | [diff] [blame] | 6270 | Implementation restriction: A compiler may restrict ImportPaths to |
| 6271 | non-empty strings using only characters belonging to |
Suriyaa Sundararuban | 1041ac8 | 2018-06-13 07:06:04 +0000 | [diff] [blame] | 6272 | <a href="https://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a> |
Robert Griesemer | ac4055b | 2012-02-22 23:51:25 -0800 | [diff] [blame] | 6273 | L, M, N, P, and S general categories (the Graphic characters without |
Russ Cox | fad10f9 | 2012-02-23 22:46:04 -0500 | [diff] [blame] | 6274 | spaces) and may also exclude the characters |
| 6275 | <code>!"#$%&'()*,:;<=>?[\]^`{|}</code> |
| 6276 | and the Unicode replacement character U+FFFD. |
Robert Griesemer | ac4055b | 2012-02-22 23:51:25 -0800 | [diff] [blame] | 6277 | </p> |
| 6278 | |
| 6279 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6280 | Assume we have compiled a package containing the package clause |
| 6281 | <code>package math</code>, which exports function <code>Sin</code>, and |
| 6282 | installed the compiled package in the file identified by |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6283 | <code>"lib/math"</code>. |
Rob Pike | 227fe5f | 2014-01-14 15:16:01 -0800 | [diff] [blame] | 6284 | This table illustrates how <code>Sin</code> is accessed in files |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6285 | that import the package after the |
| 6286 | various types of import declaration. |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6287 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6288 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6289 | <pre class="grammar"> |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6290 | Import declaration Local name of Sin |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6291 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6292 | import "lib/math" math.Sin |
Rob Pike | b51ad9c | 2012-09-23 05:03:43 +1000 | [diff] [blame] | 6293 | import m "lib/math" m.Sin |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6294 | import . "lib/math" Sin |
| 6295 | </pre> |
| 6296 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6297 | <p> |
Rob Pike | 3aec2e4 | 2009-09-25 17:00:22 -0700 | [diff] [blame] | 6298 | An import declaration declares a dependency relation between |
| 6299 | the importing and imported package. |
Robert Griesemer | 4be38dd | 2013-03-04 12:59:40 -0800 | [diff] [blame] | 6300 | It is illegal for a package to import itself, directly or indirectly, |
| 6301 | or to directly import a package without |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6302 | referring to any of its exported identifiers. To import a package solely for |
| 6303 | its side-effects (initialization), use the <a href="#Blank_identifier">blank</a> |
| 6304 | identifier as explicit package name: |
| 6305 | </p> |
| 6306 | |
| 6307 | <pre> |
| 6308 | import _ "lib/math" |
| 6309 | </pre> |
| 6310 | |
| 6311 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6312 | <h3 id="An_example_package">An example package</h3> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6313 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6314 | <p> |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6315 | Here is a complete Go package that implements a concurrent prime sieve. |
| 6316 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6317 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6318 | <pre> |
| 6319 | package main |
| 6320 | |
Rob Pike | 4659685 | 2009-03-02 16:17:29 -0800 | [diff] [blame] | 6321 | import "fmt" |
| 6322 | |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 6323 | // Send the sequence 2, 3, 4, … to channel 'ch'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6324 | func generate(ch chan<- int) { |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6325 | for i := 2; ; i++ { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6326 | ch <- i // Send 'i' to channel 'ch'. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6327 | } |
| 6328 | } |
| 6329 | |
Fazlul Shahriar | 330139e | 2009-11-30 21:23:58 -0800 | [diff] [blame] | 6330 | // Copy the values from channel 'src' to channel 'dst', |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6331 | // removing those divisible by 'prime'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6332 | func filter(src <-chan int, dst chan<- int, prime int) { |
David Symonds | 72a2979 | 2011-11-29 15:47:36 -0800 | [diff] [blame] | 6333 | for i := range src { // Loop over values received from 'src'. |
Robert Griesemer | e1e7619 | 2009-09-25 14:11:03 -0700 | [diff] [blame] | 6334 | if i%prime != 0 { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6335 | dst <- i // Send 'i' to channel 'dst'. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6336 | } |
| 6337 | } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6338 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6339 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6340 | // The prime sieve: Daisy-chain filter processes together. |
| 6341 | func sieve() { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6342 | ch := make(chan int) // Create a new channel. |
| 6343 | go generate(ch) // Start generate() as a subprocess. |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6344 | for { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6345 | prime := <-ch |
| 6346 | fmt.Print(prime, "\n") |
| 6347 | ch1 := make(chan int) |
| 6348 | go filter(ch, ch1, prime) |
| 6349 | ch = ch1 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6350 | } |
| 6351 | } |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6352 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6353 | func main() { |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6354 | sieve() |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6355 | } |
| 6356 | </pre> |
Robert Griesemer | 6715358 | 2008-12-16 14:45:09 -0800 | [diff] [blame] | 6357 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6358 | <h2 id="Program_initialization_and_execution">Program initialization and execution</h2> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6359 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6360 | <h3 id="The_zero_value">The zero value</h3> |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6361 | <p> |
Robert Griesemer | 6962c15 | 2014-10-16 15:08:49 -0700 | [diff] [blame] | 6362 | When storage is allocated for a <a href="#Variables">variable</a>, |
| 6363 | either through a declaration or a call of <code>new</code>, or when |
| 6364 | a new value is created, either through a composite literal or a call |
| 6365 | of <code>make</code>, |
| 6366 | and no explicit initialization is provided, the variable or value is |
| 6367 | given a default value. Each element of such a variable or value is |
Robert Griesemer | ef45e64 | 2009-08-21 11:25:00 -0700 | [diff] [blame] | 6368 | set to the <i>zero value</i> for its type: <code>false</code> for booleans, |
griesemer | a9f832a | 2017-08-24 15:20:18 +0200 | [diff] [blame] | 6369 | <code>0</code> for numeric types, <code>""</code> |
Robert Griesemer | 19b1d35 | 2009-09-24 19:36:48 -0700 | [diff] [blame] | 6370 | for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps. |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 6371 | This initialization is done recursively, so for instance each element of an |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6372 | array of structs will have its fields zeroed if no value is specified. |
| 6373 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6374 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6375 | These two simple declarations are equivalent: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6376 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6377 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6378 | <pre> |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6379 | var i int |
| 6380 | var i int = 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6381 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6382 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6383 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6384 | After |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6385 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6386 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6387 | <pre> |
Robert Griesemer | b94c0d2 | 2011-01-19 23:07:21 -0500 | [diff] [blame] | 6388 | type T struct { i int; f float64; next *T } |
Robert Griesemer | 130ac74 | 2009-12-10 16:43:01 -0800 | [diff] [blame] | 6389 | t := new(T) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6390 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6391 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6392 | <p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6393 | the following holds: |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6394 | </p> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6395 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6396 | <pre> |
| 6397 | t.i == 0 |
| 6398 | t.f == 0.0 |
| 6399 | t.next == nil |
| 6400 | </pre> |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6401 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6402 | <p> |
| 6403 | The same would also be true after |
| 6404 | </p> |
| 6405 | |
| 6406 | <pre> |
| 6407 | var t T |
| 6408 | </pre> |
| 6409 | |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6410 | <h3 id="Package_initialization">Package initialization</h3> |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6411 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6412 | <p> |
Robert Griesemer | 451cf3e | 2019-05-08 13:21:02 -0700 | [diff] [blame] | 6413 | Within a package, package-level variable initialization proceeds stepwise, |
| 6414 | with each step selecting the variable earliest in <i>declaration order</i> |
| 6415 | which has no dependencies on uninitialized variables. |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6416 | </p> |
| 6417 | |
| 6418 | <p> |
| 6419 | More precisely, a package-level variable is considered <i>ready for |
| 6420 | initialization</i> if it is not yet initialized and either has |
| 6421 | no <a href="#Variable_declarations">initialization expression</a> or |
Robert Griesemer | 451cf3e | 2019-05-08 13:21:02 -0700 | [diff] [blame] | 6422 | its initialization expression has no <i>dependencies</i> on uninitialized variables. |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6423 | Initialization proceeds by repeatedly initializing the next package-level |
| 6424 | variable that is earliest in declaration order and ready for initialization, |
| 6425 | until there are no variables ready for initialization. |
| 6426 | </p> |
| 6427 | |
| 6428 | <p> |
| 6429 | If any variables are still uninitialized when this |
| 6430 | process ends, those variables are part of one or more initialization cycles, |
| 6431 | and the program is not valid. |
| 6432 | </p> |
| 6433 | |
| 6434 | <p> |
Robert Griesemer | 451cf3e | 2019-05-08 13:21:02 -0700 | [diff] [blame] | 6435 | Multiple variables on the left-hand side of a variable declaration initialized |
| 6436 | by single (multi-valued) expression on the right-hand side are initialized |
| 6437 | together: If any of the variables on the left-hand side is initialized, all |
| 6438 | those variables are initialized in the same step. |
| 6439 | </p> |
| 6440 | |
| 6441 | <pre> |
| 6442 | var x = a |
| 6443 | var a, b = f() // a and b are initialized together, before x is initialized |
| 6444 | </pre> |
| 6445 | |
| 6446 | <p> |
| 6447 | For the purpose of package initialization, <a href="#Blank_identifier">blank</a> |
| 6448 | variables are treated like any other variables in declarations. |
| 6449 | </p> |
| 6450 | |
| 6451 | <p> |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6452 | The declaration order of variables declared in multiple files is determined |
| 6453 | by the order in which the files are presented to the compiler: Variables |
| 6454 | declared in the first file are declared before any of the variables declared |
| 6455 | in the second file, and so on. |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6456 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6457 | |
| 6458 | <p> |
| 6459 | Dependency analysis does not rely on the actual values of the |
| 6460 | variables, only on lexical <i>references</i> to them in the source, |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6461 | analyzed transitively. For instance, if a variable <code>x</code>'s |
| 6462 | initialization expression refers to a function whose body refers to |
| 6463 | variable <code>y</code> then <code>x</code> depends on <code>y</code>. |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6464 | Specifically: |
| 6465 | </p> |
| 6466 | |
| 6467 | <ul> |
| 6468 | <li> |
| 6469 | A reference to a variable or function is an identifier denoting that |
| 6470 | variable or function. |
| 6471 | </li> |
| 6472 | |
| 6473 | <li> |
| 6474 | A reference to a method <code>m</code> is a |
| 6475 | <a href="#Method_values">method value</a> or |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 6476 | <a href="#Method_expressions">method expression</a> of the form |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6477 | <code>t.m</code>, where the (static) type of <code>t</code> is |
| 6478 | not an interface type, and the method <code>m</code> is in the |
| 6479 | <a href="#Method_sets">method set</a> of <code>t</code>. |
| 6480 | It is immaterial whether the resulting function value |
| 6481 | <code>t.m</code> is invoked. |
| 6482 | </li> |
| 6483 | |
| 6484 | <li> |
Robin Eklind | cac006a | 2014-08-30 10:27:01 -0700 | [diff] [blame] | 6485 | A variable, function, or method <code>x</code> depends on a variable |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6486 | <code>y</code> if <code>x</code>'s initialization expression or body |
| 6487 | (for functions and methods) contains a reference to <code>y</code> |
| 6488 | or to a function or method that depends on <code>y</code>. |
| 6489 | </li> |
| 6490 | </ul> |
| 6491 | |
| 6492 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6493 | For example, given the declarations |
| 6494 | </p> |
| 6495 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6496 | <pre> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6497 | var ( |
Robert Griesemer | 451cf3e | 2019-05-08 13:21:02 -0700 | [diff] [blame] | 6498 | a = c + b // == 9 |
| 6499 | b = f() // == 4 |
| 6500 | c = f() // == 5 |
| 6501 | d = 3 // == 5 after initialization has finished |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6502 | ) |
| 6503 | |
| 6504 | func f() int { |
| 6505 | d++ |
| 6506 | return d |
| 6507 | } |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6508 | </pre> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6509 | |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6510 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6511 | the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>. |
Robert Griesemer | 451cf3e | 2019-05-08 13:21:02 -0700 | [diff] [blame] | 6512 | Note that the order of subexpressions in initialization expressions is irrelevant: |
| 6513 | <code>a = c + b</code> and <code>a = b + c</code> result in the same initialization |
| 6514 | order in this example. |
| 6515 | </p> |
| 6516 | |
| 6517 | <p> |
| 6518 | Dependency analysis is performed per package; only references referring |
| 6519 | to variables, functions, and (non-interface) methods declared in the current |
| 6520 | package are considered. If other, hidden, data dependencies exists between |
| 6521 | variables, the initialization order between those variables is unspecified. |
| 6522 | </p> |
| 6523 | |
| 6524 | <p> |
| 6525 | For instance, given the declarations |
| 6526 | </p> |
| 6527 | |
| 6528 | <pre> |
| 6529 | var x = I(T{}).ab() // x has an undetected, hidden dependency on a and b |
| 6530 | var _ = sideEffect() // unrelated to x, a, or b |
| 6531 | var a = b |
| 6532 | var b = 42 |
| 6533 | |
| 6534 | type I interface { ab() []int } |
| 6535 | type T struct{} |
| 6536 | func (T) ab() []int { return []int{a, b} } |
| 6537 | </pre> |
| 6538 | |
| 6539 | <p> |
| 6540 | the variable <code>a</code> will be initialized after <code>b</code> but |
| 6541 | whether <code>x</code> is initialized before <code>b</code>, between |
| 6542 | <code>b</code> and <code>a</code>, or after <code>a</code>, and |
| 6543 | thus also the moment at which <code>sideEffect()</code> is called (before |
| 6544 | or after <code>x</code> is initialized) is not specified. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6545 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6546 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6547 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6548 | Variables may also be initialized using functions named <code>init</code> |
| 6549 | declared in the package block, with no arguments and no result parameters. |
Rob Pike | 8cb9184 | 2009-09-15 11:56:39 -0700 | [diff] [blame] | 6550 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6551 | |
| 6552 | <pre> |
| 6553 | func init() { … } |
| 6554 | </pre> |
| 6555 | |
Rob Pike | 8cb9184 | 2009-09-15 11:56:39 -0700 | [diff] [blame] | 6556 | <p> |
Robert Griesemer | a656390 | 2016-08-25 21:01:17 -0700 | [diff] [blame] | 6557 | Multiple such functions may be defined per package, even within a single |
| 6558 | source file. In the package block, the <code>init</code> identifier can |
| 6559 | be used only to declare <code>init</code> functions, yet the identifier |
| 6560 | itself is not <a href="#Declarations_and_scope">declared</a>. Thus |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6561 | <code>init</code> functions cannot be referred to from anywhere |
| 6562 | in a program. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6563 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6564 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6565 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6566 | A package with no imports is initialized by assigning initial values |
| 6567 | to all its package-level variables followed by calling all <code>init</code> |
Robert Griesemer | c00043b | 2014-05-20 17:46:08 -0700 | [diff] [blame] | 6568 | functions in the order they appear in the source, possibly in multiple files, |
| 6569 | as presented to the compiler. |
Robert Griesemer | df49fb3 | 2008-08-28 17:47:53 -0700 | [diff] [blame] | 6570 | If a package has imports, the imported packages are initialized |
Robert Griesemer | 566e3b2 | 2008-09-26 16:41:50 -0700 | [diff] [blame] | 6571 | before initializing the package itself. If multiple packages import |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6572 | a package, the imported package will be initialized only once. |
| 6573 | The importing of packages, by construction, guarantees that there |
| 6574 | can be no cyclic initialization dependencies. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6575 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6576 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6577 | <p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6578 | Package initialization—variable initialization and the invocation of |
| 6579 | <code>init</code> functions—happens in a single goroutine, |
| 6580 | sequentially, one package at a time. |
| 6581 | An <code>init</code> function may launch other goroutines, which can run |
| 6582 | concurrently with the initialization code. However, initialization |
| 6583 | always sequences |
| 6584 | the <code>init</code> functions: it will not invoke the next one |
| 6585 | until the previous one has returned. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6586 | </p> |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6587 | |
Robert Griesemer | 259f0ff | 2014-09-29 12:44:50 -0700 | [diff] [blame] | 6588 | <p> |
| 6589 | To ensure reproducible initialization behavior, build systems are encouraged |
| 6590 | to present multiple files belonging to the same package in lexical file name |
| 6591 | order to a compiler. |
| 6592 | </p> |
| 6593 | |
Robert Griesemer | a436698 | 2014-05-20 13:51:39 -0700 | [diff] [blame] | 6594 | |
| 6595 | <h3 id="Program_execution">Program execution</h3> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6596 | <p> |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6597 | A complete program is created by linking a single, unimported package |
| 6598 | called the <i>main package</i> with all the packages it imports, transitively. |
| 6599 | The main package must |
| 6600 | have package name <code>main</code> and |
Charles L. Dorian | 44262d1 | 2011-11-01 15:13:33 +0900 | [diff] [blame] | 6601 | declare a function <code>main</code> that takes no |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6602 | arguments and returns no value. |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6603 | </p> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 6604 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6605 | <pre> |
Robert Griesemer | 3c7271f | 2011-05-24 14:18:44 -0700 | [diff] [blame] | 6606 | func main() { … } |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6607 | </pre> |
Robert Griesemer | 4dc2528 | 2008-09-09 10:37:19 -0700 | [diff] [blame] | 6608 | |
Rob Pike | 8f2330d | 2009-02-25 16:20:44 -0800 | [diff] [blame] | 6609 | <p> |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6610 | Program execution begins by initializing the main package and then |
| 6611 | invoking the function <code>main</code>. |
Robert Griesemer | 7f1d62d | 2014-05-19 08:54:19 -0700 | [diff] [blame] | 6612 | When that function invocation returns, the program exits. |
Russ Cox | a6736ca | 2011-02-03 13:40:51 -0500 | [diff] [blame] | 6613 | It does not wait for other (non-<code>main</code>) goroutines to complete. |
Rob Pike | 811dd25 | 2009-03-04 20:39:39 -0800 | [diff] [blame] | 6614 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6615 | |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6616 | <h2 id="Errors">Errors</h2> |
| 6617 | |
| 6618 | <p> |
| 6619 | The predeclared type <code>error</code> is defined as |
| 6620 | </p> |
| 6621 | |
| 6622 | <pre> |
| 6623 | type error interface { |
| 6624 | Error() string |
| 6625 | } |
| 6626 | </pre> |
| 6627 | |
| 6628 | <p> |
| 6629 | It is the conventional interface for representing an error condition, |
| 6630 | with the nil value representing no error. |
| 6631 | For instance, a function to read data from a file might be defined: |
| 6632 | </p> |
| 6633 | |
| 6634 | <pre> |
| 6635 | func Read(f *File, b []byte) (n int, err error) |
| 6636 | </pre> |
| 6637 | |
Evan Shaw | 21110c7 | 2010-04-22 10:14:53 -0700 | [diff] [blame] | 6638 | <h2 id="Run_time_panics">Run-time panics</h2> |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6639 | |
| 6640 | <p> |
| 6641 | Execution errors such as attempting to index an array out |
| 6642 | of bounds trigger a <i>run-time panic</i> equivalent to a call of |
| 6643 | the built-in function <a href="#Handling_panics"><code>panic</code></a> |
| 6644 | with a value of the implementation-defined interface type <code>runtime.Error</code>. |
Charles L. Dorian | 9a358df | 2011-12-08 22:27:14 -0500 | [diff] [blame] | 6645 | That type satisfies the predeclared interface type |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6646 | <a href="#Errors"><code>error</code></a>. |
| 6647 | The exact error values that |
| 6648 | represent distinct run-time error conditions are unspecified. |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6649 | </p> |
| 6650 | |
| 6651 | <pre> |
| 6652 | package runtime |
| 6653 | |
| 6654 | type Error interface { |
Russ Cox | d9877e2 | 2011-11-01 21:45:02 -0400 | [diff] [blame] | 6655 | error |
| 6656 | // and perhaps other methods |
Rob Pike | 5bb29fb | 2010-03-25 17:59:59 -0700 | [diff] [blame] | 6657 | } |
| 6658 | </pre> |
| 6659 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6660 | <h2 id="System_considerations">System considerations</h2> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6661 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6662 | <h3 id="Package_unsafe">Package <code>unsafe</code></h3> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6663 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6664 | <p> |
griesemer | ddc64de | 2017-10-17 13:38:10 -0700 | [diff] [blame] | 6665 | The built-in package <code>unsafe</code>, known to the compiler |
| 6666 | and accessible through the <a href="#Import_declarations">import path</a> <code>"unsafe"</code>, |
Rob Pike | 96750f1 | 2009-02-27 16:47:48 -0800 | [diff] [blame] | 6667 | provides facilities for low-level programming including operations |
| 6668 | that violate the type system. A package using <code>unsafe</code> |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6669 | must be vetted manually for type safety and may not be portable. |
| 6670 | The package provides the following interface: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6671 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6672 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 6673 | <pre class="grammar"> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6674 | package unsafe |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6675 | |
Robert Griesemer | 98b4f6a | 2009-05-12 21:37:46 -0700 | [diff] [blame] | 6676 | type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type |
| 6677 | type Pointer *ArbitraryType |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6678 | |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6679 | func Alignof(variable ArbitraryType) uintptr |
Hong Ruiqi | 8374e67 | 2012-04-05 22:37:07 +1000 | [diff] [blame] | 6680 | func Offsetof(selector ArbitraryType) uintptr |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6681 | func Sizeof(variable ArbitraryType) uintptr |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6682 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6683 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6684 | <p> |
Robert Griesemer | e121de2 | 2013-10-07 10:43:28 -0700 | [diff] [blame] | 6685 | A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code> |
| 6686 | value may not be <a href="#Address_operators">dereferenced</a>. |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6687 | Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to |
Robert Griesemer | 86f5f7f | 2017-04-28 10:32:31 -0700 | [diff] [blame] | 6688 | a type of underlying type <code>Pointer</code> and vice versa. |
Robert Griesemer | 5361b74 | 2014-10-23 09:45:11 -0700 | [diff] [blame] | 6689 | The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6690 | </p> |
Russ Cox | 81eb930 | 2013-02-09 17:36:31 -0500 | [diff] [blame] | 6691 | |
| 6692 | <pre> |
| 6693 | var f float64 |
| 6694 | bits = *(*uint64)(unsafe.Pointer(&f)) |
| 6695 | |
| 6696 | type ptr unsafe.Pointer |
| 6697 | bits = *(*uint64)(ptr(&f)) |
Robert Griesemer | e121de2 | 2013-10-07 10:43:28 -0700 | [diff] [blame] | 6698 | |
| 6699 | var p ptr = nil |
Russ Cox | 81eb930 | 2013-02-09 17:36:31 -0500 | [diff] [blame] | 6700 | </pre> |
| 6701 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6702 | <p> |
Robert Griesemer | c7631f5 | 2012-09-17 12:23:41 -0700 | [diff] [blame] | 6703 | The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code> |
| 6704 | of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code> |
| 6705 | as if <code>v</code> was declared via <code>var v = x</code>. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6706 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6707 | <p> |
Robert Griesemer | 8c058b3 | 2012-09-18 11:25:53 -0700 | [diff] [blame] | 6708 | The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a> |
Robert Griesemer | 5133809 | 2013-03-07 20:11:37 -0800 | [diff] [blame] | 6709 | <code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code> |
| 6710 | or <code>*s</code>, and returns the field offset in bytes relative to the struct's address. |
| 6711 | If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable |
| 6712 | without pointer indirections through fields of the struct. |
Rob Pike | 678625d | 2009-09-15 09:54:22 -0700 | [diff] [blame] | 6713 | For a struct <code>s</code> with field <code>f</code>: |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6714 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6715 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6716 | <pre> |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6717 | uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f)) |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6718 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6719 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6720 | <p> |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6721 | Computer architectures may require memory addresses to be <i>aligned</i>; |
| 6722 | that is, for addresses of a variable to be a multiple of a factor, |
| 6723 | the variable's type's <i>alignment</i>. The function <code>Alignof</code> |
| 6724 | takes an expression denoting a variable of any type and returns the |
| 6725 | alignment of the (type of the) variable in bytes. For a variable |
| 6726 | <code>x</code>: |
| 6727 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6728 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6729 | <pre> |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6730 | uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6731 | </pre> |
Robert Griesemer | 533dfd6 | 2009-05-13 16:56:00 -0700 | [diff] [blame] | 6732 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6733 | <p> |
| 6734 | Calls to <code>Alignof</code>, <code>Offsetof</code>, and |
Robert Griesemer | eee70b0 | 2011-06-13 16:46:42 -0700 | [diff] [blame] | 6735 | <code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>. |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6736 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6737 | |
Russ Cox | 7c4f7cc | 2009-08-20 11:11:03 -0700 | [diff] [blame] | 6738 | <h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6739 | |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6740 | <p> |
Robert Griesemer | 462a17e | 2013-03-22 15:36:04 -0700 | [diff] [blame] | 6741 | For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed: |
Robert Griesemer | 997851e | 2009-09-25 15:36:25 -0700 | [diff] [blame] | 6742 | </p> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6743 | |
Rob Pike | ff70f09 | 2009-02-20 13:36:14 -0800 | [diff] [blame] | 6744 | <pre class="grammar"> |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 6745 | type size in bytes |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6746 | |
Robert Griesemer | 777a96a | 2010-12-02 12:32:14 -0800 | [diff] [blame] | 6747 | byte, uint8, int8 1 |
| 6748 | uint16, int16 2 |
| 6749 | uint32, int32, float32 4 |
| 6750 | uint64, int64, float64, complex64 8 |
| 6751 | complex128 16 |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6752 | </pre> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6753 | |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6754 | <p> |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6755 | The following minimal alignment properties are guaranteed: |
Rob Pike | 4501d34 | 2009-02-19 17:31:36 -0800 | [diff] [blame] | 6756 | </p> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6757 | <ol> |
Robert Griesemer | dd916be | 2011-01-10 14:25:17 -0800 | [diff] [blame] | 6758 | <li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 6759 | </li> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6760 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6761 | <li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of |
Robert Griesemer | dd916be | 2011-01-10 14:25:17 -0800 | [diff] [blame] | 6762 | all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 6763 | </li> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6764 | |
Rob Pike | f27e9f0 | 2009-02-23 19:22:05 -0800 | [diff] [blame] | 6765 | <li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as |
Robert Griesemer | e62aab1 | 2017-02-06 23:33:21 -0800 | [diff] [blame] | 6766 | the alignment of a variable of the array's element type. |
Robert Griesemer | 3af48037 | 2010-05-14 13:11:48 -0700 | [diff] [blame] | 6767 | </li> |
Robert Griesemer | c2d5586 | 2009-02-19 16:49:10 -0800 | [diff] [blame] | 6768 | </ol> |
Robert Griesemer | 52c02c2 | 2009-02-11 13:46:30 -0800 | [diff] [blame] | 6769 | |
Robert Griesemer | 1320ce0 | 2012-01-09 16:54:24 -0800 | [diff] [blame] | 6770 | <p> |
| 6771 | A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory. |
| 6772 | </p> |